# Persefone.jl

![Persefone.jl splash screen](docs/persefonejl_logo_v3_splash.png)

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

[Persefone.jl](https://persefone-model.eu/) 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](https://persefone-model.eu/documentation), or read the manual in the `docs` folder.
To use Persefone.jl with a graphical user interface, see [here](https://git.idiv.de/persefone/persefone-desktop).*

### Installation

Install the latest version of the [Julia](https://julialang.org/downloads/) programming 
language (1.10+). The recommended editors are [VSCode](https://www.julia-vscode.org/) or
[Emacs](https://www.emacswiki.org/emacs/JuliaProgrammingLanguage). 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:

```julia
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:

```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()`](https://persefone-model.eu/documentation/simulation.html#Persefone.simulate) 
(which runs a complete simulation, as when calling `julia run.jl` from the commandline). 
See [`src/Persefone.jl`](https://git.idiv.de/persefone/persefone-model/-/blob/master/src/Persefone.jl?ref_type=heads) 
or the [documentation](https://persefone-model.eu/documentation/simulation.html) for a 
list of exported functions.

---

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