Adapting Persefone

A key development goal of Persefone is to be FAIR: findable, accessible, interoperable, and reusable. We aim to build a model that is both easy to use and easy to adapt to new situations.

There are multiple ways to adapt Persefone for a new modelling study:

Changing the parameters

The simplest way to adapt Persefone is simply by changing the parameters. Copy src/parameters.toml to a new location, adjust it to your needs, and run the model using julia run.jl -c <configfile>.

Changing the region

To apply Persefone to a new region, you need to create new input maps of land cover, field geometries, and soil type, and download the local weather data. How to do so is described here.

Adding new animal species

To implement a new species to the nature submodel, add a new file to the src/nature/species directory and include it in src/Persefone.jl, as well as adding the name of the species to the nature.targetspecies parameter. In the new file, implement the species using the @species syntax as described here.

Adding new crop species

To calibrate the AquaCrop crop growth model for new crop species, follow the tutorial here.

Adding new farmer behaviour or a new crop model

To implement new farmer behaviour or add another crop model, create a new subtype of Farmer or AbstractCropState, respectively. As this is somewhat more complex, read through the current implementations of the farm and crop components to understand how they work.

Adding a new submodel

To add a new submodel in addition to the existing ones (nature, crop, and farm), you need to familiarise yourself with the software architecture. In particular, you need to understand how initialisation and scheduling works in src/core/simulation.jl, and what information is stored in the model object.

If you want to add a new agent type, create a subtype of ModelAgent, implement a stepagent! function for it and add it to Persefone.initmodel.

Linking to another model

Persefone can also be used as a software library and be called from another application. For this purpose, it is set up as a Julia package, with a module exporting various model functions, types, and macros (see src/Persefone.jl). Of particular interest are the functions simulate (set up and run a complete simulation based on a config file), initialise (create one or more model objects from a config file), simulate! (do a simulation run with an existing model object), and stepsimulation! (update a model object by one time step).

To interface with Julia from another language, see the Julia docs here and here.