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 and farmplots. How to do so is described here.

You may also need to change aspects of the farm submodel. This is not yet implemented.

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

Crop growth is not yet implemented.

Adding new farmer behaviour

Farmer behaviour is not yet implemented.

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, use Agents.jl's @agent macro. (But be aware that Persefone already has three agent types and you may encounter performance problems.) Having implemented the new agent type, add it to the model objects type definition and scheduler, and write an initialisation function and a stepagent! function. (See Persefone.initmodel and stepsimulation! for details.)

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.