# Persefone.jl

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

[Persefone.jl](https://git.idiv.de/persefone/persefone-model) 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 policy changes in the CAP) 
influence biodiversity.

The model is based on the [Agents.jl](https://juliadynamics.github.io/Agents.jl/stable/) 
framework. It is currently in the early stages of development.

## Usage

*For the full documentation, open `docs/documentation.html` in a browser, or visit
[https://persefone-model.eu/documentation](https://persefone-model.eu/documentation).*

### Installation

Install the latest version of the [Julia](https://julialang.org/downloads/) programming 
language (1.9+). The recommended editors are [VSCode](https://www.julia-vscode.org/) or
[Emacs](https://www.emacswiki.org/emacs/JuliaProgrammingLanguage).
To install package dependencies, open a Julia REPL in this folder and run 
`using Pkg; Pkg.activate("."); Pkg.instantiate()`.

### Running from the commandline

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:

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

You can then access all Persefone functions, such as `simulate()`. (See
`src/Persefone.jl` for a list of exported functions.)

---

&copy; 2022-2023 the contributors (MIT license)