Persefone.jl

A multidisciplinary mechanistic model of agricultural landscapes and ecosystems in Europe.

Description

Persefone.jl models agricultural practice and how it impacts animal species at a landscape scale. It includes a farm submodel, a crop growth submodel, and individual-based models of multiple indicator species. Its aim is to investigate how changes in farm operations (e.g. through changes in the European Common Agricultural Policy) influence biodiversity.

The model is still in development. A first version will be available in spring 2025.

Usage

For the full documentation, visit the website, or read the manual in the docs folder. To use Persefone.jl with a graphical user interface, see here.

Installation

Install the latest version of the Julia programming language (1.10+). The recommended editors are VSCode or Emacs. Clone this repository, then install package dependencies by opening a Julia REPL in the Persefone root folder and running using Pkg; Pkg.activate("."); Pkg.instantiate().

Alternatively, if you only want to use the package from within Julia (see below), you can install it directly in any Julia REPL:

using Pkg
Pkg.add(url="https://git.idiv.de/persefone/persefone-model.git")
using Persefone

Running from the command line

This is the normal mode of operation. Simply execute run.jl in a terminal, typically like so (in Linux):

> julia run.jl -c <config>

where <config> specifies the configuration file to use. The recommended workflow is to copy scr/parameters.toml to a location of your choice and edit the copy to suit your requirements. The adapted config file can then be passed to run.jl. (If no configuration file is specified, Persefone will run with its default settings.)

The full list of commandline arguments is:

usage: run.jl [-c CONFIGFILE] [-s SEED] [-o OUTDIR] [-l LOGLEVEL] 
              [--version] [-h]

optional arguments:
  -c, --configfile CONFIGFILE
                        name of the configuration file
  -s, --seed SEED       inital random seed (type: Int64)
  -o, --outdir OUTDIR   location of the output directory
  -l, --loglevel LOGLEVEL
                        verbosity: "debug", "info", or "quiet"
  --version             show version information and exit
  -h, --help            show this help message and exit

To run the test suite, switch to the test directory and execute runtests.jl.

If you are on Linux or MacOS, you can also use make:

> make run       # run a simulation with default values
> make test      # run the test suite
> make profile   # run and profile a default simulation
> make docs      # build the documentation
> make release   # create a release

Running from within Julia

To use the model from within Julia (either inside an interactive REPL or if you want to import it from your own software), do the following:

using Pkg
Pkg.activate(".") # assuming you're in the Persefone root folder
using Persefone

You can then access all Persefone functions, such as simulate() (which runs a complete simulation, as when calling julia run.jl from the commandline). See src/Persefone.jl or the documentation for a list of exported functions.

© 2022-2025 the contributors (MIT license)