From 57264494452da78432cb0fefa16932e606c6eef6 Mon Sep 17 00:00:00 2001
From: Daniel Vedder <daniel.vedder@idiv.de>
Date: Thu, 27 Jul 2023 10:15:07 +0200
Subject: [PATCH] Updated documentation
---
docs/build/adapting.html | 2 +-
docs/build/architecture.html | 2 +-
docs/build/assets/deb.png | Bin 0 -> 84309 bytes
docs/build/crops.html | 2 +-
docs/build/developing.html | 2 +-
docs/build/energy.html | 2 ++
docs/build/farm.html | 2 +-
docs/build/gis.html | 26 ++++++++++++--
docs/build/index.html | 4 +--
docs/build/io.html | 2 +-
docs/build/nature.html | 4 +--
docs/build/odd.html | 2 +-
docs/build/search.html | 2 +-
docs/build/search_index.js | 2 +-
docs/build/simulation.html | 2 +-
docs/build/species-dsl.html | 4 +--
docs/build/species.html | 2 +-
docs/src/assets/deb.png | Bin 0 -> 84309 bytes
docs/src/energy.md | 22 ++++++++++++
docs/src/gis.md | 63 ++++++++++++++++++++++++++++++++--
docs/src/index.md | 2 +-
src/nature/species/skylark.jl | 46 +++++++++++++++++--------
test/nature_tests.jl | 18 ++++++++++
23 files changed, 176 insertions(+), 37 deletions(-)
create mode 100644 docs/build/assets/deb.png
create mode 100644 docs/build/energy.html
create mode 100644 docs/src/assets/deb.png
create mode 100644 docs/src/energy.md
diff --git a/docs/build/adapting.html b/docs/build/adapting.html
index d0b6aef..3072e18 100644
--- a/docs/build/adapting.html
+++ b/docs/build/adapting.html
@@ -1,2 +1,2 @@
<!DOCTYPE html>
-<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Adapting Persefone · Persefone</title><script data-outdated-warner src="assets/warner.js"></script><link href="https://cdnjs.cloudflare.com/ajax/libs/lato-font/3.0.0/css/lato-font.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/juliamono/0.045/juliamono.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.13.24/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL="."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="assets/documenter.js"></script><script src="siteinfo.js"></script><script src="../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-dark.css" data-theme-name="documenter-dark" data-theme-primary-dark/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="assets/themeswap.js"></script></head><body><div id="documenter"><nav class="docs-sidebar"><a class="docs-logo" href="index.html"><img src="assets/logo.png" alt="Persefone logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="index.html">Persefone</a></span></div><form class="docs-search" action="search.html"><input class="docs-search-query" id="documenter-search-query" name="q" type="text" placeholder="Search docs"/></form><ul class="docs-menu"><li><a class="tocitem" href="index.html">Introduction</a></li><li><a class="tocitem" href="odd.html">Overview, Design, Details (ODD)</a></li><li><span class="tocitem">Developing</span><ul><li><a class="tocitem" href="developing.html">Developing Persefone</a></li><li class="is-active"><a class="tocitem" href="adapting.html">Adapting Persefone</a></li><li><a class="tocitem" href="architecture.html">Source code architecture</a></li><li><a class="tocitem" href="gis.html">GIS data</a></li><li><a class="tocitem" href="species-dsl.html">Defining new species</a></li></ul></li><li><span class="tocitem">Core</span><ul><li><a class="tocitem" href="simulation.html">Simulation</a></li><li><a class="tocitem" href="io.html">Input, Output, and Settings</a></li></ul></li><li><span class="tocitem">Nature</span><ul><li><a class="tocitem" href="nature.html">Nature</a></li><li><a class="tocitem" href="energy.html">Dynamic Energy Budgets</a></li><li><a class="tocitem" href="species.html">Species</a></li></ul></li><li><a class="tocitem" href="crops.html">Crop submodel</a></li><li><a class="tocitem" href="farm.html">Farm submodel</a></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><nav class="breadcrumb"><ul class="is-hidden-mobile"><li><a class="is-disabled">Developing</a></li><li class="is-active"><a href="adapting.html">Adapting Persefone</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href="adapting.html">Adapting Persefone</a></li></ul></nav><div class="docs-right"><a class="docs-edit-link" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//docs/src/adapting.md#" title="Edit source"><span class="docs-icon fa"></span><span class="docs-label is-hidden-touch">Edit source</span></a><a class="docs-settings-button fas fa-cog" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-sidebar-button fa fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a></div></header><article class="content" id="documenter-page"><h1 id="Adapting-Persefone"><a class="docs-heading-anchor" href="#Adapting-Persefone">Adapting Persefone</a><a id="Adapting-Persefone-1"></a><a class="docs-heading-anchor-permalink" href="#Adapting-Persefone" title="Permalink"></a></h1><p>A key development goal of Persefone is to be <a href="https://doi.org/10.1515/itit-2019-0040">FAIR</a>: <em>findable, accessible, interoperable, and reusable</em>. We aim to build a model that is both easy to use and easy to adapt to new situations.</p><p>There are multiple ways to adapt Persefone for a new modelling study:</p><h3 id="Changing-the-parameters"><a class="docs-heading-anchor" href="#Changing-the-parameters">Changing the parameters</a><a id="Changing-the-parameters-1"></a><a class="docs-heading-anchor-permalink" href="#Changing-the-parameters" title="Permalink"></a></h3><p>The simplest way to adapt Persefone is simply by changing the parameters. Copy <code>src/parameters.toml</code> to a new location, adjust it to your needs, and run the model using <code>julia run.jl -c <configfile></code>.</p><h3 id="Changing-the-region"><a class="docs-heading-anchor" href="#Changing-the-region">Changing the region</a><a id="Changing-the-region-1"></a><a class="docs-heading-anchor-permalink" href="#Changing-the-region" title="Permalink"></a></h3><p>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 <a href="gis.html">here</a>.</p><p><em>You may also need to change aspects of the <code>farm</code> submodel. This is not yet implemented.</em></p><h3 id="Adding-new-animal-species"><a class="docs-heading-anchor" href="#Adding-new-animal-species">Adding new animal species</a><a id="Adding-new-animal-species-1"></a><a class="docs-heading-anchor-permalink" href="#Adding-new-animal-species" title="Permalink"></a></h3><p>To implement a new species to the <code>nature</code> submodel, add a new file to the <code>src/nature/species</code> directory and <code>include</code> it in <code>src/Persefone.jl</code>, as well as adding the name of the species to the <code>nature.targetspecies</code> parameter. In the new file, implement the species using the <a href="nature.html#Persefone.@species-Tuple{Any, Any}"><code>@species</code></a> syntax as described <a href="species-dsl.html">here</a>.</p><h3 id="Adding-new-crop-species"><a class="docs-heading-anchor" href="#Adding-new-crop-species">Adding new crop species</a><a id="Adding-new-crop-species-1"></a><a class="docs-heading-anchor-permalink" href="#Adding-new-crop-species" title="Permalink"></a></h3><p><em>Crop growth is not yet implemented.</em></p><h3 id="Adding-new-farmer-behaviour"><a class="docs-heading-anchor" href="#Adding-new-farmer-behaviour">Adding new farmer behaviour</a><a id="Adding-new-farmer-behaviour-1"></a><a class="docs-heading-anchor-permalink" href="#Adding-new-farmer-behaviour" title="Permalink"></a></h3><p><em>Farmer behaviour is not yet implemented.</em></p><h3 id="Adding-a-new-submodel"><a class="docs-heading-anchor" href="#Adding-a-new-submodel">Adding a new submodel</a><a id="Adding-a-new-submodel-1"></a><a class="docs-heading-anchor-permalink" href="#Adding-a-new-submodel" title="Permalink"></a></h3><p>To add a new submodel in addition to the existing ones (<code>nature</code>, <code>crop</code>, and <code>farm</code>), you need to familiarise yourself with the <a href="architecture.html">software architecture</a>. In particular, you need to understand how initialisation and scheduling works in <a href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master/src/core/simulation.jl"><code>src/core/simulation.jl</code></a>, and what information is stored in the <code>model</code> object.</p><p>If you want to add a new agent type, use Agents.jl's <a href="https://juliadynamics.github.io/Agents.jl/stable/tutorial/#Agents.@agent"><code>@agent</code></a> macro. (But be aware that Persefone already has three agent types and you may encounter <a href="https://juliadynamics.github.io/Agents.jl/stable/performance_tips/#Avoid-Unions-of-many-different-agent-types-(temporary!)-1">performance problems</a>.) Having implemented the new agent type, add it to the <code>model</code> objects type definition and scheduler, and write an initialisation function and a <code>stepagent!</code> function. (See <a href="@ref"><code>initmodel</code></a> and <a href="simulation.html#Persefone.stepsimulation!-Tuple{Agents.AgentBasedModel}"><code>stepsimulation!</code></a> for details.)</p><h3 id="Linking-to-another-model"><a class="docs-heading-anchor" href="#Linking-to-another-model">Linking to another model</a><a id="Linking-to-another-model-1"></a><a class="docs-heading-anchor-permalink" href="#Linking-to-another-model" title="Permalink"></a></h3><p>Persefone can also be used as a software library and be called from another application. For this purpose, it is set up as a <a href="https://pkgdocs.julialang.org/v1/">Julia package</a>, with a <a href="https://docs.julialang.org/en/v1/manual/modules/">module</a> exporting various model functions, types, and macros (see <a href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master/src/Persephone.jl"><code>src/Persefone.jl</code></a>). Of particular interest are the functions <a href="simulation.html#Persefone.simulate"><code>simulate</code></a> (set up and run a complete simulation based on a config file), <a href="simulation.html#Persefone.initialise"><code>initialise</code></a> (create one or more <code>model</code> objects from a config file), <a href="simulation.html#Persefone.simulate!-Tuple{Agents.AgentBasedModel}"><code>simulate!</code></a> (do a simulation run with an existing <code>model</code> object), and <a href="simulation.html#Persefone.stepsimulation!-Tuple{Agents.AgentBasedModel}"><code>stepsimulation!</code></a> (update a <code>model</code> object by one time step).</p><p>To interface with Julia from another language, see the Julia docs <a href="https://docs.julialang.org/en/v1/manual/calling-c-and-fortran-code/">here</a> and <a href="https://docs.julialang.org/en/v1/manual/embedding/">here</a>.</p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="developing.html">« Developing Persefone</a><a class="docs-footer-nextpage" href="architecture.html">Source code architecture »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.23 on <span class="colophon-date" title="Thursday 20 July 2023 16:01">Thursday 20 July 2023</span>. Using Julia version 1.9.1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
+<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Adapting Persefone · Persefone</title><script data-outdated-warner src="assets/warner.js"></script><link href="https://cdnjs.cloudflare.com/ajax/libs/lato-font/3.0.0/css/lato-font.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/juliamono/0.045/juliamono.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.13.24/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL="."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="assets/documenter.js"></script><script src="siteinfo.js"></script><script src="../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-dark.css" data-theme-name="documenter-dark" data-theme-primary-dark/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="assets/themeswap.js"></script></head><body><div id="documenter"><nav class="docs-sidebar"><a class="docs-logo" href="index.html"><img src="assets/logo.png" alt="Persefone logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="index.html">Persefone</a></span></div><form class="docs-search" action="search.html"><input class="docs-search-query" id="documenter-search-query" name="q" type="text" placeholder="Search docs"/></form><ul class="docs-menu"><li><a class="tocitem" href="index.html">Introduction</a></li><li><a class="tocitem" href="odd.html">Overview, Design, Details (ODD)</a></li><li><span class="tocitem">Developing</span><ul><li><a class="tocitem" href="developing.html">Developing Persefone</a></li><li class="is-active"><a class="tocitem" href="adapting.html">Adapting Persefone</a></li><li><a class="tocitem" href="architecture.html">Source code architecture</a></li><li><a class="tocitem" href="gis.html">Maps and weather data</a></li><li><a class="tocitem" href="species-dsl.html">Defining new species</a></li></ul></li><li><span class="tocitem">Core</span><ul><li><a class="tocitem" href="simulation.html">Simulation</a></li><li><a class="tocitem" href="io.html">Input, Output, and Settings</a></li></ul></li><li><span class="tocitem">Nature</span><ul><li><a class="tocitem" href="nature.html">Nature</a></li><li><a class="tocitem" href="energy.html">Dynamic Energy Budgets</a></li><li><a class="tocitem" href="species.html">Species</a></li></ul></li><li><a class="tocitem" href="crops.html">Crop submodel</a></li><li><a class="tocitem" href="farm.html">Farm submodel</a></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><nav class="breadcrumb"><ul class="is-hidden-mobile"><li><a class="is-disabled">Developing</a></li><li class="is-active"><a href="adapting.html">Adapting Persefone</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href="adapting.html">Adapting Persefone</a></li></ul></nav><div class="docs-right"><a class="docs-edit-link" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//docs/src/adapting.md#" title="Edit source"><span class="docs-icon fa"></span><span class="docs-label is-hidden-touch">Edit source</span></a><a class="docs-settings-button fas fa-cog" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-sidebar-button fa fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a></div></header><article class="content" id="documenter-page"><h1 id="Adapting-Persefone"><a class="docs-heading-anchor" href="#Adapting-Persefone">Adapting Persefone</a><a id="Adapting-Persefone-1"></a><a class="docs-heading-anchor-permalink" href="#Adapting-Persefone" title="Permalink"></a></h1><p>A key development goal of Persefone is to be <a href="https://doi.org/10.1515/itit-2019-0040">FAIR</a>: <em>findable, accessible, interoperable, and reusable</em>. We aim to build a model that is both easy to use and easy to adapt to new situations.</p><p>There are multiple ways to adapt Persefone for a new modelling study:</p><h3 id="Changing-the-parameters"><a class="docs-heading-anchor" href="#Changing-the-parameters">Changing the parameters</a><a id="Changing-the-parameters-1"></a><a class="docs-heading-anchor-permalink" href="#Changing-the-parameters" title="Permalink"></a></h3><p>The simplest way to adapt Persefone is simply by changing the parameters. Copy <code>src/parameters.toml</code> to a new location, adjust it to your needs, and run the model using <code>julia run.jl -c <configfile></code>.</p><h3 id="Changing-the-region"><a class="docs-heading-anchor" href="#Changing-the-region">Changing the region</a><a id="Changing-the-region-1"></a><a class="docs-heading-anchor-permalink" href="#Changing-the-region" title="Permalink"></a></h3><p>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 <a href="gis.html">here</a>.</p><p><em>You may also need to change aspects of the <code>farm</code> submodel. This is not yet implemented.</em></p><h3 id="Adding-new-animal-species"><a class="docs-heading-anchor" href="#Adding-new-animal-species">Adding new animal species</a><a id="Adding-new-animal-species-1"></a><a class="docs-heading-anchor-permalink" href="#Adding-new-animal-species" title="Permalink"></a></h3><p>To implement a new species to the <code>nature</code> submodel, add a new file to the <code>src/nature/species</code> directory and <code>include</code> it in <code>src/Persefone.jl</code>, as well as adding the name of the species to the <code>nature.targetspecies</code> parameter. In the new file, implement the species using the <a href="nature.html#Persefone.@species-Tuple{Any, Any}"><code>@species</code></a> syntax as described <a href="species-dsl.html">here</a>.</p><h3 id="Adding-new-crop-species"><a class="docs-heading-anchor" href="#Adding-new-crop-species">Adding new crop species</a><a id="Adding-new-crop-species-1"></a><a class="docs-heading-anchor-permalink" href="#Adding-new-crop-species" title="Permalink"></a></h3><p><em>Crop growth is not yet implemented.</em></p><h3 id="Adding-new-farmer-behaviour"><a class="docs-heading-anchor" href="#Adding-new-farmer-behaviour">Adding new farmer behaviour</a><a id="Adding-new-farmer-behaviour-1"></a><a class="docs-heading-anchor-permalink" href="#Adding-new-farmer-behaviour" title="Permalink"></a></h3><p><em>Farmer behaviour is not yet implemented.</em></p><h3 id="Adding-a-new-submodel"><a class="docs-heading-anchor" href="#Adding-a-new-submodel">Adding a new submodel</a><a id="Adding-a-new-submodel-1"></a><a class="docs-heading-anchor-permalink" href="#Adding-a-new-submodel" title="Permalink"></a></h3><p>To add a new submodel in addition to the existing ones (<code>nature</code>, <code>crop</code>, and <code>farm</code>), you need to familiarise yourself with the <a href="architecture.html">software architecture</a>. In particular, you need to understand how initialisation and scheduling works in <a href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master/src/core/simulation.jl"><code>src/core/simulation.jl</code></a>, and what information is stored in the <code>model</code> object.</p><p>If you want to add a new agent type, use Agents.jl's <a href="https://juliadynamics.github.io/Agents.jl/stable/tutorial/#Agents.@agent"><code>@agent</code></a> macro. (But be aware that Persefone already has three agent types and you may encounter <a href="https://juliadynamics.github.io/Agents.jl/stable/performance_tips/#Avoid-Unions-of-many-different-agent-types-(temporary!)-1">performance problems</a>.) Having implemented the new agent type, add it to the <code>model</code> objects type definition and scheduler, and write an initialisation function and a <code>stepagent!</code> function. (See <a href="@ref"><code>initmodel</code></a> and <a href="simulation.html#Persefone.stepsimulation!-Tuple{Agents.AgentBasedModel}"><code>stepsimulation!</code></a> for details.)</p><h3 id="Linking-to-another-model"><a class="docs-heading-anchor" href="#Linking-to-another-model">Linking to another model</a><a id="Linking-to-another-model-1"></a><a class="docs-heading-anchor-permalink" href="#Linking-to-another-model" title="Permalink"></a></h3><p>Persefone can also be used as a software library and be called from another application. For this purpose, it is set up as a <a href="https://pkgdocs.julialang.org/v1/">Julia package</a>, with a <a href="https://docs.julialang.org/en/v1/manual/modules/">module</a> exporting various model functions, types, and macros (see <a href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master/src/Persephone.jl"><code>src/Persefone.jl</code></a>). Of particular interest are the functions <a href="simulation.html#Persefone.simulate"><code>simulate</code></a> (set up and run a complete simulation based on a config file), <a href="simulation.html#Persefone.initialise"><code>initialise</code></a> (create one or more <code>model</code> objects from a config file), <a href="simulation.html#Persefone.simulate!-Tuple{Agents.AgentBasedModel}"><code>simulate!</code></a> (do a simulation run with an existing <code>model</code> object), and <a href="simulation.html#Persefone.stepsimulation!-Tuple{Agents.AgentBasedModel}"><code>stepsimulation!</code></a> (update a <code>model</code> object by one time step).</p><p>To interface with Julia from another language, see the Julia docs <a href="https://docs.julialang.org/en/v1/manual/calling-c-and-fortran-code/">here</a> and <a href="https://docs.julialang.org/en/v1/manual/embedding/">here</a>.</p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="developing.html">« Developing Persefone</a><a class="docs-footer-nextpage" href="architecture.html">Source code architecture »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.23 on <span class="colophon-date" title="Thursday 27 July 2023 10:12">Thursday 27 July 2023</span>. Using Julia version 1.9.1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
diff --git a/docs/build/architecture.html b/docs/build/architecture.html
index 22c8524..8a26e2a 100644
--- a/docs/build/architecture.html
+++ b/docs/build/architecture.html
@@ -1,2 +1,2 @@
<!DOCTYPE html>
-<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Source code architecture · Persefone</title><script data-outdated-warner src="assets/warner.js"></script><link href="https://cdnjs.cloudflare.com/ajax/libs/lato-font/3.0.0/css/lato-font.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/juliamono/0.045/juliamono.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.13.24/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL="."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="assets/documenter.js"></script><script src="siteinfo.js"></script><script src="../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-dark.css" data-theme-name="documenter-dark" data-theme-primary-dark/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="assets/themeswap.js"></script></head><body><div id="documenter"><nav class="docs-sidebar"><a class="docs-logo" href="index.html"><img src="assets/logo.png" alt="Persefone logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="index.html">Persefone</a></span></div><form class="docs-search" action="search.html"><input class="docs-search-query" id="documenter-search-query" name="q" type="text" placeholder="Search docs"/></form><ul class="docs-menu"><li><a class="tocitem" href="index.html">Introduction</a></li><li><a class="tocitem" href="odd.html">Overview, Design, Details (ODD)</a></li><li><span class="tocitem">Developing</span><ul><li><a class="tocitem" href="developing.html">Developing Persefone</a></li><li><a class="tocitem" href="adapting.html">Adapting Persefone</a></li><li class="is-active"><a class="tocitem" href="architecture.html">Source code architecture</a><ul class="internal"><li class="toplevel"><a class="tocitem" href="#Model-components"><span>Model components</span></a></li><li class="toplevel"><a class="tocitem" href="#Important-implementation-details"><span>Important implementation details</span></a></li></ul></li><li><a class="tocitem" href="gis.html">GIS data</a></li><li><a class="tocitem" href="species-dsl.html">Defining new species</a></li></ul></li><li><span class="tocitem">Core</span><ul><li><a class="tocitem" href="simulation.html">Simulation</a></li><li><a class="tocitem" href="io.html">Input, Output, and Settings</a></li></ul></li><li><span class="tocitem">Nature</span><ul><li><a class="tocitem" href="nature.html">Nature</a></li><li><a class="tocitem" href="energy.html">Dynamic Energy Budgets</a></li><li><a class="tocitem" href="species.html">Species</a></li></ul></li><li><a class="tocitem" href="crops.html">Crop submodel</a></li><li><a class="tocitem" href="farm.html">Farm submodel</a></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><nav class="breadcrumb"><ul class="is-hidden-mobile"><li><a class="is-disabled">Developing</a></li><li class="is-active"><a href="architecture.html">Source code architecture</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href="architecture.html">Source code architecture</a></li></ul></nav><div class="docs-right"><a class="docs-edit-link" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//docs/src/architecture.md#" title="Edit source"><span class="docs-icon fa"></span><span class="docs-label is-hidden-touch">Edit source</span></a><a class="docs-settings-button fas fa-cog" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-sidebar-button fa fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a></div></header><article class="content" id="documenter-page"><h1 id="Source-code-architecture"><a class="docs-heading-anchor" href="#Source-code-architecture">Source code architecture</a><a id="Source-code-architecture-1"></a><a class="docs-heading-anchor-permalink" href="#Source-code-architecture" title="Permalink"></a></h1><h1 id="Model-components"><a class="docs-heading-anchor" href="#Model-components">Model components</a><a id="Model-components-1"></a><a class="docs-heading-anchor-permalink" href="#Model-components" title="Permalink"></a></h1><p><img src="assets/architecture.png" alt=""model architecture""/></p><p>Persefone is divided into four components, three of which are semi-independent submodels:</p><ol><li><p><code>core</code>: This is the foundation of the model software, which sets up and executes simulation runs. It also reads in the configuration file and landscape maps, and provides data output functionality. (Eventually, it will also provide weather data.)</p></li><li><p><code>nature</code>: This is an individual-based model of species in agricultural landscapes. It defines the <a href="nature.html#Persefone.Animal"><code>Animal</code></a> agent type, and a set of macros that can be used to rapidly create new species. It also includes ecological process functions that are useful for all species.</p></li><li><p><code>farm</code>: This is an agent-based model of farmer decision making. It is not yet implemented, but will provide the <a href="farm.html#Persefone.Farmer"><code>Farmer</code></a> agent type.</p></li><li><p><code>crop</code>: This is a mathematical growth model for various crops. It is not yet implemented, but already provides the agent type <a href="crops.html#Persefone.FarmPlot"><code>FarmPlot</code></a>, representing one field and its associated extent and crop type.</p></li></ol><p>Conceptually, <code>core</code> provides functionality that is needed by all of the submodels. Decisions made by <code>Farmer</code>s affect the <code>FarmPlot</code>s they own, and (directly or indirectly) the <code>Animal</code>s in the model landscape.</p><h1 id="Important-implementation-details"><a class="docs-heading-anchor" href="#Important-implementation-details">Important implementation details</a><a id="Important-implementation-details-1"></a><a class="docs-heading-anchor-permalink" href="#Important-implementation-details" title="Permalink"></a></h1><p><img src="assets/model_object.png" alt=""the model object""/></p><h3 id="The-model-object"><a class="docs-heading-anchor" href="#The-model-object">The <code>model</code> object</a><a id="The-model-object-1"></a><a class="docs-heading-anchor-permalink" href="#The-model-object" title="Permalink"></a></h3><p>A cursory reading of the source code will quickly show that most functions take an <code>AgentBasedModel</code> object as one of their arguments. This is the key data structure of <a href="https://juliadynamics.github.io/Agents.jl/stable/tutorial/#.-The-model-1">Agents.jl</a>, and holds all state that is in any way relevant to a simulation run. (Persefone has a strict "no global state" policy to avoid state-dependent bugs and allow parallelisation.) The model object gives access to all agent instances (via <code>model[id]</code>, where <code>id</code> is the unique identifier of this agent). It also stores the configuration (<code>model.settings</code>), the landscape (<code>model.landscape</code>, a matrix of <a href="@ref"><code>Pixel</code></a> objects that store the local land cover, amongst other things), and the current simulation date (<code>model.date</code>). (See <a href="@ref"><code>initmodel</code></a> for details.)</p><p>For more information about working with agent objects, see the <a href="https://juliadynamics.github.io/Agents.jl/stable/api/">Agents.jl API</a>.</p><h3 id="Model-configuration/the-@param-macro"><a class="docs-heading-anchor" href="#Model-configuration/the-@param-macro">Model configuration/the <code>@param</code> macro</a><a id="Model-configuration/the-@param-macro-1"></a><a class="docs-heading-anchor-permalink" href="#Model-configuration/the-@param-macro" title="Permalink"></a></h3><p>The model is configured via a <a href="https://toml.io/en/">TOML</a> file, the default version of which is at <a href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master/src/parameters.toml"><code>src/parameters.toml</code></a>. An individual run can be configured using a user-defined configuration file, commandline arguments, or function calls (when Persefone is used as a package rather than an application). During a model run, the <a href="io.html#Persefone.@param-Tuple{Any}"><code>@param</code></a> macro can be used to access parameter values. Note that parameter names are prepended with the name of the component they are associated with. For example, the <code>outdir</code> parameter belongs to the <code>[core]</code> section of the TOML file, and must therefore be referenced as <code>@param(core.outdir)</code>. (See <a href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master/src/core/input.jl"><code>src/core/input.jl</code></a> for details.)</p><div class="admonition is-info"><header class="admonition-header">@param and other macros</header><div class="admonition-body"><p>As <code>@param(parameter)</code> expands to <code>model.settings["parameter"]</code>, it can obviously only be used in a context where the <code>model</code> object is actually available. (This is the case for most functions in Persefone, but not for all.) Similarly, many of the <code>nature</code> macros depend on specific variables being available where they are called, and can therefore only be used in specific contexts (this is indicated in their documentation).</p></div></div><h3 id="Output-data"><a class="docs-heading-anchor" href="#Output-data">Output data</a><a id="Output-data-1"></a><a class="docs-heading-anchor-permalink" href="#Output-data" title="Permalink"></a></h3><p>Persefone can output model data into text files with a specified frequency (daily, monthly, yearly, or at the simulation end). Submodels can use <a href="@ref"><code>newdataoutput!</code></a> to plug into this system. For an example of how to use this, see <a href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master/src/nature/ecologicaldata.jl"><code>src/nature/ecologicaldata.jl</code></a>. (See <a href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master/src/core/output.jl"><code>src/core/output.jl</code></a> for details.)</p><h3 id="Farm-events"><a class="docs-heading-anchor" href="#Farm-events">Farm events</a><a id="Farm-events-1"></a><a class="docs-heading-anchor-permalink" href="#Farm-events" title="Permalink"></a></h3><p>The <a href="@ref"><code>FarmEvent</code></a> struct is used to communicate farming-related events between submodels. An event can be triggered with <a href="@ref"><code>createevent!</code></a> and affects all pixels within a <a href="crops.html#Persefone.FarmPlot"><code>FarmPlot</code></a>. (See <a href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master/src/core/landscape.jl"><code>src/core/landscape.jl</code></a> for details.)</p><h3 id="Random-numbers-and-logging"><a class="docs-heading-anchor" href="#Random-numbers-and-logging">Random numbers and logging</a><a id="Random-numbers-and-logging-1"></a><a class="docs-heading-anchor-permalink" href="#Random-numbers-and-logging" title="Permalink"></a></h3><p>By default in Julia, the <a href="https://docs.julialang.org/en/v1/stdlib/Random/">random number generator</a> (RNG) and the <a href="https://docs.julialang.org/en/v1/stdlib/Logging/#Logging.global_logger">system logger</a> are two globally accessible variables. As Persefone needs to avoid all global data (since this would interfere with reproducibility in parallel runs), the <code>model</code> object stores a local logger and a local RNG. The local logger generally does not change the way the model uses <a href="https://docs.julialang.org/en/v1/stdlib/Logging/">log statements</a>, it is only relevant for some functions in <a href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master/src/core/simulation.jl"><code>src/core/simulation.jl</code></a>.</p><div class="admonition is-info"><header class="admonition-header">Using the model RNG</header><div class="admonition-body"><p>Whenever you need to use a <a href="https://docs.julialang.org/en/v1/stdlib/Random/#Base.rand">random number</a>, you must use the <code>model.rng</code>. The easiest way to do this is with the <a href="io.html#Persefone.@rand-Tuple"><code>@rand</code></a> and <a href="io.html#Persefone.@shuffle!-Tuple{Any}"><code>@shuffle!</code></a> macros. (Note that these, too, require access to the <code>model</code> object.)</p></div></div></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="adapting.html">« Adapting Persefone</a><a class="docs-footer-nextpage" href="gis.html">GIS data »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.23 on <span class="colophon-date" title="Thursday 20 July 2023 16:01">Thursday 20 July 2023</span>. Using Julia version 1.9.1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
+<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Source code architecture · Persefone</title><script data-outdated-warner src="assets/warner.js"></script><link href="https://cdnjs.cloudflare.com/ajax/libs/lato-font/3.0.0/css/lato-font.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/juliamono/0.045/juliamono.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.13.24/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL="."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="assets/documenter.js"></script><script src="siteinfo.js"></script><script src="../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-dark.css" data-theme-name="documenter-dark" data-theme-primary-dark/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="assets/themeswap.js"></script></head><body><div id="documenter"><nav class="docs-sidebar"><a class="docs-logo" href="index.html"><img src="assets/logo.png" alt="Persefone logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="index.html">Persefone</a></span></div><form class="docs-search" action="search.html"><input class="docs-search-query" id="documenter-search-query" name="q" type="text" placeholder="Search docs"/></form><ul class="docs-menu"><li><a class="tocitem" href="index.html">Introduction</a></li><li><a class="tocitem" href="odd.html">Overview, Design, Details (ODD)</a></li><li><span class="tocitem">Developing</span><ul><li><a class="tocitem" href="developing.html">Developing Persefone</a></li><li><a class="tocitem" href="adapting.html">Adapting Persefone</a></li><li class="is-active"><a class="tocitem" href="architecture.html">Source code architecture</a><ul class="internal"><li class="toplevel"><a class="tocitem" href="#Model-components"><span>Model components</span></a></li><li class="toplevel"><a class="tocitem" href="#Important-implementation-details"><span>Important implementation details</span></a></li></ul></li><li><a class="tocitem" href="gis.html">Maps and weather data</a></li><li><a class="tocitem" href="species-dsl.html">Defining new species</a></li></ul></li><li><span class="tocitem">Core</span><ul><li><a class="tocitem" href="simulation.html">Simulation</a></li><li><a class="tocitem" href="io.html">Input, Output, and Settings</a></li></ul></li><li><span class="tocitem">Nature</span><ul><li><a class="tocitem" href="nature.html">Nature</a></li><li><a class="tocitem" href="energy.html">Dynamic Energy Budgets</a></li><li><a class="tocitem" href="species.html">Species</a></li></ul></li><li><a class="tocitem" href="crops.html">Crop submodel</a></li><li><a class="tocitem" href="farm.html">Farm submodel</a></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><nav class="breadcrumb"><ul class="is-hidden-mobile"><li><a class="is-disabled">Developing</a></li><li class="is-active"><a href="architecture.html">Source code architecture</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href="architecture.html">Source code architecture</a></li></ul></nav><div class="docs-right"><a class="docs-edit-link" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//docs/src/architecture.md#" title="Edit source"><span class="docs-icon fa"></span><span class="docs-label is-hidden-touch">Edit source</span></a><a class="docs-settings-button fas fa-cog" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-sidebar-button fa fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a></div></header><article class="content" id="documenter-page"><h1 id="Source-code-architecture"><a class="docs-heading-anchor" href="#Source-code-architecture">Source code architecture</a><a id="Source-code-architecture-1"></a><a class="docs-heading-anchor-permalink" href="#Source-code-architecture" title="Permalink"></a></h1><h1 id="Model-components"><a class="docs-heading-anchor" href="#Model-components">Model components</a><a id="Model-components-1"></a><a class="docs-heading-anchor-permalink" href="#Model-components" title="Permalink"></a></h1><p><img src="assets/architecture.png" alt=""model architecture""/></p><p>Persefone is divided into four components, three of which are semi-independent submodels:</p><ol><li><p><code>core</code>: This is the foundation of the model software, which sets up and executes simulation runs. It also reads in the configuration file and landscape maps, and provides data output functionality. (Eventually, it will also provide weather data.)</p></li><li><p><code>nature</code>: This is an individual-based model of species in agricultural landscapes. It defines the <a href="nature.html#Persefone.Animal"><code>Animal</code></a> agent type, and a set of macros that can be used to rapidly create new species. It also includes ecological process functions that are useful for all species.</p></li><li><p><code>farm</code>: This is an agent-based model of farmer decision making. It is not yet implemented, but will provide the <a href="farm.html#Persefone.Farmer"><code>Farmer</code></a> agent type.</p></li><li><p><code>crop</code>: This is a mathematical growth model for various crops. It is not yet implemented, but already provides the agent type <a href="crops.html#Persefone.FarmPlot"><code>FarmPlot</code></a>, representing one field and its associated extent and crop type.</p></li></ol><p>Conceptually, <code>core</code> provides functionality that is needed by all of the submodels. Decisions made by <code>Farmer</code>s affect the <code>FarmPlot</code>s they own, and (directly or indirectly) the <code>Animal</code>s in the model landscape.</p><h1 id="Important-implementation-details"><a class="docs-heading-anchor" href="#Important-implementation-details">Important implementation details</a><a id="Important-implementation-details-1"></a><a class="docs-heading-anchor-permalink" href="#Important-implementation-details" title="Permalink"></a></h1><p><img src="assets/model_object.png" alt=""the model object""/></p><h3 id="The-model-object"><a class="docs-heading-anchor" href="#The-model-object">The <code>model</code> object</a><a id="The-model-object-1"></a><a class="docs-heading-anchor-permalink" href="#The-model-object" title="Permalink"></a></h3><p>A cursory reading of the source code will quickly show that most functions take an <code>AgentBasedModel</code> object as one of their arguments. This is the key data structure of <a href="https://juliadynamics.github.io/Agents.jl/stable/tutorial/#.-The-model-1">Agents.jl</a>, and holds all state that is in any way relevant to a simulation run. (Persefone has a strict "no global state" policy to avoid state-dependent bugs and allow parallelisation.) The model object gives access to all agent instances (via <code>model[id]</code>, where <code>id</code> is the unique identifier of this agent). It also stores the configuration (<code>model.settings</code>), the landscape (<code>model.landscape</code>, a matrix of <a href="@ref"><code>Pixel</code></a> objects that store the local land cover, amongst other things), and the current simulation date (<code>model.date</code>). (See <a href="@ref"><code>initmodel</code></a> for details.)</p><p>For more information about working with agent objects, see the <a href="https://juliadynamics.github.io/Agents.jl/stable/api/">Agents.jl API</a>.</p><h3 id="Model-configuration/the-@param-macro"><a class="docs-heading-anchor" href="#Model-configuration/the-@param-macro">Model configuration/the <code>@param</code> macro</a><a id="Model-configuration/the-@param-macro-1"></a><a class="docs-heading-anchor-permalink" href="#Model-configuration/the-@param-macro" title="Permalink"></a></h3><p>The model is configured via a <a href="https://toml.io/en/">TOML</a> file, the default version of which is at <a href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master/src/parameters.toml"><code>src/parameters.toml</code></a>. An individual run can be configured using a user-defined configuration file, commandline arguments, or function calls (when Persefone is used as a package rather than an application). During a model run, the <a href="io.html#Persefone.@param-Tuple{Any}"><code>@param</code></a> macro can be used to access parameter values. Note that parameter names are prepended with the name of the component they are associated with. For example, the <code>outdir</code> parameter belongs to the <code>[core]</code> section of the TOML file, and must therefore be referenced as <code>@param(core.outdir)</code>. (See <a href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master/src/core/input.jl"><code>src/core/input.jl</code></a> for details.)</p><div class="admonition is-info"><header class="admonition-header">@param and other macros</header><div class="admonition-body"><p>As <code>@param(parameter)</code> expands to <code>model.settings["parameter"]</code>, it can obviously only be used in a context where the <code>model</code> object is actually available. (This is the case for most functions in Persefone, but not for all.) Similarly, many of the <code>nature</code> macros depend on specific variables being available where they are called, and can therefore only be used in specific contexts (this is indicated in their documentation).</p></div></div><h3 id="Output-data"><a class="docs-heading-anchor" href="#Output-data">Output data</a><a id="Output-data-1"></a><a class="docs-heading-anchor-permalink" href="#Output-data" title="Permalink"></a></h3><p>Persefone can output model data into text files with a specified frequency (daily, monthly, yearly, or at the simulation end). Submodels can use <a href="@ref"><code>newdataoutput!</code></a> to plug into this system. For an example of how to use this, see <a href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master/src/nature/ecologicaldata.jl"><code>src/nature/ecologicaldata.jl</code></a>. (See <a href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master/src/core/output.jl"><code>src/core/output.jl</code></a> for details.)</p><h3 id="Farm-events"><a class="docs-heading-anchor" href="#Farm-events">Farm events</a><a id="Farm-events-1"></a><a class="docs-heading-anchor-permalink" href="#Farm-events" title="Permalink"></a></h3><p>The <a href="@ref"><code>FarmEvent</code></a> struct is used to communicate farming-related events between submodels. An event can be triggered with <a href="@ref"><code>createevent!</code></a> and affects all pixels within a <a href="crops.html#Persefone.FarmPlot"><code>FarmPlot</code></a>. (See <a href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master/src/core/landscape.jl"><code>src/core/landscape.jl</code></a> for details.)</p><h3 id="Random-numbers-and-logging"><a class="docs-heading-anchor" href="#Random-numbers-and-logging">Random numbers and logging</a><a id="Random-numbers-and-logging-1"></a><a class="docs-heading-anchor-permalink" href="#Random-numbers-and-logging" title="Permalink"></a></h3><p>By default in Julia, the <a href="https://docs.julialang.org/en/v1/stdlib/Random/">random number generator</a> (RNG) and the <a href="https://docs.julialang.org/en/v1/stdlib/Logging/#Logging.global_logger">system logger</a> are two globally accessible variables. As Persefone needs to avoid all global data (since this would interfere with reproducibility in parallel runs), the <code>model</code> object stores a local logger and a local RNG. The local logger generally does not change the way the model uses <a href="https://docs.julialang.org/en/v1/stdlib/Logging/">log statements</a>, it is only relevant for some functions in <a href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master/src/core/simulation.jl"><code>src/core/simulation.jl</code></a>.</p><div class="admonition is-info"><header class="admonition-header">Using the model RNG</header><div class="admonition-body"><p>Whenever you need to use a <a href="https://docs.julialang.org/en/v1/stdlib/Random/#Base.rand">random number</a>, you must use the <code>model.rng</code>. The easiest way to do this is with the <a href="io.html#Persefone.@rand-Tuple"><code>@rand</code></a> and <a href="io.html#Persefone.@shuffle!-Tuple{Any}"><code>@shuffle!</code></a> macros. (Note that these, too, require access to the <code>model</code> object.)</p></div></div></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="adapting.html">« Adapting Persefone</a><a class="docs-footer-nextpage" href="gis.html">Maps and weather data »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.23 on <span class="colophon-date" title="Thursday 27 July 2023 10:12">Thursday 27 July 2023</span>. Using Julia version 1.9.1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
diff --git a/docs/build/assets/deb.png b/docs/build/assets/deb.png
new file mode 100644
index 0000000000000000000000000000000000000000..23607ea7e0793e10791de31929673369fc880cf9
GIT binary patch
literal 84309
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
literal 0
HcmV?d00001
diff --git a/docs/build/crops.html b/docs/build/crops.html
index 7f96157..2a5466d 100644
--- a/docs/build/crops.html
+++ b/docs/build/crops.html
@@ -1,2 +1,2 @@
<!DOCTYPE html>
-<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Crop submodel · Persefone</title><script data-outdated-warner src="assets/warner.js"></script><link href="https://cdnjs.cloudflare.com/ajax/libs/lato-font/3.0.0/css/lato-font.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/juliamono/0.045/juliamono.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.13.24/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL="."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="assets/documenter.js"></script><script src="siteinfo.js"></script><script src="../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-dark.css" data-theme-name="documenter-dark" data-theme-primary-dark/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="assets/themeswap.js"></script></head><body><div id="documenter"><nav class="docs-sidebar"><a class="docs-logo" href="index.html"><img src="assets/logo.png" alt="Persefone logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="index.html">Persefone</a></span></div><form class="docs-search" action="search.html"><input class="docs-search-query" id="documenter-search-query" name="q" type="text" placeholder="Search docs"/></form><ul class="docs-menu"><li><a class="tocitem" href="index.html">Introduction</a></li><li><a class="tocitem" href="odd.html">Overview, Design, Details (ODD)</a></li><li><span class="tocitem">Developing</span><ul><li><a class="tocitem" href="developing.html">Developing Persefone</a></li><li><a class="tocitem" href="adapting.html">Adapting Persefone</a></li><li><a class="tocitem" href="architecture.html">Source code architecture</a></li><li><a class="tocitem" href="gis.html">GIS data</a></li><li><a class="tocitem" href="species-dsl.html">Defining new species</a></li></ul></li><li><span class="tocitem">Core</span><ul><li><a class="tocitem" href="simulation.html">Simulation</a></li><li><a class="tocitem" href="io.html">Input, Output, and Settings</a></li></ul></li><li><span class="tocitem">Nature</span><ul><li><a class="tocitem" href="nature.html">Nature</a></li><li><a class="tocitem" href="energy.html">Dynamic Energy Budgets</a></li><li><a class="tocitem" href="species.html">Species</a></li></ul></li><li class="is-active"><a class="tocitem" href="crops.html">Crop submodel</a><ul class="internal"><li><a class="tocitem" href="#crops.jl"><span>crops.jl</span></a></li></ul></li><li><a class="tocitem" href="farm.html">Farm submodel</a></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><nav class="breadcrumb"><ul class="is-hidden-mobile"><li class="is-active"><a href="crops.html">Crop submodel</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href="crops.html">Crop submodel</a></li></ul></nav><div class="docs-right"><a class="docs-edit-link" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//docs/src/crops.md#" title="Edit source"><span class="docs-icon fa"></span><span class="docs-label is-hidden-touch">Edit source</span></a><a class="docs-settings-button fas fa-cog" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-sidebar-button fa fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a></div></header><article class="content" id="documenter-page"><h1 id="Crop-submodel"><a class="docs-heading-anchor" href="#Crop-submodel">Crop submodel</a><a id="Crop-submodel-1"></a><a class="docs-heading-anchor-permalink" href="#Crop-submodel" title="Permalink"></a></h1><p>Eventually, Persefone will include a full-blown crop-growth model (an adaptation of AquaCrop, created by the FAO). At the moment, we are only working with a very basic mock-up.</p><h2 id="crops.jl"><a class="docs-heading-anchor" href="#crops.jl">crops.jl</a><a id="crops.jl-1"></a><a class="docs-heading-anchor-permalink" href="#crops.jl" title="Permalink"></a></h2><p>This includes the types and functions needed for all crop growth model, which are also referenced by the other submodels.</p><article class="docstring"><header><a class="docstring-binding" id="Persefone.CropType" href="#Persefone.CropType"><code>Persefone.CropType</code></a> — <span class="docstring-category">Type</span></header><section><div><p>The crop types simulated by the model</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/crop/crops.jl#L6">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.FarmPlot" href="#Persefone.FarmPlot"><code>Persefone.FarmPlot</code></a> — <span class="docstring-category">Type</span></header><section><div><pre><code class="language-julia hljs">FarmPlot</code></pre><p>This represents one field, i.e. a collection of pixels with the same management. This is the spatial unit with which the crop growth model and the farm model work.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/crop/crops.jl#L11-L16">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.averagefieldsize-Tuple{Agents.AgentBasedModel}" href="#Persefone.averagefieldsize-Tuple{Agents.AgentBasedModel}"><code>Persefone.averagefieldsize</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">averagefieldsize(model)</code></pre><p>Calculate the average field size in hectares for the model landscape.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/crop/crops.jl#L65-L69">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.cropheight-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel}" href="#Persefone.cropheight-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel}"><code>Persefone.cropheight</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">cropheight(model, position)</code></pre><p>Return the height of the crop at this position, or nothing if there is no crop here (utility wrapper).</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/crop/crops.jl#L90-L95">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.croptype-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel}" href="#Persefone.croptype-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel}"><code>Persefone.croptype</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">croptype(model, position)</code></pre><p>Return the crop at this position, or nothing if there is no crop here (utility wrapper).</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/crop/crops.jl#L80-L84">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.initfields!-Tuple{Agents.AgentBasedModel}" href="#Persefone.initfields!-Tuple{Agents.AgentBasedModel}"><code>Persefone.initfields!</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">initfields!(model)</code></pre><p>Initialise the model with its farm plots.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/crop/crops.jl#L34-L38">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.stepagent!-Tuple{FarmPlot, Agents.AgentBasedModel}" href="#Persefone.stepagent!-Tuple{FarmPlot, Agents.AgentBasedModel}"><code>Persefone.stepagent!</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">stepagent!(farmplot, model)</code></pre><p>Update a farm plot by one day.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/crop/crops.jl#L25-L29">source</a></section></article></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="species.html">« Species</a><a class="docs-footer-nextpage" href="farm.html">Farm submodel »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.23 on <span class="colophon-date" title="Thursday 20 July 2023 16:01">Thursday 20 July 2023</span>. Using Julia version 1.9.1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
+<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Crop submodel · Persefone</title><script data-outdated-warner src="assets/warner.js"></script><link href="https://cdnjs.cloudflare.com/ajax/libs/lato-font/3.0.0/css/lato-font.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/juliamono/0.045/juliamono.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.13.24/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL="."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="assets/documenter.js"></script><script src="siteinfo.js"></script><script src="../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-dark.css" data-theme-name="documenter-dark" data-theme-primary-dark/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="assets/themeswap.js"></script></head><body><div id="documenter"><nav class="docs-sidebar"><a class="docs-logo" href="index.html"><img src="assets/logo.png" alt="Persefone logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="index.html">Persefone</a></span></div><form class="docs-search" action="search.html"><input class="docs-search-query" id="documenter-search-query" name="q" type="text" placeholder="Search docs"/></form><ul class="docs-menu"><li><a class="tocitem" href="index.html">Introduction</a></li><li><a class="tocitem" href="odd.html">Overview, Design, Details (ODD)</a></li><li><span class="tocitem">Developing</span><ul><li><a class="tocitem" href="developing.html">Developing Persefone</a></li><li><a class="tocitem" href="adapting.html">Adapting Persefone</a></li><li><a class="tocitem" href="architecture.html">Source code architecture</a></li><li><a class="tocitem" href="gis.html">Maps and weather data</a></li><li><a class="tocitem" href="species-dsl.html">Defining new species</a></li></ul></li><li><span class="tocitem">Core</span><ul><li><a class="tocitem" href="simulation.html">Simulation</a></li><li><a class="tocitem" href="io.html">Input, Output, and Settings</a></li></ul></li><li><span class="tocitem">Nature</span><ul><li><a class="tocitem" href="nature.html">Nature</a></li><li><a class="tocitem" href="energy.html">Dynamic Energy Budgets</a></li><li><a class="tocitem" href="species.html">Species</a></li></ul></li><li class="is-active"><a class="tocitem" href="crops.html">Crop submodel</a><ul class="internal"><li><a class="tocitem" href="#crops.jl"><span>crops.jl</span></a></li></ul></li><li><a class="tocitem" href="farm.html">Farm submodel</a></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><nav class="breadcrumb"><ul class="is-hidden-mobile"><li class="is-active"><a href="crops.html">Crop submodel</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href="crops.html">Crop submodel</a></li></ul></nav><div class="docs-right"><a class="docs-edit-link" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//docs/src/crops.md#" title="Edit source"><span class="docs-icon fa"></span><span class="docs-label is-hidden-touch">Edit source</span></a><a class="docs-settings-button fas fa-cog" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-sidebar-button fa fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a></div></header><article class="content" id="documenter-page"><h1 id="Crop-submodel"><a class="docs-heading-anchor" href="#Crop-submodel">Crop submodel</a><a id="Crop-submodel-1"></a><a class="docs-heading-anchor-permalink" href="#Crop-submodel" title="Permalink"></a></h1><p>Eventually, Persefone will include a full-blown crop-growth model (an adaptation of AquaCrop, created by the FAO). At the moment, we are only working with a very basic mock-up.</p><h2 id="crops.jl"><a class="docs-heading-anchor" href="#crops.jl">crops.jl</a><a id="crops.jl-1"></a><a class="docs-heading-anchor-permalink" href="#crops.jl" title="Permalink"></a></h2><p>This includes the types and functions needed for all crop growth model, which are also referenced by the other submodels.</p><article class="docstring"><header><a class="docstring-binding" id="Persefone.CropType" href="#Persefone.CropType"><code>Persefone.CropType</code></a> — <span class="docstring-category">Type</span></header><section><div><p>The crop types simulated by the model</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/crop/crops.jl#L6">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.FarmPlot" href="#Persefone.FarmPlot"><code>Persefone.FarmPlot</code></a> — <span class="docstring-category">Type</span></header><section><div><pre><code class="language-julia hljs">FarmPlot</code></pre><p>This represents one field, i.e. a collection of pixels with the same management. This is the spatial unit with which the crop growth model and the farm model work.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/crop/crops.jl#L11-L16">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.averagefieldsize-Tuple{Agents.AgentBasedModel}" href="#Persefone.averagefieldsize-Tuple{Agents.AgentBasedModel}"><code>Persefone.averagefieldsize</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">averagefieldsize(model)</code></pre><p>Calculate the average field size in hectares for the model landscape.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/crop/crops.jl#L65-L69">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.cropheight-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel}" href="#Persefone.cropheight-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel}"><code>Persefone.cropheight</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">cropheight(model, position)</code></pre><p>Return the height of the crop at this position, or nothing if there is no crop here (utility wrapper).</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/crop/crops.jl#L90-L95">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.croptype-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel}" href="#Persefone.croptype-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel}"><code>Persefone.croptype</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">croptype(model, position)</code></pre><p>Return the crop at this position, or nothing if there is no crop here (utility wrapper).</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/crop/crops.jl#L80-L84">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.initfields!-Tuple{Agents.AgentBasedModel}" href="#Persefone.initfields!-Tuple{Agents.AgentBasedModel}"><code>Persefone.initfields!</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">initfields!(model)</code></pre><p>Initialise the model with its farm plots.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/crop/crops.jl#L34-L38">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.stepagent!-Tuple{FarmPlot, Agents.AgentBasedModel}" href="#Persefone.stepagent!-Tuple{FarmPlot, Agents.AgentBasedModel}"><code>Persefone.stepagent!</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">stepagent!(farmplot, model)</code></pre><p>Update a farm plot by one day.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/crop/crops.jl#L25-L29">source</a></section></article></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="species.html">« Species</a><a class="docs-footer-nextpage" href="farm.html">Farm submodel »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.23 on <span class="colophon-date" title="Thursday 27 July 2023 10:12">Thursday 27 July 2023</span>. Using Julia version 1.9.1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
diff --git a/docs/build/developing.html b/docs/build/developing.html
index 81544c3..aca8652 100644
--- a/docs/build/developing.html
+++ b/docs/build/developing.html
@@ -1,2 +1,2 @@
<!DOCTYPE html>
-<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Developing Persefone · Persefone</title><script data-outdated-warner src="assets/warner.js"></script><link href="https://cdnjs.cloudflare.com/ajax/libs/lato-font/3.0.0/css/lato-font.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/juliamono/0.045/juliamono.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.13.24/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL="."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="assets/documenter.js"></script><script src="siteinfo.js"></script><script src="../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-dark.css" data-theme-name="documenter-dark" data-theme-primary-dark/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="assets/themeswap.js"></script></head><body><div id="documenter"><nav class="docs-sidebar"><a class="docs-logo" href="index.html"><img src="assets/logo.png" alt="Persefone logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="index.html">Persefone</a></span></div><form class="docs-search" action="search.html"><input class="docs-search-query" id="documenter-search-query" name="q" type="text" placeholder="Search docs"/></form><ul class="docs-menu"><li><a class="tocitem" href="index.html">Introduction</a></li><li><a class="tocitem" href="odd.html">Overview, Design, Details (ODD)</a></li><li><span class="tocitem">Developing</span><ul><li class="is-active"><a class="tocitem" href="developing.html">Developing Persefone</a><ul class="internal"><li><a class="tocitem" href="#Workflow"><span>Workflow</span></a></li><li><a class="tocitem" href="#Libraries"><span>Libraries</span></a></li><li><a class="tocitem" href="#Julia-editors"><span>Julia editors</span></a></li></ul></li><li><a class="tocitem" href="adapting.html">Adapting Persefone</a></li><li><a class="tocitem" href="architecture.html">Source code architecture</a></li><li><a class="tocitem" href="gis.html">GIS data</a></li><li><a class="tocitem" href="species-dsl.html">Defining new species</a></li></ul></li><li><span class="tocitem">Core</span><ul><li><a class="tocitem" href="simulation.html">Simulation</a></li><li><a class="tocitem" href="io.html">Input, Output, and Settings</a></li></ul></li><li><span class="tocitem">Nature</span><ul><li><a class="tocitem" href="nature.html">Nature</a></li><li><a class="tocitem" href="energy.html">Dynamic Energy Budgets</a></li><li><a class="tocitem" href="species.html">Species</a></li></ul></li><li><a class="tocitem" href="crops.html">Crop submodel</a></li><li><a class="tocitem" href="farm.html">Farm submodel</a></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><nav class="breadcrumb"><ul class="is-hidden-mobile"><li><a class="is-disabled">Developing</a></li><li class="is-active"><a href="developing.html">Developing Persefone</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href="developing.html">Developing Persefone</a></li></ul></nav><div class="docs-right"><a class="docs-edit-link" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//docs/src/developing.md#" title="Edit source"><span class="docs-icon fa"></span><span class="docs-label is-hidden-touch">Edit source</span></a><a class="docs-settings-button fas fa-cog" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-sidebar-button fa fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a></div></header><article class="content" id="documenter-page"><h1 id="Developing-Persefone"><a class="docs-heading-anchor" href="#Developing-Persefone">Developing Persefone</a><a id="Developing-Persefone-1"></a><a class="docs-heading-anchor-permalink" href="#Developing-Persefone" title="Permalink"></a></h1><h2 id="Workflow"><a class="docs-heading-anchor" href="#Workflow">Workflow</a><a id="Workflow-1"></a><a class="docs-heading-anchor-permalink" href="#Workflow" title="Permalink"></a></h2><ol><li><p>Pull the current version from the master branch on Gitlab: <a href="https://git.idiv.de/xo30xoqa/persephone">https://git.idiv.de/xo30xoqa/persephone</a>.</p></li><li><p>If you are working on a new feature, create a new branch to avoid breaking the <code>master</code> branch. (The <code>master</code> branch on Github should always be in a runnable and error-free state.)</p></li><li><p>Implement your changes.</p></li><li><p>Run an example simulation and the test suite to make sure everything works without crashing (<code>make run</code> and <code>make test</code> on Linux, or execute <code>run.jl</code> and <code>test/runtests.jl</code> manually.)</p></li><li><p>Commit your work frequently, and try to keep each commit small. Don't forget to add relevant tests to the test suite.</p></li><li><p>Once your satisfied with your work, do another pull/merge from the <code>master</code> branch in case somebody else changed the branch in the meantime. Then merge your work into <code>master</code> and push to the Gitlab server.</p></li><li><p>Repeat :-)</p></li></ol><p>The Gitlab <a href="https://git.idiv.de/xo30xoqa/persephone/-/boards/373">issue tracker</a> can be used to create, discuss, and assign tasks, as well as to monitor progress towards milestones/releases. Once we have a first release, we will start using <a href="https://semver.org/">semantic versioning</a>.</p><h2 id="Libraries"><a class="docs-heading-anchor" href="#Libraries">Libraries</a><a id="Libraries-1"></a><a class="docs-heading-anchor-permalink" href="#Libraries" title="Permalink"></a></h2><h3 id="Agents.jl"><a class="docs-heading-anchor" href="#Agents.jl">Agents.jl</a><a id="Agents.jl-1"></a><a class="docs-heading-anchor-permalink" href="#Agents.jl" title="Permalink"></a></h3><p>Our model uses <a href="https://juliadynamics.github.io/Agents.jl/stable/">Agents.jl</a> as a framework. Their <a href="https://github.com/JuliaDynamics/Agents.jl">repository</a> can be used to inspect the source code or submit bug reports (the authors are quick to respond). Questions can be asked at the <a href="https://discourse.julialang.org/c/domain/models/21">Julia Discourse forum</a>.</p><p><em>Tutorial on collaborating on Julia packages: <a href="https://www.matecdev.com/posts/julia-package-collaboration.html">https://www.matecdev.com/posts/julia-package-collaboration.html</a>.</em></p><h3 id="Revise.jl"><a class="docs-heading-anchor" href="#Revise.jl">Revise.jl</a><a id="Revise.jl-1"></a><a class="docs-heading-anchor-permalink" href="#Revise.jl" title="Permalink"></a></h3><p><a href="https://timholy.github.io/Revise.jl/stable/"><code>Revise.jl</code></a> allows one to reload code without restarting the Julia interpreter. Get it with <code>Pkg.add("Revise")</code>, then add <code>using Revise</code> to <code>.julia/config/startup.jl</code> to have it automatically available.</p><h3 id="Test"><a class="docs-heading-anchor" href="#Test">Test</a><a id="Test-1"></a><a class="docs-heading-anchor-permalink" href="#Test" title="Permalink"></a></h3><p>Persefone uses the inbuilt Julia <a href="https://docs.julialang.org/en/v1/stdlib/Test/">testing framework</a>. All new functions should have appropriate tests written for them in the appropriate file in the <code>test</code> directory. (See <a href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master/test/runtests.jl"><code>test/runtests.jl</code></a> for details.) There are three ways to run the test suite: in the terminal, executing <code>make test</code> or <code>cd test; julia runtests.jl</code>; or in the Julia REPL, <code>Pkg.activate("."); Pkg.test()</code>.</p><h3 id="Documenter.jl"><a class="docs-heading-anchor" href="#Documenter.jl">Documenter.jl</a><a id="Documenter.jl-1"></a><a class="docs-heading-anchor-permalink" href="#Documenter.jl" title="Permalink"></a></h3><p>The HTML documentation is generated using <a href="https://documenter.juliadocs.org">Documenter.jl</a>. Therefore, all new functions should have docstrings attached. New files need to be integrated into the relevant documentation source files in <code>docs/src</code>, and if necessary into <a href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master/docs/builddocs.jl"><code>docs/builddocs.jl</code></a>. To build the documentation, run <code>make docs</code>, or <code>cd docs; julia builddocs.jl</code> (if using the latter, don't forget to update the date and commit in <code>docs/src/index.md</code>).</p><h2 id="Julia-editors"><a class="docs-heading-anchor" href="#Julia-editors">Julia editors</a><a id="Julia-editors-1"></a><a class="docs-heading-anchor-permalink" href="#Julia-editors" title="Permalink"></a></h2><h3 id="Emacs"><a class="docs-heading-anchor" href="#Emacs">Emacs</a><a id="Emacs-1"></a><a class="docs-heading-anchor-permalink" href="#Emacs" title="Permalink"></a></h3><p>There are a couple of addons that make working with Julia much nicer in Emacs:</p><ol><li><p><code>julia-mode</code> gives syntax highlighting. Install with <code>M-x package-install julia-mode</code>.</p></li><li><p><a href="https://github.com/gcv/julia-snail"><code>julia-snail</code></a> provides IDE-like features, especially a fully-functional REPL and the ability to evaluate code straight from inside a buffer. Note that the installation can be somewhat tricky. You first need to manually install all the dependencies of its dependency <a href="https://github.com/akermu/emacs-libvterm">vterm</a>, then install vterm itself with <code>M-x package-install vterm</code>, <em>before</em> you can do <code>M-x package-install julia-snail</code>. Then add it to your <code>init.el</code> with <code>(require 'julia-snail)</code> and <code>(add-hook 'julia-mode-hook #'julia-snail-mode)</code>.</p></li><li><p><a href="http://company-mode.github.io/"><code>company-mode</code></a> integrates with Snail to give code completion. Install with <code>M-x package-install company</code>, then add <code>(add-hook 'julia-mode-hook #'company-mode)</code> and <code>(global-set-key (kbd "C-<tab>") 'company-complete)</code> to your <code>init.el</code>.</p></li><li><p><a href="https://magit.vc/"><code>magit</code></a> is a great git interface for Emacs. Install with <code>M-x package-install magit</code> and add <code>(global-set-key (kbd "C-x g") 'magit-status)</code> to your <code>init.el</code>.</p></li></ol><h3 id="VSCode"><a class="docs-heading-anchor" href="#VSCode">VSCode</a><a id="VSCode-1"></a><a class="docs-heading-anchor-permalink" href="#VSCode" title="Permalink"></a></h3><p>See <a href="https://www.julia-vscode.org/">here</a>.</p><p><em>TODO: add more detail.</em></p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="odd.html">« Overview, Design, Details (ODD)</a><a class="docs-footer-nextpage" href="adapting.html">Adapting Persefone »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.23 on <span class="colophon-date" title="Thursday 20 July 2023 16:01">Thursday 20 July 2023</span>. Using Julia version 1.9.1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
+<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Developing Persefone · Persefone</title><script data-outdated-warner src="assets/warner.js"></script><link href="https://cdnjs.cloudflare.com/ajax/libs/lato-font/3.0.0/css/lato-font.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/juliamono/0.045/juliamono.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.13.24/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL="."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="assets/documenter.js"></script><script src="siteinfo.js"></script><script src="../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-dark.css" data-theme-name="documenter-dark" data-theme-primary-dark/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="assets/themeswap.js"></script></head><body><div id="documenter"><nav class="docs-sidebar"><a class="docs-logo" href="index.html"><img src="assets/logo.png" alt="Persefone logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="index.html">Persefone</a></span></div><form class="docs-search" action="search.html"><input class="docs-search-query" id="documenter-search-query" name="q" type="text" placeholder="Search docs"/></form><ul class="docs-menu"><li><a class="tocitem" href="index.html">Introduction</a></li><li><a class="tocitem" href="odd.html">Overview, Design, Details (ODD)</a></li><li><span class="tocitem">Developing</span><ul><li class="is-active"><a class="tocitem" href="developing.html">Developing Persefone</a><ul class="internal"><li><a class="tocitem" href="#Workflow"><span>Workflow</span></a></li><li><a class="tocitem" href="#Libraries"><span>Libraries</span></a></li><li><a class="tocitem" href="#Julia-editors"><span>Julia editors</span></a></li></ul></li><li><a class="tocitem" href="adapting.html">Adapting Persefone</a></li><li><a class="tocitem" href="architecture.html">Source code architecture</a></li><li><a class="tocitem" href="gis.html">Maps and weather data</a></li><li><a class="tocitem" href="species-dsl.html">Defining new species</a></li></ul></li><li><span class="tocitem">Core</span><ul><li><a class="tocitem" href="simulation.html">Simulation</a></li><li><a class="tocitem" href="io.html">Input, Output, and Settings</a></li></ul></li><li><span class="tocitem">Nature</span><ul><li><a class="tocitem" href="nature.html">Nature</a></li><li><a class="tocitem" href="energy.html">Dynamic Energy Budgets</a></li><li><a class="tocitem" href="species.html">Species</a></li></ul></li><li><a class="tocitem" href="crops.html">Crop submodel</a></li><li><a class="tocitem" href="farm.html">Farm submodel</a></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><nav class="breadcrumb"><ul class="is-hidden-mobile"><li><a class="is-disabled">Developing</a></li><li class="is-active"><a href="developing.html">Developing Persefone</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href="developing.html">Developing Persefone</a></li></ul></nav><div class="docs-right"><a class="docs-edit-link" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//docs/src/developing.md#" title="Edit source"><span class="docs-icon fa"></span><span class="docs-label is-hidden-touch">Edit source</span></a><a class="docs-settings-button fas fa-cog" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-sidebar-button fa fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a></div></header><article class="content" id="documenter-page"><h1 id="Developing-Persefone"><a class="docs-heading-anchor" href="#Developing-Persefone">Developing Persefone</a><a id="Developing-Persefone-1"></a><a class="docs-heading-anchor-permalink" href="#Developing-Persefone" title="Permalink"></a></h1><h2 id="Workflow"><a class="docs-heading-anchor" href="#Workflow">Workflow</a><a id="Workflow-1"></a><a class="docs-heading-anchor-permalink" href="#Workflow" title="Permalink"></a></h2><ol><li><p>Pull the current version from the master branch on Gitlab: <a href="https://git.idiv.de/xo30xoqa/persephone">https://git.idiv.de/xo30xoqa/persephone</a>.</p></li><li><p>If you are working on a new feature, create a new branch to avoid breaking the <code>master</code> branch. (The <code>master</code> branch on Github should always be in a runnable and error-free state.)</p></li><li><p>Implement your changes.</p></li><li><p>Run an example simulation and the test suite to make sure everything works without crashing (<code>make run</code> and <code>make test</code> on Linux, or execute <code>run.jl</code> and <code>test/runtests.jl</code> manually.)</p></li><li><p>Commit your work frequently, and try to keep each commit small. Don't forget to add relevant tests to the test suite.</p></li><li><p>Once your satisfied with your work, do another pull/merge from the <code>master</code> branch in case somebody else changed the branch in the meantime. Then merge your work into <code>master</code> and push to the Gitlab server.</p></li><li><p>Repeat :-)</p></li></ol><p>The Gitlab <a href="https://git.idiv.de/xo30xoqa/persephone/-/boards/373">issue tracker</a> can be used to create, discuss, and assign tasks, as well as to monitor progress towards milestones/releases. Once we have a first release, we will start using <a href="https://semver.org/">semantic versioning</a>.</p><h2 id="Libraries"><a class="docs-heading-anchor" href="#Libraries">Libraries</a><a id="Libraries-1"></a><a class="docs-heading-anchor-permalink" href="#Libraries" title="Permalink"></a></h2><h3 id="Agents.jl"><a class="docs-heading-anchor" href="#Agents.jl">Agents.jl</a><a id="Agents.jl-1"></a><a class="docs-heading-anchor-permalink" href="#Agents.jl" title="Permalink"></a></h3><p>Our model uses <a href="https://juliadynamics.github.io/Agents.jl/stable/">Agents.jl</a> as a framework. Their <a href="https://github.com/JuliaDynamics/Agents.jl">repository</a> can be used to inspect the source code or submit bug reports (the authors are quick to respond). Questions can be asked at the <a href="https://discourse.julialang.org/c/domain/models/21">Julia Discourse forum</a>.</p><p><em>Tutorial on collaborating on Julia packages: <a href="https://www.matecdev.com/posts/julia-package-collaboration.html">https://www.matecdev.com/posts/julia-package-collaboration.html</a>.</em></p><h3 id="Revise.jl"><a class="docs-heading-anchor" href="#Revise.jl">Revise.jl</a><a id="Revise.jl-1"></a><a class="docs-heading-anchor-permalink" href="#Revise.jl" title="Permalink"></a></h3><p><a href="https://timholy.github.io/Revise.jl/stable/"><code>Revise.jl</code></a> allows one to reload code without restarting the Julia interpreter. Get it with <code>Pkg.add("Revise")</code>, then add <code>using Revise</code> to <code>.julia/config/startup.jl</code> to have it automatically available.</p><h3 id="Test"><a class="docs-heading-anchor" href="#Test">Test</a><a id="Test-1"></a><a class="docs-heading-anchor-permalink" href="#Test" title="Permalink"></a></h3><p>Persefone uses the inbuilt Julia <a href="https://docs.julialang.org/en/v1/stdlib/Test/">testing framework</a>. All new functions should have appropriate tests written for them in the appropriate file in the <code>test</code> directory. (See <a href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master/test/runtests.jl"><code>test/runtests.jl</code></a> for details.) There are three ways to run the test suite: in the terminal, executing <code>make test</code> or <code>cd test; julia runtests.jl</code>; or in the Julia REPL, <code>Pkg.activate("."); Pkg.test()</code>.</p><h3 id="Documenter.jl"><a class="docs-heading-anchor" href="#Documenter.jl">Documenter.jl</a><a id="Documenter.jl-1"></a><a class="docs-heading-anchor-permalink" href="#Documenter.jl" title="Permalink"></a></h3><p>The HTML documentation is generated using <a href="https://documenter.juliadocs.org">Documenter.jl</a>. Therefore, all new functions should have docstrings attached. New files need to be integrated into the relevant documentation source files in <code>docs/src</code>, and if necessary into <a href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master/docs/builddocs.jl"><code>docs/builddocs.jl</code></a>. To build the documentation, run <code>make docs</code>, or <code>cd docs; julia builddocs.jl</code> (if using the latter, don't forget to update the date and commit in <code>docs/src/index.md</code>).</p><h2 id="Julia-editors"><a class="docs-heading-anchor" href="#Julia-editors">Julia editors</a><a id="Julia-editors-1"></a><a class="docs-heading-anchor-permalink" href="#Julia-editors" title="Permalink"></a></h2><h3 id="Emacs"><a class="docs-heading-anchor" href="#Emacs">Emacs</a><a id="Emacs-1"></a><a class="docs-heading-anchor-permalink" href="#Emacs" title="Permalink"></a></h3><p>There are a couple of addons that make working with Julia much nicer in Emacs:</p><ol><li><p><code>julia-mode</code> gives syntax highlighting. Install with <code>M-x package-install julia-mode</code>.</p></li><li><p><a href="https://github.com/gcv/julia-snail"><code>julia-snail</code></a> provides IDE-like features, especially a fully-functional REPL and the ability to evaluate code straight from inside a buffer. Note that the installation can be somewhat tricky. You first need to manually install all the dependencies of its dependency <a href="https://github.com/akermu/emacs-libvterm">vterm</a>, then install vterm itself with <code>M-x package-install vterm</code>, <em>before</em> you can do <code>M-x package-install julia-snail</code>. Then add it to your <code>init.el</code> with <code>(require 'julia-snail)</code> and <code>(add-hook 'julia-mode-hook #'julia-snail-mode)</code>.</p></li><li><p><a href="http://company-mode.github.io/"><code>company-mode</code></a> integrates with Snail to give code completion. Install with <code>M-x package-install company</code>, then add <code>(add-hook 'julia-mode-hook #'company-mode)</code> and <code>(global-set-key (kbd "C-<tab>") 'company-complete)</code> to your <code>init.el</code>.</p></li><li><p><a href="https://magit.vc/"><code>magit</code></a> is a great git interface for Emacs. Install with <code>M-x package-install magit</code> and add <code>(global-set-key (kbd "C-x g") 'magit-status)</code> to your <code>init.el</code>.</p></li></ol><h3 id="VSCode"><a class="docs-heading-anchor" href="#VSCode">VSCode</a><a id="VSCode-1"></a><a class="docs-heading-anchor-permalink" href="#VSCode" title="Permalink"></a></h3><p>See <a href="https://www.julia-vscode.org/">here</a>.</p><p><em>TODO: add more detail.</em></p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="odd.html">« Overview, Design, Details (ODD)</a><a class="docs-footer-nextpage" href="adapting.html">Adapting Persefone »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.23 on <span class="colophon-date" title="Thursday 27 July 2023 10:12">Thursday 27 July 2023</span>. Using Julia version 1.9.1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
diff --git a/docs/build/energy.html b/docs/build/energy.html
new file mode 100644
index 0000000..f2f2ab9
--- /dev/null
+++ b/docs/build/energy.html
@@ -0,0 +1,2 @@
+<!DOCTYPE html>
+<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Dynamic Energy Budgets · Persefone</title><script data-outdated-warner src="assets/warner.js"></script><link href="https://cdnjs.cloudflare.com/ajax/libs/lato-font/3.0.0/css/lato-font.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/juliamono/0.045/juliamono.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.13.24/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL="."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="assets/documenter.js"></script><script src="siteinfo.js"></script><script src="../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-dark.css" data-theme-name="documenter-dark" data-theme-primary-dark/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="assets/themeswap.js"></script></head><body><div id="documenter"><nav class="docs-sidebar"><a class="docs-logo" href="index.html"><img src="assets/logo.png" alt="Persefone logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="index.html">Persefone</a></span></div><form class="docs-search" action="search.html"><input class="docs-search-query" id="documenter-search-query" name="q" type="text" placeholder="Search docs"/></form><ul class="docs-menu"><li><a class="tocitem" href="index.html">Introduction</a></li><li><a class="tocitem" href="odd.html">Overview, Design, Details (ODD)</a></li><li><span class="tocitem">Developing</span><ul><li><a class="tocitem" href="developing.html">Developing Persefone</a></li><li><a class="tocitem" href="adapting.html">Adapting Persefone</a></li><li><a class="tocitem" href="architecture.html">Source code architecture</a></li><li><a class="tocitem" href="gis.html">Maps and weather data</a></li><li><a class="tocitem" href="species-dsl.html">Defining new species</a></li></ul></li><li><span class="tocitem">Core</span><ul><li><a class="tocitem" href="simulation.html">Simulation</a></li><li><a class="tocitem" href="io.html">Input, Output, and Settings</a></li></ul></li><li><span class="tocitem">Nature</span><ul><li><a class="tocitem" href="nature.html">Nature</a></li><li class="is-active"><a class="tocitem" href="energy.html">Dynamic Energy Budgets</a><ul class="internal"><li><a class="tocitem" href="#energy.jl"><span>energy.jl</span></a></li></ul></li><li><a class="tocitem" href="species.html">Species</a></li></ul></li><li><a class="tocitem" href="crops.html">Crop submodel</a></li><li><a class="tocitem" href="farm.html">Farm submodel</a></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><nav class="breadcrumb"><ul class="is-hidden-mobile"><li><a class="is-disabled">Nature</a></li><li class="is-active"><a href="energy.html">Dynamic Energy Budgets</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href="energy.html">Dynamic Energy Budgets</a></li></ul></nav><div class="docs-right"><a class="docs-edit-link" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//docs/src/energy.md#" title="Edit source"><span class="docs-icon fa"></span><span class="docs-label is-hidden-touch">Edit source</span></a><a class="docs-settings-button fas fa-cog" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-sidebar-button fa fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a></div></header><article class="content" id="documenter-page"><h1 id="Dynamic-Energy-Budgets"><a class="docs-heading-anchor" href="#Dynamic-Energy-Budgets">Dynamic Energy Budgets</a><a id="Dynamic-Energy-Budgets-1"></a><a class="docs-heading-anchor-permalink" href="#Dynamic-Energy-Budgets" title="Permalink"></a></h1><p>Persefone's nature module uses Kooijman's Dynamic Energy Budget theory to model energy flows within individuals.</p><p><img src="assets/deb.png" alt=""The standard model of the Dynamic Energy Budget theory""/></p><p><em>The standard model of the Dynamic Energy Budget theory. (Fig. 1 from Sousa et al. (2010).)</em></p><ul><li><p><a href="https://doi.org/10.1098/rstb.2010.0166">Sousa et al. (2010)</a>. Dynamic energy budget theory restores coherence in biology. Philosophical Transactions of the Royal Society B: Biological Sciences, 365(1557), 3413–3428.</p></li><li><p><a href="https://www.researchgate.net/profile/Edgar-Meza-3/post/Is_there_a_toxicokinetic_model_for_daphnia_magna_or_other_zooplankton/attachment/59d62cf579197b807798b396/AS%3A348547653357569%401460111644286/download/Dynamic+Energy+Budget+theory+-+Kooijman.pdf">Kooijman, S. A. L. M. (2009)</a>. Dynamic energy and mass budgets in biological systems (3rd ed). Cambridge University Press.</p></li><li><p><a href="https://doi.org/10.1111/2041-210x.12002">Sibly et al. (2013)</a>. Representing the acquisition and use of energy by individuals in agent-based models of animal populations. Methods in Ecology and Evolution, 4(2), 151–161.</p></li></ul><h2 id="energy.jl"><a class="docs-heading-anchor" href="#energy.jl">energy.jl</a><a id="energy.jl-1"></a><a class="docs-heading-anchor-permalink" href="#energy.jl" title="Permalink"></a></h2><article class="docstring"><header><a class="docstring-binding" id="Persefone.DEBparameters" href="#Persefone.DEBparameters"><code>Persefone.DEBparameters</code></a> — <span class="docstring-category">Type</span></header><section><div><pre><code class="language-julia hljs">DEBparameters</code></pre><p>An immutable struct to save the parameter list for a species' Dynamic Energy Budget model. (See Sousa et al., 2010.)</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/energy.jl#L9-L14">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.EnergyBudget" href="#Persefone.EnergyBudget"><code>Persefone.EnergyBudget</code></a> — <span class="docstring-category">Type</span></header><section><div><pre><code class="language-julia hljs">EnergyBudget</code></pre><p>This struct represents an individual's energy balance, as conceptualised by the Dynamic Energy Budget theory. Upon assimilation, energy is first stored as biomass in a reserve buffer, before being used for maintenance, growth, and reproduction. (Note that this is a simplified model form which ignores maturity as a separate buffer.)</p><p><strong>Sources:</strong></p><ul><li>Malishev & Kramer-Schadt (2021). Movement, models, and metabolism: Individual-based energy budget models as next-generation extensions for predicting animal movement outcomes across scales. Ecological Modelling, 441, 109413. https://doi.org/10.1016/j.ecolmodel.2020.109413</li><li>Marques et al. (2018). The AmP project: Comparing species on the basis of dynamic energy budget parameters. PLOS Computational Biology,14(5), e1006100. https://doi.org/10.1371/journal.pcbi.1006100</li><li>Sibly et al. (2013). Representing the acquisition and use of energy by individuals in agent-based models of animal populations. Methods in Ecology and Evolution, 4(2), 151–161. https://doi.org/10.1111/2041-210x.12002</li><li>Sousa et al. (2010). Dynamic energy budget theory restores coherence in biology. Philosophical Transactions of the Royal Society B: Biological Sciences, 365(1557), 3413–3428. https://doi.org/10.1098/rstb.2010.0166</li><li>Kooijman, S. A. L. M. (2009). Dynamic energy and mass budgets in biological systems (3rd ed). Cambridge University Press. https://www.researchgate.net/profile/Edgar-Meza-3/post/Is<em>there</em>a<em>toxicokinetic</em>model<em>for</em>daphnia<em>magna</em>or<em>other</em>zooplankton/attachment/59d62cf579197b807798b396/AS%3A348547653357569%401460111644286/download/Dynamic+Energy+Budget+theory+-+Kooijman.pdf</li><li><em>see also:</em> Brown et al. (2004). Toward a metabolic theory of ecology. Ecology, 85(7), 1771–1789. https://doi.org/10.1890/03-9000</li></ul></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/energy.jl#L30-L46">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.feed!-Tuple{Float64, Persefone.EnergyBudget}" href="#Persefone.feed!-Tuple{Float64, Persefone.EnergyBudget}"><code>Persefone.feed!</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">feed!(quantity, energybudget)</code></pre><p>Consume a given quantity of food. Expands the energy reserve by an amount determined by the assimilation rate. Returns <code>true</code> if successful, <code>false</code> if the reserve is already full.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/energy.jl#L207-L213">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.growthrate-Tuple{Persefone.EnergyBudget}" href="#Persefone.growthrate-Tuple{Persefone.EnergyBudget}"><code>Persefone.growthrate</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">growthrate(energybudget)</code></pre><p>Calculate the specific growth rate r. (Internal function.)</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/energy.jl#L115-L120">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.investmentratio-Tuple{Persefone.EnergyBudget}" href="#Persefone.investmentratio-Tuple{Persefone.EnergyBudget}"><code>Persefone.investmentratio</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">investmentratio(energybudget)</code></pre><p>Calculate the investment ratio g. (Internal function.)</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/energy.jl#L99-L104">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.maturitymaintenance-Tuple{Persefone.EnergyBudget}" href="#Persefone.maturitymaintenance-Tuple{Persefone.EnergyBudget}"><code>Persefone.maturitymaintenance</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">maturitymaintenance(energybudget)</code></pre><p>Calculate the specific maturity maintenance k_J. (Internal function.)</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/energy.jl#L71-L76">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.mobilisation-Tuple{Persefone.EnergyBudget}" href="#Persefone.mobilisation-Tuple{Persefone.EnergyBudget}"><code>Persefone.mobilisation</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">mobilisation(energybudget)</code></pre><p>Calculate the mobilisation rate J_EC. (Internal function.)</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/energy.jl#L136-L141">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.reproduce!-Tuple{Persefone.EnergyBudget}" href="#Persefone.reproduce!-Tuple{Persefone.EnergyBudget}"><code>Persefone.reproduce!</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">reproduce!(energybudget)</code></pre><p>If there is sufficient energy in the <code>offspring</code> buffer of an adult, produce an embryo/egg, reducing the parent energy in the process. Returns the embryo's energy budget, or <code>nothing</code> if the conditions are not met.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/energy.jl#L234-L240">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.scaledreservedensity-Tuple{Persefone.EnergyBudget}" href="#Persefone.scaledreservedensity-Tuple{Persefone.EnergyBudget}"><code>Persefone.scaledreservedensity</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">scaledreservedensity(energybudget)</code></pre><p>Calculate the scaled reserve density e. (Internal function.)</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/energy.jl#L85-L90">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.update!-Tuple{Persefone.EnergyBudget}" href="#Persefone.update!-Tuple{Persefone.EnergyBudget}"><code>Persefone.update!</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">update!(energybudget)</code></pre><p>Carry out a daily update of the energy budget. Mobilises reserves and allocates these to maintenance (prioritised), growth, and reproduction.</p><p>Return <code>true</code> if the individual has enough energy to survive, or <code>false</code> if the reserve is empty and it starves.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/energy.jl#L154-L162">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.volumetriclength-Tuple{Persefone.EnergyBudget}" href="#Persefone.volumetriclength-Tuple{Persefone.EnergyBudget}"><code>Persefone.volumetriclength</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">volumetriclength(energybudget)</code></pre><p>Calculate the structural length in cm based on an individual's weight (assuming a density of 1 g/cm³ to calculate volume, see Kooijman 2009).</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/energy.jl#L58-L63">source</a></section></article></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="nature.html">« Nature</a><a class="docs-footer-nextpage" href="species.html">Species »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.23 on <span class="colophon-date" title="Thursday 27 July 2023 10:12">Thursday 27 July 2023</span>. Using Julia version 1.9.1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
diff --git a/docs/build/farm.html b/docs/build/farm.html
index ef7398a..7354437 100644
--- a/docs/build/farm.html
+++ b/docs/build/farm.html
@@ -1,2 +1,2 @@
<!DOCTYPE html>
-<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Farm submodel · Persefone</title><script data-outdated-warner src="assets/warner.js"></script><link href="https://cdnjs.cloudflare.com/ajax/libs/lato-font/3.0.0/css/lato-font.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/juliamono/0.045/juliamono.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.13.24/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL="."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="assets/documenter.js"></script><script src="siteinfo.js"></script><script src="../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-dark.css" data-theme-name="documenter-dark" data-theme-primary-dark/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="assets/themeswap.js"></script></head><body><div id="documenter"><nav class="docs-sidebar"><a class="docs-logo" href="index.html"><img src="assets/logo.png" alt="Persefone logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="index.html">Persefone</a></span></div><form class="docs-search" action="search.html"><input class="docs-search-query" id="documenter-search-query" name="q" type="text" placeholder="Search docs"/></form><ul class="docs-menu"><li><a class="tocitem" href="index.html">Introduction</a></li><li><a class="tocitem" href="odd.html">Overview, Design, Details (ODD)</a></li><li><span class="tocitem">Developing</span><ul><li><a class="tocitem" href="developing.html">Developing Persefone</a></li><li><a class="tocitem" href="adapting.html">Adapting Persefone</a></li><li><a class="tocitem" href="architecture.html">Source code architecture</a></li><li><a class="tocitem" href="gis.html">GIS data</a></li><li><a class="tocitem" href="species-dsl.html">Defining new species</a></li></ul></li><li><span class="tocitem">Core</span><ul><li><a class="tocitem" href="simulation.html">Simulation</a></li><li><a class="tocitem" href="io.html">Input, Output, and Settings</a></li></ul></li><li><span class="tocitem">Nature</span><ul><li><a class="tocitem" href="nature.html">Nature</a></li><li><a class="tocitem" href="energy.html">Dynamic Energy Budgets</a></li><li><a class="tocitem" href="species.html">Species</a></li></ul></li><li><a class="tocitem" href="crops.html">Crop submodel</a></li><li class="is-active"><a class="tocitem" href="farm.html">Farm submodel</a><ul class="internal"><li><a class="tocitem" href="#farm.jl"><span>farm.jl</span></a></li></ul></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><nav class="breadcrumb"><ul class="is-hidden-mobile"><li class="is-active"><a href="farm.html">Farm submodel</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href="farm.html">Farm submodel</a></li></ul></nav><div class="docs-right"><a class="docs-edit-link" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//docs/src/farm.md#" title="Edit source"><span class="docs-icon fa"></span><span class="docs-label is-hidden-touch">Edit source</span></a><a class="docs-settings-button fas fa-cog" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-sidebar-button fa fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a></div></header><article class="content" id="documenter-page"><h1 id="Farm-submodel"><a class="docs-heading-anchor" href="#Farm-submodel">Farm submodel</a><a id="Farm-submodel-1"></a><a class="docs-heading-anchor-permalink" href="#Farm-submodel" title="Permalink"></a></h1><p>Eventually, Persefone will include multiple farm-decision submodels. At the moment, we are only working with a very basic mock-up.</p><h2 id="farm.jl"><a class="docs-heading-anchor" href="#farm.jl">farm.jl</a><a id="farm.jl-1"></a><a class="docs-heading-anchor-permalink" href="#farm.jl" title="Permalink"></a></h2><p>This file is responsible for managing the farm module(s).</p><article class="docstring"><header><a class="docstring-binding" id="Persefone.Farmer" href="#Persefone.Farmer"><code>Persefone.Farmer</code></a> — <span class="docstring-category">Type</span></header><section><div><pre><code class="language-julia hljs">Farmer</code></pre><p>This is the agent type for the farm ABM. (Not yet implemented.)</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/farm/farm.jl#L6-L10">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.initfarms!-Tuple{Agents.AgentBasedModel}" href="#Persefone.initfarms!-Tuple{Agents.AgentBasedModel}"><code>Persefone.initfarms!</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">initfarms!(model)</code></pre><p>Initialise the model with a set of farm agents.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/farm/farm.jl#L24-L28">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.stepagent!-Tuple{Farmer, Agents.AgentBasedModel}" href="#Persefone.stepagent!-Tuple{Farmer, Agents.AgentBasedModel}"><code>Persefone.stepagent!</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">stepagent!(farmer, model)</code></pre><p>Update a farmer by one day.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/farm/farm.jl#L15-L19">source</a></section></article></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="crops.html">« Crop submodel</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.23 on <span class="colophon-date" title="Thursday 20 July 2023 16:01">Thursday 20 July 2023</span>. Using Julia version 1.9.1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
+<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Farm submodel · Persefone</title><script data-outdated-warner src="assets/warner.js"></script><link href="https://cdnjs.cloudflare.com/ajax/libs/lato-font/3.0.0/css/lato-font.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/juliamono/0.045/juliamono.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.13.24/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL="."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="assets/documenter.js"></script><script src="siteinfo.js"></script><script src="../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-dark.css" data-theme-name="documenter-dark" data-theme-primary-dark/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="assets/themeswap.js"></script></head><body><div id="documenter"><nav class="docs-sidebar"><a class="docs-logo" href="index.html"><img src="assets/logo.png" alt="Persefone logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="index.html">Persefone</a></span></div><form class="docs-search" action="search.html"><input class="docs-search-query" id="documenter-search-query" name="q" type="text" placeholder="Search docs"/></form><ul class="docs-menu"><li><a class="tocitem" href="index.html">Introduction</a></li><li><a class="tocitem" href="odd.html">Overview, Design, Details (ODD)</a></li><li><span class="tocitem">Developing</span><ul><li><a class="tocitem" href="developing.html">Developing Persefone</a></li><li><a class="tocitem" href="adapting.html">Adapting Persefone</a></li><li><a class="tocitem" href="architecture.html">Source code architecture</a></li><li><a class="tocitem" href="gis.html">Maps and weather data</a></li><li><a class="tocitem" href="species-dsl.html">Defining new species</a></li></ul></li><li><span class="tocitem">Core</span><ul><li><a class="tocitem" href="simulation.html">Simulation</a></li><li><a class="tocitem" href="io.html">Input, Output, and Settings</a></li></ul></li><li><span class="tocitem">Nature</span><ul><li><a class="tocitem" href="nature.html">Nature</a></li><li><a class="tocitem" href="energy.html">Dynamic Energy Budgets</a></li><li><a class="tocitem" href="species.html">Species</a></li></ul></li><li><a class="tocitem" href="crops.html">Crop submodel</a></li><li class="is-active"><a class="tocitem" href="farm.html">Farm submodel</a><ul class="internal"><li><a class="tocitem" href="#farm.jl"><span>farm.jl</span></a></li></ul></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><nav class="breadcrumb"><ul class="is-hidden-mobile"><li class="is-active"><a href="farm.html">Farm submodel</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href="farm.html">Farm submodel</a></li></ul></nav><div class="docs-right"><a class="docs-edit-link" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//docs/src/farm.md#" title="Edit source"><span class="docs-icon fa"></span><span class="docs-label is-hidden-touch">Edit source</span></a><a class="docs-settings-button fas fa-cog" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-sidebar-button fa fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a></div></header><article class="content" id="documenter-page"><h1 id="Farm-submodel"><a class="docs-heading-anchor" href="#Farm-submodel">Farm submodel</a><a id="Farm-submodel-1"></a><a class="docs-heading-anchor-permalink" href="#Farm-submodel" title="Permalink"></a></h1><p>Eventually, Persefone will include multiple farm-decision submodels. At the moment, we are only working with a very basic mock-up.</p><h2 id="farm.jl"><a class="docs-heading-anchor" href="#farm.jl">farm.jl</a><a id="farm.jl-1"></a><a class="docs-heading-anchor-permalink" href="#farm.jl" title="Permalink"></a></h2><p>This file is responsible for managing the farm module(s).</p><article class="docstring"><header><a class="docstring-binding" id="Persefone.Farmer" href="#Persefone.Farmer"><code>Persefone.Farmer</code></a> — <span class="docstring-category">Type</span></header><section><div><pre><code class="language-julia hljs">Farmer</code></pre><p>This is the agent type for the farm ABM. (Not yet implemented.)</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/farm/farm.jl#L6-L10">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.initfarms!-Tuple{Agents.AgentBasedModel}" href="#Persefone.initfarms!-Tuple{Agents.AgentBasedModel}"><code>Persefone.initfarms!</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">initfarms!(model)</code></pre><p>Initialise the model with a set of farm agents.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/farm/farm.jl#L24-L28">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.stepagent!-Tuple{Farmer, Agents.AgentBasedModel}" href="#Persefone.stepagent!-Tuple{Farmer, Agents.AgentBasedModel}"><code>Persefone.stepagent!</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">stepagent!(farmer, model)</code></pre><p>Update a farmer by one day.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/farm/farm.jl#L15-L19">source</a></section></article></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="crops.html">« Crop submodel</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.23 on <span class="colophon-date" title="Thursday 27 July 2023 10:12">Thursday 27 July 2023</span>. Using Julia version 1.9.1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
diff --git a/docs/build/gis.html b/docs/build/gis.html
index 17b979f..ce5dd40 100644
--- a/docs/build/gis.html
+++ b/docs/build/gis.html
@@ -1,7 +1,29 @@
<!DOCTYPE html>
-<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>GIS data · Persefone</title><script data-outdated-warner src="assets/warner.js"></script><link href="https://cdnjs.cloudflare.com/ajax/libs/lato-font/3.0.0/css/lato-font.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/juliamono/0.045/juliamono.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.13.24/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL="."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="assets/documenter.js"></script><script src="siteinfo.js"></script><script src="../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-dark.css" data-theme-name="documenter-dark" data-theme-primary-dark/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="assets/themeswap.js"></script></head><body><div id="documenter"><nav class="docs-sidebar"><a class="docs-logo" href="index.html"><img src="assets/logo.png" alt="Persefone logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="index.html">Persefone</a></span></div><form class="docs-search" action="search.html"><input class="docs-search-query" id="documenter-search-query" name="q" type="text" placeholder="Search docs"/></form><ul class="docs-menu"><li><a class="tocitem" href="index.html">Introduction</a></li><li><a class="tocitem" href="odd.html">Overview, Design, Details (ODD)</a></li><li><span class="tocitem">Developing</span><ul><li><a class="tocitem" href="developing.html">Developing Persefone</a></li><li><a class="tocitem" href="adapting.html">Adapting Persefone</a></li><li><a class="tocitem" href="architecture.html">Source code architecture</a></li><li class="is-active"><a class="tocitem" href="gis.html">GIS data</a><ul class="internal"><li><a class="tocitem" href="#Land-cover-maps"><span>Land cover maps</span></a></li><li><a class="tocitem" href="#Field-ID-maps"><span>Field ID maps</span></a></li></ul></li><li><a class="tocitem" href="species-dsl.html">Defining new species</a></li></ul></li><li><span class="tocitem">Core</span><ul><li><a class="tocitem" href="simulation.html">Simulation</a></li><li><a class="tocitem" href="io.html">Input, Output, and Settings</a></li></ul></li><li><span class="tocitem">Nature</span><ul><li><a class="tocitem" href="nature.html">Nature</a></li><li><a class="tocitem" href="energy.html">Dynamic Energy Budgets</a></li><li><a class="tocitem" href="species.html">Species</a></li></ul></li><li><a class="tocitem" href="crops.html">Crop submodel</a></li><li><a class="tocitem" href="farm.html">Farm submodel</a></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><nav class="breadcrumb"><ul class="is-hidden-mobile"><li><a class="is-disabled">Developing</a></li><li class="is-active"><a href="gis.html">GIS data</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href="gis.html">GIS data</a></li></ul></nav><div class="docs-right"><a class="docs-edit-link" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//docs/src/gis.md#" title="Edit source"><span class="docs-icon fa"></span><span class="docs-label is-hidden-touch">Edit source</span></a><a class="docs-settings-button fas fa-cog" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-sidebar-button fa fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a></div></header><article class="content" id="documenter-page"><h1 id="GIS-data"><a class="docs-heading-anchor" href="#GIS-data">GIS data</a><a id="GIS-data-1"></a><a class="docs-heading-anchor-permalink" href="#GIS-data" title="Permalink"></a></h1><p>Persefone currently requires two separate map input files: one for land cover, the other for field geometry. This documents describe how to obtain and process the data needed for each of these.</p><h2 id="Land-cover-maps"><a class="docs-heading-anchor" href="#Land-cover-maps">Land cover maps</a><a id="Land-cover-maps-1"></a><a class="docs-heading-anchor-permalink" href="#Land-cover-maps" title="Permalink"></a></h2><p>Land cover maps for Germany at 10m resolution can be obtained from <a href="https://data.mundialis.de/geonetwork/srv/eng/catalog.search#/metadata/9246503f-6adf-460b-a31e-73a649182d07">Mundialis</a>. These are generated annually from Sentinel data and comprise the following land cover classes:</p><pre><code class="nohighlight hljs">10: forest
+<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Maps and weather data · Persefone</title><script data-outdated-warner src="assets/warner.js"></script><link href="https://cdnjs.cloudflare.com/ajax/libs/lato-font/3.0.0/css/lato-font.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/juliamono/0.045/juliamono.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.13.24/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL="."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="assets/documenter.js"></script><script src="siteinfo.js"></script><script src="../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-dark.css" data-theme-name="documenter-dark" data-theme-primary-dark/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="assets/themeswap.js"></script></head><body><div id="documenter"><nav class="docs-sidebar"><a class="docs-logo" href="index.html"><img src="assets/logo.png" alt="Persefone logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="index.html">Persefone</a></span></div><form class="docs-search" action="search.html"><input class="docs-search-query" id="documenter-search-query" name="q" type="text" placeholder="Search docs"/></form><ul class="docs-menu"><li><a class="tocitem" href="index.html">Introduction</a></li><li><a class="tocitem" href="odd.html">Overview, Design, Details (ODD)</a></li><li><span class="tocitem">Developing</span><ul><li><a class="tocitem" href="developing.html">Developing Persefone</a></li><li><a class="tocitem" href="adapting.html">Adapting Persefone</a></li><li><a class="tocitem" href="architecture.html">Source code architecture</a></li><li class="is-active"><a class="tocitem" href="gis.html">Maps and weather data</a><ul class="internal"><li><a class="tocitem" href="#Land-cover-maps"><span>Land cover maps</span></a></li><li><a class="tocitem" href="#Field-ID-maps"><span>Field ID maps</span></a></li><li><a class="tocitem" href="#Weather-data"><span>Weather data</span></a></li></ul></li><li><a class="tocitem" href="species-dsl.html">Defining new species</a></li></ul></li><li><span class="tocitem">Core</span><ul><li><a class="tocitem" href="simulation.html">Simulation</a></li><li><a class="tocitem" href="io.html">Input, Output, and Settings</a></li></ul></li><li><span class="tocitem">Nature</span><ul><li><a class="tocitem" href="nature.html">Nature</a></li><li><a class="tocitem" href="energy.html">Dynamic Energy Budgets</a></li><li><a class="tocitem" href="species.html">Species</a></li></ul></li><li><a class="tocitem" href="crops.html">Crop submodel</a></li><li><a class="tocitem" href="farm.html">Farm submodel</a></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><nav class="breadcrumb"><ul class="is-hidden-mobile"><li><a class="is-disabled">Developing</a></li><li class="is-active"><a href="gis.html">Maps and weather data</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href="gis.html">Maps and weather data</a></li></ul></nav><div class="docs-right"><a class="docs-edit-link" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//docs/src/gis.md#" title="Edit source"><span class="docs-icon fa"></span><span class="docs-label is-hidden-touch">Edit source</span></a><a class="docs-settings-button fas fa-cog" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-sidebar-button fa fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a></div></header><article class="content" id="documenter-page"><h1 id="Maps-and-weather-data"><a class="docs-heading-anchor" href="#Maps-and-weather-data">Maps and weather data</a><a id="Maps-and-weather-data-1"></a><a class="docs-heading-anchor-permalink" href="#Maps-and-weather-data" title="Permalink"></a></h1><p>Persefone currently requires two separate map input files: one for land cover, the other for field geometry. Additionally, a weather input file is needed. This documents describe how to obtain and process the data needed for each of these.</p><h2 id="Land-cover-maps"><a class="docs-heading-anchor" href="#Land-cover-maps">Land cover maps</a><a id="Land-cover-maps-1"></a><a class="docs-heading-anchor-permalink" href="#Land-cover-maps" title="Permalink"></a></h2><p>Land cover maps for Germany at 10m resolution can be obtained from <a href="https://data.mundialis.de/geonetwork/srv/eng/catalog.search#/metadata/9246503f-6adf-460b-a31e-73a649182d07">Mundialis</a>. These are generated annually from Sentinel data and comprise the following land cover classes:</p><pre><code class="nohighlight hljs">10: forest
20: low vegetation
30: water
40: built-up
50: bare soil
-60: agriculture</code></pre><p>To create a Persefone map input file, you need to crop the national Mundialis map to the extent that you want to simulate (suggestion: approx. 10x10km is a reasonable size).</p><p>To do so, download the Mundialis map and import it into QGIS. Then create a new vector layer and create a rectangle feature to delimit the extent of your region. Then go to <code>Raster -> Extraction -> Clip Raster by Extent</code>. Select the Mundialis map as the input layer, set the clipping extent by choosing your region vector layer under <code>Calculate from Layer</code> and specify the output file name before clicking <code>Run</code>. This will generate a TIF file that you can pass to Persefone as the <code>landcovermap</code> parameter.</p><h2 id="Field-ID-maps"><a class="docs-heading-anchor" href="#Field-ID-maps">Field ID maps</a><a id="Field-ID-maps-1"></a><a class="docs-heading-anchor-permalink" href="#Field-ID-maps" title="Permalink"></a></h2><p>In addition to the land cover data explained above, Persefone also needs information about agricultural field boundaries in order to assign these to the farming agents. Unfortunately, getting this is rather more complicated.</p><p>In the EU, every country runs a Land Parcel Information System (LPIS) to administer CAP payments. In Germany, this is called InVeKoS and is run by the Länder. For example, you can view and download the InVeKoS data for Thüringen <a href="https://thueringenviewer.thueringen.de/thviewer/invekos.html">here</a>. This gives you a vector layer which can be loaded into QGIS. However, it needs to be converted to a raster layer and cropped to your region extent before it can be used in Persefone.</p><p>The first thing to do is to make sure that the vector layer has a numeric (!) field with a unique identifier for each field block (check the attribute table). The Thüringen data has the FBI ("Feldblockident") field, but this is a string value and therefore not usable by the rasteriser. So, we set the vector layer to edit mode, open the field calculator, enter the information for a new field (call it "FID" and set it to a 32-bit integer), and enter <code>@row_number</code> in the expression field. Then save the layer and close the calculator.</p><p>Secondly, you need to filter out all non-field/non-grassland plot types. (LPIS also has data on forests and various landscape elements that are not relevant to our use case.) Assuming you're working with the Thüringen InVeKoS data (other data sets may have a different structure), right-click on the layer name in QGIS' layer overview and click on "Filter...". Then, enter this expression in the query builder: <code>"BNK" = 'AL' OR "BNK" = 'GL'</code> and click "OK". This will select only field and grassland plots.</p><p>Next, open the rasteriser (<code>Raster -> Conversion -> Rasterize</code>). Select your FID field as the "Field to use for a burn-in value", and your land cover map (as created above - this ensures the two layers match) as the output extent. Make sure the "fixed value to burn" is "Not set". Then choose "Georeferenced units" as the "Out raster size units" and set horizontal and vertical resolution to 10.0. In the advanced parameters, set the output data type to <code>UInt32</code>. Finally, enter an output file name and run. The resulting TIF file can be passed to Persefone as the <code>farmfieldmap</code> parameter.</p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="architecture.html">« Source code architecture</a><a class="docs-footer-nextpage" href="species-dsl.html">Defining new species »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.23 on <span class="colophon-date" title="Thursday 20 July 2023 16:01">Thursday 20 July 2023</span>. Using Julia version 1.9.1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
+60: agriculture</code></pre><p>To create a Persefone map input file, you need to crop the national Mundialis map to the extent that you want to simulate (suggestion: approx. 10x10km is a reasonable size).</p><p>To do so, download the Mundialis map and import it into QGIS. Then create a new vector layer and create a rectangle feature to delimit the extent of your region. Then go to <code>Raster -> Extraction -> Clip Raster by Extent</code>. Select the Mundialis map as the input layer, set the clipping extent by choosing your region vector layer under <code>Calculate from Layer</code> and specify the output file name before clicking <code>Run</code>. This will generate a TIF file that you can pass to Persefone as the <code>landcovermap</code> parameter.</p><h2 id="Field-ID-maps"><a class="docs-heading-anchor" href="#Field-ID-maps">Field ID maps</a><a id="Field-ID-maps-1"></a><a class="docs-heading-anchor-permalink" href="#Field-ID-maps" title="Permalink"></a></h2><p>In addition to the land cover data explained above, Persefone also needs information about agricultural field boundaries in order to assign these to the farming agents. Unfortunately, getting this is rather more complicated.</p><p>In the EU, every country runs a Land Parcel Information System (LPIS) to administer CAP payments. In Germany, this is called InVeKoS and is run by the Länder. For example, you can view and download the InVeKoS data for Thüringen <a href="https://thueringenviewer.thueringen.de/thviewer/invekos.html">here</a>. This gives you a vector layer which can be loaded into QGIS. However, it needs to be converted to a raster layer and cropped to your region extent before it can be used in Persefone.</p><p>The first thing to do is to make sure that the vector layer has a numeric (!) field with a unique identifier for each field block (check the attribute table). The Thüringen data has the FBI ("Feldblockident") field, but this is a string value and therefore not usable by the rasteriser. So, we set the vector layer to edit mode, open the field calculator, enter the information for a new field (call it "FID" and set it to a 32-bit integer), and enter <code>@row_number</code> in the expression field. Then save the layer and close the calculator.</p><p>Secondly, you need to filter out all non-field/non-grassland plot types. (LPIS also has data on forests and various landscape elements that are not relevant to our use case.) Assuming you're working with the Thüringen InVeKoS data (other data sets may have a different structure), right-click on the layer name in QGIS' layer overview and click on "Filter...". Then, enter this expression in the query builder: <code>"BNK" = 'AL' OR "BNK" = 'GL'</code> and click "OK". This will select only field and grassland plots.</p><p>Next, open the rasteriser (<code>Raster -> Conversion -> Rasterize</code>). Select your FID field as the "Field to use for a burn-in value", and your land cover map (as created above - this ensures the two layers match) as the output extent. Make sure the "fixed value to burn" is "Not set". Then choose "Georeferenced units" as the "Out raster size units" and set horizontal and vertical resolution to 10.0. In the advanced parameters, set the output data type to <code>UInt32</code>. Finally, enter an output file name and run. The resulting TIF file can be passed to Persefone as the <code>farmfieldmap</code> parameter.</p><h2 id="Weather-data"><a class="docs-heading-anchor" href="#Weather-data">Weather data</a><a id="Weather-data-1"></a><a class="docs-heading-anchor-permalink" href="#Weather-data" title="Permalink"></a></h2><p>Currently, Persefone uses historical weather data from the closes weather station as its weather input. (In future, this may be changed to a more detailed raster input, which could then also provide future weather predictions under climate change.) Weather data can be downloaded from the <a href="https://www.dwd.de/DE/leistungen/cdc/cdc_ueberblick-klimadaten.html?nn=16102">German weather service (DWD)</a>. The relevant data are in the folder <a href="https://opendata.dwd.de/climate_environment/CDC/observations_germany/climate/daily/kl/historical/"><code>daily/kl/historical</code></a>.</p><p>The description of this data set and the list of weather stations can be found in the Persefone repository, in the <code>docs</code> folder (or downloaded from the link above). Using the list of weather stations, select the one closest to the area of study. Note that not all stations were continuously in operation; make sure that the selected station covers the years of interest.</p><ul><li><strong>Region Jena:</strong> station number 02444 ("Jena (Sternwarte)")</li><li><strong>Region Eichsfeld:</strong></li><li><strong>Region Thüringer Becken:</strong></li><li><strong>Region Hohenlohe:</strong></li><li><strong>Region Bodensee:</strong></li><li><strong>Region Nördlicher Oberrhein:</strong></li></ul><p>From the link above, download the ZIP file associated with the station number. Check the included meta-data if there is any important missing data, or other relevant information (e.g. the station moved position).</p><p>Then use <code>data/extract_weather_data.R</code> to process the data into the format needed by Persefone:</p><pre><code class="language-R hljs">library(tidyverse)
+
+## replace this with the correct file name
+weatherfile = "produkt_klima_tag_18210101_20221231_02444.txt"
+
+data = read.table(weatherfile, sep=";", header=T)
+
+weather = data %>%
+ ## drop values before 2000 to save space
+ filter(MESS_DATUM>=20000101) %>%
+ ## select relevant variables and convert place-holder values to NA
+ select(MESS_DATUM, FM, RSK, SDK, VPM, TMK, TXK, TNK) %>%
+ mutate(date=MESS_DATUM, MESS_DATUM=NULL,
+ mean_windspeed=na_if(FM, -999), FM=NULL,
+ precipitation=na_if(RSK, -999), RSK=NULL,
+ sunshine_hours=na_if(SDK, -999), SDK=NULL,
+ mean_vapour_pressure=na_if(VPM, -999), VPM=NULL,
+ mean_temperature=na_if(TMK, -999), TMK=NULL,
+ max_temperature=na_if(TXK, -999), TXK=NULL,
+ min_temperature=na_if(TNK, -999), TNK=NULL)
+
+## replace with the desired file name
+write.csv(weather, file="weather_jena.csv", row.names=FALSE)</code></pre><p><em>Note: for calculating the reference evapotranspiration ET_0 (needed for the AquaCrop model), use the <a href="https://www.fao.org/3/X0490E/x0490e06.htm#equation">FAO Penman-Monteith equation</a>.</em></p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="architecture.html">« Source code architecture</a><a class="docs-footer-nextpage" href="species-dsl.html">Defining new species »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.23 on <span class="colophon-date" title="Thursday 27 July 2023 10:12">Thursday 27 July 2023</span>. Using Julia version 1.9.1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
diff --git a/docs/build/index.html b/docs/build/index.html
index 80ea7f6..f78acaf 100644
--- a/docs/build/index.html
+++ b/docs/build/index.html
@@ -1,5 +1,5 @@
<!DOCTYPE html>
-<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Introduction · Persefone</title><script data-outdated-warner src="assets/warner.js"></script><link href="https://cdnjs.cloudflare.com/ajax/libs/lato-font/3.0.0/css/lato-font.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/juliamono/0.045/juliamono.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.13.24/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL="."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="assets/documenter.js"></script><script src="siteinfo.js"></script><script src="../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-dark.css" data-theme-name="documenter-dark" data-theme-primary-dark/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="assets/themeswap.js"></script></head><body><div id="documenter"><nav class="docs-sidebar"><a class="docs-logo" href="index.html"><img src="assets/logo.png" alt="Persefone logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="index.html">Persefone</a></span></div><form class="docs-search" action="search.html"><input class="docs-search-query" id="documenter-search-query" name="q" type="text" placeholder="Search docs"/></form><ul class="docs-menu"><li class="is-active"><a class="tocitem" href="index.html">Introduction</a><ul class="internal"><li><a class="tocitem" href="#Running-the-model"><span>Running the model</span></a></li><li><a class="tocitem" href="#Model-input"><span>Model input</span></a></li></ul></li><li><a class="tocitem" href="odd.html">Overview, Design, Details (ODD)</a></li><li><span class="tocitem">Developing</span><ul><li><a class="tocitem" href="developing.html">Developing Persefone</a></li><li><a class="tocitem" href="adapting.html">Adapting Persefone</a></li><li><a class="tocitem" href="architecture.html">Source code architecture</a></li><li><a class="tocitem" href="gis.html">GIS data</a></li><li><a class="tocitem" href="species-dsl.html">Defining new species</a></li></ul></li><li><span class="tocitem">Core</span><ul><li><a class="tocitem" href="simulation.html">Simulation</a></li><li><a class="tocitem" href="io.html">Input, Output, and Settings</a></li></ul></li><li><span class="tocitem">Nature</span><ul><li><a class="tocitem" href="nature.html">Nature</a></li><li><a class="tocitem" href="energy.html">Dynamic Energy Budgets</a></li><li><a class="tocitem" href="species.html">Species</a></li></ul></li><li><a class="tocitem" href="crops.html">Crop submodel</a></li><li><a class="tocitem" href="farm.html">Farm submodel</a></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><nav class="breadcrumb"><ul class="is-hidden-mobile"><li class="is-active"><a href="index.html">Introduction</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href="index.html">Introduction</a></li></ul></nav><div class="docs-right"><a class="docs-edit-link" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//docs/src/index.md#" title="Edit source"><span class="docs-icon fa"></span><span class="docs-label is-hidden-touch">Edit source</span></a><a class="docs-settings-button fas fa-cog" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-sidebar-button fa fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a></div></header><article class="content" id="documenter-page"><h1 id="Introduction"><a class="docs-heading-anchor" href="#Introduction">Introduction</a><a id="Introduction-1"></a><a class="docs-heading-anchor-permalink" href="#Introduction" title="Permalink"></a></h1><p>Persefone is an agent-based, socio-economic-ecological model of agricultural landscapes in Europe under the Common Agricultural Policy (CAP).</p><p>It's aim is to investigate how policy affects farmer decision-making, and how this in turn affects various animal species. It includes a farm submodel, a crop-growth submodel, and an ecological submodels.</p><h2 id="Running-the-model"><a class="docs-heading-anchor" href="#Running-the-model">Running the model</a><a id="Running-the-model-1"></a><a class="docs-heading-anchor-permalink" href="#Running-the-model" title="Permalink"></a></h2><p>To run a single experiment, execute <code>run.jl</code>:</p><pre><code class="nohighlight hljs">julia run.jl -c <CONFIG></code></pre><p>Other commandline arguments are:</p><pre><code class="nohighlight hljs">usage: run.jl [-c CONFIGFILE] [-s SEED] [-o OUTDIR] [-l LOGLEVEL]
+<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Introduction · Persefone</title><script data-outdated-warner src="assets/warner.js"></script><link href="https://cdnjs.cloudflare.com/ajax/libs/lato-font/3.0.0/css/lato-font.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/juliamono/0.045/juliamono.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.13.24/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL="."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="assets/documenter.js"></script><script src="siteinfo.js"></script><script src="../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-dark.css" data-theme-name="documenter-dark" data-theme-primary-dark/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="assets/themeswap.js"></script></head><body><div id="documenter"><nav class="docs-sidebar"><a class="docs-logo" href="index.html"><img src="assets/logo.png" alt="Persefone logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="index.html">Persefone</a></span></div><form class="docs-search" action="search.html"><input class="docs-search-query" id="documenter-search-query" name="q" type="text" placeholder="Search docs"/></form><ul class="docs-menu"><li class="is-active"><a class="tocitem" href="index.html">Introduction</a><ul class="internal"><li><a class="tocitem" href="#Running-the-model"><span>Running the model</span></a></li><li><a class="tocitem" href="#Model-input"><span>Model input</span></a></li></ul></li><li><a class="tocitem" href="odd.html">Overview, Design, Details (ODD)</a></li><li><span class="tocitem">Developing</span><ul><li><a class="tocitem" href="developing.html">Developing Persefone</a></li><li><a class="tocitem" href="adapting.html">Adapting Persefone</a></li><li><a class="tocitem" href="architecture.html">Source code architecture</a></li><li><a class="tocitem" href="gis.html">Maps and weather data</a></li><li><a class="tocitem" href="species-dsl.html">Defining new species</a></li></ul></li><li><span class="tocitem">Core</span><ul><li><a class="tocitem" href="simulation.html">Simulation</a></li><li><a class="tocitem" href="io.html">Input, Output, and Settings</a></li></ul></li><li><span class="tocitem">Nature</span><ul><li><a class="tocitem" href="nature.html">Nature</a></li><li><a class="tocitem" href="energy.html">Dynamic Energy Budgets</a></li><li><a class="tocitem" href="species.html">Species</a></li></ul></li><li><a class="tocitem" href="crops.html">Crop submodel</a></li><li><a class="tocitem" href="farm.html">Farm submodel</a></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><nav class="breadcrumb"><ul class="is-hidden-mobile"><li class="is-active"><a href="index.html">Introduction</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href="index.html">Introduction</a></li></ul></nav><div class="docs-right"><a class="docs-edit-link" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//docs/src/index.md#" title="Edit source"><span class="docs-icon fa"></span><span class="docs-label is-hidden-touch">Edit source</span></a><a class="docs-settings-button fas fa-cog" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-sidebar-button fa fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a></div></header><article class="content" id="documenter-page"><h1 id="Introduction"><a class="docs-heading-anchor" href="#Introduction">Introduction</a><a id="Introduction-1"></a><a class="docs-heading-anchor-permalink" href="#Introduction" title="Permalink"></a></h1><p>Persefone is an agent-based, socio-economic-ecological model of agricultural landscapes in Europe under the Common Agricultural Policy (CAP).</p><p>It's aim is to investigate how policy affects farmer decision-making, and how this in turn affects various animal species. It includes a farm submodel, a crop-growth submodel, and an ecological submodels.</p><h2 id="Running-the-model"><a class="docs-heading-anchor" href="#Running-the-model">Running the model</a><a id="Running-the-model-1"></a><a class="docs-heading-anchor-permalink" href="#Running-the-model" title="Permalink"></a></h2><p>To run a single experiment, execute <code>run.jl</code>:</p><pre><code class="nohighlight hljs">julia run.jl -c <CONFIG></code></pre><p>Other commandline arguments are:</p><pre><code class="nohighlight hljs">usage: run.jl [-c CONFIGFILE] [-s SEED] [-o OUTDIR] [-l LOGLEVEL]
[--version] [-h]
optional arguments:
@@ -39,4 +39,4 @@ popoutfreq = "daily" # output frequency population-level data, daily/m
indoutfreq = "end" # output frequency individual-level data, daily/monthly/yearly/end/never
[crop]
-cropmodel = "linear" # crop growth model to use, "linear" or "aquacrop" (not yet implemented)</code></pre><div class="admonition is-info"><header class="admonition-header">Parameter scanning</header><div class="admonition-body"><p>You can set any parameter to a list of different values, e.g. <code>seed = [1,2,3]</code>. Persefone will then set up and run multiple simulations, one for every possible combination of parameters that you entered (i.e. do a full-factorial simulation experiment).</p></div></div><p><em>Last updated: 2023-07-20 (commit 0fd9917)</em></p></article><nav class="docs-footer"><a class="docs-footer-nextpage" href="odd.html">Overview, Design, Details (ODD) »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.23 on <span class="colophon-date" title="Thursday 20 July 2023 16:01">Thursday 20 July 2023</span>. Using Julia version 1.9.1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
+cropmodel = "linear" # crop growth model to use, "linear" or "aquacrop" (not yet implemented)</code></pre><div class="admonition is-info"><header class="admonition-header">Parameter scanning</header><div class="admonition-body"><p>You can set any parameter to a list of different values, e.g. <code>seed = [1,2,3]</code>. Persefone will then set up and run multiple simulations, one for every possible combination of parameters that you entered (i.e. do a full-factorial simulation experiment).</p></div></div><p><em>Last updated: 2023-07-27 (commit 1e6e7d6)</em></p></article><nav class="docs-footer"><a class="docs-footer-nextpage" href="odd.html">Overview, Design, Details (ODD) »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.23 on <span class="colophon-date" title="Thursday 27 July 2023 10:12">Thursday 27 July 2023</span>. Using Julia version 1.9.1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
diff --git a/docs/build/io.html b/docs/build/io.html
index 0663e44..10d2433 100644
--- a/docs/build/io.html
+++ b/docs/build/io.html
@@ -1,2 +1,2 @@
<!DOCTYPE html>
-<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Input, Output, and Settings · Persefone</title><script data-outdated-warner src="assets/warner.js"></script><link href="https://cdnjs.cloudflare.com/ajax/libs/lato-font/3.0.0/css/lato-font.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/juliamono/0.045/juliamono.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.13.24/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL="."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="assets/documenter.js"></script><script src="siteinfo.js"></script><script src="../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-dark.css" data-theme-name="documenter-dark" data-theme-primary-dark/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="assets/themeswap.js"></script></head><body><div id="documenter"><nav class="docs-sidebar"><a class="docs-logo" href="index.html"><img src="assets/logo.png" alt="Persefone logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="index.html">Persefone</a></span></div><form class="docs-search" action="search.html"><input class="docs-search-query" id="documenter-search-query" name="q" type="text" placeholder="Search docs"/></form><ul class="docs-menu"><li><a class="tocitem" href="index.html">Introduction</a></li><li><a class="tocitem" href="odd.html">Overview, Design, Details (ODD)</a></li><li><span class="tocitem">Developing</span><ul><li><a class="tocitem" href="developing.html">Developing Persefone</a></li><li><a class="tocitem" href="adapting.html">Adapting Persefone</a></li><li><a class="tocitem" href="architecture.html">Source code architecture</a></li><li><a class="tocitem" href="gis.html">GIS data</a></li><li><a class="tocitem" href="species-dsl.html">Defining new species</a></li></ul></li><li><span class="tocitem">Core</span><ul><li><a class="tocitem" href="simulation.html">Simulation</a></li><li class="is-active"><a class="tocitem" href="io.html">Input, Output, and Settings</a><ul class="internal"><li><a class="tocitem" href="#parameters.toml"><span>parameters.toml</span></a></li><li><a class="tocitem" href="#input.jl"><span>input.jl</span></a></li><li><a class="tocitem" href="#output.jl"><span>output.jl</span></a></li></ul></li></ul></li><li><span class="tocitem">Nature</span><ul><li><a class="tocitem" href="nature.html">Nature</a></li><li><a class="tocitem" href="energy.html">Dynamic Energy Budgets</a></li><li><a class="tocitem" href="species.html">Species</a></li></ul></li><li><a class="tocitem" href="crops.html">Crop submodel</a></li><li><a class="tocitem" href="farm.html">Farm submodel</a></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><nav class="breadcrumb"><ul class="is-hidden-mobile"><li><a class="is-disabled">Core</a></li><li class="is-active"><a href="io.html">Input, Output, and Settings</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href="io.html">Input, Output, and Settings</a></li></ul></nav><div class="docs-right"><a class="docs-edit-link" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//docs/src/io.md#" title="Edit source"><span class="docs-icon fa"></span><span class="docs-label is-hidden-touch">Edit source</span></a><a class="docs-settings-button fas fa-cog" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-sidebar-button fa fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a></div></header><article class="content" id="documenter-page"><h1 id="Input,-Output,-and-Settings"><a class="docs-heading-anchor" href="#Input,-Output,-and-Settings">Input, Output, and Settings</a><a id="Input,-Output,-and-Settings-1"></a><a class="docs-heading-anchor-permalink" href="#Input,-Output,-and-Settings" title="Permalink"></a></h1><p>These functions are responsible for reading in all model configurations (passed by config file or commandline), administrating them during a run, and printing any output.</p><h2 id="parameters.toml"><a class="docs-heading-anchor" href="#parameters.toml">parameters.toml</a><a id="parameters.toml-1"></a><a class="docs-heading-anchor-permalink" href="#parameters.toml" title="Permalink"></a></h2><p>This is the default configuration file for Persefone, containing all model parameters. The syntax is described here: <a href="https://toml.io/en/">https://toml.io/en/</a></p><p>DO NOT MODIFY THIS FILE FOR SIMULATION EXPERIMENTS! Instead, copy it to another directory, modify the copy, and then pass it to the model using the <code>--config</code> parameter.</p><h2 id="input.jl"><a class="docs-heading-anchor" href="#input.jl">input.jl</a><a id="input.jl-1"></a><a class="docs-heading-anchor-permalink" href="#input.jl" title="Permalink"></a></h2><article class="docstring"><header><a class="docstring-binding" id="Persefone.PARAMFILE" href="#Persefone.PARAMFILE"><code>Persefone.PARAMFILE</code></a> — <span class="docstring-category">Constant</span></header><section><div><p>The file that stores all default parameters: <code>src/parameters.toml</code></p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/input.jl#L9-L11">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.flattenTOML-Tuple{Any}" href="#Persefone.flattenTOML-Tuple{Any}"><code>Persefone.flattenTOML</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">flattenTOML(dict)</code></pre><p>An internal utility function to convert the two-dimensional dict returned by <code>TOML.parsefile()</code> into a one-dimensional dict, so that instead of writing <code>settings["domain"]["param"]</code> one can use <code>settings["domain.param"]</code>. Can be reversed with <a href="io.html#Persefone.prepareTOML-Tuple{Any}"><code>prepareTOML</code></a>.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/input.jl#L97-L104">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.getsettings" href="#Persefone.getsettings"><code>Persefone.getsettings</code></a> — <span class="docstring-category">Function</span></header><section><div><pre><code class="language-julia hljs">getsettings(configfile, seed=nothing)</code></pre><p>Combines all configuration options to produce a single settings dict. Precedence: commandline parameters - user config file - default values</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/input.jl#L34-L39">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.parsecommandline-Tuple{}" href="#Persefone.parsecommandline-Tuple{}"><code>Persefone.parsecommandline</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">parsecommandline()</code></pre><p>Certain software parameters can be set via the commandline.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/input.jl#L137-L141">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.preprocessparameters-Tuple{Dict{String, Any}, String}" href="#Persefone.preprocessparameters-Tuple{Dict{String, Any}, String}"><code>Persefone.preprocessparameters</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">preprocessparameters(settings)</code></pre><p>Take the raw input parameters and process them (convert types, perform checks, etc.). This is a helper function for <a href="io.html#Persefone.getsettings"><code>getsettings</code></a>.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/input.jl#L72-L77">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.@param-Tuple{Any}" href="#Persefone.@param-Tuple{Any}"><code>Persefone.@param</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@param(domainparam)</code></pre><p>Return a configuration parameter from the global settings. The argument should be in the form <code><domain>.<parameter></code>, for example <code>@param(core.outdir)</code>. Possible values for <code><domain></code> are <code>core</code>, <code>nature</code>, <code>farm</code>, or <code>crop</code>. For a full list of parameters, see <code>src/parameters.toml</code>.</p><p>Note: this macro only works in a context where the <code>model</code> object is available!</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/input.jl#L16-L27">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.@rand-Tuple" href="#Persefone.@rand-Tuple"><code>Persefone.@rand</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@rand(args...)</code></pre><p>Return a random number or element from the sample, using the model RNG. This is a utility wrapper that can only be used a context where the <code>model</code> object is available.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/input.jl#L115-L121">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.@shuffle!-Tuple{Any}" href="#Persefone.@shuffle!-Tuple{Any}"><code>Persefone.@shuffle!</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@shuffle!(collection)</code></pre><p>Shuffle the given collection in place, using the model RNG. This is a utility wrapper that can only be used a context where the <code>model</code> object is available.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/input.jl#L126-L132">source</a></section></article><h2 id="output.jl"><a class="docs-heading-anchor" href="#output.jl">output.jl</a><a id="output.jl-1"></a><a class="docs-heading-anchor-permalink" href="#output.jl" title="Permalink"></a></h2><article class="docstring"><header><a class="docstring-binding" id="Persefone.DataOutput" href="#Persefone.DataOutput"><code>Persefone.DataOutput</code></a> — <span class="docstring-category">Type</span></header><section><div><pre><code class="language-julia hljs">DataOutput</code></pre><p>A struct for organising model output. This is designed for text-based data output that is updated more or less regularly (e.g. population data in csv files). Submodels can register their own output functions using <a href="io.html#Persefone.newdataoutput!-Tuple{Agents.AgentBasedModel, String, String, Function, String}"><code>newdataoutput!</code></a>.</p><p>Struct fields: - filename: the name of the file to be created in the user-specified output directory - header: a string to be written to the start of the file as it is initialised - outputfunction: a function that takes a model object and returns a string to write to file - frequency: how often to call the output function (daily/monthly/yearly/end/never)</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/output.jl#L122-L134">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.createdatadir-Tuple{String, Union{Bool, String}}" href="#Persefone.createdatadir-Tuple{String, Union{Bool, String}}"><code>Persefone.createdatadir</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">createdatadir(outdir, overwrite)</code></pre><p>Creates the output directory, dealing with possible conflicts.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/output.jl#L11-L15">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.modellogger-Tuple{String, String}" href="#Persefone.modellogger-Tuple{String, String}"><code>Persefone.modellogger</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">modellogger(loglevel, outdir)</code></pre><p>Create a logger object that writes output both to screen and to a logfile. This object is stored as <code>model.logger</code> and can then be used with <code>with_logger()</code>. Note: requires <a href="io.html#Persefone.createdatadir-Tuple{String, Union{Bool, String}}"><code>createdatadir</code></a> to be run first.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/output.jl#L32-L38">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.newdataoutput!-Tuple{Agents.AgentBasedModel, String, String, Function, String}" href="#Persefone.newdataoutput!-Tuple{Agents.AgentBasedModel, String, String, Function, String}"><code>Persefone.newdataoutput!</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">newdataoutput!(model, filename, header, outputfunction, frequency)</code></pre><p>Create and register a new data output. This function must be called by all submodels that want to have their output functions called regularly.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/output.jl#L142-L147">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.outputdata-Tuple{Agents.AgentBasedModel}" href="#Persefone.outputdata-Tuple{Agents.AgentBasedModel}"><code>Persefone.outputdata</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">outputdata(model)</code></pre><p>Cycle through all registered data outputs and activate them according to their configured frequency.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/output.jl#L162-L167">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.prepareTOML-Tuple{Any}" href="#Persefone.prepareTOML-Tuple{Any}"><code>Persefone.prepareTOML</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">prepareTOML(dict)</code></pre><p>An internal utility function to re-convert the one-dimensional dict created by <a href="io.html#Persefone.flattenTOML-Tuple{Any}"><code>flattenTOML</code></a> into the two-dimensional dict needed by <code>TOML.print</code>, and convert any data types into TOML-compatible types where necessary.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/output.jl#L100-L106">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.saveinputfiles-Tuple{Agents.AgentBasedModel}" href="#Persefone.saveinputfiles-Tuple{Agents.AgentBasedModel}"><code>Persefone.saveinputfiles</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">saveinputfiles(model)</code></pre><p>Copy all input files into the output directory, including the actual parameter settings used. This allows replicating a run in future.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/output.jl#L66-L71">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.withtestlogger-Tuple{Agents.AgentBasedModel}" href="#Persefone.withtestlogger-Tuple{Agents.AgentBasedModel}"><code>Persefone.withtestlogger</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">withtestlogger(model)</code></pre><p>Replace the model logger with the currently active logger. This is intended to be used in the testsuite to circumvent a <a href="https://github.com/JuliaLang/julia/issues/48456">Julia issue</a>, where <code>@test_logs</code> doesn't work with local loggers.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/output.jl#L52-L58">source</a></section></article></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="simulation.html">« Simulation</a><a class="docs-footer-nextpage" href="nature.html">Nature »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.23 on <span class="colophon-date" title="Thursday 20 July 2023 16:01">Thursday 20 July 2023</span>. Using Julia version 1.9.1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
+<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Input, Output, and Settings · Persefone</title><script data-outdated-warner src="assets/warner.js"></script><link href="https://cdnjs.cloudflare.com/ajax/libs/lato-font/3.0.0/css/lato-font.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/juliamono/0.045/juliamono.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.13.24/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL="."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="assets/documenter.js"></script><script src="siteinfo.js"></script><script src="../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-dark.css" data-theme-name="documenter-dark" data-theme-primary-dark/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="assets/themeswap.js"></script></head><body><div id="documenter"><nav class="docs-sidebar"><a class="docs-logo" href="index.html"><img src="assets/logo.png" alt="Persefone logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="index.html">Persefone</a></span></div><form class="docs-search" action="search.html"><input class="docs-search-query" id="documenter-search-query" name="q" type="text" placeholder="Search docs"/></form><ul class="docs-menu"><li><a class="tocitem" href="index.html">Introduction</a></li><li><a class="tocitem" href="odd.html">Overview, Design, Details (ODD)</a></li><li><span class="tocitem">Developing</span><ul><li><a class="tocitem" href="developing.html">Developing Persefone</a></li><li><a class="tocitem" href="adapting.html">Adapting Persefone</a></li><li><a class="tocitem" href="architecture.html">Source code architecture</a></li><li><a class="tocitem" href="gis.html">Maps and weather data</a></li><li><a class="tocitem" href="species-dsl.html">Defining new species</a></li></ul></li><li><span class="tocitem">Core</span><ul><li><a class="tocitem" href="simulation.html">Simulation</a></li><li class="is-active"><a class="tocitem" href="io.html">Input, Output, and Settings</a><ul class="internal"><li><a class="tocitem" href="#parameters.toml"><span>parameters.toml</span></a></li><li><a class="tocitem" href="#input.jl"><span>input.jl</span></a></li><li><a class="tocitem" href="#output.jl"><span>output.jl</span></a></li></ul></li></ul></li><li><span class="tocitem">Nature</span><ul><li><a class="tocitem" href="nature.html">Nature</a></li><li><a class="tocitem" href="energy.html">Dynamic Energy Budgets</a></li><li><a class="tocitem" href="species.html">Species</a></li></ul></li><li><a class="tocitem" href="crops.html">Crop submodel</a></li><li><a class="tocitem" href="farm.html">Farm submodel</a></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><nav class="breadcrumb"><ul class="is-hidden-mobile"><li><a class="is-disabled">Core</a></li><li class="is-active"><a href="io.html">Input, Output, and Settings</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href="io.html">Input, Output, and Settings</a></li></ul></nav><div class="docs-right"><a class="docs-edit-link" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//docs/src/io.md#" title="Edit source"><span class="docs-icon fa"></span><span class="docs-label is-hidden-touch">Edit source</span></a><a class="docs-settings-button fas fa-cog" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-sidebar-button fa fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a></div></header><article class="content" id="documenter-page"><h1 id="Input,-Output,-and-Settings"><a class="docs-heading-anchor" href="#Input,-Output,-and-Settings">Input, Output, and Settings</a><a id="Input,-Output,-and-Settings-1"></a><a class="docs-heading-anchor-permalink" href="#Input,-Output,-and-Settings" title="Permalink"></a></h1><p>These functions are responsible for reading in all model configurations (passed by config file or commandline), administrating them during a run, and printing any output.</p><h2 id="parameters.toml"><a class="docs-heading-anchor" href="#parameters.toml">parameters.toml</a><a id="parameters.toml-1"></a><a class="docs-heading-anchor-permalink" href="#parameters.toml" title="Permalink"></a></h2><p>This is the default configuration file for Persefone, containing all model parameters. The syntax is described here: <a href="https://toml.io/en/">https://toml.io/en/</a></p><p>DO NOT MODIFY THIS FILE FOR SIMULATION EXPERIMENTS! Instead, copy it to another directory, modify the copy, and then pass it to the model using the <code>--config</code> parameter.</p><h2 id="input.jl"><a class="docs-heading-anchor" href="#input.jl">input.jl</a><a id="input.jl-1"></a><a class="docs-heading-anchor-permalink" href="#input.jl" title="Permalink"></a></h2><article class="docstring"><header><a class="docstring-binding" id="Persefone.PARAMFILE" href="#Persefone.PARAMFILE"><code>Persefone.PARAMFILE</code></a> — <span class="docstring-category">Constant</span></header><section><div><p>The file that stores all default parameters: <code>src/parameters.toml</code></p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/input.jl#L9-L11">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.flattenTOML-Tuple{Any}" href="#Persefone.flattenTOML-Tuple{Any}"><code>Persefone.flattenTOML</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">flattenTOML(dict)</code></pre><p>An internal utility function to convert the two-dimensional dict returned by <code>TOML.parsefile()</code> into a one-dimensional dict, so that instead of writing <code>settings["domain"]["param"]</code> one can use <code>settings["domain.param"]</code>. Can be reversed with <a href="io.html#Persefone.prepareTOML-Tuple{Any}"><code>prepareTOML</code></a>.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/input.jl#L97-L104">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.getsettings" href="#Persefone.getsettings"><code>Persefone.getsettings</code></a> — <span class="docstring-category">Function</span></header><section><div><pre><code class="language-julia hljs">getsettings(configfile, seed=nothing)</code></pre><p>Combines all configuration options to produce a single settings dict. Precedence: commandline parameters - user config file - default values</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/input.jl#L34-L39">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.parsecommandline-Tuple{}" href="#Persefone.parsecommandline-Tuple{}"><code>Persefone.parsecommandline</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">parsecommandline()</code></pre><p>Certain software parameters can be set via the commandline.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/input.jl#L137-L141">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.preprocessparameters-Tuple{Dict{String, Any}, String}" href="#Persefone.preprocessparameters-Tuple{Dict{String, Any}, String}"><code>Persefone.preprocessparameters</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">preprocessparameters(settings)</code></pre><p>Take the raw input parameters and process them (convert types, perform checks, etc.). This is a helper function for <a href="io.html#Persefone.getsettings"><code>getsettings</code></a>.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/input.jl#L72-L77">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.@param-Tuple{Any}" href="#Persefone.@param-Tuple{Any}"><code>Persefone.@param</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@param(domainparam)</code></pre><p>Return a configuration parameter from the global settings. The argument should be in the form <code><domain>.<parameter></code>, for example <code>@param(core.outdir)</code>. Possible values for <code><domain></code> are <code>core</code>, <code>nature</code>, <code>farm</code>, or <code>crop</code>. For a full list of parameters, see <code>src/parameters.toml</code>.</p><p>Note: this macro only works in a context where the <code>model</code> object is available!</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/input.jl#L16-L27">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.@rand-Tuple" href="#Persefone.@rand-Tuple"><code>Persefone.@rand</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@rand(args...)</code></pre><p>Return a random number or element from the sample, using the model RNG. This is a utility wrapper that can only be used a context where the <code>model</code> object is available.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/input.jl#L115-L121">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.@shuffle!-Tuple{Any}" href="#Persefone.@shuffle!-Tuple{Any}"><code>Persefone.@shuffle!</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@shuffle!(collection)</code></pre><p>Shuffle the given collection in place, using the model RNG. This is a utility wrapper that can only be used a context where the <code>model</code> object is available.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/input.jl#L126-L132">source</a></section></article><h2 id="output.jl"><a class="docs-heading-anchor" href="#output.jl">output.jl</a><a id="output.jl-1"></a><a class="docs-heading-anchor-permalink" href="#output.jl" title="Permalink"></a></h2><article class="docstring"><header><a class="docstring-binding" id="Persefone.DataOutput" href="#Persefone.DataOutput"><code>Persefone.DataOutput</code></a> — <span class="docstring-category">Type</span></header><section><div><pre><code class="language-julia hljs">DataOutput</code></pre><p>A struct for organising model output. This is designed for text-based data output that is updated more or less regularly (e.g. population data in csv files). Submodels can register their own output functions using <a href="io.html#Persefone.newdataoutput!-Tuple{Agents.AgentBasedModel, String, String, Function, String}"><code>newdataoutput!</code></a>.</p><p>Struct fields: - filename: the name of the file to be created in the user-specified output directory - header: a string to be written to the start of the file as it is initialised - outputfunction: a function that takes a model object and returns a string to write to file - frequency: how often to call the output function (daily/monthly/yearly/end/never)</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/output.jl#L122-L134">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.createdatadir-Tuple{String, Union{Bool, String}}" href="#Persefone.createdatadir-Tuple{String, Union{Bool, String}}"><code>Persefone.createdatadir</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">createdatadir(outdir, overwrite)</code></pre><p>Creates the output directory, dealing with possible conflicts.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/output.jl#L11-L15">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.modellogger-Tuple{String, String}" href="#Persefone.modellogger-Tuple{String, String}"><code>Persefone.modellogger</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">modellogger(loglevel, outdir)</code></pre><p>Create a logger object that writes output both to screen and to a logfile. This object is stored as <code>model.logger</code> and can then be used with <code>with_logger()</code>. Note: requires <a href="io.html#Persefone.createdatadir-Tuple{String, Union{Bool, String}}"><code>createdatadir</code></a> to be run first.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/output.jl#L32-L38">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.newdataoutput!-Tuple{Agents.AgentBasedModel, String, String, Function, String}" href="#Persefone.newdataoutput!-Tuple{Agents.AgentBasedModel, String, String, Function, String}"><code>Persefone.newdataoutput!</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">newdataoutput!(model, filename, header, outputfunction, frequency)</code></pre><p>Create and register a new data output. This function must be called by all submodels that want to have their output functions called regularly.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/output.jl#L142-L147">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.outputdata-Tuple{Agents.AgentBasedModel}" href="#Persefone.outputdata-Tuple{Agents.AgentBasedModel}"><code>Persefone.outputdata</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">outputdata(model)</code></pre><p>Cycle through all registered data outputs and activate them according to their configured frequency.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/output.jl#L162-L167">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.prepareTOML-Tuple{Any}" href="#Persefone.prepareTOML-Tuple{Any}"><code>Persefone.prepareTOML</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">prepareTOML(dict)</code></pre><p>An internal utility function to re-convert the one-dimensional dict created by <a href="io.html#Persefone.flattenTOML-Tuple{Any}"><code>flattenTOML</code></a> into the two-dimensional dict needed by <code>TOML.print</code>, and convert any data types into TOML-compatible types where necessary.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/output.jl#L100-L106">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.saveinputfiles-Tuple{Agents.AgentBasedModel}" href="#Persefone.saveinputfiles-Tuple{Agents.AgentBasedModel}"><code>Persefone.saveinputfiles</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">saveinputfiles(model)</code></pre><p>Copy all input files into the output directory, including the actual parameter settings used. This allows replicating a run in future.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/output.jl#L66-L71">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.withtestlogger-Tuple{Agents.AgentBasedModel}" href="#Persefone.withtestlogger-Tuple{Agents.AgentBasedModel}"><code>Persefone.withtestlogger</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">withtestlogger(model)</code></pre><p>Replace the model logger with the currently active logger. This is intended to be used in the testsuite to circumvent a <a href="https://github.com/JuliaLang/julia/issues/48456">Julia issue</a>, where <code>@test_logs</code> doesn't work with local loggers.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/output.jl#L52-L58">source</a></section></article></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="simulation.html">« Simulation</a><a class="docs-footer-nextpage" href="nature.html">Nature »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.23 on <span class="colophon-date" title="Thursday 27 July 2023 10:12">Thursday 27 July 2023</span>. Using Julia version 1.9.1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
diff --git a/docs/build/nature.html b/docs/build/nature.html
index 5178c11..d236d80 100644
--- a/docs/build/nature.html
+++ b/docs/build/nature.html
@@ -1,5 +1,5 @@
<!DOCTYPE html>
-<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Nature · Persefone</title><script data-outdated-warner src="assets/warner.js"></script><link href="https://cdnjs.cloudflare.com/ajax/libs/lato-font/3.0.0/css/lato-font.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/juliamono/0.045/juliamono.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.13.24/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL="."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="assets/documenter.js"></script><script src="siteinfo.js"></script><script src="../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-dark.css" data-theme-name="documenter-dark" data-theme-primary-dark/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="assets/themeswap.js"></script></head><body><div id="documenter"><nav class="docs-sidebar"><a class="docs-logo" href="index.html"><img src="assets/logo.png" alt="Persefone logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="index.html">Persefone</a></span></div><form class="docs-search" action="search.html"><input class="docs-search-query" id="documenter-search-query" name="q" type="text" placeholder="Search docs"/></form><ul class="docs-menu"><li><a class="tocitem" href="index.html">Introduction</a></li><li><a class="tocitem" href="odd.html">Overview, Design, Details (ODD)</a></li><li><span class="tocitem">Developing</span><ul><li><a class="tocitem" href="developing.html">Developing Persefone</a></li><li><a class="tocitem" href="adapting.html">Adapting Persefone</a></li><li><a class="tocitem" href="architecture.html">Source code architecture</a></li><li><a class="tocitem" href="gis.html">GIS data</a></li><li><a class="tocitem" href="species-dsl.html">Defining new species</a></li></ul></li><li><span class="tocitem">Core</span><ul><li><a class="tocitem" href="simulation.html">Simulation</a></li><li><a class="tocitem" href="io.html">Input, Output, and Settings</a></li></ul></li><li><span class="tocitem">Nature</span><ul><li class="is-active"><a class="tocitem" href="nature.html">Nature</a><ul class="internal"><li><a class="tocitem" href="#nature.jl"><span>nature.jl</span></a></li><li><a class="tocitem" href="#populations.jl"><span>populations.jl</span></a></li><li><a class="tocitem" href="#insects.jl"><span>insects.jl</span></a></li><li><a class="tocitem" href="#ecologicaldata.jl"><span>ecologicaldata.jl</span></a></li></ul></li><li><a class="tocitem" href="energy.html">Dynamic Energy Budgets</a></li><li><a class="tocitem" href="species.html">Species</a></li></ul></li><li><a class="tocitem" href="crops.html">Crop submodel</a></li><li><a class="tocitem" href="farm.html">Farm submodel</a></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><nav class="breadcrumb"><ul class="is-hidden-mobile"><li><a class="is-disabled">Nature</a></li><li class="is-active"><a href="nature.html">Nature</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href="nature.html">Nature</a></li></ul></nav><div class="docs-right"><a class="docs-edit-link" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//docs/src/nature.md#" title="Edit source"><span class="docs-icon fa"></span><span class="docs-label is-hidden-touch">Edit source</span></a><a class="docs-settings-button fas fa-cog" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-sidebar-button fa fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a></div></header><article class="content" id="documenter-page"><h1 id="Nature"><a class="docs-heading-anchor" href="#Nature">Nature</a><a id="Nature-1"></a><a class="docs-heading-anchor-permalink" href="#Nature" title="Permalink"></a></h1><h2 id="nature.jl"><a class="docs-heading-anchor" href="#nature.jl">nature.jl</a><a id="nature.jl-1"></a><a class="docs-heading-anchor-permalink" href="#nature.jl" title="Permalink"></a></h2><p>This file is responsible for managing the animal modules.</p><article class="docstring"><header><a class="docstring-binding" id="Persefone.Animal" href="#Persefone.Animal"><code>Persefone.Animal</code></a> — <span class="docstring-category">Type</span></header><section><div><pre><code class="language-julia hljs">Animal</code></pre><p>This is the generic agent type for all animals. Species are differentiated by trait dictionaries passed by them during initialisation. (Note that each trait variable can still be accessed as if it were a normal field name, i.e. the trait <code>phase</code> can be accessed and modified with <code>animal.phase</code>.)</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L12-L19">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.animalid-Tuple{Animal}" href="#Persefone.animalid-Tuple{Animal}"><code>Persefone.animalid</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">animalid(animal)</code></pre><p>A small utility function to return a string with the species name and ID of an animal.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L57-L61">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.initnature!-Tuple{Agents.AgentBasedModel}" href="#Persefone.initnature!-Tuple{Agents.AgentBasedModel}"><code>Persefone.initnature!</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">initnature!(model)</code></pre><p>Initialise the model with all simulated animal populations.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L76-L80">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.stepagent!-Tuple{Animal, Agents.AgentBasedModel}" href="#Persefone.stepagent!-Tuple{Animal, Agents.AgentBasedModel}"><code>Persefone.stepagent!</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">stepagent!(animal, model)</code></pre><p>Update an animal by one day, executing it's currently active phase function.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L66-L70">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.@countanimals-Tuple" href="#Persefone.@countanimals-Tuple"><code>Persefone.@countanimals</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@countanimals(species="", radius=0)</code></pre><p>Count the number of animals of the given species in this location. This is a utility wrapper that can only be used nested within <a href="nature.html#Persefone.@phase-Tuple{Any, Any}"><code>@phase</code></a> or <a href="nature.html#Persefone.@habitat-Tuple{Any}"><code>@habitat</code></a>.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L379-L385">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.@cropheight-Tuple{}" href="#Persefone.@cropheight-Tuple{}"><code>Persefone.@cropheight</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@cropheight</code></pre><p>Return the height of the crop at this position, or 0 if there is no crop here. This is a utility wrapper that can only be used nested within <a href="nature.html#Persefone.@phase-Tuple{Any, Any}"><code>@phase</code></a> or <a href="nature.html#Persefone.@habitat-Tuple{Any}"><code>@habitat</code></a>.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L346-L352">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.@croptype-Tuple{}" href="#Persefone.@croptype-Tuple{}"><code>Persefone.@croptype</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@croptype</code></pre><p>Return the local croptype, or nothing if there is no crop here. This is a utility wrapper that can only be used nested within <a href="nature.html#Persefone.@phase-Tuple{Any, Any}"><code>@phase</code></a> or <a href="nature.html#Persefone.@habitat-Tuple{Any}"><code>@habitat</code></a>.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L335-L341">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.@distanceto-Tuple{Any}" href="#Persefone.@distanceto-Tuple{Any}"><code>Persefone.@distanceto</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@distanceto(habitat)</code></pre><p>Calculate the distance to the closest habitat of the specified type or descriptor. This is a utility wrapper that can only be used nested within <a href="nature.html#Persefone.@phase-Tuple{Any, Any}"><code>@phase</code></a> or <a href="nature.html#Persefone.@habitat-Tuple{Any}"><code>@habitat</code></a>.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L357-L363">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.@distancetoedge-Tuple{}" href="#Persefone.@distancetoedge-Tuple{}"><code>Persefone.@distancetoedge</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@distancetoedge</code></pre><p>Calculate the distance to the closest neighbouring habitat. This is a utility wrapper that can only be used nested within <a href="nature.html#Persefone.@phase-Tuple{Any, Any}"><code>@phase</code></a> or <a href="nature.html#Persefone.@habitat-Tuple{Any}"><code>@habitat</code></a>.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L368-L374">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.@habitat-Tuple{Any}" href="#Persefone.@habitat-Tuple{Any}"><code>Persefone.@habitat</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@habitat</code></pre><p>Specify habitat suitability for spatial ecological processes.</p><p>This macro works by creating an anonymous function that takes in a model object and a position, and returns <code>true</code> or <code>false</code> depending on the conditions specified in the macro body.</p><p>Several utility macros can be used within the body of <code>@habitat</code> as a short-hand for common expressions: <a href="nature.html#Persefone.@landcover-Tuple{}"><code>@landcover</code></a>, <a href="nature.html#Persefone.@croptype-Tuple{}"><code>@croptype</code></a>, <a href="nature.html#Persefone.@cropheight-Tuple{}"><code>@cropheight</code></a>, <a href="nature.html#Persefone.@distanceto-Tuple{Any}"><code>@distanceto</code></a>, <a href="nature.html#Persefone.@distancetoedge-Tuple{}"><code>@distancetoedge</code></a>, <a href="nature.html#Persefone.@countanimals-Tuple"><code>@countanimals</code></a>. The variables <code>model</code> and <code>pos</code> can be used for checks that don't have a macro available.</p><p>Two example uses of <code>@habitat</code> might look like this:</p><pre><code class="language-julia hljs">movementhabitat = @habitat(@landcover() in (grass agriculture soil))
+<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Nature · Persefone</title><script data-outdated-warner src="assets/warner.js"></script><link href="https://cdnjs.cloudflare.com/ajax/libs/lato-font/3.0.0/css/lato-font.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/juliamono/0.045/juliamono.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.13.24/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL="."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="assets/documenter.js"></script><script src="siteinfo.js"></script><script src="../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-dark.css" data-theme-name="documenter-dark" data-theme-primary-dark/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="assets/themeswap.js"></script></head><body><div id="documenter"><nav class="docs-sidebar"><a class="docs-logo" href="index.html"><img src="assets/logo.png" alt="Persefone logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="index.html">Persefone</a></span></div><form class="docs-search" action="search.html"><input class="docs-search-query" id="documenter-search-query" name="q" type="text" placeholder="Search docs"/></form><ul class="docs-menu"><li><a class="tocitem" href="index.html">Introduction</a></li><li><a class="tocitem" href="odd.html">Overview, Design, Details (ODD)</a></li><li><span class="tocitem">Developing</span><ul><li><a class="tocitem" href="developing.html">Developing Persefone</a></li><li><a class="tocitem" href="adapting.html">Adapting Persefone</a></li><li><a class="tocitem" href="architecture.html">Source code architecture</a></li><li><a class="tocitem" href="gis.html">Maps and weather data</a></li><li><a class="tocitem" href="species-dsl.html">Defining new species</a></li></ul></li><li><span class="tocitem">Core</span><ul><li><a class="tocitem" href="simulation.html">Simulation</a></li><li><a class="tocitem" href="io.html">Input, Output, and Settings</a></li></ul></li><li><span class="tocitem">Nature</span><ul><li class="is-active"><a class="tocitem" href="nature.html">Nature</a><ul class="internal"><li><a class="tocitem" href="#nature.jl"><span>nature.jl</span></a></li><li><a class="tocitem" href="#populations.jl"><span>populations.jl</span></a></li><li><a class="tocitem" href="#insects.jl"><span>insects.jl</span></a></li><li><a class="tocitem" href="#ecologicaldata.jl"><span>ecologicaldata.jl</span></a></li></ul></li><li><a class="tocitem" href="energy.html">Dynamic Energy Budgets</a></li><li><a class="tocitem" href="species.html">Species</a></li></ul></li><li><a class="tocitem" href="crops.html">Crop submodel</a></li><li><a class="tocitem" href="farm.html">Farm submodel</a></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><nav class="breadcrumb"><ul class="is-hidden-mobile"><li><a class="is-disabled">Nature</a></li><li class="is-active"><a href="nature.html">Nature</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href="nature.html">Nature</a></li></ul></nav><div class="docs-right"><a class="docs-edit-link" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//docs/src/nature.md#" title="Edit source"><span class="docs-icon fa"></span><span class="docs-label is-hidden-touch">Edit source</span></a><a class="docs-settings-button fas fa-cog" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-sidebar-button fa fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a></div></header><article class="content" id="documenter-page"><h1 id="Nature"><a class="docs-heading-anchor" href="#Nature">Nature</a><a id="Nature-1"></a><a class="docs-heading-anchor-permalink" href="#Nature" title="Permalink"></a></h1><h2 id="nature.jl"><a class="docs-heading-anchor" href="#nature.jl">nature.jl</a><a id="nature.jl-1"></a><a class="docs-heading-anchor-permalink" href="#nature.jl" title="Permalink"></a></h2><p>This file is responsible for managing the animal modules.</p><article class="docstring"><header><a class="docstring-binding" id="Persefone.Animal" href="#Persefone.Animal"><code>Persefone.Animal</code></a> — <span class="docstring-category">Type</span></header><section><div><pre><code class="language-julia hljs">Animal</code></pre><p>This is the generic agent type for all animals. Species are differentiated by trait dictionaries passed by them during initialisation. (Note that each trait variable can still be accessed as if it were a normal field name, i.e. the trait <code>phase</code> can be accessed and modified with <code>animal.phase</code>.)</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L12-L19">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.animalid-Tuple{Animal}" href="#Persefone.animalid-Tuple{Animal}"><code>Persefone.animalid</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">animalid(animal)</code></pre><p>A small utility function to return a string with the species name and ID of an animal.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L57-L61">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.initnature!-Tuple{Agents.AgentBasedModel}" href="#Persefone.initnature!-Tuple{Agents.AgentBasedModel}"><code>Persefone.initnature!</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">initnature!(model)</code></pre><p>Initialise the model with all simulated animal populations.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L76-L80">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.stepagent!-Tuple{Animal, Agents.AgentBasedModel}" href="#Persefone.stepagent!-Tuple{Animal, Agents.AgentBasedModel}"><code>Persefone.stepagent!</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">stepagent!(animal, model)</code></pre><p>Update an animal by one day, executing it's currently active phase function.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L66-L70">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.@countanimals-Tuple" href="#Persefone.@countanimals-Tuple"><code>Persefone.@countanimals</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@countanimals(species="", radius=0)</code></pre><p>Count the number of animals of the given species in this location. This is a utility wrapper that can only be used nested within <a href="nature.html#Persefone.@phase-Tuple{Any, Any}"><code>@phase</code></a> or <a href="nature.html#Persefone.@habitat-Tuple{Any}"><code>@habitat</code></a>.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L379-L385">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.@cropheight-Tuple{}" href="#Persefone.@cropheight-Tuple{}"><code>Persefone.@cropheight</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@cropheight</code></pre><p>Return the height of the crop at this position, or 0 if there is no crop here. This is a utility wrapper that can only be used nested within <a href="nature.html#Persefone.@phase-Tuple{Any, Any}"><code>@phase</code></a> or <a href="nature.html#Persefone.@habitat-Tuple{Any}"><code>@habitat</code></a>.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L346-L352">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.@croptype-Tuple{}" href="#Persefone.@croptype-Tuple{}"><code>Persefone.@croptype</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@croptype</code></pre><p>Return the local croptype, or nothing if there is no crop here. This is a utility wrapper that can only be used nested within <a href="nature.html#Persefone.@phase-Tuple{Any, Any}"><code>@phase</code></a> or <a href="nature.html#Persefone.@habitat-Tuple{Any}"><code>@habitat</code></a>.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L335-L341">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.@distanceto-Tuple{Any}" href="#Persefone.@distanceto-Tuple{Any}"><code>Persefone.@distanceto</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@distanceto(habitat)</code></pre><p>Calculate the distance to the closest habitat of the specified type or descriptor. This is a utility wrapper that can only be used nested within <a href="nature.html#Persefone.@phase-Tuple{Any, Any}"><code>@phase</code></a> or <a href="nature.html#Persefone.@habitat-Tuple{Any}"><code>@habitat</code></a>.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L357-L363">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.@distancetoedge-Tuple{}" href="#Persefone.@distancetoedge-Tuple{}"><code>Persefone.@distancetoedge</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@distancetoedge</code></pre><p>Calculate the distance to the closest neighbouring habitat. This is a utility wrapper that can only be used nested within <a href="nature.html#Persefone.@phase-Tuple{Any, Any}"><code>@phase</code></a> or <a href="nature.html#Persefone.@habitat-Tuple{Any}"><code>@habitat</code></a>.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L368-L374">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.@habitat-Tuple{Any}" href="#Persefone.@habitat-Tuple{Any}"><code>Persefone.@habitat</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@habitat</code></pre><p>Specify habitat suitability for spatial ecological processes.</p><p>This macro works by creating an anonymous function that takes in a model object and a position, and returns <code>true</code> or <code>false</code> depending on the conditions specified in the macro body.</p><p>Several utility macros can be used within the body of <code>@habitat</code> as a short-hand for common expressions: <a href="nature.html#Persefone.@landcover-Tuple{}"><code>@landcover</code></a>, <a href="nature.html#Persefone.@croptype-Tuple{}"><code>@croptype</code></a>, <a href="nature.html#Persefone.@cropheight-Tuple{}"><code>@cropheight</code></a>, <a href="nature.html#Persefone.@distanceto-Tuple{Any}"><code>@distanceto</code></a>, <a href="nature.html#Persefone.@distancetoedge-Tuple{}"><code>@distancetoedge</code></a>, <a href="nature.html#Persefone.@countanimals-Tuple"><code>@countanimals</code></a>. The variables <code>model</code> and <code>pos</code> can be used for checks that don't have a macro available.</p><p>Two example uses of <code>@habitat</code> might look like this:</p><pre><code class="language-julia hljs">movementhabitat = @habitat(@landcover() in (grass agriculture soil))
nestinghabitat = @habitat((@landcover() == grass ||
(@landcover() == agriculture && @croptype() != maize &&
@@ -13,4 +13,4 @@ nestinghabitat = @habitat((@landcover() == grass ||
@phase phase1 begin
...
end
-end</code></pre><p>The definition body (enclosed in the begin/end block) has two sections. First comes a call to <a href="nature.html#Persefone.@initialise-Tuple{Any, Vararg{Any}}"><code>@initialise</code></a>, and optionally a list of species-specific parameters, which are assigned just like normal variables. Second come one or more phase definitions, that describe the behaviour of the species during various parts of its life cycle. (See the documentation to <a href="nature.html#Persefone.@initialise-Tuple{Any, Vararg{Any}}"><code>@initialise</code></a> and <a href="nature.html#Persefone.@phase-Tuple{Any, Any}"><code>@phase</code></a> for details).</p><p>Code in a species definition block can access the rest of the model using the <code>model</code> variable (an object of type <code>AgentBasedModel</code>).</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L99-L128">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.@trait-Tuple{Any}" href="#Persefone.@trait-Tuple{Any}"><code>Persefone.@trait</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@trait(traitname)</code></pre><p>A utility macro to quickly access an animal's trait value. This can only be used nested within <a href="nature.html#Persefone.@phase-Tuple{Any, Any}"><code>@phase</code></a>.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L207-L212">source</a></section></article><h2 id="populations.jl"><a class="docs-heading-anchor" href="#populations.jl">populations.jl</a><a id="populations.jl-1"></a><a class="docs-heading-anchor-permalink" href="#populations.jl" title="Permalink"></a></h2><p>This file contains a set of utility functions for species, including initialisation, reproduction, and mortality.</p><article class="docstring"><header><a class="docstring-binding" id="Persefone.countanimals-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel}" href="#Persefone.countanimals-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel}"><code>Persefone.countanimals</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">countanimals(pos, model; species="", radius=0)</code></pre><p>Count the number of animals in this location (optionally supplying a species name and radius).</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/populations.jl#L137-L141">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.initpopulation-Tuple{Function}" href="#Persefone.initpopulation-Tuple{Function}"><code>Persefone.initpopulation</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">initpopulation(habitatdescriptor; popsize=-1, pairs=false, asexual=false)</code></pre><p>Creates a function that initialises individuals at random locations across the landscape. This can be used to create the <code>initialise!</code> variable in a species definition block.</p><ul><li><p><code>habitatdescriptor</code> is a function that determines whether a given location is suitable or not (create this using <a href="nature.html#Persefone.@habitat-Tuple{Any}"><code>@habitat</code></a>).</p></li><li><p><code>phase</code> determines which life phase individuals will be assigned to. If this is <code>nothing</code>, the species' default post-natal life stage will be used (although note that this is probably not what you want).</p></li><li><p><code>popsize</code> determines the number of individuals that will be created. If this is zero or negative, one individual will be created in every suitable location in the landscape. If <code>popsize</code> is greater than the number of suitable locations, multiple individuals will be created in one place. (Maximum population density can be set in the habitat descriptor using the <a href="nature.html#Persefone.@countanimals-Tuple"><code>@countanimals</code></a> macro.)</p></li><li><p>If <code>pairs</code> is true, a male and a female individual will be created in each selected location, otherwise, only one individual will be created at a time.</p></li><li><p>If <code>asexual</code> is true, all created individuals are assigned the sex <code>hermaphrodite</code>, otherwise, they are randomly assigned male of female. (If <code>pairs</code> is true, <code>asexual</code> is ignored.)</p></li></ul></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/populations.jl#L7-L32">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.initrandompopulation-Tuple{Int64}" href="#Persefone.initrandompopulation-Tuple{Int64}"><code>Persefone.initrandompopulation</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">initrandompopulation(popsize; kwargs...)</code></pre><p>A simplified version of <a href="nature.html#Persefone.initpopulation-Tuple{Function}"><code>initpopulation</code></a>. Creates a function that initialises <code>popsize</code> individuals, spread at random across the landscape.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/populations.jl#L70-L75">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.kill!" href="#Persefone.kill!"><code>Persefone.kill!</code></a> — <span class="docstring-category">Function</span></header><section><div><pre><code class="language-julia hljs">kill(animal, model, probability=1.0, cause="")</code></pre><p>Kill this animal, optionally with a given percentage probability. Returns true if the animal dies, false if not.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/populations.jl#L99-L104">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.nearby_animals-Tuple{Animal, Agents.AgentBasedModel, Int64}" href="#Persefone.nearby_animals-Tuple{Animal, Agents.AgentBasedModel, Int64}"><code>Persefone.nearby_animals</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">nearby_animals(animal, model, radius)</code></pre><p>Return an iterator over all animals in the given radius around this animal, excluding itself.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/populations.jl#L126-L130">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.nearby_animals-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel, Int64}" href="#Persefone.nearby_animals-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel, Int64}"><code>Persefone.nearby_animals</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">nearby_animals(pos, model, radius)</code></pre><p>Return an iterator over all animals in the given radius around this position.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/populations.jl#L115-L119">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.reproduce!" href="#Persefone.reproduce!"><code>Persefone.reproduce!</code></a> — <span class="docstring-category">Function</span></header><section><div><pre><code class="language-julia hljs">reproduce!(animal, model, n=1)</code></pre><p>Produce one or more offspring for the given animal at its current location.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/populations.jl#L84-L88">source</a></section></article><h2 id="insects.jl"><a class="docs-heading-anchor" href="#insects.jl">insects.jl</a><a id="insects.jl-1"></a><a class="docs-heading-anchor-permalink" href="#insects.jl" title="Permalink"></a></h2><p>This file contains the insect submodel, which calculates the likely insect biomass in a given location at a given time.</p><article class="docstring"><header><a class="docstring-binding" id="Persefone.insectbiomass-Tuple{Pixel, Agents.AgentBasedModel}" href="#Persefone.insectbiomass-Tuple{Pixel, Agents.AgentBasedModel}"><code>Persefone.insectbiomass</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">insectbiomass(pixel, model)</code></pre><p>Calculate the insect biomass in this location, using the factors configured in the <code>nature.insectmodel</code> settings (any combination of: "season", "habitat", "weather", "pesticides"). Returns a float value in g/m².</p><p><strong>Biological note:</strong> this is a very approximate calculation! Insect biomass varies wildly in time and space and is hard to measure. This calculation is based on the idea of a parabolic seasonal development of insect abundance, modified by habitat suitability, weather, and pesticide application. Although it is based on empirical studies, it can only deliver a rough, order-of-magnitude estimation of likely insect biomass in a given location.</p><p><strong>Sources:</strong></p><ul><li>Odderskær et al. (1997). Skylark Reproduction in Pesticide Treated and Untreated Fields (32; Pesticides Research). Danish Environmental Protection Agency.</li><li>Grüebler et al. (2008). A predictive model of the density of airborne insects in agricultural environments. Agriculture, Ecosystems & Environment, 123(1), 75–80. https://doi.org/10.1016/j.agee.2007.05.001</li><li>Paquette et al. (2013). Seasonal patterns in Tree Swallow prey (Diptera) abundance are affected by agricultural intensification. Ecological Applications, 23(1), 122–133. https://doi.org/10.1890/12-0068.1</li><li>Püttmanns et al. (2022). Habitat use and foraging parameters of breeding Skylarks indicate no seasonal decrease in food availability in heterogeneous farmland. Ecology and Evolution, 12(1), e8461. https://doi.org/10.1002/ece3.8461</li></ul></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/insects.jl#L6-L26">source</a></section></article><h2 id="ecologicaldata.jl"><a class="docs-heading-anchor" href="#ecologicaldata.jl">ecologicaldata.jl</a><a id="ecologicaldata.jl-1"></a><a class="docs-heading-anchor-permalink" href="#ecologicaldata.jl" title="Permalink"></a></h2><p>This file contains a set of life-history related utility functions needed by species.</p><article class="docstring"><header><a class="docstring-binding" id="Persefone.initecologicaldata-Tuple{Agents.AgentBasedModel}" href="#Persefone.initecologicaldata-Tuple{Agents.AgentBasedModel}"><code>Persefone.initecologicaldata</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">initecologicaldata()</code></pre><p>Create output files for each data group collected by the nature model.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/ecologicaldata.jl#L9-L13">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.saveindividualdata-Tuple{Agents.AgentBasedModel}" href="#Persefone.saveindividualdata-Tuple{Agents.AgentBasedModel}"><code>Persefone.saveindividualdata</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">saveindividualdata(model)</code></pre><p>Return a comma-separated set of lines (to be printed to <code>individuals.csv</code>), listing all properties of all animal individuals in the model. May be called never, daily, monthly, yearly, or at the end of a simulation, depending on the parameter <code>nature.indoutfreq</code>. WARNING: Produces very big files!</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/ecologicaldata.jl#L42-L49">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.savepopulationdata-Tuple{Agents.AgentBasedModel}" href="#Persefone.savepopulationdata-Tuple{Agents.AgentBasedModel}"><code>Persefone.savepopulationdata</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">savepopulationdata(model)</code></pre><p>Return a comma-separated set of lines (to be printed to <code>populations.csv</code>), giving the current date and population size for each animal species. May be called never, daily, monthly, yearly, or at the end of a simulation, depending on the parameter <code>nature.popoutfreq</code>.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/ecologicaldata.jl#L21-L28">source</a></section></article></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="io.html">« Input, Output, and Settings</a><a class="docs-footer-nextpage" href="energy.html">Dynamic Energy Budgets »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.23 on <span class="colophon-date" title="Thursday 20 July 2023 16:01">Thursday 20 July 2023</span>. Using Julia version 1.9.1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
+end</code></pre><p>The definition body (enclosed in the begin/end block) has two sections. First comes a call to <a href="nature.html#Persefone.@initialise-Tuple{Any, Vararg{Any}}"><code>@initialise</code></a>, and optionally a list of species-specific parameters, which are assigned just like normal variables. Second come one or more phase definitions, that describe the behaviour of the species during various parts of its life cycle. (See the documentation to <a href="nature.html#Persefone.@initialise-Tuple{Any, Vararg{Any}}"><code>@initialise</code></a> and <a href="nature.html#Persefone.@phase-Tuple{Any, Any}"><code>@phase</code></a> for details).</p><p>Code in a species definition block can access the rest of the model using the <code>model</code> variable (an object of type <code>AgentBasedModel</code>).</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L99-L128">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.@trait-Tuple{Any}" href="#Persefone.@trait-Tuple{Any}"><code>Persefone.@trait</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@trait(traitname)</code></pre><p>A utility macro to quickly access an animal's trait value. This can only be used nested within <a href="nature.html#Persefone.@phase-Tuple{Any, Any}"><code>@phase</code></a>.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L207-L212">source</a></section></article><h2 id="populations.jl"><a class="docs-heading-anchor" href="#populations.jl">populations.jl</a><a id="populations.jl-1"></a><a class="docs-heading-anchor-permalink" href="#populations.jl" title="Permalink"></a></h2><p>This file contains a set of utility functions for species, including initialisation, reproduction, and mortality.</p><article class="docstring"><header><a class="docstring-binding" id="Persefone.countanimals-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel}" href="#Persefone.countanimals-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel}"><code>Persefone.countanimals</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">countanimals(pos, model; species="", radius=0)</code></pre><p>Count the number of animals in this location (optionally supplying a species name and radius).</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/populations.jl#L137-L141">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.initpopulation-Tuple{Function}" href="#Persefone.initpopulation-Tuple{Function}"><code>Persefone.initpopulation</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">initpopulation(habitatdescriptor; popsize=-1, pairs=false, asexual=false)</code></pre><p>Creates a function that initialises individuals at random locations across the landscape. This can be used to create the <code>initialise!</code> variable in a species definition block.</p><ul><li><p><code>habitatdescriptor</code> is a function that determines whether a given location is suitable or not (create this using <a href="nature.html#Persefone.@habitat-Tuple{Any}"><code>@habitat</code></a>).</p></li><li><p><code>phase</code> determines which life phase individuals will be assigned to. If this is <code>nothing</code>, the species' default post-natal life stage will be used (although note that this is probably not what you want).</p></li><li><p><code>popsize</code> determines the number of individuals that will be created. If this is zero or negative, one individual will be created in every suitable location in the landscape. If <code>popsize</code> is greater than the number of suitable locations, multiple individuals will be created in one place. (Maximum population density can be set in the habitat descriptor using the <a href="nature.html#Persefone.@countanimals-Tuple"><code>@countanimals</code></a> macro.)</p></li><li><p>If <code>pairs</code> is true, a male and a female individual will be created in each selected location, otherwise, only one individual will be created at a time.</p></li><li><p>If <code>asexual</code> is true, all created individuals are assigned the sex <code>hermaphrodite</code>, otherwise, they are randomly assigned male of female. (If <code>pairs</code> is true, <code>asexual</code> is ignored.)</p></li></ul></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/populations.jl#L7-L32">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.initrandompopulation-Tuple{Int64}" href="#Persefone.initrandompopulation-Tuple{Int64}"><code>Persefone.initrandompopulation</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">initrandompopulation(popsize; kwargs...)</code></pre><p>A simplified version of <a href="nature.html#Persefone.initpopulation-Tuple{Function}"><code>initpopulation</code></a>. Creates a function that initialises <code>popsize</code> individuals, spread at random across the landscape.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/populations.jl#L70-L75">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.kill!" href="#Persefone.kill!"><code>Persefone.kill!</code></a> — <span class="docstring-category">Function</span></header><section><div><pre><code class="language-julia hljs">kill(animal, model, probability=1.0, cause="")</code></pre><p>Kill this animal, optionally with a given percentage probability. Returns true if the animal dies, false if not.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/populations.jl#L99-L104">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.nearby_animals-Tuple{Animal, Agents.AgentBasedModel, Int64}" href="#Persefone.nearby_animals-Tuple{Animal, Agents.AgentBasedModel, Int64}"><code>Persefone.nearby_animals</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">nearby_animals(animal, model, radius)</code></pre><p>Return an iterator over all animals in the given radius around this animal, excluding itself.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/populations.jl#L126-L130">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.nearby_animals-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel, Int64}" href="#Persefone.nearby_animals-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel, Int64}"><code>Persefone.nearby_animals</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">nearby_animals(pos, model, radius)</code></pre><p>Return an iterator over all animals in the given radius around this position.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/populations.jl#L115-L119">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.reproduce!" href="#Persefone.reproduce!"><code>Persefone.reproduce!</code></a> — <span class="docstring-category">Function</span></header><section><div><pre><code class="language-julia hljs">reproduce!(animal, model, n=1)</code></pre><p>Produce one or more offspring for the given animal at its current location.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/populations.jl#L84-L88">source</a></section></article><h2 id="insects.jl"><a class="docs-heading-anchor" href="#insects.jl">insects.jl</a><a id="insects.jl-1"></a><a class="docs-heading-anchor-permalink" href="#insects.jl" title="Permalink"></a></h2><p>This file contains the insect submodel, which calculates the likely insect biomass in a given location at a given time.</p><article class="docstring"><header><a class="docstring-binding" id="Persefone.insectbiomass-Tuple{Pixel, Agents.AgentBasedModel}" href="#Persefone.insectbiomass-Tuple{Pixel, Agents.AgentBasedModel}"><code>Persefone.insectbiomass</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">insectbiomass(pixel, model)</code></pre><p>Calculate the insect biomass in this location, using the factors configured in the <code>nature.insectmodel</code> settings (any combination of: "season", "habitat", "weather", "pesticides"). Returns a float value in g/m².</p><p><strong>Biological note:</strong> this is a very approximate calculation! Insect biomass varies wildly in time and space and is hard to measure. This calculation is based on the idea of a parabolic seasonal development of insect abundance, modified by habitat suitability, weather, and pesticide application. Although it is based on empirical studies, it can only deliver a rough, order-of-magnitude estimation of likely insect biomass in a given location.</p><p><strong>Sources:</strong></p><ul><li>Odderskær et al. (1997). Skylark Reproduction in Pesticide Treated and Untreated Fields (32; Pesticides Research). Danish Environmental Protection Agency.</li><li>Grüebler et al. (2008). A predictive model of the density of airborne insects in agricultural environments. Agriculture, Ecosystems & Environment, 123(1), 75–80. https://doi.org/10.1016/j.agee.2007.05.001</li><li>Paquette et al. (2013). Seasonal patterns in Tree Swallow prey (Diptera) abundance are affected by agricultural intensification. Ecological Applications, 23(1), 122–133. https://doi.org/10.1890/12-0068.1</li><li>Püttmanns et al. (2022). Habitat use and foraging parameters of breeding Skylarks indicate no seasonal decrease in food availability in heterogeneous farmland. Ecology and Evolution, 12(1), e8461. https://doi.org/10.1002/ece3.8461</li></ul></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/insects.jl#L6-L26">source</a></section></article><h2 id="ecologicaldata.jl"><a class="docs-heading-anchor" href="#ecologicaldata.jl">ecologicaldata.jl</a><a id="ecologicaldata.jl-1"></a><a class="docs-heading-anchor-permalink" href="#ecologicaldata.jl" title="Permalink"></a></h2><p>This file contains a set of life-history related utility functions needed by species.</p><article class="docstring"><header><a class="docstring-binding" id="Persefone.initecologicaldata-Tuple{Agents.AgentBasedModel}" href="#Persefone.initecologicaldata-Tuple{Agents.AgentBasedModel}"><code>Persefone.initecologicaldata</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">initecologicaldata()</code></pre><p>Create output files for each data group collected by the nature model.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/ecologicaldata.jl#L9-L13">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.saveindividualdata-Tuple{Agents.AgentBasedModel}" href="#Persefone.saveindividualdata-Tuple{Agents.AgentBasedModel}"><code>Persefone.saveindividualdata</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">saveindividualdata(model)</code></pre><p>Return a comma-separated set of lines (to be printed to <code>individuals.csv</code>), listing all properties of all animal individuals in the model. May be called never, daily, monthly, yearly, or at the end of a simulation, depending on the parameter <code>nature.indoutfreq</code>. WARNING: Produces very big files!</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/ecologicaldata.jl#L42-L49">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.savepopulationdata-Tuple{Agents.AgentBasedModel}" href="#Persefone.savepopulationdata-Tuple{Agents.AgentBasedModel}"><code>Persefone.savepopulationdata</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">savepopulationdata(model)</code></pre><p>Return a comma-separated set of lines (to be printed to <code>populations.csv</code>), giving the current date and population size for each animal species. May be called never, daily, monthly, yearly, or at the end of a simulation, depending on the parameter <code>nature.popoutfreq</code>.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/ecologicaldata.jl#L21-L28">source</a></section></article></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="io.html">« Input, Output, and Settings</a><a class="docs-footer-nextpage" href="energy.html">Dynamic Energy Budgets »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.23 on <span class="colophon-date" title="Thursday 27 July 2023 10:12">Thursday 27 July 2023</span>. Using Julia version 1.9.1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
diff --git a/docs/build/odd.html b/docs/build/odd.html
index 5cd4517..c42b2c0 100644
--- a/docs/build/odd.html
+++ b/docs/build/odd.html
@@ -1,2 +1,2 @@
<!DOCTYPE html>
-<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Overview, Design, Details (ODD) · Persefone</title><script data-outdated-warner src="assets/warner.js"></script><link href="https://cdnjs.cloudflare.com/ajax/libs/lato-font/3.0.0/css/lato-font.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/juliamono/0.045/juliamono.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.13.24/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL="."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="assets/documenter.js"></script><script src="siteinfo.js"></script><script src="../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-dark.css" data-theme-name="documenter-dark" data-theme-primary-dark/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="assets/themeswap.js"></script></head><body><div id="documenter"><nav class="docs-sidebar"><a class="docs-logo" href="index.html"><img src="assets/logo.png" alt="Persefone logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="index.html">Persefone</a></span></div><form class="docs-search" action="search.html"><input class="docs-search-query" id="documenter-search-query" name="q" type="text" placeholder="Search docs"/></form><ul class="docs-menu"><li><a class="tocitem" href="index.html">Introduction</a></li><li class="is-active"><a class="tocitem" href="odd.html">Overview, Design, Details (ODD)</a></li><li><span class="tocitem">Developing</span><ul><li><a class="tocitem" href="developing.html">Developing Persefone</a></li><li><a class="tocitem" href="adapting.html">Adapting Persefone</a></li><li><a class="tocitem" href="architecture.html">Source code architecture</a></li><li><a class="tocitem" href="gis.html">GIS data</a></li><li><a class="tocitem" href="species-dsl.html">Defining new species</a></li></ul></li><li><span class="tocitem">Core</span><ul><li><a class="tocitem" href="simulation.html">Simulation</a></li><li><a class="tocitem" href="io.html">Input, Output, and Settings</a></li></ul></li><li><span class="tocitem">Nature</span><ul><li><a class="tocitem" href="nature.html">Nature</a></li><li><a class="tocitem" href="energy.html">Dynamic Energy Budgets</a></li><li><a class="tocitem" href="species.html">Species</a></li></ul></li><li><a class="tocitem" href="crops.html">Crop submodel</a></li><li><a class="tocitem" href="farm.html">Farm submodel</a></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><nav class="breadcrumb"><ul class="is-hidden-mobile"><li class="is-active"><a href="odd.html">Overview, Design, Details (ODD)</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href="odd.html">Overview, Design, Details (ODD)</a></li></ul></nav><div class="docs-right"><a class="docs-edit-link" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//docs/src/odd.md#" title="Edit source"><span class="docs-icon fa"></span><span class="docs-label is-hidden-touch">Edit source</span></a><a class="docs-settings-button fas fa-cog" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-sidebar-button fa fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a></div></header><article class="content" id="documenter-page"><h1 id="Overview,-Design,-Details-(ODD)"><a class="docs-heading-anchor" href="#Overview,-Design,-Details-(ODD)">Overview, Design, Details (ODD)</a><a id="Overview,-Design,-Details-(ODD)-1"></a><a class="docs-heading-anchor-permalink" href="#Overview,-Design,-Details-(ODD)" title="Permalink"></a></h1><p><em>TODO</em></p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="index.html">« Introduction</a><a class="docs-footer-nextpage" href="developing.html">Developing Persefone »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.23 on <span class="colophon-date" title="Thursday 20 July 2023 16:01">Thursday 20 July 2023</span>. Using Julia version 1.9.1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
+<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Overview, Design, Details (ODD) · Persefone</title><script data-outdated-warner src="assets/warner.js"></script><link href="https://cdnjs.cloudflare.com/ajax/libs/lato-font/3.0.0/css/lato-font.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/juliamono/0.045/juliamono.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.13.24/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL="."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="assets/documenter.js"></script><script src="siteinfo.js"></script><script src="../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-dark.css" data-theme-name="documenter-dark" data-theme-primary-dark/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="assets/themeswap.js"></script></head><body><div id="documenter"><nav class="docs-sidebar"><a class="docs-logo" href="index.html"><img src="assets/logo.png" alt="Persefone logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="index.html">Persefone</a></span></div><form class="docs-search" action="search.html"><input class="docs-search-query" id="documenter-search-query" name="q" type="text" placeholder="Search docs"/></form><ul class="docs-menu"><li><a class="tocitem" href="index.html">Introduction</a></li><li class="is-active"><a class="tocitem" href="odd.html">Overview, Design, Details (ODD)</a></li><li><span class="tocitem">Developing</span><ul><li><a class="tocitem" href="developing.html">Developing Persefone</a></li><li><a class="tocitem" href="adapting.html">Adapting Persefone</a></li><li><a class="tocitem" href="architecture.html">Source code architecture</a></li><li><a class="tocitem" href="gis.html">Maps and weather data</a></li><li><a class="tocitem" href="species-dsl.html">Defining new species</a></li></ul></li><li><span class="tocitem">Core</span><ul><li><a class="tocitem" href="simulation.html">Simulation</a></li><li><a class="tocitem" href="io.html">Input, Output, and Settings</a></li></ul></li><li><span class="tocitem">Nature</span><ul><li><a class="tocitem" href="nature.html">Nature</a></li><li><a class="tocitem" href="energy.html">Dynamic Energy Budgets</a></li><li><a class="tocitem" href="species.html">Species</a></li></ul></li><li><a class="tocitem" href="crops.html">Crop submodel</a></li><li><a class="tocitem" href="farm.html">Farm submodel</a></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><nav class="breadcrumb"><ul class="is-hidden-mobile"><li class="is-active"><a href="odd.html">Overview, Design, Details (ODD)</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href="odd.html">Overview, Design, Details (ODD)</a></li></ul></nav><div class="docs-right"><a class="docs-edit-link" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//docs/src/odd.md#" title="Edit source"><span class="docs-icon fa"></span><span class="docs-label is-hidden-touch">Edit source</span></a><a class="docs-settings-button fas fa-cog" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-sidebar-button fa fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a></div></header><article class="content" id="documenter-page"><h1 id="Overview,-Design,-Details-(ODD)"><a class="docs-heading-anchor" href="#Overview,-Design,-Details-(ODD)">Overview, Design, Details (ODD)</a><a id="Overview,-Design,-Details-(ODD)-1"></a><a class="docs-heading-anchor-permalink" href="#Overview,-Design,-Details-(ODD)" title="Permalink"></a></h1><p><em>TODO</em></p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="index.html">« Introduction</a><a class="docs-footer-nextpage" href="developing.html">Developing Persefone »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.23 on <span class="colophon-date" title="Thursday 27 July 2023 10:12">Thursday 27 July 2023</span>. Using Julia version 1.9.1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
diff --git a/docs/build/search.html b/docs/build/search.html
index be55e2c..53a8f35 100644
--- a/docs/build/search.html
+++ b/docs/build/search.html
@@ -1,2 +1,2 @@
<!DOCTYPE html>
-<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Search · Persefone</title><script data-outdated-warner src="assets/warner.js"></script><link href="https://cdnjs.cloudflare.com/ajax/libs/lato-font/3.0.0/css/lato-font.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/juliamono/0.045/juliamono.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.13.24/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL="."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="assets/documenter.js"></script><script src="siteinfo.js"></script><script src="../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-dark.css" data-theme-name="documenter-dark" data-theme-primary-dark/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="assets/themeswap.js"></script></head><body><div id="documenter"><nav class="docs-sidebar"><a class="docs-logo" href="index.html"><img src="assets/logo.png" alt="Persefone logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="index.html">Persefone</a></span></div><form class="docs-search" action="search.html"><input class="docs-search-query" id="documenter-search-query" name="q" type="text" placeholder="Search docs"/></form><ul class="docs-menu"><li><a class="tocitem" href="index.html">Introduction</a></li><li><a class="tocitem" href="odd.html">Overview, Design, Details (ODD)</a></li><li><span class="tocitem">Developing</span><ul><li><a class="tocitem" href="developing.html">Developing Persefone</a></li><li><a class="tocitem" href="adapting.html">Adapting Persefone</a></li><li><a class="tocitem" href="architecture.html">Source code architecture</a></li><li><a class="tocitem" href="gis.html">GIS data</a></li><li><a class="tocitem" href="species-dsl.html">Defining new species</a></li></ul></li><li><span class="tocitem">Core</span><ul><li><a class="tocitem" href="simulation.html">Simulation</a></li><li><a class="tocitem" href="io.html">Input, Output, and Settings</a></li></ul></li><li><span class="tocitem">Nature</span><ul><li><a class="tocitem" href="nature.html">Nature</a></li><li><a class="tocitem" href="energy.html">Dynamic Energy Budgets</a></li><li><a class="tocitem" href="species.html">Species</a></li></ul></li><li><a class="tocitem" href="crops.html">Crop submodel</a></li><li><a class="tocitem" href="farm.html">Farm submodel</a></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><nav class="breadcrumb"><ul class="is-hidden-mobile"><li class="is-active"><a href="search.html">Search</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href="search.html">Search</a></li></ul></nav><div class="docs-right"><a class="docs-settings-button fas fa-cog" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-sidebar-button fa fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a></div></header><article><p id="documenter-search-info">Loading search...</p><ul id="documenter-search-results"></ul></article><nav class="docs-footer"><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.23 on <span class="colophon-date" title="Thursday 20 July 2023 16:01">Thursday 20 July 2023</span>. Using Julia version 1.9.1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body><script src="search_index.js"></script><script src="assets/search.js"></script></html>
+<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Search · Persefone</title><script data-outdated-warner src="assets/warner.js"></script><link href="https://cdnjs.cloudflare.com/ajax/libs/lato-font/3.0.0/css/lato-font.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/juliamono/0.045/juliamono.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.13.24/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL="."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="assets/documenter.js"></script><script src="siteinfo.js"></script><script src="../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-dark.css" data-theme-name="documenter-dark" data-theme-primary-dark/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="assets/themeswap.js"></script></head><body><div id="documenter"><nav class="docs-sidebar"><a class="docs-logo" href="index.html"><img src="assets/logo.png" alt="Persefone logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="index.html">Persefone</a></span></div><form class="docs-search" action="search.html"><input class="docs-search-query" id="documenter-search-query" name="q" type="text" placeholder="Search docs"/></form><ul class="docs-menu"><li><a class="tocitem" href="index.html">Introduction</a></li><li><a class="tocitem" href="odd.html">Overview, Design, Details (ODD)</a></li><li><span class="tocitem">Developing</span><ul><li><a class="tocitem" href="developing.html">Developing Persefone</a></li><li><a class="tocitem" href="adapting.html">Adapting Persefone</a></li><li><a class="tocitem" href="architecture.html">Source code architecture</a></li><li><a class="tocitem" href="gis.html">Maps and weather data</a></li><li><a class="tocitem" href="species-dsl.html">Defining new species</a></li></ul></li><li><span class="tocitem">Core</span><ul><li><a class="tocitem" href="simulation.html">Simulation</a></li><li><a class="tocitem" href="io.html">Input, Output, and Settings</a></li></ul></li><li><span class="tocitem">Nature</span><ul><li><a class="tocitem" href="nature.html">Nature</a></li><li><a class="tocitem" href="energy.html">Dynamic Energy Budgets</a></li><li><a class="tocitem" href="species.html">Species</a></li></ul></li><li><a class="tocitem" href="crops.html">Crop submodel</a></li><li><a class="tocitem" href="farm.html">Farm submodel</a></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><nav class="breadcrumb"><ul class="is-hidden-mobile"><li class="is-active"><a href="search.html">Search</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href="search.html">Search</a></li></ul></nav><div class="docs-right"><a class="docs-settings-button fas fa-cog" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-sidebar-button fa fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a></div></header><article><p id="documenter-search-info">Loading search...</p><ul id="documenter-search-results"></ul></article><nav class="docs-footer"><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.23 on <span class="colophon-date" title="Thursday 27 July 2023 10:12">Thursday 27 July 2023</span>. Using Julia version 1.9.1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body><script src="search_index.js"></script><script src="assets/search.js"></script></html>
diff --git a/docs/build/search_index.js b/docs/build/search_index.js
index 0f62030..9f16808 100644
--- a/docs/build/search_index.js
+++ b/docs/build/search_index.js
@@ -1,3 +1,3 @@
var documenterSearchIndex = {"docs":
-[{"location":"energy.html#Dynamic-Energy-Budgets","page":"Dynamic Energy Budgets","title":"Dynamic Energy Budgets","text":"","category":"section"},{"location":"energy.html","page":"Dynamic Energy Budgets","title":"Dynamic Energy Budgets","text":"Persefone's nature module uses Kooijman's Dynamic Energy Budget theory to model energy flows within individuals.","category":"page"},{"location":"energy.html","page":"Dynamic Energy Budgets","title":"Dynamic Energy Budgets","text":"(Image: \"The standard model of the Dynamic Energy Budget theory\")","category":"page"},{"location":"energy.html","page":"Dynamic Energy Budgets","title":"Dynamic Energy Budgets","text":"The standard model of the Dynamic Energy Budget theory. (Fig. 1 from Sousa et al. (2010).)","category":"page"},{"location":"energy.html","page":"Dynamic Energy Budgets","title":"Dynamic Energy Budgets","text":"Sousa et al. (2010). Dynamic energy budget theory restores coherence in biology. Philosophical Transactions of the Royal Society B: Biological Sciences, 365(1557), 3413–3428.\nKooijman, S. A. L. M. (2009). Dynamic energy and mass budgets in biological systems (3rd ed). Cambridge University Press.\nSibly et al. (2013). Representing the acquisition and use of energy by individuals in agent-based models of animal populations. Methods in Ecology and Evolution, 4(2), 151–161.","category":"page"},{"location":"energy.html#energy.jl","page":"Dynamic Energy Budgets","title":"energy.jl","text":"","category":"section"},{"location":"energy.html","page":"Dynamic Energy Budgets","title":"Dynamic Energy Budgets","text":"Modules = [Persefone]\nPages = [\"nature/energy.jl\"]","category":"page"},{"location":"energy.html#Persefone.DEBparameters","page":"Dynamic Energy Budgets","title":"Persefone.DEBparameters","text":"DEBparameters\n\nAn immutable struct to save the parameter list for a species' Dynamic Energy Budget model. (See Sousa et al., 2010.)\n\n\n\n\n\n","category":"type"},{"location":"energy.html#Persefone.EnergyBudget","page":"Dynamic Energy Budgets","title":"Persefone.EnergyBudget","text":"EnergyBudget\n\nThis struct represents an individual's energy balance, as conceptualised by the Dynamic Energy Budget theory. Upon assimilation, energy is first stored as biomass in a reserve buffer, before being used for maintenance, growth, and reproduction. (Note that this is a simplified model form which ignores maturity as a separate buffer.)\n\nSources:\n\nMalishev & Kramer-Schadt (2021). Movement, models, and metabolism: Individual-based energy budget models as next-generation extensions for predicting animal movement outcomes across scales. Ecological Modelling, 441, 109413. https://doi.org/10.1016/j.ecolmodel.2020.109413\nMarques et al. (2018). The AmP project: Comparing species on the basis of dynamic energy budget parameters. PLOS Computational Biology,14(5), e1006100. https://doi.org/10.1371/journal.pcbi.1006100\nSibly et al. (2013). Representing the acquisition and use of energy by individuals in agent-based models of animal populations. Methods in Ecology and Evolution, 4(2), 151–161. https://doi.org/10.1111/2041-210x.12002\nSousa et al. (2010). Dynamic energy budget theory restores coherence in biology. Philosophical Transactions of the Royal Society B: Biological Sciences, 365(1557), 3413–3428. https://doi.org/10.1098/rstb.2010.0166\nKooijman, S. A. L. M. (2009). Dynamic energy and mass budgets in biological systems (3rd ed). Cambridge University Press. https://www.researchgate.net/profile/Edgar-Meza-3/post/Isthereatoxicokineticmodelfordaphniamagnaorotherzooplankton/attachment/59d62cf579197b807798b396/AS%3A348547653357569%401460111644286/download/Dynamic+Energy+Budget+theory+-+Kooijman.pdf\nsee also: Brown et al. (2004). Toward a metabolic theory of ecology. Ecology, 85(7), 1771–1789. https://doi.org/10.1890/03-9000\n\n\n\n\n\n","category":"type"},{"location":"energy.html#Persefone.feed!-Tuple{Float64, Persefone.EnergyBudget}","page":"Dynamic Energy Budgets","title":"Persefone.feed!","text":"feed!(quantity, energybudget)\n\nConsume a given quantity of food. Expands the energy reserve by an amount determined by the assimilation rate. Returns true if successful, false if the reserve is already full.\n\n\n\n\n\n","category":"method"},{"location":"energy.html#Persefone.growthrate-Tuple{Persefone.EnergyBudget}","page":"Dynamic Energy Budgets","title":"Persefone.growthrate","text":"growthrate(energybudget)\n\nCalculate the specific growth rate r. (Internal function.)\n\n\n\n\n\n","category":"method"},{"location":"energy.html#Persefone.investmentratio-Tuple{Persefone.EnergyBudget}","page":"Dynamic Energy Budgets","title":"Persefone.investmentratio","text":"investmentratio(energybudget)\n\nCalculate the investment ratio g. (Internal function.)\n\n\n\n\n\n","category":"method"},{"location":"energy.html#Persefone.maturitymaintenance-Tuple{Persefone.EnergyBudget}","page":"Dynamic Energy Budgets","title":"Persefone.maturitymaintenance","text":"maturitymaintenance(energybudget)\n\nCalculate the specific maturity maintenance k_J. (Internal function.)\n\n\n\n\n\n","category":"method"},{"location":"energy.html#Persefone.mobilisation-Tuple{Persefone.EnergyBudget}","page":"Dynamic Energy Budgets","title":"Persefone.mobilisation","text":"mobilisation(energybudget)\n\nCalculate the mobilisation rate J_EC. (Internal function.)\n\n\n\n\n\n","category":"method"},{"location":"energy.html#Persefone.reproduce!-Tuple{Persefone.EnergyBudget}","page":"Dynamic Energy Budgets","title":"Persefone.reproduce!","text":"reproduce!(energybudget)\n\nIf there is sufficient energy in the offspring buffer of an adult, produce an embryo/egg, reducing the parent energy in the process. Returns the embryo's energy budget, or nothing if the conditions are not met.\n\n\n\n\n\n","category":"method"},{"location":"energy.html#Persefone.scaledreservedensity-Tuple{Persefone.EnergyBudget}","page":"Dynamic Energy Budgets","title":"Persefone.scaledreservedensity","text":"scaledreservedensity(energybudget)\n\nCalculate the scaled reserve density e. (Internal function.)\n\n\n\n\n\n","category":"method"},{"location":"energy.html#Persefone.update!-Tuple{Persefone.EnergyBudget}","page":"Dynamic Energy Budgets","title":"Persefone.update!","text":"update!(energybudget)\n\nCarry out a daily update of the energy budget. Mobilises reserves and allocates these to maintenance (prioritised), growth, and reproduction.\n\nReturn true if the individual has enough energy to survive, or false if the reserve is empty and it starves.\n\n\n\n\n\n","category":"method"},{"location":"energy.html#Persefone.volumetriclength-Tuple{Persefone.EnergyBudget}","page":"Dynamic Energy Budgets","title":"Persefone.volumetriclength","text":"volumetriclength(energybudget)\n\nCalculate the structural length in cm based on an individual's weight (assuming a density of 1 g/cm³ to calculate volume, see Kooijman 2009).\n\n\n\n\n\n","category":"method"},{"location":"nature.html#Nature","page":"Nature","title":"Nature","text":"","category":"section"},{"location":"nature.html#nature.jl","page":"Nature","title":"nature.jl","text":"","category":"section"},{"location":"nature.html","page":"Nature","title":"Nature","text":"This file is responsible for managing the animal modules.","category":"page"},{"location":"nature.html","page":"Nature","title":"Nature","text":"Modules = [Persefone]\nPages = [\"nature/nature.jl\"]","category":"page"},{"location":"nature.html#Persefone.Animal","page":"Nature","title":"Persefone.Animal","text":"Animal\n\nThis is the generic agent type for all animals. Species are differentiated by trait dictionaries passed by them during initialisation. (Note that each trait variable can still be accessed as if it were a normal field name, i.e. the trait phase can be accessed and modified with animal.phase.)\n\n\n\n\n\n","category":"type"},{"location":"nature.html#Persefone.animalid-Tuple{Animal}","page":"Nature","title":"Persefone.animalid","text":"animalid(animal)\n\nA small utility function to return a string with the species name and ID of an animal.\n\n\n\n\n\n","category":"method"},{"location":"nature.html#Persefone.initnature!-Tuple{Agents.AgentBasedModel}","page":"Nature","title":"Persefone.initnature!","text":"initnature!(model)\n\nInitialise the model with all simulated animal populations.\n\n\n\n\n\n","category":"method"},{"location":"nature.html#Persefone.stepagent!-Tuple{Animal, Agents.AgentBasedModel}","page":"Nature","title":"Persefone.stepagent!","text":"stepagent!(animal, model)\n\nUpdate an animal by one day, executing it's currently active phase function.\n\n\n\n\n\n","category":"method"},{"location":"nature.html#Persefone.@countanimals-Tuple","page":"Nature","title":"Persefone.@countanimals","text":"@countanimals(species=\"\", radius=0)\n\nCount the number of animals of the given species in this location. This is a utility wrapper that can only be used nested within @phase or @habitat.\n\n\n\n\n\n","category":"macro"},{"location":"nature.html#Persefone.@cropheight-Tuple{}","page":"Nature","title":"Persefone.@cropheight","text":"@cropheight\n\nReturn the height of the crop at this position, or 0 if there is no crop here. This is a utility wrapper that can only be used nested within @phase or @habitat.\n\n\n\n\n\n","category":"macro"},{"location":"nature.html#Persefone.@croptype-Tuple{}","page":"Nature","title":"Persefone.@croptype","text":"@croptype\n\nReturn the local croptype, or nothing if there is no crop here. This is a utility wrapper that can only be used nested within @phase or @habitat.\n\n\n\n\n\n","category":"macro"},{"location":"nature.html#Persefone.@distanceto-Tuple{Any}","page":"Nature","title":"Persefone.@distanceto","text":"@distanceto(habitat)\n\nCalculate the distance to the closest habitat of the specified type or descriptor. This is a utility wrapper that can only be used nested within @phase or @habitat.\n\n\n\n\n\n","category":"macro"},{"location":"nature.html#Persefone.@distancetoedge-Tuple{}","page":"Nature","title":"Persefone.@distancetoedge","text":"@distancetoedge\n\nCalculate the distance to the closest neighbouring habitat. This is a utility wrapper that can only be used nested within @phase or @habitat.\n\n\n\n\n\n","category":"macro"},{"location":"nature.html#Persefone.@habitat-Tuple{Any}","page":"Nature","title":"Persefone.@habitat","text":"@habitat\n\nSpecify habitat suitability for spatial ecological processes.\n\nThis macro works by creating an anonymous function that takes in a model object and a position, and returns true or false depending on the conditions specified in the macro body.\n\nSeveral utility macros can be used within the body of @habitat as a short-hand for common expressions: @landcover, @croptype, @cropheight, @distanceto, @distancetoedge, @countanimals. The variables model and pos can be used for checks that don't have a macro available.\n\nTwo example uses of @habitat might look like this:\n\nmovementhabitat = @habitat(@landcover() in (grass agriculture soil))\n\nnestinghabitat = @habitat((@landcover() == grass || \n (@landcover() == agriculture && @croptype() != maize &&\n @cropheight() < 10)) &&\n @distanceto(forest) > 20)\n\nFor more complex habitat suitability checks, the use of this macro can be circumvented by directly creating an equivalent function.\n\n\n\n\n\n","category":"macro"},{"location":"nature.html#Persefone.@initialise-Tuple{Any, Vararg{Any}}","page":"Nature","title":"Persefone.@initialise","text":"@initialise(habitatdescriptor; kwargs...)\n\nCall this macro within the body of @species. It passes the given habitat descriptor function and keyword arguments on to initpopulation when setting up the simulation.\n\nNote: if this macro is not used, the variable initialise! must be set manually in the species definition.\n\n\n\n\n\n","category":"macro"},{"location":"nature.html#Persefone.@kill-Tuple","page":"Nature","title":"Persefone.@kill","text":"@kill\n\nKill this animal (and immediately abort its current update). This is a thin wrapper around kill!, and passes on any arguments. This can only be used nested within @phase.\n\n\n\n\n\n","category":"macro"},{"location":"nature.html#Persefone.@landcover-Tuple{}","page":"Nature","title":"Persefone.@landcover","text":"@landcover\n\nReturns the local landcover. This is a utility wrapper that can only be used nested within @phase or @habitat.\n\n\n\n\n\n","category":"macro"},{"location":"nature.html#Persefone.@neighbours-Tuple{Any}","page":"Nature","title":"Persefone.@neighbours","text":"@neighbours(radius)\n\nReturn an iterator over all animals in the given radius around this animal, excluding itself. This can only be used nested within @phase.\n\n\n\n\n\n","category":"macro"},{"location":"nature.html#Persefone.@phase-Tuple{Any, Any}","page":"Nature","title":"Persefone.@phase","text":"@phase(name, body)\n\nThis macro is designed to be used within a species definition block (i.e. within the body of a call to @species).\n\nThe idea behind this is that species show very different behaviour during different phases of their lives. Therefore, @phase can be used define the behaviour for one such phase, and the conditions under which the animal transitions to another phase.\n\n@phase works by creating a function that will be called by the model if the animal is in the relevant phase. When it is called, it has access to the following variables:\n\nanimal a reference to the animal itself. This provides access to animal.age, animal.sex, and animal.<trait> (where <trait> is a variable that was defined in the top part of the species definition body).\npos gives the animal's current position as a coordinate tuple.\nmodel a reference to the model world (an object of type AgentBasedModel). This allows access to model.date (the current simulation date) and model.landscape (a two-dimensional array of pixels containing geographic information).\n\nSeveral utility macros can be used within the body of @phase as a short-hand for common expressions: @trait, @setphase, @respond, @kill, @reproduce, @neighbours, @rand, @shuffle!.\n\nNote that the first phase that is defined in a species definition block will be the phase that animals are assigned at birth, unless the variable phase is explicitly defined by the user in the species definition block.\n\n\n\n\n\n","category":"macro"},{"location":"nature.html#Persefone.@reproduce-Tuple","page":"Nature","title":"Persefone.@reproduce","text":"@reproduce\n\nLet this animal reproduce. This is a thin wrapper around reproduce!, and passes on any arguments. This can only be used nested within @phase.\n\n\n\n\n\n","category":"macro"},{"location":"nature.html#Persefone.@respond-Tuple{Any, Any}","page":"Nature","title":"Persefone.@respond","text":"@respond(eventname, body)\n\nDefine how an animal responds to a landscape event that affects its current position. This can only be used nested within @phase.\n\n\n\n\n\n","category":"macro"},{"location":"nature.html#Persefone.@setphase-Tuple{Any}","page":"Nature","title":"Persefone.@setphase","text":"@setphase(newphase)\n\nSwitch this animal over to a different phase. This can only be used nested within @phase.\n\n\n\n\n\n","category":"macro"},{"location":"nature.html#Persefone.@species-Tuple{Any, Any}","page":"Nature","title":"Persefone.@species","text":"@species(name, body)\n\nA macro used to create new species definitions for the nature model. This is effectively a simple domain-specific language, establishing a custom syntax to describe species' biology:\n\n@species name begin\n\n @initialise(@habitat(...))\n speciesvar1 = 3.14\n ...\n\n @phase phase1 begin\n ...\n end\nend\n\nThe definition body (enclosed in the begin/end block) has two sections. First comes a call to @initialise, and optionally a list of species-specific parameters, which are assigned just like normal variables. Second come one or more phase definitions, that describe the behaviour of the species during various parts of its life cycle. (See the documentation to @initialise and @phase for details).\n\nCode in a species definition block can access the rest of the model using the model variable (an object of type AgentBasedModel).\n\n\n\n\n\n","category":"macro"},{"location":"nature.html#Persefone.@trait-Tuple{Any}","page":"Nature","title":"Persefone.@trait","text":"@trait(traitname)\n\nA utility macro to quickly access an animal's trait value. This can only be used nested within @phase.\n\n\n\n\n\n","category":"macro"},{"location":"nature.html#populations.jl","page":"Nature","title":"populations.jl","text":"","category":"section"},{"location":"nature.html","page":"Nature","title":"Nature","text":"This file contains a set of utility functions for species, including initialisation, reproduction, and mortality.","category":"page"},{"location":"nature.html","page":"Nature","title":"Nature","text":"Modules = [Persefone]\nPages = [\"nature/populations.jl\"]","category":"page"},{"location":"nature.html#Persefone.countanimals-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel}","page":"Nature","title":"Persefone.countanimals","text":"countanimals(pos, model; species=\"\", radius=0)\n\nCount the number of animals in this location (optionally supplying a species name and radius).\n\n\n\n\n\n","category":"method"},{"location":"nature.html#Persefone.initpopulation-Tuple{Function}","page":"Nature","title":"Persefone.initpopulation","text":"initpopulation(habitatdescriptor; popsize=-1, pairs=false, asexual=false)\n\nCreates a function that initialises individuals at random locations across the landscape. This can be used to create the initialise! variable in a species definition block.\n\nhabitatdescriptor is a function that determines whether a given location is suitable or not (create this using @habitat).\nphase determines which life phase individuals will be assigned to. If this is nothing, the species' default post-natal life stage will be used (although note that this is probably not what you want).\npopsize determines the number of individuals that will be created. If this is zero or negative, one individual will be created in every suitable location in the landscape. If popsize is greater than the number of suitable locations, multiple individuals will be created in one place. (Maximum population density can be set in the habitat descriptor using the @countanimals macro.)\nIf pairs is true, a male and a female individual will be created in each selected location, otherwise, only one individual will be created at a time.\nIf asexual is true, all created individuals are assigned the sex hermaphrodite, otherwise, they are randomly assigned male of female. (If pairs is true, asexual is ignored.)\n\n\n\n\n\n","category":"method"},{"location":"nature.html#Persefone.initrandompopulation-Tuple{Int64}","page":"Nature","title":"Persefone.initrandompopulation","text":"initrandompopulation(popsize; kwargs...)\n\nA simplified version of initpopulation. Creates a function that initialises popsize individuals, spread at random across the landscape.\n\n\n\n\n\n","category":"method"},{"location":"nature.html#Persefone.kill!","page":"Nature","title":"Persefone.kill!","text":"kill(animal, model, probability=1.0, cause=\"\")\n\nKill this animal, optionally with a given percentage probability. Returns true if the animal dies, false if not.\n\n\n\n\n\n","category":"function"},{"location":"nature.html#Persefone.nearby_animals-Tuple{Animal, Agents.AgentBasedModel, Int64}","page":"Nature","title":"Persefone.nearby_animals","text":"nearby_animals(animal, model, radius)\n\nReturn an iterator over all animals in the given radius around this animal, excluding itself.\n\n\n\n\n\n","category":"method"},{"location":"nature.html#Persefone.nearby_animals-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel, Int64}","page":"Nature","title":"Persefone.nearby_animals","text":"nearby_animals(pos, model, radius)\n\nReturn an iterator over all animals in the given radius around this position.\n\n\n\n\n\n","category":"method"},{"location":"nature.html#Persefone.reproduce!","page":"Nature","title":"Persefone.reproduce!","text":"reproduce!(animal, model, n=1)\n\nProduce one or more offspring for the given animal at its current location.\n\n\n\n\n\n","category":"function"},{"location":"nature.html#insects.jl","page":"Nature","title":"insects.jl","text":"","category":"section"},{"location":"nature.html","page":"Nature","title":"Nature","text":"This file contains the insect submodel, which calculates the likely insect biomass in a given location at a given time.","category":"page"},{"location":"nature.html","page":"Nature","title":"Nature","text":"Modules = [Persefone]\nPages = [\"nature/insects.jl\"]","category":"page"},{"location":"nature.html#Persefone.insectbiomass-Tuple{Pixel, Agents.AgentBasedModel}","page":"Nature","title":"Persefone.insectbiomass","text":"insectbiomass(pixel, model)\n\nCalculate the insect biomass in this location, using the factors configured in the nature.insectmodel settings (any combination of: \"season\", \"habitat\", \"weather\", \"pesticides\"). Returns a float value in g/m².\n\nBiological note: this is a very approximate calculation! Insect biomass varies wildly in time and space and is hard to measure. This calculation is based on the idea of a parabolic seasonal development of insect abundance, modified by habitat suitability, weather, and pesticide application. Although it is based on empirical studies, it can only deliver a rough, order-of-magnitude estimation of likely insect biomass in a given location.\n\nSources:\n\nOdderskær et al. (1997). Skylark Reproduction in Pesticide Treated and Untreated Fields (32; Pesticides Research). Danish Environmental Protection Agency.\nGrüebler et al. (2008). A predictive model of the density of airborne insects in agricultural environments. Agriculture, Ecosystems & Environment, 123(1), 75–80. https://doi.org/10.1016/j.agee.2007.05.001\nPaquette et al. (2013). Seasonal patterns in Tree Swallow prey (Diptera) abundance are affected by agricultural intensification. Ecological Applications, 23(1), 122–133. https://doi.org/10.1890/12-0068.1\nPüttmanns et al. (2022). Habitat use and foraging parameters of breeding Skylarks indicate no seasonal decrease in food availability in heterogeneous farmland. Ecology and Evolution, 12(1), e8461. https://doi.org/10.1002/ece3.8461\n\n\n\n\n\n","category":"method"},{"location":"nature.html#ecologicaldata.jl","page":"Nature","title":"ecologicaldata.jl","text":"","category":"section"},{"location":"nature.html","page":"Nature","title":"Nature","text":"This file contains a set of life-history related utility functions needed by species.","category":"page"},{"location":"nature.html","page":"Nature","title":"Nature","text":"Modules = [Persefone]\nPages = [\"nature/ecologicaldata.jl\"]","category":"page"},{"location":"nature.html#Persefone.initecologicaldata-Tuple{Agents.AgentBasedModel}","page":"Nature","title":"Persefone.initecologicaldata","text":"initecologicaldata()\n\nCreate output files for each data group collected by the nature model.\n\n\n\n\n\n","category":"method"},{"location":"nature.html#Persefone.saveindividualdata-Tuple{Agents.AgentBasedModel}","page":"Nature","title":"Persefone.saveindividualdata","text":"saveindividualdata(model)\n\nReturn a comma-separated set of lines (to be printed to individuals.csv), listing all properties of all animal individuals in the model. May be called never, daily, monthly, yearly, or at the end of a simulation, depending on the parameter nature.indoutfreq. WARNING: Produces very big files!\n\n\n\n\n\n","category":"method"},{"location":"nature.html#Persefone.savepopulationdata-Tuple{Agents.AgentBasedModel}","page":"Nature","title":"Persefone.savepopulationdata","text":"savepopulationdata(model)\n\nReturn a comma-separated set of lines (to be printed to populations.csv), giving the current date and population size for each animal species. May be called never, daily, monthly, yearly, or at the end of a simulation, depending on the parameter nature.popoutfreq.\n\n\n\n\n\n","category":"method"},{"location":"io.html#Input,-Output,-and-Settings","page":"Input, Output, and Settings","title":"Input, Output, and Settings","text":"","category":"section"},{"location":"io.html","page":"Input, Output, and Settings","title":"Input, Output, and Settings","text":"These functions are responsible for reading in all model configurations (passed by config file or commandline), administrating them during a run, and printing any output.","category":"page"},{"location":"io.html#parameters.toml","page":"Input, Output, and Settings","title":"parameters.toml","text":"","category":"section"},{"location":"io.html","page":"Input, Output, and Settings","title":"Input, Output, and Settings","text":"This is the default configuration file for Persefone, containing all model parameters. The syntax is described here: https://toml.io/en/","category":"page"},{"location":"io.html","page":"Input, Output, and Settings","title":"Input, Output, and Settings","text":"DO NOT MODIFY THIS FILE FOR SIMULATION EXPERIMENTS! Instead, copy it to another directory, modify the copy, and then pass it to the model using the --config parameter.","category":"page"},{"location":"io.html#input.jl","page":"Input, Output, and Settings","title":"input.jl","text":"","category":"section"},{"location":"io.html","page":"Input, Output, and Settings","title":"Input, Output, and Settings","text":"Modules = [Persefone]\nPages = [\"core/input.jl\"]","category":"page"},{"location":"io.html#Persefone.PARAMFILE","page":"Input, Output, and Settings","title":"Persefone.PARAMFILE","text":"The file that stores all default parameters: src/parameters.toml\n\n\n\n\n\n","category":"constant"},{"location":"io.html#Persefone.flattenTOML-Tuple{Any}","page":"Input, Output, and Settings","title":"Persefone.flattenTOML","text":"flattenTOML(dict)\n\nAn internal utility function to convert the two-dimensional dict returned by TOML.parsefile() into a one-dimensional dict, so that instead of writing settings[\"domain\"][\"param\"] one can use settings[\"domain.param\"]. Can be reversed with prepareTOML.\n\n\n\n\n\n","category":"method"},{"location":"io.html#Persefone.getsettings","page":"Input, Output, and Settings","title":"Persefone.getsettings","text":"getsettings(configfile, seed=nothing)\n\nCombines all configuration options to produce a single settings dict. Precedence: commandline parameters - user config file - default values\n\n\n\n\n\n","category":"function"},{"location":"io.html#Persefone.parsecommandline-Tuple{}","page":"Input, Output, and Settings","title":"Persefone.parsecommandline","text":"parsecommandline()\n\nCertain software parameters can be set via the commandline.\n\n\n\n\n\n","category":"method"},{"location":"io.html#Persefone.preprocessparameters-Tuple{Dict{String, Any}, String}","page":"Input, Output, and Settings","title":"Persefone.preprocessparameters","text":"preprocessparameters(settings)\n\nTake the raw input parameters and process them (convert types, perform checks, etc.). This is a helper function for getsettings.\n\n\n\n\n\n","category":"method"},{"location":"io.html#Persefone.@param-Tuple{Any}","page":"Input, Output, and Settings","title":"Persefone.@param","text":"@param(domainparam)\n\nReturn a configuration parameter from the global settings. The argument should be in the form <domain>.<parameter>, for example @param(core.outdir). Possible values for <domain> are core, nature, farm, or crop. For a full list of parameters, see src/parameters.toml.\n\nNote: this macro only works in a context where the model object is available!\n\n\n\n\n\n","category":"macro"},{"location":"io.html#Persefone.@rand-Tuple","page":"Input, Output, and Settings","title":"Persefone.@rand","text":"@rand(args...)\n\nReturn a random number or element from the sample, using the model RNG. This is a utility wrapper that can only be used a context where the model object is available.\n\n\n\n\n\n","category":"macro"},{"location":"io.html#Persefone.@shuffle!-Tuple{Any}","page":"Input, Output, and Settings","title":"Persefone.@shuffle!","text":"@shuffle!(collection)\n\nShuffle the given collection in place, using the model RNG. This is a utility wrapper that can only be used a context where the model object is available.\n\n\n\n\n\n","category":"macro"},{"location":"io.html#output.jl","page":"Input, Output, and Settings","title":"output.jl","text":"","category":"section"},{"location":"io.html","page":"Input, Output, and Settings","title":"Input, Output, and Settings","text":"Modules = [Persefone]\nPages = [\"core/output.jl\"]","category":"page"},{"location":"io.html#Persefone.DataOutput","page":"Input, Output, and Settings","title":"Persefone.DataOutput","text":"DataOutput\n\nA struct for organising model output. This is designed for text-based data output that is updated more or less regularly (e.g. population data in csv files). Submodels can register their own output functions using newdataoutput!.\n\nStruct fields: - filename: the name of the file to be created in the user-specified output directory - header: a string to be written to the start of the file as it is initialised - outputfunction: a function that takes a model object and returns a string to write to file - frequency: how often to call the output function (daily/monthly/yearly/end/never)\n\n\n\n\n\n","category":"type"},{"location":"io.html#Persefone.createdatadir-Tuple{String, Union{Bool, String}}","page":"Input, Output, and Settings","title":"Persefone.createdatadir","text":"createdatadir(outdir, overwrite)\n\nCreates the output directory, dealing with possible conflicts.\n\n\n\n\n\n","category":"method"},{"location":"io.html#Persefone.modellogger-Tuple{String, String}","page":"Input, Output, and Settings","title":"Persefone.modellogger","text":"modellogger(loglevel, outdir)\n\nCreate a logger object that writes output both to screen and to a logfile. This object is stored as model.logger and can then be used with with_logger(). Note: requires createdatadir to be run first.\n\n\n\n\n\n","category":"method"},{"location":"io.html#Persefone.newdataoutput!-Tuple{Agents.AgentBasedModel, String, String, Function, String}","page":"Input, Output, and Settings","title":"Persefone.newdataoutput!","text":"newdataoutput!(model, filename, header, outputfunction, frequency)\n\nCreate and register a new data output. This function must be called by all submodels that want to have their output functions called regularly.\n\n\n\n\n\n","category":"method"},{"location":"io.html#Persefone.outputdata-Tuple{Agents.AgentBasedModel}","page":"Input, Output, and Settings","title":"Persefone.outputdata","text":"outputdata(model)\n\nCycle through all registered data outputs and activate them according to their configured frequency.\n\n\n\n\n\n","category":"method"},{"location":"io.html#Persefone.prepareTOML-Tuple{Any}","page":"Input, Output, and Settings","title":"Persefone.prepareTOML","text":"prepareTOML(dict)\n\nAn internal utility function to re-convert the one-dimensional dict created by flattenTOML into the two-dimensional dict needed by TOML.print, and convert any data types into TOML-compatible types where necessary.\n\n\n\n\n\n","category":"method"},{"location":"io.html#Persefone.saveinputfiles-Tuple{Agents.AgentBasedModel}","page":"Input, Output, and Settings","title":"Persefone.saveinputfiles","text":"saveinputfiles(model)\n\nCopy all input files into the output directory, including the actual parameter settings used. This allows replicating a run in future.\n\n\n\n\n\n","category":"method"},{"location":"io.html#Persefone.withtestlogger-Tuple{Agents.AgentBasedModel}","page":"Input, Output, and Settings","title":"Persefone.withtestlogger","text":"withtestlogger(model)\n\nReplace the model logger with the currently active logger. This is intended to be used in the testsuite to circumvent a Julia issue, where @test_logs doesn't work with local loggers.\n\n\n\n\n\n","category":"method"},{"location":"architecture.html#Source-code-architecture","page":"Source code architecture","title":"Source code architecture","text":"","category":"section"},{"location":"architecture.html#Model-components","page":"Source code architecture","title":"Model components","text":"","category":"section"},{"location":"architecture.html","page":"Source code architecture","title":"Source code architecture","text":"(Image: \"model architecture\")","category":"page"},{"location":"architecture.html","page":"Source code architecture","title":"Source code architecture","text":"Persefone is divided into four components, three of which are semi-independent submodels:","category":"page"},{"location":"architecture.html","page":"Source code architecture","title":"Source code architecture","text":"core: This is the foundation of the model software, which sets up and executes simulation runs. It also reads in the configuration file and landscape maps, and provides data output functionality. (Eventually, it will also provide weather data.)\nnature: This is an individual-based model of species in agricultural landscapes. It defines the Animal agent type, and a set of macros that can be used to rapidly create new species. It also includes ecological process functions that are useful for all species.\nfarm: This is an agent-based model of farmer decision making. It is not yet implemented, but will provide the Farmer agent type.\ncrop: This is a mathematical growth model for various crops. It is not yet implemented, but already provides the agent type FarmPlot, representing one field and its associated extent and crop type.","category":"page"},{"location":"architecture.html","page":"Source code architecture","title":"Source code architecture","text":"Conceptually, core provides functionality that is needed by all of the submodels. Decisions made by Farmers affect the FarmPlots they own, and (directly or indirectly) the Animals in the model landscape.","category":"page"},{"location":"architecture.html#Important-implementation-details","page":"Source code architecture","title":"Important implementation details","text":"","category":"section"},{"location":"architecture.html","page":"Source code architecture","title":"Source code architecture","text":"(Image: \"the model object\")","category":"page"},{"location":"architecture.html#The-model-object","page":"Source code architecture","title":"The model object","text":"","category":"section"},{"location":"architecture.html","page":"Source code architecture","title":"Source code architecture","text":"A cursory reading of the source code will quickly show that most functions take an AgentBasedModel object as one of their arguments. This is the key data structure of Agents.jl, and holds all state that is in any way relevant to a simulation run. (Persefone has a strict \"no global state\" policy to avoid state-dependent bugs and allow parallelisation.) The model object gives access to all agent instances (via model[id], where id is the unique identifier of this agent). It also stores the configuration (model.settings), the landscape (model.landscape, a matrix of Pixel objects that store the local land cover, amongst other things), and the current simulation date (model.date). (See initmodel for details.)","category":"page"},{"location":"architecture.html","page":"Source code architecture","title":"Source code architecture","text":"For more information about working with agent objects, see the Agents.jl API.","category":"page"},{"location":"architecture.html#Model-configuration/the-@param-macro","page":"Source code architecture","title":"Model configuration/the @param macro","text":"","category":"section"},{"location":"architecture.html","page":"Source code architecture","title":"Source code architecture","text":"The model is configured via a TOML file, the default version of which is at src/parameters.toml. An individual run can be configured using a user-defined configuration file, commandline arguments, or function calls (when Persefone is used as a package rather than an application). During a model run, the @param macro can be used to access parameter values. Note that parameter names are prepended with the name of the component they are associated with. For example, the outdir parameter belongs to the [core] section of the TOML file, and must therefore be referenced as @param(core.outdir). (See src/core/input.jl for details.)","category":"page"},{"location":"architecture.html","page":"Source code architecture","title":"Source code architecture","text":"info: @param and other macros\nAs @param(parameter) expands to model.settings[\"parameter\"], it can obviously only be used in a context where the model object is actually available. (This is the case for most functions in Persefone, but not for all.) Similarly, many of the nature macros depend on specific variables being available where they are called, and can therefore only be used in specific contexts (this is indicated in their documentation).","category":"page"},{"location":"architecture.html#Output-data","page":"Source code architecture","title":"Output data","text":"","category":"section"},{"location":"architecture.html","page":"Source code architecture","title":"Source code architecture","text":"Persefone can output model data into text files with a specified frequency (daily, monthly, yearly, or at the simulation end). Submodels can use newdataoutput! to plug into this system. For an example of how to use this, see src/nature/ecologicaldata.jl. (See src/core/output.jl for details.)","category":"page"},{"location":"architecture.html#Farm-events","page":"Source code architecture","title":"Farm events","text":"","category":"section"},{"location":"architecture.html","page":"Source code architecture","title":"Source code architecture","text":"The FarmEvent struct is used to communicate farming-related events between submodels. An event can be triggered with createevent! and affects all pixels within a FarmPlot. (See src/core/landscape.jl for details.)","category":"page"},{"location":"architecture.html#Random-numbers-and-logging","page":"Source code architecture","title":"Random numbers and logging","text":"","category":"section"},{"location":"architecture.html","page":"Source code architecture","title":"Source code architecture","text":"By default in Julia, the random number generator (RNG) and the system logger are two globally accessible variables. As Persefone needs to avoid all global data (since this would interfere with reproducibility in parallel runs), the model object stores a local logger and a local RNG. The local logger generally does not change the way the model uses log statements, it is only relevant for some functions in src/core/simulation.jl.","category":"page"},{"location":"architecture.html","page":"Source code architecture","title":"Source code architecture","text":"info: Using the model RNG\nWhenever you need to use a random number, you must use the model.rng. The easiest way to do this is with the @rand and @shuffle! macros. (Note that these, too, require access to the model object.)","category":"page"},{"location":"species.html#Species","page":"Species","title":"Species","text":"","category":"section"},{"location":"species.html","page":"Species","title":"Species","text":"The ecological submodel in Persefone simulates a range of species in agricultural landscapes.","category":"page"},{"location":"species.html#Skylark","page":"Species","title":"Skylark","text":"","category":"section"},{"location":"species.html","page":"Species","title":"Species","text":"Modules = [Persefone]\nPages = [\"nature/species/skylark.jl\"]","category":"page"},{"location":"species-dsl.html#Defining-new-species","page":"Defining new species","title":"Defining new species","text":"","category":"section"},{"location":"species-dsl.html#The-Persefone-species-DSL","page":"Defining new species","title":"The Persefone species DSL","text":"","category":"section"},{"location":"species-dsl.html","page":"Defining new species","title":"Defining new species","text":"In order to make implementing new species as easy as possible, Persefone includes a domain-specific language (DSL) built from a collection of macros and functions.","category":"page"},{"location":"species-dsl.html","page":"Defining new species","title":"Defining new species","text":"Here is an example of what this looks like, using a hypothetical mermaid species:","category":"page"},{"location":"species-dsl.html","page":"Defining new species","title":"Defining new species","text":"@species Mermaid begin\n ageofmaturity = 2\n pesticidemortality = 1.0\n @initialise(@habitat(@landcover() == water), pairs=true)\n\t\n @phase life begin\n @debug \"$(animalid(animal)) is swimming happily in its pond.\"\n @respond pesticide @kill(@trait(pesticidemortality), \"poisoning\")\n @respond harvest @setphase(drought)\n @debug \"Animal: $animal\"\n if @trait(sex) == female && @countanimals() < 3 &&\n @trait(age) >= @trait(ageofmaturity) && @landcover() == water\n @reproduce()\n end\n end\n\t\n @phase drought begin\n n = sum(1 for a in @neighbours(0))\n @debug \"$(animalid(animal)) is experiencing drought with $n neighbour(s).\"\n @respond sowing @setphase(life)\n end\nend","category":"page"},{"location":"species-dsl.html","page":"Defining new species","title":"Defining new species","text":"The two most important macros are @species and @phase, followed by @initialise, @trait, @respond, and @habitat. Other macros provide convenience wrappers for common functions. (See src/nature/nature.jl for details.)","category":"page"},{"location":"species-dsl.html","page":"Defining new species","title":"Defining new species","text":"The top-level macro is @species. This takes two arguments: a species name and a definition block (enclosed in begin and end tags). At the start of the definition block, species-specific variables can be defined that should be available throughout a species' lifetime. Code in this section has access to the model object and can thus reference the current model state. In this section, the user also has to call the @initialise macro. This wraps the initpopulation function, and takes a habitat descriptor (see @habitat below) and several options to specify how the species' population should be distributed in the landscape during model initialisation.","category":"page"},{"location":"species-dsl.html","page":"Defining new species","title":"Defining new species","text":"Following this section, each species must define one or more @phase blocks. The concept behind this is that species show different behaviours at different phases of their lifecycle. Each @phase block defines the behaviour in one of these phases. (Technically, it defines a function that will be called daily, so long as the species' phase variable is set to the name of this phase.) Code in this section has access to the model object as well as an animal object, which is the currently active animal agent. Properties of the animal agent, regardless of whether they were defined by the user or by Persefone, can be accessed using the @trait macro. Within a phase block, @respond can be used to define the species' response to a FarmEvent that affects the species' current location, while a variety of other macros provide wrappers to ecological process functions from src/nature/populations.jl.","category":"page"},{"location":"species-dsl.html","page":"Defining new species","title":"Defining new species","text":"Another important macro is @habitat. This defines a \"habitat descriptor\", i.e. a predicate function that tests whether or not a given landscape pixel is suitable for a specified purpose. Such habitat descriptors are used as arguments to various functions, for example for population initialisation or movement. The argument to @habitat consists of a logical expression, which has access to the animal's current position (the pos tuple variable) and the model. Various macros are available to easily reference information about the current location, such as @landcover or @distancetoedge.","category":"page"},{"location":"species-dsl.html#Implementation-details","page":"Defining new species","title":"Implementation details","text":"","category":"section"},{"location":"species-dsl.html","page":"Defining new species","title":"Defining new species","text":"Due to a known performance problem with multi-agent models, the underlying implementation of species is rather complicated (see src/nature/nature.jl for details.)","category":"page"},{"location":"species-dsl.html","page":"Defining new species","title":"Defining new species","text":"Rather than creating a new type/struct for each species, all Animal agents have the same type. Instead, they are differentiated by a traits dict, which stores both species-specific parameters and run-time variables. Note that due to a redefinition of the getproperty()/setproperty!() methods, variables from the trait dict can be accessed and modified just like normal struct fields (i.e. although phase is defined in the dict, not the struct, animal.phase = \"newphase\" works just fine - one does not have to use animal.traits[\"phase\"] = \"newphase\".)","category":"page"},{"location":"species-dsl.html","page":"Defining new species","title":"Defining new species","text":"Under the hood, the @species macro generates a function (with the name of the species), which in turn creates the trait dict when called. Thus, adding a new animal agent to the model involves instantiating an Animal object, then calling the relevant species function and attaching the returned dict to the agent object.","category":"page"},{"location":"species-dsl.html","page":"Defining new species","title":"Defining new species","text":"Similarly, the @phase macro too works by defining a new function, which is stored in the species' trait dict. These functions take an animal object and the model object as input, and define what the species does during its daily update.","category":"page"},{"location":"species-dsl.html","page":"Defining new species","title":"Defining new species","text":"Once again, @habitat creates a function that takes model and pos as input and returns a boolean response. Functions that require a habitat descriptor thus take in this (anonymous) function and call it internally.","category":"page"},{"location":"species-dsl.html","page":"Defining new species","title":"Defining new species","text":"Finally, the @initialise macro is a wrapper around initpopulation, which (yet again) creates a function that specifies how a species' population is to be initialised at the beginning of a simulation run. This function is stored in the species trait dict and accessed during model setup.","category":"page"},{"location":"developing.html#Developing-Persefone","page":"Developing Persefone","title":"Developing Persefone","text":"","category":"section"},{"location":"developing.html#Workflow","page":"Developing Persefone","title":"Workflow","text":"","category":"section"},{"location":"developing.html","page":"Developing Persefone","title":"Developing Persefone","text":"Pull the current version from the master branch on Gitlab: https://git.idiv.de/xo30xoqa/persephone.\nIf you are working on a new feature, create a new branch to avoid breaking the master branch. (The master branch on Github should always be in a runnable and error-free state.)\nImplement your changes.\nRun an example simulation and the test suite to make sure everything works without crashing (make run and make test on Linux, or execute run.jl and test/runtests.jl manually.)\nCommit your work frequently, and try to keep each commit small. Don't forget to add relevant tests to the test suite.\nOnce your satisfied with your work, do another pull/merge from the master branch in case somebody else changed the branch in the meantime. Then merge your work into master and push to the Gitlab server.\nRepeat :-)","category":"page"},{"location":"developing.html","page":"Developing Persefone","title":"Developing Persefone","text":"The Gitlab issue tracker can be used to create, discuss, and assign tasks, as well as to monitor progress towards milestones/releases. Once we have a first release, we will start using semantic versioning.","category":"page"},{"location":"developing.html#Libraries","page":"Developing Persefone","title":"Libraries","text":"","category":"section"},{"location":"developing.html#Agents.jl","page":"Developing Persefone","title":"Agents.jl","text":"","category":"section"},{"location":"developing.html","page":"Developing Persefone","title":"Developing Persefone","text":"Our model uses Agents.jl as a framework. Their repository can be used to inspect the source code or submit bug reports (the authors are quick to respond). Questions can be asked at the Julia Discourse forum.","category":"page"},{"location":"developing.html","page":"Developing Persefone","title":"Developing Persefone","text":"Tutorial on collaborating on Julia packages: https://www.matecdev.com/posts/julia-package-collaboration.html.","category":"page"},{"location":"developing.html#Revise.jl","page":"Developing Persefone","title":"Revise.jl","text":"","category":"section"},{"location":"developing.html","page":"Developing Persefone","title":"Developing Persefone","text":"Revise.jl allows one to reload code without restarting the Julia interpreter. Get it with Pkg.add(\"Revise\"), then add using Revise to .julia/config/startup.jl to have it automatically available.","category":"page"},{"location":"developing.html#Test","page":"Developing Persefone","title":"Test","text":"","category":"section"},{"location":"developing.html","page":"Developing Persefone","title":"Developing Persefone","text":"Persefone uses the inbuilt Julia testing framework. All new functions should have appropriate tests written for them in the appropriate file in the test directory. (See test/runtests.jl for details.) There are three ways to run the test suite: in the terminal, executing make test or cd test; julia runtests.jl; or in the Julia REPL, Pkg.activate(\".\"); Pkg.test().","category":"page"},{"location":"developing.html#Documenter.jl","page":"Developing Persefone","title":"Documenter.jl","text":"","category":"section"},{"location":"developing.html","page":"Developing Persefone","title":"Developing Persefone","text":"The HTML documentation is generated using Documenter.jl. Therefore, all new functions should have docstrings attached. New files need to be integrated into the relevant documentation source files in docs/src, and if necessary into docs/builddocs.jl. To build the documentation, run make docs, or cd docs; julia builddocs.jl (if using the latter, don't forget to update the date and commit in docs/src/index.md).","category":"page"},{"location":"developing.html#Julia-editors","page":"Developing Persefone","title":"Julia editors","text":"","category":"section"},{"location":"developing.html#Emacs","page":"Developing Persefone","title":"Emacs","text":"","category":"section"},{"location":"developing.html","page":"Developing Persefone","title":"Developing Persefone","text":"There are a couple of addons that make working with Julia much nicer in Emacs:","category":"page"},{"location":"developing.html","page":"Developing Persefone","title":"Developing Persefone","text":"julia-mode gives syntax highlighting. Install with M-x package-install julia-mode.\njulia-snail provides IDE-like features, especially a fully-functional REPL and the ability to evaluate code straight from inside a buffer. Note that the installation can be somewhat tricky. You first need to manually install all the dependencies of its dependency vterm, then install vterm itself with M-x package-install vterm, before you can do M-x package-install julia-snail. Then add it to your init.el with (require 'julia-snail) and (add-hook 'julia-mode-hook #'julia-snail-mode).\ncompany-mode integrates with Snail to give code completion. Install with M-x package-install company, then add (add-hook 'julia-mode-hook #'company-mode) and (global-set-key (kbd \"C-<tab>\") 'company-complete) to your init.el.\nmagit is a great git interface for Emacs. Install with M-x package-install magit and add (global-set-key (kbd \"C-x g\") 'magit-status) to your init.el.","category":"page"},{"location":"developing.html#VSCode","page":"Developing Persefone","title":"VSCode","text":"","category":"section"},{"location":"developing.html","page":"Developing Persefone","title":"Developing Persefone","text":"See here.","category":"page"},{"location":"developing.html","page":"Developing Persefone","title":"Developing Persefone","text":"TODO: add more detail.","category":"page"},{"location":"simulation.html#Simulation","page":"Simulation","title":"Simulation","text":"","category":"section"},{"location":"simulation.html","page":"Simulation","title":"Simulation","text":"The core directory holds source files that are important for all submodels, including scheduling, landscape, and input/output functions.","category":"page"},{"location":"simulation.html#simulation.jl","page":"Simulation","title":"simulation.jl","text":"","category":"section"},{"location":"simulation.html","page":"Simulation","title":"Simulation","text":"This file includes the basal functions for initialising and running simulations.","category":"page"},{"location":"simulation.html","page":"Simulation","title":"Simulation","text":"Modules = [Persefone]\nPages = [\"core/simulation.jl\"]","category":"page"},{"location":"simulation.html#Persefone.finalise!-Tuple{Agents.AgentBasedModel}","page":"Simulation","title":"Persefone.finalise!","text":"finalise!(model)\n\nWrap up the simulation. Currently doesn't do anything except print some information.\n\n\n\n\n\n","category":"method"},{"location":"simulation.html#Persefone.initialise","page":"Simulation","title":"Persefone.initialise","text":"initialise(config=PARAMFILE, seed=nothing)\n\nInitialise the model: read in parameters, create the output data directory, and instantiate the AgentBasedModel object(s). Optionally allows specifying the configuration file and overriding the seed parameter. This returns a single model object, unless the config file contains multiple values for one or more parameters, in which case it creates a full-factorial simulation experiment and returns a vector of model objects.\n\n\n\n\n\n","category":"function"},{"location":"simulation.html#Persefone.initmodel-Tuple{Dict{String, Any}}","page":"Simulation","title":"Persefone.initmodel","text":"initmodel(settings)\n\nInitialise a model object using a ready-made settings dict. This is a helper function for initialise().\n\n\n\n\n\n","category":"method"},{"location":"simulation.html#Persefone.paramscan-Tuple{Dict{String, Any}, Vector{String}}","page":"Simulation","title":"Persefone.paramscan","text":"paramscan(settings)\n\nCreate a list of settings dicts, covering all possible parameter combinations given by the input settings (i.e. a full-factorial experiment). This is a helper function for initialise().\n\n\n\n\n\n","category":"method"},{"location":"simulation.html#Persefone.simulate","page":"Simulation","title":"Persefone.simulate","text":"simulate(config=PARAMFILE, seed=nothing)\n\nInitialise one or more model objects and carry out a full simulation experiment, optionally specifying a configuration file and a seed for the RNG.\n\nThis is the default way to run a Persefone simulation.\n\n\n\n\n\n","category":"function"},{"location":"simulation.html#Persefone.simulate!-Tuple{Agents.AgentBasedModel}","page":"Simulation","title":"Persefone.simulate!","text":"simulate!(model)\n\nCarry out a complete simulation run using a pre-initialised model object.\n\n\n\n\n\n","category":"method"},{"location":"simulation.html#Persefone.stepsimulation!-Tuple{Agents.AgentBasedModel}","page":"Simulation","title":"Persefone.stepsimulation!","text":"stepsimulation!(model)\n\nExecute one update of the model.\n\n\n\n\n\n","category":"method"},{"location":"simulation.html#landscape.jl","page":"Simulation","title":"landscape.jl","text":"","category":"section"},{"location":"simulation.html","page":"Simulation","title":"Simulation","text":"This file manages the landscape maps that underlie the model.","category":"page"},{"location":"simulation.html","page":"Simulation","title":"Simulation","text":"Modules = [Persefone]\nPages = [\"core/landscape.jl\"]","category":"page"},{"location":"farm.html#Farm-submodel","page":"Farm submodel","title":"Farm submodel","text":"","category":"section"},{"location":"farm.html","page":"Farm submodel","title":"Farm submodel","text":"Eventually, Persefone will include multiple farm-decision submodels. At the moment, we are only working with a very basic mock-up.","category":"page"},{"location":"farm.html#farm.jl","page":"Farm submodel","title":"farm.jl","text":"","category":"section"},{"location":"farm.html","page":"Farm submodel","title":"Farm submodel","text":"This file is responsible for managing the farm module(s).","category":"page"},{"location":"farm.html","page":"Farm submodel","title":"Farm submodel","text":"Modules = [Persefone]\nPages = [\"farm/farm.jl\"]","category":"page"},{"location":"farm.html#Persefone.Farmer","page":"Farm submodel","title":"Persefone.Farmer","text":"Farmer\n\nThis is the agent type for the farm ABM. (Not yet implemented.)\n\n\n\n\n\n","category":"type"},{"location":"farm.html#Persefone.initfarms!-Tuple{Agents.AgentBasedModel}","page":"Farm submodel","title":"Persefone.initfarms!","text":"initfarms!(model)\n\nInitialise the model with a set of farm agents.\n\n\n\n\n\n","category":"method"},{"location":"farm.html#Persefone.stepagent!-Tuple{Farmer, Agents.AgentBasedModel}","page":"Farm submodel","title":"Persefone.stepagent!","text":"stepagent!(farmer, model)\n\nUpdate a farmer by one day.\n\n\n\n\n\n","category":"method"},{"location":"adapting.html#Adapting-Persefone","page":"Adapting Persefone","title":"Adapting Persefone","text":"","category":"section"},{"location":"adapting.html","page":"Adapting Persefone","title":"Adapting Persefone","text":"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.","category":"page"},{"location":"adapting.html","page":"Adapting Persefone","title":"Adapting Persefone","text":"There are multiple ways to adapt Persefone for a new modelling study:","category":"page"},{"location":"adapting.html#Changing-the-parameters","page":"Adapting Persefone","title":"Changing the parameters","text":"","category":"section"},{"location":"adapting.html","page":"Adapting Persefone","title":"Adapting Persefone","text":"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>.","category":"page"},{"location":"adapting.html#Changing-the-region","page":"Adapting Persefone","title":"Changing the region","text":"","category":"section"},{"location":"adapting.html","page":"Adapting Persefone","title":"Adapting Persefone","text":"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.","category":"page"},{"location":"adapting.html","page":"Adapting Persefone","title":"Adapting Persefone","text":"You may also need to change aspects of the farm submodel. This is not yet implemented.","category":"page"},{"location":"adapting.html#Adding-new-animal-species","page":"Adapting Persefone","title":"Adding new animal species","text":"","category":"section"},{"location":"adapting.html","page":"Adapting Persefone","title":"Adapting Persefone","text":"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.","category":"page"},{"location":"adapting.html#Adding-new-crop-species","page":"Adapting Persefone","title":"Adding new crop species","text":"","category":"section"},{"location":"adapting.html","page":"Adapting Persefone","title":"Adapting Persefone","text":"Crop growth is not yet implemented.","category":"page"},{"location":"adapting.html#Adding-new-farmer-behaviour","page":"Adapting Persefone","title":"Adding new farmer behaviour","text":"","category":"section"},{"location":"adapting.html","page":"Adapting Persefone","title":"Adapting Persefone","text":"Farmer behaviour is not yet implemented.","category":"page"},{"location":"adapting.html#Adding-a-new-submodel","page":"Adapting Persefone","title":"Adding a new submodel","text":"","category":"section"},{"location":"adapting.html","page":"Adapting Persefone","title":"Adapting Persefone","text":"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.","category":"page"},{"location":"adapting.html","page":"Adapting Persefone","title":"Adapting Persefone","text":"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 initmodel and stepsimulation! for details.)","category":"page"},{"location":"adapting.html#Linking-to-another-model","page":"Adapting Persefone","title":"Linking to another model","text":"","category":"section"},{"location":"adapting.html","page":"Adapting Persefone","title":"Adapting Persefone","text":"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).","category":"page"},{"location":"adapting.html","page":"Adapting Persefone","title":"Adapting Persefone","text":"To interface with Julia from another language, see the Julia docs here and here.","category":"page"},{"location":"odd.html#Overview,-Design,-Details-(ODD)","page":"Overview, Design, Details (ODD)","title":"Overview, Design, Details (ODD)","text":"","category":"section"},{"location":"odd.html","page":"Overview, Design, Details (ODD)","title":"Overview, Design, Details (ODD)","text":"TODO","category":"page"},{"location":"gis.html#GIS-data","page":"GIS data","title":"GIS data","text":"","category":"section"},{"location":"gis.html","page":"GIS data","title":"GIS data","text":"Persefone currently requires two separate map input files: one for land cover, the other for field geometry. This documents describe how to obtain and process the data needed for each of these.","category":"page"},{"location":"gis.html#Land-cover-maps","page":"GIS data","title":"Land cover maps","text":"","category":"section"},{"location":"gis.html","page":"GIS data","title":"GIS data","text":"Land cover maps for Germany at 10m resolution can be obtained from Mundialis. These are generated annually from Sentinel data and comprise the following land cover classes:","category":"page"},{"location":"gis.html","page":"GIS data","title":"GIS data","text":"10: forest\n20: low vegetation\n30: water\n40: built-up\n50: bare soil\n60: agriculture","category":"page"},{"location":"gis.html","page":"GIS data","title":"GIS data","text":"To create a Persefone map input file, you need to crop the national Mundialis map to the extent that you want to simulate (suggestion: approx. 10x10km is a reasonable size).","category":"page"},{"location":"gis.html","page":"GIS data","title":"GIS data","text":"To do so, download the Mundialis map and import it into QGIS. Then create a new vector layer and create a rectangle feature to delimit the extent of your region. Then go to Raster -> Extraction -> Clip Raster by Extent. Select the Mundialis map as the input layer, set the clipping extent by choosing your region vector layer under Calculate from Layer and specify the output file name before clicking Run. This will generate a TIF file that you can pass to Persefone as the landcovermap parameter.","category":"page"},{"location":"gis.html#Field-ID-maps","page":"GIS data","title":"Field ID maps","text":"","category":"section"},{"location":"gis.html","page":"GIS data","title":"GIS data","text":"In addition to the land cover data explained above, Persefone also needs information about agricultural field boundaries in order to assign these to the farming agents. Unfortunately, getting this is rather more complicated.","category":"page"},{"location":"gis.html","page":"GIS data","title":"GIS data","text":"In the EU, every country runs a Land Parcel Information System (LPIS) to administer CAP payments. In Germany, this is called InVeKoS and is run by the Länder. For example, you can view and download the InVeKoS data for Thüringen here. This gives you a vector layer which can be loaded into QGIS. However, it needs to be converted to a raster layer and cropped to your region extent before it can be used in Persefone.","category":"page"},{"location":"gis.html","page":"GIS data","title":"GIS data","text":"The first thing to do is to make sure that the vector layer has a numeric (!) field with a unique identifier for each field block (check the attribute table). The Thüringen data has the FBI (\"Feldblockident\") field, but this is a string value and therefore not usable by the rasteriser. So, we set the vector layer to edit mode, open the field calculator, enter the information for a new field (call it \"FID\" and set it to a 32-bit integer), and enter @row_number in the expression field. Then save the layer and close the calculator.","category":"page"},{"location":"gis.html","page":"GIS data","title":"GIS data","text":"Secondly, you need to filter out all non-field/non-grassland plot types. (LPIS also has data on forests and various landscape elements that are not relevant to our use case.) Assuming you're working with the Thüringen InVeKoS data (other data sets may have a different structure), right-click on the layer name in QGIS' layer overview and click on \"Filter...\". Then, enter this expression in the query builder: \"BNK\" = 'AL' OR \"BNK\" = 'GL' and click \"OK\". This will select only field and grassland plots.","category":"page"},{"location":"gis.html","page":"GIS data","title":"GIS data","text":"Next, open the rasteriser (Raster -> Conversion -> Rasterize). Select your FID field as the \"Field to use for a burn-in value\", and your land cover map (as created above - this ensures the two layers match) as the output extent. Make sure the \"fixed value to burn\" is \"Not set\". Then choose \"Georeferenced units\" as the \"Out raster size units\" and set horizontal and vertical resolution to 10.0. In the advanced parameters, set the output data type to UInt32. Finally, enter an output file name and run. The resulting TIF file can be passed to Persefone as the farmfieldmap parameter.","category":"page"},{"location":"crops.html#Crop-submodel","page":"Crop submodel","title":"Crop submodel","text":"","category":"section"},{"location":"crops.html","page":"Crop submodel","title":"Crop submodel","text":"Eventually, Persefone will include a full-blown crop-growth model (an adaptation of AquaCrop, created by the FAO). At the moment, we are only working with a very basic mock-up.","category":"page"},{"location":"crops.html#crops.jl","page":"Crop submodel","title":"crops.jl","text":"","category":"section"},{"location":"crops.html","page":"Crop submodel","title":"Crop submodel","text":"This includes the types and functions needed for all crop growth model, which are also referenced by the other submodels.","category":"page"},{"location":"crops.html","page":"Crop submodel","title":"Crop submodel","text":"Modules = [Persefone]\nPages = [\"crop/crops.jl\"]","category":"page"},{"location":"crops.html#Persefone.CropType","page":"Crop submodel","title":"Persefone.CropType","text":"The crop types simulated by the model\n\n\n\n\n\n","category":"type"},{"location":"crops.html#Persefone.FarmPlot","page":"Crop submodel","title":"Persefone.FarmPlot","text":"FarmPlot\n\nThis represents one field, i.e. a collection of pixels with the same management. This is the spatial unit with which the crop growth model and the farm model work.\n\n\n\n\n\n","category":"type"},{"location":"crops.html#Persefone.averagefieldsize-Tuple{Agents.AgentBasedModel}","page":"Crop submodel","title":"Persefone.averagefieldsize","text":"averagefieldsize(model)\n\nCalculate the average field size in hectares for the model landscape.\n\n\n\n\n\n","category":"method"},{"location":"crops.html#Persefone.cropheight-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel}","page":"Crop submodel","title":"Persefone.cropheight","text":"cropheight(model, position)\n\nReturn the height of the crop at this position, or nothing if there is no crop here (utility wrapper).\n\n\n\n\n\n","category":"method"},{"location":"crops.html#Persefone.croptype-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel}","page":"Crop submodel","title":"Persefone.croptype","text":"croptype(model, position)\n\nReturn the crop at this position, or nothing if there is no crop here (utility wrapper).\n\n\n\n\n\n","category":"method"},{"location":"crops.html#Persefone.initfields!-Tuple{Agents.AgentBasedModel}","page":"Crop submodel","title":"Persefone.initfields!","text":"initfields!(model)\n\nInitialise the model with its farm plots.\n\n\n\n\n\n","category":"method"},{"location":"crops.html#Persefone.stepagent!-Tuple{FarmPlot, Agents.AgentBasedModel}","page":"Crop submodel","title":"Persefone.stepagent!","text":"stepagent!(farmplot, model)\n\nUpdate a farm plot by one day.\n\n\n\n\n\n","category":"method"},{"location":"index.html","page":"Introduction","title":"Introduction","text":"CurrentModule = Persefone","category":"page"},{"location":"index.html#Introduction","page":"Introduction","title":"Introduction","text":"","category":"section"},{"location":"index.html","page":"Introduction","title":"Introduction","text":"Persefone is an agent-based, socio-economic-ecological model of agricultural landscapes in Europe under the Common Agricultural Policy (CAP).","category":"page"},{"location":"index.html","page":"Introduction","title":"Introduction","text":"It's aim is to investigate how policy affects farmer decision-making, and how this in turn affects various animal species. It includes a farm submodel, a crop-growth submodel, and an ecological submodels.","category":"page"},{"location":"index.html#Running-the-model","page":"Introduction","title":"Running the model","text":"","category":"section"},{"location":"index.html","page":"Introduction","title":"Introduction","text":"To run a single experiment, execute run.jl:","category":"page"},{"location":"index.html","page":"Introduction","title":"Introduction","text":"julia run.jl -c <CONFIG>","category":"page"},{"location":"index.html","page":"Introduction","title":"Introduction","text":"Other commandline arguments are:","category":"page"},{"location":"index.html","page":"Introduction","title":"Introduction","text":"usage: run.jl [-c CONFIGFILE] [-s SEED] [-o OUTDIR] [-l LOGLEVEL] \n [--version] [-h]\n\noptional arguments:\n -c, --configfile CONFIGFILE\n name of the configuration file\n -s, --seed SEED inital random seed (type: Int64)\n -o, --outdir OUTDIR location of the output directory\n -l, --loglevel LOGLEVEL\n verbosity: \"debug\", \"info\", or \"quiet\"\n --version show version information and exit\n -h, --help show this help message and exit","category":"page"},{"location":"index.html#Model-input","page":"Introduction","title":"Model input","text":"","category":"section"},{"location":"index.html","page":"Introduction","title":"Introduction","text":"Persefone requires three input files: a configuration file and two map files. How to generate the map files is documented elsewhere. The configuration file defines parameter values and looks like this (see src/parameters.toml for a complete list of parameters):","category":"page"},{"location":"index.html","page":"Introduction","title":"Introduction","text":"### Persefone - a socio-economic-ecological model of European agricultural landscapes.\n###\n### This is the default configuration file for Persefone, containing all model parameters.\n### The syntax is described here: https://toml.io/en/\n\n[core]\nconfigfile = \"src/parameters.toml\" # location of the configuration file\noutdir = \"results\" # location and name of the output folder\noverwrite = \"ask\" # overwrite the output directory? (true/false/\"ask\")\nloglevel = \"debug\" # verbosity level: \"debug\", \"info\", \"warn\"\nprocessors = 2 # number of processors to use on parallel runs\nseed = 2 # seed value for the RNG (0 -> random value)\n# dates to start and end the simulation\nstartdate = 2022-01-01\nenddate = 2022-12-31\n\n[world]\nlandcovermap = \"data/landcover_jena.tif\" # location of the landcover map\nfarmfieldsmap = \"data/fields_jena.tif\" # location of the field geometry map\n\n[farm]\nfarmmodel = \"FieldManager\" # which version of the farm model to use (not yet implemented)\n\n[nature]\ntargetspecies = [\"Wolpertinger\", \"Wyvern\"] # list of target species to simulate\npopoutfreq = \"daily\" # output frequency population-level data, daily/monthly/yearly/end/never\nindoutfreq = \"end\" # output frequency individual-level data, daily/monthly/yearly/end/never\n\t\n[crop]\ncropmodel = \"linear\" # crop growth model to use, \"linear\" or \"aquacrop\" (not yet implemented)","category":"page"},{"location":"index.html","page":"Introduction","title":"Introduction","text":"info: Parameter scanning\nYou can set any parameter to a list of different values, e.g. seed = [1,2,3]. Persefone will then set up and run multiple simulations, one for every possible combination of parameters that you entered (i.e. do a full-factorial simulation experiment).","category":"page"},{"location":"index.html","page":"Introduction","title":"Introduction","text":"Last updated: 2023-07-20 (commit 0fd9917)","category":"page"}]
+[{"location":"energy.html#Dynamic-Energy-Budgets","page":"Dynamic Energy Budgets","title":"Dynamic Energy Budgets","text":"","category":"section"},{"location":"energy.html","page":"Dynamic Energy Budgets","title":"Dynamic Energy Budgets","text":"Persefone's nature module uses Kooijman's Dynamic Energy Budget theory to model energy flows within individuals.","category":"page"},{"location":"energy.html","page":"Dynamic Energy Budgets","title":"Dynamic Energy Budgets","text":"(Image: \"The standard model of the Dynamic Energy Budget theory\")","category":"page"},{"location":"energy.html","page":"Dynamic Energy Budgets","title":"Dynamic Energy Budgets","text":"The standard model of the Dynamic Energy Budget theory. (Fig. 1 from Sousa et al. (2010).)","category":"page"},{"location":"energy.html","page":"Dynamic Energy Budgets","title":"Dynamic Energy Budgets","text":"Sousa et al. (2010). Dynamic energy budget theory restores coherence in biology. Philosophical Transactions of the Royal Society B: Biological Sciences, 365(1557), 3413–3428.\nKooijman, S. A. L. M. (2009). Dynamic energy and mass budgets in biological systems (3rd ed). Cambridge University Press.\nSibly et al. (2013). Representing the acquisition and use of energy by individuals in agent-based models of animal populations. Methods in Ecology and Evolution, 4(2), 151–161.","category":"page"},{"location":"energy.html#energy.jl","page":"Dynamic Energy Budgets","title":"energy.jl","text":"","category":"section"},{"location":"energy.html","page":"Dynamic Energy Budgets","title":"Dynamic Energy Budgets","text":"Modules = [Persefone]\nPages = [\"nature/energy.jl\"]","category":"page"},{"location":"energy.html#Persefone.DEBparameters","page":"Dynamic Energy Budgets","title":"Persefone.DEBparameters","text":"DEBparameters\n\nAn immutable struct to save the parameter list for a species' Dynamic Energy Budget model. (See Sousa et al., 2010.)\n\n\n\n\n\n","category":"type"},{"location":"energy.html#Persefone.EnergyBudget","page":"Dynamic Energy Budgets","title":"Persefone.EnergyBudget","text":"EnergyBudget\n\nThis struct represents an individual's energy balance, as conceptualised by the Dynamic Energy Budget theory. Upon assimilation, energy is first stored as biomass in a reserve buffer, before being used for maintenance, growth, and reproduction. (Note that this is a simplified model form which ignores maturity as a separate buffer.)\n\nSources:\n\nMalishev & Kramer-Schadt (2021). Movement, models, and metabolism: Individual-based energy budget models as next-generation extensions for predicting animal movement outcomes across scales. Ecological Modelling, 441, 109413. https://doi.org/10.1016/j.ecolmodel.2020.109413\nMarques et al. (2018). The AmP project: Comparing species on the basis of dynamic energy budget parameters. PLOS Computational Biology,14(5), e1006100. https://doi.org/10.1371/journal.pcbi.1006100\nSibly et al. (2013). Representing the acquisition and use of energy by individuals in agent-based models of animal populations. Methods in Ecology and Evolution, 4(2), 151–161. https://doi.org/10.1111/2041-210x.12002\nSousa et al. (2010). Dynamic energy budget theory restores coherence in biology. Philosophical Transactions of the Royal Society B: Biological Sciences, 365(1557), 3413–3428. https://doi.org/10.1098/rstb.2010.0166\nKooijman, S. A. L. M. (2009). Dynamic energy and mass budgets in biological systems (3rd ed). Cambridge University Press. https://www.researchgate.net/profile/Edgar-Meza-3/post/Isthereatoxicokineticmodelfordaphniamagnaorotherzooplankton/attachment/59d62cf579197b807798b396/AS%3A348547653357569%401460111644286/download/Dynamic+Energy+Budget+theory+-+Kooijman.pdf\nsee also: Brown et al. (2004). Toward a metabolic theory of ecology. Ecology, 85(7), 1771–1789. https://doi.org/10.1890/03-9000\n\n\n\n\n\n","category":"type"},{"location":"energy.html#Persefone.feed!-Tuple{Float64, Persefone.EnergyBudget}","page":"Dynamic Energy Budgets","title":"Persefone.feed!","text":"feed!(quantity, energybudget)\n\nConsume a given quantity of food. Expands the energy reserve by an amount determined by the assimilation rate. Returns true if successful, false if the reserve is already full.\n\n\n\n\n\n","category":"method"},{"location":"energy.html#Persefone.growthrate-Tuple{Persefone.EnergyBudget}","page":"Dynamic Energy Budgets","title":"Persefone.growthrate","text":"growthrate(energybudget)\n\nCalculate the specific growth rate r. (Internal function.)\n\n\n\n\n\n","category":"method"},{"location":"energy.html#Persefone.investmentratio-Tuple{Persefone.EnergyBudget}","page":"Dynamic Energy Budgets","title":"Persefone.investmentratio","text":"investmentratio(energybudget)\n\nCalculate the investment ratio g. (Internal function.)\n\n\n\n\n\n","category":"method"},{"location":"energy.html#Persefone.maturitymaintenance-Tuple{Persefone.EnergyBudget}","page":"Dynamic Energy Budgets","title":"Persefone.maturitymaintenance","text":"maturitymaintenance(energybudget)\n\nCalculate the specific maturity maintenance k_J. (Internal function.)\n\n\n\n\n\n","category":"method"},{"location":"energy.html#Persefone.mobilisation-Tuple{Persefone.EnergyBudget}","page":"Dynamic Energy Budgets","title":"Persefone.mobilisation","text":"mobilisation(energybudget)\n\nCalculate the mobilisation rate J_EC. (Internal function.)\n\n\n\n\n\n","category":"method"},{"location":"energy.html#Persefone.reproduce!-Tuple{Persefone.EnergyBudget}","page":"Dynamic Energy Budgets","title":"Persefone.reproduce!","text":"reproduce!(energybudget)\n\nIf there is sufficient energy in the offspring buffer of an adult, produce an embryo/egg, reducing the parent energy in the process. Returns the embryo's energy budget, or nothing if the conditions are not met.\n\n\n\n\n\n","category":"method"},{"location":"energy.html#Persefone.scaledreservedensity-Tuple{Persefone.EnergyBudget}","page":"Dynamic Energy Budgets","title":"Persefone.scaledreservedensity","text":"scaledreservedensity(energybudget)\n\nCalculate the scaled reserve density e. (Internal function.)\n\n\n\n\n\n","category":"method"},{"location":"energy.html#Persefone.update!-Tuple{Persefone.EnergyBudget}","page":"Dynamic Energy Budgets","title":"Persefone.update!","text":"update!(energybudget)\n\nCarry out a daily update of the energy budget. Mobilises reserves and allocates these to maintenance (prioritised), growth, and reproduction.\n\nReturn true if the individual has enough energy to survive, or false if the reserve is empty and it starves.\n\n\n\n\n\n","category":"method"},{"location":"energy.html#Persefone.volumetriclength-Tuple{Persefone.EnergyBudget}","page":"Dynamic Energy Budgets","title":"Persefone.volumetriclength","text":"volumetriclength(energybudget)\n\nCalculate the structural length in cm based on an individual's weight (assuming a density of 1 g/cm³ to calculate volume, see Kooijman 2009).\n\n\n\n\n\n","category":"method"},{"location":"nature.html#Nature","page":"Nature","title":"Nature","text":"","category":"section"},{"location":"nature.html#nature.jl","page":"Nature","title":"nature.jl","text":"","category":"section"},{"location":"nature.html","page":"Nature","title":"Nature","text":"This file is responsible for managing the animal modules.","category":"page"},{"location":"nature.html","page":"Nature","title":"Nature","text":"Modules = [Persefone]\nPages = [\"nature/nature.jl\"]","category":"page"},{"location":"nature.html#Persefone.Animal","page":"Nature","title":"Persefone.Animal","text":"Animal\n\nThis is the generic agent type for all animals. Species are differentiated by trait dictionaries passed by them during initialisation. (Note that each trait variable can still be accessed as if it were a normal field name, i.e. the trait phase can be accessed and modified with animal.phase.)\n\n\n\n\n\n","category":"type"},{"location":"nature.html#Persefone.animalid-Tuple{Animal}","page":"Nature","title":"Persefone.animalid","text":"animalid(animal)\n\nA small utility function to return a string with the species name and ID of an animal.\n\n\n\n\n\n","category":"method"},{"location":"nature.html#Persefone.initnature!-Tuple{Agents.AgentBasedModel}","page":"Nature","title":"Persefone.initnature!","text":"initnature!(model)\n\nInitialise the model with all simulated animal populations.\n\n\n\n\n\n","category":"method"},{"location":"nature.html#Persefone.stepagent!-Tuple{Animal, Agents.AgentBasedModel}","page":"Nature","title":"Persefone.stepagent!","text":"stepagent!(animal, model)\n\nUpdate an animal by one day, executing it's currently active phase function.\n\n\n\n\n\n","category":"method"},{"location":"nature.html#Persefone.@countanimals-Tuple","page":"Nature","title":"Persefone.@countanimals","text":"@countanimals(species=\"\", radius=0)\n\nCount the number of animals of the given species in this location. This is a utility wrapper that can only be used nested within @phase or @habitat.\n\n\n\n\n\n","category":"macro"},{"location":"nature.html#Persefone.@cropheight-Tuple{}","page":"Nature","title":"Persefone.@cropheight","text":"@cropheight\n\nReturn the height of the crop at this position, or 0 if there is no crop here. This is a utility wrapper that can only be used nested within @phase or @habitat.\n\n\n\n\n\n","category":"macro"},{"location":"nature.html#Persefone.@croptype-Tuple{}","page":"Nature","title":"Persefone.@croptype","text":"@croptype\n\nReturn the local croptype, or nothing if there is no crop here. This is a utility wrapper that can only be used nested within @phase or @habitat.\n\n\n\n\n\n","category":"macro"},{"location":"nature.html#Persefone.@distanceto-Tuple{Any}","page":"Nature","title":"Persefone.@distanceto","text":"@distanceto(habitat)\n\nCalculate the distance to the closest habitat of the specified type or descriptor. This is a utility wrapper that can only be used nested within @phase or @habitat.\n\n\n\n\n\n","category":"macro"},{"location":"nature.html#Persefone.@distancetoedge-Tuple{}","page":"Nature","title":"Persefone.@distancetoedge","text":"@distancetoedge\n\nCalculate the distance to the closest neighbouring habitat. This is a utility wrapper that can only be used nested within @phase or @habitat.\n\n\n\n\n\n","category":"macro"},{"location":"nature.html#Persefone.@habitat-Tuple{Any}","page":"Nature","title":"Persefone.@habitat","text":"@habitat\n\nSpecify habitat suitability for spatial ecological processes.\n\nThis macro works by creating an anonymous function that takes in a model object and a position, and returns true or false depending on the conditions specified in the macro body.\n\nSeveral utility macros can be used within the body of @habitat as a short-hand for common expressions: @landcover, @croptype, @cropheight, @distanceto, @distancetoedge, @countanimals. The variables model and pos can be used for checks that don't have a macro available.\n\nTwo example uses of @habitat might look like this:\n\nmovementhabitat = @habitat(@landcover() in (grass agriculture soil))\n\nnestinghabitat = @habitat((@landcover() == grass || \n (@landcover() == agriculture && @croptype() != maize &&\n @cropheight() < 10)) &&\n @distanceto(forest) > 20)\n\nFor more complex habitat suitability checks, the use of this macro can be circumvented by directly creating an equivalent function.\n\n\n\n\n\n","category":"macro"},{"location":"nature.html#Persefone.@initialise-Tuple{Any, Vararg{Any}}","page":"Nature","title":"Persefone.@initialise","text":"@initialise(habitatdescriptor; kwargs...)\n\nCall this macro within the body of @species. It passes the given habitat descriptor function and keyword arguments on to initpopulation when setting up the simulation.\n\nNote: if this macro is not used, the variable initialise! must be set manually in the species definition.\n\n\n\n\n\n","category":"macro"},{"location":"nature.html#Persefone.@kill-Tuple","page":"Nature","title":"Persefone.@kill","text":"@kill\n\nKill this animal (and immediately abort its current update). This is a thin wrapper around kill!, and passes on any arguments. This can only be used nested within @phase.\n\n\n\n\n\n","category":"macro"},{"location":"nature.html#Persefone.@landcover-Tuple{}","page":"Nature","title":"Persefone.@landcover","text":"@landcover\n\nReturns the local landcover. This is a utility wrapper that can only be used nested within @phase or @habitat.\n\n\n\n\n\n","category":"macro"},{"location":"nature.html#Persefone.@neighbours-Tuple{Any}","page":"Nature","title":"Persefone.@neighbours","text":"@neighbours(radius)\n\nReturn an iterator over all animals in the given radius around this animal, excluding itself. This can only be used nested within @phase.\n\n\n\n\n\n","category":"macro"},{"location":"nature.html#Persefone.@phase-Tuple{Any, Any}","page":"Nature","title":"Persefone.@phase","text":"@phase(name, body)\n\nThis macro is designed to be used within a species definition block (i.e. within the body of a call to @species).\n\nThe idea behind this is that species show very different behaviour during different phases of their lives. Therefore, @phase can be used define the behaviour for one such phase, and the conditions under which the animal transitions to another phase.\n\n@phase works by creating a function that will be called by the model if the animal is in the relevant phase. When it is called, it has access to the following variables:\n\nanimal a reference to the animal itself. This provides access to animal.age, animal.sex, and animal.<trait> (where <trait> is a variable that was defined in the top part of the species definition body).\npos gives the animal's current position as a coordinate tuple.\nmodel a reference to the model world (an object of type AgentBasedModel). This allows access to model.date (the current simulation date) and model.landscape (a two-dimensional array of pixels containing geographic information).\n\nSeveral utility macros can be used within the body of @phase as a short-hand for common expressions: @trait, @setphase, @respond, @kill, @reproduce, @neighbours, @rand, @shuffle!.\n\nNote that the first phase that is defined in a species definition block will be the phase that animals are assigned at birth, unless the variable phase is explicitly defined by the user in the species definition block.\n\n\n\n\n\n","category":"macro"},{"location":"nature.html#Persefone.@reproduce-Tuple","page":"Nature","title":"Persefone.@reproduce","text":"@reproduce\n\nLet this animal reproduce. This is a thin wrapper around reproduce!, and passes on any arguments. This can only be used nested within @phase.\n\n\n\n\n\n","category":"macro"},{"location":"nature.html#Persefone.@respond-Tuple{Any, Any}","page":"Nature","title":"Persefone.@respond","text":"@respond(eventname, body)\n\nDefine how an animal responds to a landscape event that affects its current position. This can only be used nested within @phase.\n\n\n\n\n\n","category":"macro"},{"location":"nature.html#Persefone.@setphase-Tuple{Any}","page":"Nature","title":"Persefone.@setphase","text":"@setphase(newphase)\n\nSwitch this animal over to a different phase. This can only be used nested within @phase.\n\n\n\n\n\n","category":"macro"},{"location":"nature.html#Persefone.@species-Tuple{Any, Any}","page":"Nature","title":"Persefone.@species","text":"@species(name, body)\n\nA macro used to create new species definitions for the nature model. This is effectively a simple domain-specific language, establishing a custom syntax to describe species' biology:\n\n@species name begin\n\n @initialise(@habitat(...))\n speciesvar1 = 3.14\n ...\n\n @phase phase1 begin\n ...\n end\nend\n\nThe definition body (enclosed in the begin/end block) has two sections. First comes a call to @initialise, and optionally a list of species-specific parameters, which are assigned just like normal variables. Second come one or more phase definitions, that describe the behaviour of the species during various parts of its life cycle. (See the documentation to @initialise and @phase for details).\n\nCode in a species definition block can access the rest of the model using the model variable (an object of type AgentBasedModel).\n\n\n\n\n\n","category":"macro"},{"location":"nature.html#Persefone.@trait-Tuple{Any}","page":"Nature","title":"Persefone.@trait","text":"@trait(traitname)\n\nA utility macro to quickly access an animal's trait value. This can only be used nested within @phase.\n\n\n\n\n\n","category":"macro"},{"location":"nature.html#populations.jl","page":"Nature","title":"populations.jl","text":"","category":"section"},{"location":"nature.html","page":"Nature","title":"Nature","text":"This file contains a set of utility functions for species, including initialisation, reproduction, and mortality.","category":"page"},{"location":"nature.html","page":"Nature","title":"Nature","text":"Modules = [Persefone]\nPages = [\"nature/populations.jl\"]","category":"page"},{"location":"nature.html#Persefone.countanimals-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel}","page":"Nature","title":"Persefone.countanimals","text":"countanimals(pos, model; species=\"\", radius=0)\n\nCount the number of animals in this location (optionally supplying a species name and radius).\n\n\n\n\n\n","category":"method"},{"location":"nature.html#Persefone.initpopulation-Tuple{Function}","page":"Nature","title":"Persefone.initpopulation","text":"initpopulation(habitatdescriptor; popsize=-1, pairs=false, asexual=false)\n\nCreates a function that initialises individuals at random locations across the landscape. This can be used to create the initialise! variable in a species definition block.\n\nhabitatdescriptor is a function that determines whether a given location is suitable or not (create this using @habitat).\nphase determines which life phase individuals will be assigned to. If this is nothing, the species' default post-natal life stage will be used (although note that this is probably not what you want).\npopsize determines the number of individuals that will be created. If this is zero or negative, one individual will be created in every suitable location in the landscape. If popsize is greater than the number of suitable locations, multiple individuals will be created in one place. (Maximum population density can be set in the habitat descriptor using the @countanimals macro.)\nIf pairs is true, a male and a female individual will be created in each selected location, otherwise, only one individual will be created at a time.\nIf asexual is true, all created individuals are assigned the sex hermaphrodite, otherwise, they are randomly assigned male of female. (If pairs is true, asexual is ignored.)\n\n\n\n\n\n","category":"method"},{"location":"nature.html#Persefone.initrandompopulation-Tuple{Int64}","page":"Nature","title":"Persefone.initrandompopulation","text":"initrandompopulation(popsize; kwargs...)\n\nA simplified version of initpopulation. Creates a function that initialises popsize individuals, spread at random across the landscape.\n\n\n\n\n\n","category":"method"},{"location":"nature.html#Persefone.kill!","page":"Nature","title":"Persefone.kill!","text":"kill(animal, model, probability=1.0, cause=\"\")\n\nKill this animal, optionally with a given percentage probability. Returns true if the animal dies, false if not.\n\n\n\n\n\n","category":"function"},{"location":"nature.html#Persefone.nearby_animals-Tuple{Animal, Agents.AgentBasedModel, Int64}","page":"Nature","title":"Persefone.nearby_animals","text":"nearby_animals(animal, model, radius)\n\nReturn an iterator over all animals in the given radius around this animal, excluding itself.\n\n\n\n\n\n","category":"method"},{"location":"nature.html#Persefone.nearby_animals-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel, Int64}","page":"Nature","title":"Persefone.nearby_animals","text":"nearby_animals(pos, model, radius)\n\nReturn an iterator over all animals in the given radius around this position.\n\n\n\n\n\n","category":"method"},{"location":"nature.html#Persefone.reproduce!","page":"Nature","title":"Persefone.reproduce!","text":"reproduce!(animal, model, n=1)\n\nProduce one or more offspring for the given animal at its current location.\n\n\n\n\n\n","category":"function"},{"location":"nature.html#insects.jl","page":"Nature","title":"insects.jl","text":"","category":"section"},{"location":"nature.html","page":"Nature","title":"Nature","text":"This file contains the insect submodel, which calculates the likely insect biomass in a given location at a given time.","category":"page"},{"location":"nature.html","page":"Nature","title":"Nature","text":"Modules = [Persefone]\nPages = [\"nature/insects.jl\"]","category":"page"},{"location":"nature.html#Persefone.insectbiomass-Tuple{Pixel, Agents.AgentBasedModel}","page":"Nature","title":"Persefone.insectbiomass","text":"insectbiomass(pixel, model)\n\nCalculate the insect biomass in this location, using the factors configured in the nature.insectmodel settings (any combination of: \"season\", \"habitat\", \"weather\", \"pesticides\"). Returns a float value in g/m².\n\nBiological note: this is a very approximate calculation! Insect biomass varies wildly in time and space and is hard to measure. This calculation is based on the idea of a parabolic seasonal development of insect abundance, modified by habitat suitability, weather, and pesticide application. Although it is based on empirical studies, it can only deliver a rough, order-of-magnitude estimation of likely insect biomass in a given location.\n\nSources:\n\nOdderskær et al. (1997). Skylark Reproduction in Pesticide Treated and Untreated Fields (32; Pesticides Research). Danish Environmental Protection Agency.\nGrüebler et al. (2008). A predictive model of the density of airborne insects in agricultural environments. Agriculture, Ecosystems & Environment, 123(1), 75–80. https://doi.org/10.1016/j.agee.2007.05.001\nPaquette et al. (2013). Seasonal patterns in Tree Swallow prey (Diptera) abundance are affected by agricultural intensification. Ecological Applications, 23(1), 122–133. https://doi.org/10.1890/12-0068.1\nPüttmanns et al. (2022). Habitat use and foraging parameters of breeding Skylarks indicate no seasonal decrease in food availability in heterogeneous farmland. Ecology and Evolution, 12(1), e8461. https://doi.org/10.1002/ece3.8461\n\n\n\n\n\n","category":"method"},{"location":"nature.html#ecologicaldata.jl","page":"Nature","title":"ecologicaldata.jl","text":"","category":"section"},{"location":"nature.html","page":"Nature","title":"Nature","text":"This file contains a set of life-history related utility functions needed by species.","category":"page"},{"location":"nature.html","page":"Nature","title":"Nature","text":"Modules = [Persefone]\nPages = [\"nature/ecologicaldata.jl\"]","category":"page"},{"location":"nature.html#Persefone.initecologicaldata-Tuple{Agents.AgentBasedModel}","page":"Nature","title":"Persefone.initecologicaldata","text":"initecologicaldata()\n\nCreate output files for each data group collected by the nature model.\n\n\n\n\n\n","category":"method"},{"location":"nature.html#Persefone.saveindividualdata-Tuple{Agents.AgentBasedModel}","page":"Nature","title":"Persefone.saveindividualdata","text":"saveindividualdata(model)\n\nReturn a comma-separated set of lines (to be printed to individuals.csv), listing all properties of all animal individuals in the model. May be called never, daily, monthly, yearly, or at the end of a simulation, depending on the parameter nature.indoutfreq. WARNING: Produces very big files!\n\n\n\n\n\n","category":"method"},{"location":"nature.html#Persefone.savepopulationdata-Tuple{Agents.AgentBasedModel}","page":"Nature","title":"Persefone.savepopulationdata","text":"savepopulationdata(model)\n\nReturn a comma-separated set of lines (to be printed to populations.csv), giving the current date and population size for each animal species. May be called never, daily, monthly, yearly, or at the end of a simulation, depending on the parameter nature.popoutfreq.\n\n\n\n\n\n","category":"method"},{"location":"io.html#Input,-Output,-and-Settings","page":"Input, Output, and Settings","title":"Input, Output, and Settings","text":"","category":"section"},{"location":"io.html","page":"Input, Output, and Settings","title":"Input, Output, and Settings","text":"These functions are responsible for reading in all model configurations (passed by config file or commandline), administrating them during a run, and printing any output.","category":"page"},{"location":"io.html#parameters.toml","page":"Input, Output, and Settings","title":"parameters.toml","text":"","category":"section"},{"location":"io.html","page":"Input, Output, and Settings","title":"Input, Output, and Settings","text":"This is the default configuration file for Persefone, containing all model parameters. The syntax is described here: https://toml.io/en/","category":"page"},{"location":"io.html","page":"Input, Output, and Settings","title":"Input, Output, and Settings","text":"DO NOT MODIFY THIS FILE FOR SIMULATION EXPERIMENTS! Instead, copy it to another directory, modify the copy, and then pass it to the model using the --config parameter.","category":"page"},{"location":"io.html#input.jl","page":"Input, Output, and Settings","title":"input.jl","text":"","category":"section"},{"location":"io.html","page":"Input, Output, and Settings","title":"Input, Output, and Settings","text":"Modules = [Persefone]\nPages = [\"core/input.jl\"]","category":"page"},{"location":"io.html#Persefone.PARAMFILE","page":"Input, Output, and Settings","title":"Persefone.PARAMFILE","text":"The file that stores all default parameters: src/parameters.toml\n\n\n\n\n\n","category":"constant"},{"location":"io.html#Persefone.flattenTOML-Tuple{Any}","page":"Input, Output, and Settings","title":"Persefone.flattenTOML","text":"flattenTOML(dict)\n\nAn internal utility function to convert the two-dimensional dict returned by TOML.parsefile() into a one-dimensional dict, so that instead of writing settings[\"domain\"][\"param\"] one can use settings[\"domain.param\"]. Can be reversed with prepareTOML.\n\n\n\n\n\n","category":"method"},{"location":"io.html#Persefone.getsettings","page":"Input, Output, and Settings","title":"Persefone.getsettings","text":"getsettings(configfile, seed=nothing)\n\nCombines all configuration options to produce a single settings dict. Precedence: commandline parameters - user config file - default values\n\n\n\n\n\n","category":"function"},{"location":"io.html#Persefone.parsecommandline-Tuple{}","page":"Input, Output, and Settings","title":"Persefone.parsecommandline","text":"parsecommandline()\n\nCertain software parameters can be set via the commandline.\n\n\n\n\n\n","category":"method"},{"location":"io.html#Persefone.preprocessparameters-Tuple{Dict{String, Any}, String}","page":"Input, Output, and Settings","title":"Persefone.preprocessparameters","text":"preprocessparameters(settings)\n\nTake the raw input parameters and process them (convert types, perform checks, etc.). This is a helper function for getsettings.\n\n\n\n\n\n","category":"method"},{"location":"io.html#Persefone.@param-Tuple{Any}","page":"Input, Output, and Settings","title":"Persefone.@param","text":"@param(domainparam)\n\nReturn a configuration parameter from the global settings. The argument should be in the form <domain>.<parameter>, for example @param(core.outdir). Possible values for <domain> are core, nature, farm, or crop. For a full list of parameters, see src/parameters.toml.\n\nNote: this macro only works in a context where the model object is available!\n\n\n\n\n\n","category":"macro"},{"location":"io.html#Persefone.@rand-Tuple","page":"Input, Output, and Settings","title":"Persefone.@rand","text":"@rand(args...)\n\nReturn a random number or element from the sample, using the model RNG. This is a utility wrapper that can only be used a context where the model object is available.\n\n\n\n\n\n","category":"macro"},{"location":"io.html#Persefone.@shuffle!-Tuple{Any}","page":"Input, Output, and Settings","title":"Persefone.@shuffle!","text":"@shuffle!(collection)\n\nShuffle the given collection in place, using the model RNG. This is a utility wrapper that can only be used a context where the model object is available.\n\n\n\n\n\n","category":"macro"},{"location":"io.html#output.jl","page":"Input, Output, and Settings","title":"output.jl","text":"","category":"section"},{"location":"io.html","page":"Input, Output, and Settings","title":"Input, Output, and Settings","text":"Modules = [Persefone]\nPages = [\"core/output.jl\"]","category":"page"},{"location":"io.html#Persefone.DataOutput","page":"Input, Output, and Settings","title":"Persefone.DataOutput","text":"DataOutput\n\nA struct for organising model output. This is designed for text-based data output that is updated more or less regularly (e.g. population data in csv files). Submodels can register their own output functions using newdataoutput!.\n\nStruct fields: - filename: the name of the file to be created in the user-specified output directory - header: a string to be written to the start of the file as it is initialised - outputfunction: a function that takes a model object and returns a string to write to file - frequency: how often to call the output function (daily/monthly/yearly/end/never)\n\n\n\n\n\n","category":"type"},{"location":"io.html#Persefone.createdatadir-Tuple{String, Union{Bool, String}}","page":"Input, Output, and Settings","title":"Persefone.createdatadir","text":"createdatadir(outdir, overwrite)\n\nCreates the output directory, dealing with possible conflicts.\n\n\n\n\n\n","category":"method"},{"location":"io.html#Persefone.modellogger-Tuple{String, String}","page":"Input, Output, and Settings","title":"Persefone.modellogger","text":"modellogger(loglevel, outdir)\n\nCreate a logger object that writes output both to screen and to a logfile. This object is stored as model.logger and can then be used with with_logger(). Note: requires createdatadir to be run first.\n\n\n\n\n\n","category":"method"},{"location":"io.html#Persefone.newdataoutput!-Tuple{Agents.AgentBasedModel, String, String, Function, String}","page":"Input, Output, and Settings","title":"Persefone.newdataoutput!","text":"newdataoutput!(model, filename, header, outputfunction, frequency)\n\nCreate and register a new data output. This function must be called by all submodels that want to have their output functions called regularly.\n\n\n\n\n\n","category":"method"},{"location":"io.html#Persefone.outputdata-Tuple{Agents.AgentBasedModel}","page":"Input, Output, and Settings","title":"Persefone.outputdata","text":"outputdata(model)\n\nCycle through all registered data outputs and activate them according to their configured frequency.\n\n\n\n\n\n","category":"method"},{"location":"io.html#Persefone.prepareTOML-Tuple{Any}","page":"Input, Output, and Settings","title":"Persefone.prepareTOML","text":"prepareTOML(dict)\n\nAn internal utility function to re-convert the one-dimensional dict created by flattenTOML into the two-dimensional dict needed by TOML.print, and convert any data types into TOML-compatible types where necessary.\n\n\n\n\n\n","category":"method"},{"location":"io.html#Persefone.saveinputfiles-Tuple{Agents.AgentBasedModel}","page":"Input, Output, and Settings","title":"Persefone.saveinputfiles","text":"saveinputfiles(model)\n\nCopy all input files into the output directory, including the actual parameter settings used. This allows replicating a run in future.\n\n\n\n\n\n","category":"method"},{"location":"io.html#Persefone.withtestlogger-Tuple{Agents.AgentBasedModel}","page":"Input, Output, and Settings","title":"Persefone.withtestlogger","text":"withtestlogger(model)\n\nReplace the model logger with the currently active logger. This is intended to be used in the testsuite to circumvent a Julia issue, where @test_logs doesn't work with local loggers.\n\n\n\n\n\n","category":"method"},{"location":"architecture.html#Source-code-architecture","page":"Source code architecture","title":"Source code architecture","text":"","category":"section"},{"location":"architecture.html#Model-components","page":"Source code architecture","title":"Model components","text":"","category":"section"},{"location":"architecture.html","page":"Source code architecture","title":"Source code architecture","text":"(Image: \"model architecture\")","category":"page"},{"location":"architecture.html","page":"Source code architecture","title":"Source code architecture","text":"Persefone is divided into four components, three of which are semi-independent submodels:","category":"page"},{"location":"architecture.html","page":"Source code architecture","title":"Source code architecture","text":"core: This is the foundation of the model software, which sets up and executes simulation runs. It also reads in the configuration file and landscape maps, and provides data output functionality. (Eventually, it will also provide weather data.)\nnature: This is an individual-based model of species in agricultural landscapes. It defines the Animal agent type, and a set of macros that can be used to rapidly create new species. It also includes ecological process functions that are useful for all species.\nfarm: This is an agent-based model of farmer decision making. It is not yet implemented, but will provide the Farmer agent type.\ncrop: This is a mathematical growth model for various crops. It is not yet implemented, but already provides the agent type FarmPlot, representing one field and its associated extent and crop type.","category":"page"},{"location":"architecture.html","page":"Source code architecture","title":"Source code architecture","text":"Conceptually, core provides functionality that is needed by all of the submodels. Decisions made by Farmers affect the FarmPlots they own, and (directly or indirectly) the Animals in the model landscape.","category":"page"},{"location":"architecture.html#Important-implementation-details","page":"Source code architecture","title":"Important implementation details","text":"","category":"section"},{"location":"architecture.html","page":"Source code architecture","title":"Source code architecture","text":"(Image: \"the model object\")","category":"page"},{"location":"architecture.html#The-model-object","page":"Source code architecture","title":"The model object","text":"","category":"section"},{"location":"architecture.html","page":"Source code architecture","title":"Source code architecture","text":"A cursory reading of the source code will quickly show that most functions take an AgentBasedModel object as one of their arguments. This is the key data structure of Agents.jl, and holds all state that is in any way relevant to a simulation run. (Persefone has a strict \"no global state\" policy to avoid state-dependent bugs and allow parallelisation.) The model object gives access to all agent instances (via model[id], where id is the unique identifier of this agent). It also stores the configuration (model.settings), the landscape (model.landscape, a matrix of Pixel objects that store the local land cover, amongst other things), and the current simulation date (model.date). (See initmodel for details.)","category":"page"},{"location":"architecture.html","page":"Source code architecture","title":"Source code architecture","text":"For more information about working with agent objects, see the Agents.jl API.","category":"page"},{"location":"architecture.html#Model-configuration/the-@param-macro","page":"Source code architecture","title":"Model configuration/the @param macro","text":"","category":"section"},{"location":"architecture.html","page":"Source code architecture","title":"Source code architecture","text":"The model is configured via a TOML file, the default version of which is at src/parameters.toml. An individual run can be configured using a user-defined configuration file, commandline arguments, or function calls (when Persefone is used as a package rather than an application). During a model run, the @param macro can be used to access parameter values. Note that parameter names are prepended with the name of the component they are associated with. For example, the outdir parameter belongs to the [core] section of the TOML file, and must therefore be referenced as @param(core.outdir). (See src/core/input.jl for details.)","category":"page"},{"location":"architecture.html","page":"Source code architecture","title":"Source code architecture","text":"info: @param and other macros\nAs @param(parameter) expands to model.settings[\"parameter\"], it can obviously only be used in a context where the model object is actually available. (This is the case for most functions in Persefone, but not for all.) Similarly, many of the nature macros depend on specific variables being available where they are called, and can therefore only be used in specific contexts (this is indicated in their documentation).","category":"page"},{"location":"architecture.html#Output-data","page":"Source code architecture","title":"Output data","text":"","category":"section"},{"location":"architecture.html","page":"Source code architecture","title":"Source code architecture","text":"Persefone can output model data into text files with a specified frequency (daily, monthly, yearly, or at the simulation end). Submodels can use newdataoutput! to plug into this system. For an example of how to use this, see src/nature/ecologicaldata.jl. (See src/core/output.jl for details.)","category":"page"},{"location":"architecture.html#Farm-events","page":"Source code architecture","title":"Farm events","text":"","category":"section"},{"location":"architecture.html","page":"Source code architecture","title":"Source code architecture","text":"The FarmEvent struct is used to communicate farming-related events between submodels. An event can be triggered with createevent! and affects all pixels within a FarmPlot. (See src/core/landscape.jl for details.)","category":"page"},{"location":"architecture.html#Random-numbers-and-logging","page":"Source code architecture","title":"Random numbers and logging","text":"","category":"section"},{"location":"architecture.html","page":"Source code architecture","title":"Source code architecture","text":"By default in Julia, the random number generator (RNG) and the system logger are two globally accessible variables. As Persefone needs to avoid all global data (since this would interfere with reproducibility in parallel runs), the model object stores a local logger and a local RNG. The local logger generally does not change the way the model uses log statements, it is only relevant for some functions in src/core/simulation.jl.","category":"page"},{"location":"architecture.html","page":"Source code architecture","title":"Source code architecture","text":"info: Using the model RNG\nWhenever you need to use a random number, you must use the model.rng. The easiest way to do this is with the @rand and @shuffle! macros. (Note that these, too, require access to the model object.)","category":"page"},{"location":"species.html#Species","page":"Species","title":"Species","text":"","category":"section"},{"location":"species.html","page":"Species","title":"Species","text":"The ecological submodel in Persefone simulates a range of species in agricultural landscapes.","category":"page"},{"location":"species.html#Skylark","page":"Species","title":"Skylark","text":"","category":"section"},{"location":"species.html","page":"Species","title":"Species","text":"Modules = [Persefone]\nPages = [\"nature/species/skylark.jl\"]","category":"page"},{"location":"species-dsl.html#Defining-new-species","page":"Defining new species","title":"Defining new species","text":"","category":"section"},{"location":"species-dsl.html#The-Persefone-species-DSL","page":"Defining new species","title":"The Persefone species DSL","text":"","category":"section"},{"location":"species-dsl.html","page":"Defining new species","title":"Defining new species","text":"In order to make implementing new species as easy as possible, Persefone includes a domain-specific language (DSL) built from a collection of macros and functions.","category":"page"},{"location":"species-dsl.html","page":"Defining new species","title":"Defining new species","text":"Here is an example of what this looks like, using a hypothetical mermaid species:","category":"page"},{"location":"species-dsl.html","page":"Defining new species","title":"Defining new species","text":"@species Mermaid begin\n ageofmaturity = 2\n pesticidemortality = 1.0\n @initialise(@habitat(@landcover() == water), pairs=true)\n\t\n @phase life begin\n @debug \"$(animalid(animal)) is swimming happily in its pond.\"\n @respond pesticide @kill(@trait(pesticidemortality), \"poisoning\")\n @respond harvest @setphase(drought)\n @debug \"Animal: $animal\"\n if @trait(sex) == female && @countanimals() < 3 &&\n @trait(age) >= @trait(ageofmaturity) && @landcover() == water\n @reproduce()\n end\n end\n\t\n @phase drought begin\n n = sum(1 for a in @neighbours(0))\n @debug \"$(animalid(animal)) is experiencing drought with $n neighbour(s).\"\n @respond sowing @setphase(life)\n end\nend","category":"page"},{"location":"species-dsl.html","page":"Defining new species","title":"Defining new species","text":"The two most important macros are @species and @phase, followed by @initialise, @trait, @respond, and @habitat. Other macros provide convenience wrappers for common functions. (See src/nature/nature.jl for details.)","category":"page"},{"location":"species-dsl.html","page":"Defining new species","title":"Defining new species","text":"The top-level macro is @species. This takes two arguments: a species name and a definition block (enclosed in begin and end tags). At the start of the definition block, species-specific variables can be defined that should be available throughout a species' lifetime. Code in this section has access to the model object and can thus reference the current model state. In this section, the user also has to call the @initialise macro. This wraps the initpopulation function, and takes a habitat descriptor (see @habitat below) and several options to specify how the species' population should be distributed in the landscape during model initialisation.","category":"page"},{"location":"species-dsl.html","page":"Defining new species","title":"Defining new species","text":"Following this section, each species must define one or more @phase blocks. The concept behind this is that species show different behaviours at different phases of their lifecycle. Each @phase block defines the behaviour in one of these phases. (Technically, it defines a function that will be called daily, so long as the species' phase variable is set to the name of this phase.) Code in this section has access to the model object as well as an animal object, which is the currently active animal agent. Properties of the animal agent, regardless of whether they were defined by the user or by Persefone, can be accessed using the @trait macro. Within a phase block, @respond can be used to define the species' response to a FarmEvent that affects the species' current location, while a variety of other macros provide wrappers to ecological process functions from src/nature/populations.jl.","category":"page"},{"location":"species-dsl.html","page":"Defining new species","title":"Defining new species","text":"Another important macro is @habitat. This defines a \"habitat descriptor\", i.e. a predicate function that tests whether or not a given landscape pixel is suitable for a specified purpose. Such habitat descriptors are used as arguments to various functions, for example for population initialisation or movement. The argument to @habitat consists of a logical expression, which has access to the animal's current position (the pos tuple variable) and the model. Various macros are available to easily reference information about the current location, such as @landcover or @distancetoedge.","category":"page"},{"location":"species-dsl.html#Implementation-details","page":"Defining new species","title":"Implementation details","text":"","category":"section"},{"location":"species-dsl.html","page":"Defining new species","title":"Defining new species","text":"Due to a known performance problem with multi-agent models, the underlying implementation of species is rather complicated (see src/nature/nature.jl for details.)","category":"page"},{"location":"species-dsl.html","page":"Defining new species","title":"Defining new species","text":"Rather than creating a new type/struct for each species, all Animal agents have the same type. Instead, they are differentiated by a traits dict, which stores both species-specific parameters and run-time variables. Note that due to a redefinition of the getproperty()/setproperty!() methods, variables from the trait dict can be accessed and modified just like normal struct fields (i.e. although phase is defined in the dict, not the struct, animal.phase = \"newphase\" works just fine - one does not have to use animal.traits[\"phase\"] = \"newphase\".)","category":"page"},{"location":"species-dsl.html","page":"Defining new species","title":"Defining new species","text":"Under the hood, the @species macro generates a function (with the name of the species), which in turn creates the trait dict when called. Thus, adding a new animal agent to the model involves instantiating an Animal object, then calling the relevant species function and attaching the returned dict to the agent object.","category":"page"},{"location":"species-dsl.html","page":"Defining new species","title":"Defining new species","text":"Similarly, the @phase macro too works by defining a new function, which is stored in the species' trait dict. These functions take an animal object and the model object as input, and define what the species does during its daily update.","category":"page"},{"location":"species-dsl.html","page":"Defining new species","title":"Defining new species","text":"Once again, @habitat creates a function that takes model and pos as input and returns a boolean response. Functions that require a habitat descriptor thus take in this (anonymous) function and call it internally.","category":"page"},{"location":"species-dsl.html","page":"Defining new species","title":"Defining new species","text":"Finally, the @initialise macro is a wrapper around initpopulation, which (yet again) creates a function that specifies how a species' population is to be initialised at the beginning of a simulation run. This function is stored in the species trait dict and accessed during model setup.","category":"page"},{"location":"developing.html#Developing-Persefone","page":"Developing Persefone","title":"Developing Persefone","text":"","category":"section"},{"location":"developing.html#Workflow","page":"Developing Persefone","title":"Workflow","text":"","category":"section"},{"location":"developing.html","page":"Developing Persefone","title":"Developing Persefone","text":"Pull the current version from the master branch on Gitlab: https://git.idiv.de/xo30xoqa/persephone.\nIf you are working on a new feature, create a new branch to avoid breaking the master branch. (The master branch on Github should always be in a runnable and error-free state.)\nImplement your changes.\nRun an example simulation and the test suite to make sure everything works without crashing (make run and make test on Linux, or execute run.jl and test/runtests.jl manually.)\nCommit your work frequently, and try to keep each commit small. Don't forget to add relevant tests to the test suite.\nOnce your satisfied with your work, do another pull/merge from the master branch in case somebody else changed the branch in the meantime. Then merge your work into master and push to the Gitlab server.\nRepeat :-)","category":"page"},{"location":"developing.html","page":"Developing Persefone","title":"Developing Persefone","text":"The Gitlab issue tracker can be used to create, discuss, and assign tasks, as well as to monitor progress towards milestones/releases. Once we have a first release, we will start using semantic versioning.","category":"page"},{"location":"developing.html#Libraries","page":"Developing Persefone","title":"Libraries","text":"","category":"section"},{"location":"developing.html#Agents.jl","page":"Developing Persefone","title":"Agents.jl","text":"","category":"section"},{"location":"developing.html","page":"Developing Persefone","title":"Developing Persefone","text":"Our model uses Agents.jl as a framework. Their repository can be used to inspect the source code or submit bug reports (the authors are quick to respond). Questions can be asked at the Julia Discourse forum.","category":"page"},{"location":"developing.html","page":"Developing Persefone","title":"Developing Persefone","text":"Tutorial on collaborating on Julia packages: https://www.matecdev.com/posts/julia-package-collaboration.html.","category":"page"},{"location":"developing.html#Revise.jl","page":"Developing Persefone","title":"Revise.jl","text":"","category":"section"},{"location":"developing.html","page":"Developing Persefone","title":"Developing Persefone","text":"Revise.jl allows one to reload code without restarting the Julia interpreter. Get it with Pkg.add(\"Revise\"), then add using Revise to .julia/config/startup.jl to have it automatically available.","category":"page"},{"location":"developing.html#Test","page":"Developing Persefone","title":"Test","text":"","category":"section"},{"location":"developing.html","page":"Developing Persefone","title":"Developing Persefone","text":"Persefone uses the inbuilt Julia testing framework. All new functions should have appropriate tests written for them in the appropriate file in the test directory. (See test/runtests.jl for details.) There are three ways to run the test suite: in the terminal, executing make test or cd test; julia runtests.jl; or in the Julia REPL, Pkg.activate(\".\"); Pkg.test().","category":"page"},{"location":"developing.html#Documenter.jl","page":"Developing Persefone","title":"Documenter.jl","text":"","category":"section"},{"location":"developing.html","page":"Developing Persefone","title":"Developing Persefone","text":"The HTML documentation is generated using Documenter.jl. Therefore, all new functions should have docstrings attached. New files need to be integrated into the relevant documentation source files in docs/src, and if necessary into docs/builddocs.jl. To build the documentation, run make docs, or cd docs; julia builddocs.jl (if using the latter, don't forget to update the date and commit in docs/src/index.md).","category":"page"},{"location":"developing.html#Julia-editors","page":"Developing Persefone","title":"Julia editors","text":"","category":"section"},{"location":"developing.html#Emacs","page":"Developing Persefone","title":"Emacs","text":"","category":"section"},{"location":"developing.html","page":"Developing Persefone","title":"Developing Persefone","text":"There are a couple of addons that make working with Julia much nicer in Emacs:","category":"page"},{"location":"developing.html","page":"Developing Persefone","title":"Developing Persefone","text":"julia-mode gives syntax highlighting. Install with M-x package-install julia-mode.\njulia-snail provides IDE-like features, especially a fully-functional REPL and the ability to evaluate code straight from inside a buffer. Note that the installation can be somewhat tricky. You first need to manually install all the dependencies of its dependency vterm, then install vterm itself with M-x package-install vterm, before you can do M-x package-install julia-snail. Then add it to your init.el with (require 'julia-snail) and (add-hook 'julia-mode-hook #'julia-snail-mode).\ncompany-mode integrates with Snail to give code completion. Install with M-x package-install company, then add (add-hook 'julia-mode-hook #'company-mode) and (global-set-key (kbd \"C-<tab>\") 'company-complete) to your init.el.\nmagit is a great git interface for Emacs. Install with M-x package-install magit and add (global-set-key (kbd \"C-x g\") 'magit-status) to your init.el.","category":"page"},{"location":"developing.html#VSCode","page":"Developing Persefone","title":"VSCode","text":"","category":"section"},{"location":"developing.html","page":"Developing Persefone","title":"Developing Persefone","text":"See here.","category":"page"},{"location":"developing.html","page":"Developing Persefone","title":"Developing Persefone","text":"TODO: add more detail.","category":"page"},{"location":"simulation.html#Simulation","page":"Simulation","title":"Simulation","text":"","category":"section"},{"location":"simulation.html","page":"Simulation","title":"Simulation","text":"The core directory holds source files that are important for all submodels, including scheduling, landscape, and input/output functions.","category":"page"},{"location":"simulation.html#simulation.jl","page":"Simulation","title":"simulation.jl","text":"","category":"section"},{"location":"simulation.html","page":"Simulation","title":"Simulation","text":"This file includes the basal functions for initialising and running simulations.","category":"page"},{"location":"simulation.html","page":"Simulation","title":"Simulation","text":"Modules = [Persefone]\nPages = [\"core/simulation.jl\"]","category":"page"},{"location":"simulation.html#Persefone.finalise!-Tuple{Agents.AgentBasedModel}","page":"Simulation","title":"Persefone.finalise!","text":"finalise!(model)\n\nWrap up the simulation. Currently doesn't do anything except print some information.\n\n\n\n\n\n","category":"method"},{"location":"simulation.html#Persefone.initialise","page":"Simulation","title":"Persefone.initialise","text":"initialise(config=PARAMFILE, seed=nothing)\n\nInitialise the model: read in parameters, create the output data directory, and instantiate the AgentBasedModel object(s). Optionally allows specifying the configuration file and overriding the seed parameter. This returns a single model object, unless the config file contains multiple values for one or more parameters, in which case it creates a full-factorial simulation experiment and returns a vector of model objects.\n\n\n\n\n\n","category":"function"},{"location":"simulation.html#Persefone.initmodel-Tuple{Dict{String, Any}}","page":"Simulation","title":"Persefone.initmodel","text":"initmodel(settings)\n\nInitialise a model object using a ready-made settings dict. This is a helper function for initialise().\n\n\n\n\n\n","category":"method"},{"location":"simulation.html#Persefone.paramscan-Tuple{Dict{String, Any}, Vector{String}}","page":"Simulation","title":"Persefone.paramscan","text":"paramscan(settings)\n\nCreate a list of settings dicts, covering all possible parameter combinations given by the input settings (i.e. a full-factorial experiment). This is a helper function for initialise().\n\n\n\n\n\n","category":"method"},{"location":"simulation.html#Persefone.simulate","page":"Simulation","title":"Persefone.simulate","text":"simulate(config=PARAMFILE, seed=nothing)\n\nInitialise one or more model objects and carry out a full simulation experiment, optionally specifying a configuration file and a seed for the RNG.\n\nThis is the default way to run a Persefone simulation.\n\n\n\n\n\n","category":"function"},{"location":"simulation.html#Persefone.simulate!-Tuple{Agents.AgentBasedModel}","page":"Simulation","title":"Persefone.simulate!","text":"simulate!(model)\n\nCarry out a complete simulation run using a pre-initialised model object.\n\n\n\n\n\n","category":"method"},{"location":"simulation.html#Persefone.stepsimulation!-Tuple{Agents.AgentBasedModel}","page":"Simulation","title":"Persefone.stepsimulation!","text":"stepsimulation!(model)\n\nExecute one update of the model.\n\n\n\n\n\n","category":"method"},{"location":"simulation.html#landscape.jl","page":"Simulation","title":"landscape.jl","text":"","category":"section"},{"location":"simulation.html","page":"Simulation","title":"Simulation","text":"This file manages the landscape maps that underlie the model.","category":"page"},{"location":"simulation.html","page":"Simulation","title":"Simulation","text":"Modules = [Persefone]\nPages = [\"core/landscape.jl\"]","category":"page"},{"location":"farm.html#Farm-submodel","page":"Farm submodel","title":"Farm submodel","text":"","category":"section"},{"location":"farm.html","page":"Farm submodel","title":"Farm submodel","text":"Eventually, Persefone will include multiple farm-decision submodels. At the moment, we are only working with a very basic mock-up.","category":"page"},{"location":"farm.html#farm.jl","page":"Farm submodel","title":"farm.jl","text":"","category":"section"},{"location":"farm.html","page":"Farm submodel","title":"Farm submodel","text":"This file is responsible for managing the farm module(s).","category":"page"},{"location":"farm.html","page":"Farm submodel","title":"Farm submodel","text":"Modules = [Persefone]\nPages = [\"farm/farm.jl\"]","category":"page"},{"location":"farm.html#Persefone.Farmer","page":"Farm submodel","title":"Persefone.Farmer","text":"Farmer\n\nThis is the agent type for the farm ABM. (Not yet implemented.)\n\n\n\n\n\n","category":"type"},{"location":"farm.html#Persefone.initfarms!-Tuple{Agents.AgentBasedModel}","page":"Farm submodel","title":"Persefone.initfarms!","text":"initfarms!(model)\n\nInitialise the model with a set of farm agents.\n\n\n\n\n\n","category":"method"},{"location":"farm.html#Persefone.stepagent!-Tuple{Farmer, Agents.AgentBasedModel}","page":"Farm submodel","title":"Persefone.stepagent!","text":"stepagent!(farmer, model)\n\nUpdate a farmer by one day.\n\n\n\n\n\n","category":"method"},{"location":"adapting.html#Adapting-Persefone","page":"Adapting Persefone","title":"Adapting Persefone","text":"","category":"section"},{"location":"adapting.html","page":"Adapting Persefone","title":"Adapting Persefone","text":"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.","category":"page"},{"location":"adapting.html","page":"Adapting Persefone","title":"Adapting Persefone","text":"There are multiple ways to adapt Persefone for a new modelling study:","category":"page"},{"location":"adapting.html#Changing-the-parameters","page":"Adapting Persefone","title":"Changing the parameters","text":"","category":"section"},{"location":"adapting.html","page":"Adapting Persefone","title":"Adapting Persefone","text":"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>.","category":"page"},{"location":"adapting.html#Changing-the-region","page":"Adapting Persefone","title":"Changing the region","text":"","category":"section"},{"location":"adapting.html","page":"Adapting Persefone","title":"Adapting Persefone","text":"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.","category":"page"},{"location":"adapting.html","page":"Adapting Persefone","title":"Adapting Persefone","text":"You may also need to change aspects of the farm submodel. This is not yet implemented.","category":"page"},{"location":"adapting.html#Adding-new-animal-species","page":"Adapting Persefone","title":"Adding new animal species","text":"","category":"section"},{"location":"adapting.html","page":"Adapting Persefone","title":"Adapting Persefone","text":"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.","category":"page"},{"location":"adapting.html#Adding-new-crop-species","page":"Adapting Persefone","title":"Adding new crop species","text":"","category":"section"},{"location":"adapting.html","page":"Adapting Persefone","title":"Adapting Persefone","text":"Crop growth is not yet implemented.","category":"page"},{"location":"adapting.html#Adding-new-farmer-behaviour","page":"Adapting Persefone","title":"Adding new farmer behaviour","text":"","category":"section"},{"location":"adapting.html","page":"Adapting Persefone","title":"Adapting Persefone","text":"Farmer behaviour is not yet implemented.","category":"page"},{"location":"adapting.html#Adding-a-new-submodel","page":"Adapting Persefone","title":"Adding a new submodel","text":"","category":"section"},{"location":"adapting.html","page":"Adapting Persefone","title":"Adapting Persefone","text":"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.","category":"page"},{"location":"adapting.html","page":"Adapting Persefone","title":"Adapting Persefone","text":"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 initmodel and stepsimulation! for details.)","category":"page"},{"location":"adapting.html#Linking-to-another-model","page":"Adapting Persefone","title":"Linking to another model","text":"","category":"section"},{"location":"adapting.html","page":"Adapting Persefone","title":"Adapting Persefone","text":"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).","category":"page"},{"location":"adapting.html","page":"Adapting Persefone","title":"Adapting Persefone","text":"To interface with Julia from another language, see the Julia docs here and here.","category":"page"},{"location":"odd.html#Overview,-Design,-Details-(ODD)","page":"Overview, Design, Details (ODD)","title":"Overview, Design, Details (ODD)","text":"","category":"section"},{"location":"odd.html","page":"Overview, Design, Details (ODD)","title":"Overview, Design, Details (ODD)","text":"TODO","category":"page"},{"location":"gis.html#Maps-and-weather-data","page":"Maps and weather data","title":"Maps and weather data","text":"","category":"section"},{"location":"gis.html","page":"Maps and weather data","title":"Maps and weather data","text":"Persefone currently requires two separate map input files: one for land cover, the other for field geometry. Additionally, a weather input file is needed. This documents describe how to obtain and process the data needed for each of these.","category":"page"},{"location":"gis.html#Land-cover-maps","page":"Maps and weather data","title":"Land cover maps","text":"","category":"section"},{"location":"gis.html","page":"Maps and weather data","title":"Maps and weather data","text":"Land cover maps for Germany at 10m resolution can be obtained from Mundialis. These are generated annually from Sentinel data and comprise the following land cover classes:","category":"page"},{"location":"gis.html","page":"Maps and weather data","title":"Maps and weather data","text":"10: forest\n20: low vegetation\n30: water\n40: built-up\n50: bare soil\n60: agriculture","category":"page"},{"location":"gis.html","page":"Maps and weather data","title":"Maps and weather data","text":"To create a Persefone map input file, you need to crop the national Mundialis map to the extent that you want to simulate (suggestion: approx. 10x10km is a reasonable size).","category":"page"},{"location":"gis.html","page":"Maps and weather data","title":"Maps and weather data","text":"To do so, download the Mundialis map and import it into QGIS. Then create a new vector layer and create a rectangle feature to delimit the extent of your region. Then go to Raster -> Extraction -> Clip Raster by Extent. Select the Mundialis map as the input layer, set the clipping extent by choosing your region vector layer under Calculate from Layer and specify the output file name before clicking Run. This will generate a TIF file that you can pass to Persefone as the landcovermap parameter.","category":"page"},{"location":"gis.html#Field-ID-maps","page":"Maps and weather data","title":"Field ID maps","text":"","category":"section"},{"location":"gis.html","page":"Maps and weather data","title":"Maps and weather data","text":"In addition to the land cover data explained above, Persefone also needs information about agricultural field boundaries in order to assign these to the farming agents. Unfortunately, getting this is rather more complicated.","category":"page"},{"location":"gis.html","page":"Maps and weather data","title":"Maps and weather data","text":"In the EU, every country runs a Land Parcel Information System (LPIS) to administer CAP payments. In Germany, this is called InVeKoS and is run by the Länder. For example, you can view and download the InVeKoS data for Thüringen here. This gives you a vector layer which can be loaded into QGIS. However, it needs to be converted to a raster layer and cropped to your region extent before it can be used in Persefone.","category":"page"},{"location":"gis.html","page":"Maps and weather data","title":"Maps and weather data","text":"The first thing to do is to make sure that the vector layer has a numeric (!) field with a unique identifier for each field block (check the attribute table). The Thüringen data has the FBI (\"Feldblockident\") field, but this is a string value and therefore not usable by the rasteriser. So, we set the vector layer to edit mode, open the field calculator, enter the information for a new field (call it \"FID\" and set it to a 32-bit integer), and enter @row_number in the expression field. Then save the layer and close the calculator.","category":"page"},{"location":"gis.html","page":"Maps and weather data","title":"Maps and weather data","text":"Secondly, you need to filter out all non-field/non-grassland plot types. (LPIS also has data on forests and various landscape elements that are not relevant to our use case.) Assuming you're working with the Thüringen InVeKoS data (other data sets may have a different structure), right-click on the layer name in QGIS' layer overview and click on \"Filter...\". Then, enter this expression in the query builder: \"BNK\" = 'AL' OR \"BNK\" = 'GL' and click \"OK\". This will select only field and grassland plots.","category":"page"},{"location":"gis.html","page":"Maps and weather data","title":"Maps and weather data","text":"Next, open the rasteriser (Raster -> Conversion -> Rasterize). Select your FID field as the \"Field to use for a burn-in value\", and your land cover map (as created above - this ensures the two layers match) as the output extent. Make sure the \"fixed value to burn\" is \"Not set\". Then choose \"Georeferenced units\" as the \"Out raster size units\" and set horizontal and vertical resolution to 10.0. In the advanced parameters, set the output data type to UInt32. Finally, enter an output file name and run. The resulting TIF file can be passed to Persefone as the farmfieldmap parameter.","category":"page"},{"location":"gis.html#Weather-data","page":"Maps and weather data","title":"Weather data","text":"","category":"section"},{"location":"gis.html","page":"Maps and weather data","title":"Maps and weather data","text":"Currently, Persefone uses historical weather data from the closes weather station as its weather input. (In future, this may be changed to a more detailed raster input, which could then also provide future weather predictions under climate change.) Weather data can be downloaded from the German weather service (DWD). The relevant data are in the folder daily/kl/historical.","category":"page"},{"location":"gis.html","page":"Maps and weather data","title":"Maps and weather data","text":"The description of this data set and the list of weather stations can be found in the Persefone repository, in the docs folder (or downloaded from the link above). Using the list of weather stations, select the one closest to the area of study. Note that not all stations were continuously in operation; make sure that the selected station covers the years of interest.","category":"page"},{"location":"gis.html","page":"Maps and weather data","title":"Maps and weather data","text":"Region Jena: station number 02444 (\"Jena (Sternwarte)\")\nRegion Eichsfeld:\nRegion Thüringer Becken:\nRegion Hohenlohe:\nRegion Bodensee:\nRegion Nördlicher Oberrhein:","category":"page"},{"location":"gis.html","page":"Maps and weather data","title":"Maps and weather data","text":"From the link above, download the ZIP file associated with the station number. Check the included meta-data if there is any important missing data, or other relevant information (e.g. the station moved position).","category":"page"},{"location":"gis.html","page":"Maps and weather data","title":"Maps and weather data","text":"Then use data/extract_weather_data.R to process the data into the format needed by Persefone:","category":"page"},{"location":"gis.html","page":"Maps and weather data","title":"Maps and weather data","text":"library(tidyverse)\n\n## replace this with the correct file name\nweatherfile = \"produkt_klima_tag_18210101_20221231_02444.txt\"\n\ndata = read.table(weatherfile, sep=\";\", header=T)\n\nweather = data %>%\n ## drop values before 2000 to save space\n filter(MESS_DATUM>=20000101) %>%\n ## select relevant variables and convert place-holder values to NA\n select(MESS_DATUM, FM, RSK, SDK, VPM, TMK, TXK, TNK) %>%\n mutate(date=MESS_DATUM, MESS_DATUM=NULL,\n mean_windspeed=na_if(FM, -999), FM=NULL,\n precipitation=na_if(RSK, -999), RSK=NULL,\n sunshine_hours=na_if(SDK, -999), SDK=NULL,\n mean_vapour_pressure=na_if(VPM, -999), VPM=NULL,\n mean_temperature=na_if(TMK, -999), TMK=NULL,\n max_temperature=na_if(TXK, -999), TXK=NULL,\n min_temperature=na_if(TNK, -999), TNK=NULL)\n\n## replace with the desired file name\nwrite.csv(weather, file=\"weather_jena.csv\", row.names=FALSE)","category":"page"},{"location":"gis.html","page":"Maps and weather data","title":"Maps and weather data","text":"Note: for calculating the reference evapotranspiration ET_0 (needed for the AquaCrop model), use the FAO Penman-Monteith equation.","category":"page"},{"location":"crops.html#Crop-submodel","page":"Crop submodel","title":"Crop submodel","text":"","category":"section"},{"location":"crops.html","page":"Crop submodel","title":"Crop submodel","text":"Eventually, Persefone will include a full-blown crop-growth model (an adaptation of AquaCrop, created by the FAO). At the moment, we are only working with a very basic mock-up.","category":"page"},{"location":"crops.html#crops.jl","page":"Crop submodel","title":"crops.jl","text":"","category":"section"},{"location":"crops.html","page":"Crop submodel","title":"Crop submodel","text":"This includes the types and functions needed for all crop growth model, which are also referenced by the other submodels.","category":"page"},{"location":"crops.html","page":"Crop submodel","title":"Crop submodel","text":"Modules = [Persefone]\nPages = [\"crop/crops.jl\"]","category":"page"},{"location":"crops.html#Persefone.CropType","page":"Crop submodel","title":"Persefone.CropType","text":"The crop types simulated by the model\n\n\n\n\n\n","category":"type"},{"location":"crops.html#Persefone.FarmPlot","page":"Crop submodel","title":"Persefone.FarmPlot","text":"FarmPlot\n\nThis represents one field, i.e. a collection of pixels with the same management. This is the spatial unit with which the crop growth model and the farm model work.\n\n\n\n\n\n","category":"type"},{"location":"crops.html#Persefone.averagefieldsize-Tuple{Agents.AgentBasedModel}","page":"Crop submodel","title":"Persefone.averagefieldsize","text":"averagefieldsize(model)\n\nCalculate the average field size in hectares for the model landscape.\n\n\n\n\n\n","category":"method"},{"location":"crops.html#Persefone.cropheight-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel}","page":"Crop submodel","title":"Persefone.cropheight","text":"cropheight(model, position)\n\nReturn the height of the crop at this position, or nothing if there is no crop here (utility wrapper).\n\n\n\n\n\n","category":"method"},{"location":"crops.html#Persefone.croptype-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel}","page":"Crop submodel","title":"Persefone.croptype","text":"croptype(model, position)\n\nReturn the crop at this position, or nothing if there is no crop here (utility wrapper).\n\n\n\n\n\n","category":"method"},{"location":"crops.html#Persefone.initfields!-Tuple{Agents.AgentBasedModel}","page":"Crop submodel","title":"Persefone.initfields!","text":"initfields!(model)\n\nInitialise the model with its farm plots.\n\n\n\n\n\n","category":"method"},{"location":"crops.html#Persefone.stepagent!-Tuple{FarmPlot, Agents.AgentBasedModel}","page":"Crop submodel","title":"Persefone.stepagent!","text":"stepagent!(farmplot, model)\n\nUpdate a farm plot by one day.\n\n\n\n\n\n","category":"method"},{"location":"index.html","page":"Introduction","title":"Introduction","text":"CurrentModule = Persefone","category":"page"},{"location":"index.html#Introduction","page":"Introduction","title":"Introduction","text":"","category":"section"},{"location":"index.html","page":"Introduction","title":"Introduction","text":"Persefone is an agent-based, socio-economic-ecological model of agricultural landscapes in Europe under the Common Agricultural Policy (CAP).","category":"page"},{"location":"index.html","page":"Introduction","title":"Introduction","text":"It's aim is to investigate how policy affects farmer decision-making, and how this in turn affects various animal species. It includes a farm submodel, a crop-growth submodel, and an ecological submodels.","category":"page"},{"location":"index.html#Running-the-model","page":"Introduction","title":"Running the model","text":"","category":"section"},{"location":"index.html","page":"Introduction","title":"Introduction","text":"To run a single experiment, execute run.jl:","category":"page"},{"location":"index.html","page":"Introduction","title":"Introduction","text":"julia run.jl -c <CONFIG>","category":"page"},{"location":"index.html","page":"Introduction","title":"Introduction","text":"Other commandline arguments are:","category":"page"},{"location":"index.html","page":"Introduction","title":"Introduction","text":"usage: run.jl [-c CONFIGFILE] [-s SEED] [-o OUTDIR] [-l LOGLEVEL] \n [--version] [-h]\n\noptional arguments:\n -c, --configfile CONFIGFILE\n name of the configuration file\n -s, --seed SEED inital random seed (type: Int64)\n -o, --outdir OUTDIR location of the output directory\n -l, --loglevel LOGLEVEL\n verbosity: \"debug\", \"info\", or \"quiet\"\n --version show version information and exit\n -h, --help show this help message and exit","category":"page"},{"location":"index.html#Model-input","page":"Introduction","title":"Model input","text":"","category":"section"},{"location":"index.html","page":"Introduction","title":"Introduction","text":"Persefone requires three input files: a configuration file and two map files. How to generate the map files is documented elsewhere. The configuration file defines parameter values and looks like this (see src/parameters.toml for a complete list of parameters):","category":"page"},{"location":"index.html","page":"Introduction","title":"Introduction","text":"### Persefone - a socio-economic-ecological model of European agricultural landscapes.\n###\n### This is the default configuration file for Persefone, containing all model parameters.\n### The syntax is described here: https://toml.io/en/\n\n[core]\nconfigfile = \"src/parameters.toml\" # location of the configuration file\noutdir = \"results\" # location and name of the output folder\noverwrite = \"ask\" # overwrite the output directory? (true/false/\"ask\")\nloglevel = \"debug\" # verbosity level: \"debug\", \"info\", \"warn\"\nprocessors = 2 # number of processors to use on parallel runs\nseed = 2 # seed value for the RNG (0 -> random value)\n# dates to start and end the simulation\nstartdate = 2022-01-01\nenddate = 2022-12-31\n\n[world]\nlandcovermap = \"data/landcover_jena.tif\" # location of the landcover map\nfarmfieldsmap = \"data/fields_jena.tif\" # location of the field geometry map\n\n[farm]\nfarmmodel = \"FieldManager\" # which version of the farm model to use (not yet implemented)\n\n[nature]\ntargetspecies = [\"Wolpertinger\", \"Wyvern\"] # list of target species to simulate\npopoutfreq = \"daily\" # output frequency population-level data, daily/monthly/yearly/end/never\nindoutfreq = \"end\" # output frequency individual-level data, daily/monthly/yearly/end/never\n\t\n[crop]\ncropmodel = \"linear\" # crop growth model to use, \"linear\" or \"aquacrop\" (not yet implemented)","category":"page"},{"location":"index.html","page":"Introduction","title":"Introduction","text":"info: Parameter scanning\nYou can set any parameter to a list of different values, e.g. seed = [1,2,3]. Persefone will then set up and run multiple simulations, one for every possible combination of parameters that you entered (i.e. do a full-factorial simulation experiment).","category":"page"},{"location":"index.html","page":"Introduction","title":"Introduction","text":"Last updated: 2023-07-27 (commit 1e6e7d6)","category":"page"}]
}
diff --git a/docs/build/simulation.html b/docs/build/simulation.html
index ddbe8ca..74eb4bf 100644
--- a/docs/build/simulation.html
+++ b/docs/build/simulation.html
@@ -1,2 +1,2 @@
<!DOCTYPE html>
-<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Simulation · Persefone</title><script data-outdated-warner src="assets/warner.js"></script><link href="https://cdnjs.cloudflare.com/ajax/libs/lato-font/3.0.0/css/lato-font.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/juliamono/0.045/juliamono.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.13.24/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL="."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="assets/documenter.js"></script><script src="siteinfo.js"></script><script src="../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-dark.css" data-theme-name="documenter-dark" data-theme-primary-dark/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="assets/themeswap.js"></script></head><body><div id="documenter"><nav class="docs-sidebar"><a class="docs-logo" href="index.html"><img src="assets/logo.png" alt="Persefone logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="index.html">Persefone</a></span></div><form class="docs-search" action="search.html"><input class="docs-search-query" id="documenter-search-query" name="q" type="text" placeholder="Search docs"/></form><ul class="docs-menu"><li><a class="tocitem" href="index.html">Introduction</a></li><li><a class="tocitem" href="odd.html">Overview, Design, Details (ODD)</a></li><li><span class="tocitem">Developing</span><ul><li><a class="tocitem" href="developing.html">Developing Persefone</a></li><li><a class="tocitem" href="adapting.html">Adapting Persefone</a></li><li><a class="tocitem" href="architecture.html">Source code architecture</a></li><li><a class="tocitem" href="gis.html">GIS data</a></li><li><a class="tocitem" href="species-dsl.html">Defining new species</a></li></ul></li><li><span class="tocitem">Core</span><ul><li class="is-active"><a class="tocitem" href="simulation.html">Simulation</a><ul class="internal"><li><a class="tocitem" href="#simulation.jl"><span>simulation.jl</span></a></li><li><a class="tocitem" href="#landscape.jl"><span>landscape.jl</span></a></li></ul></li><li><a class="tocitem" href="io.html">Input, Output, and Settings</a></li></ul></li><li><span class="tocitem">Nature</span><ul><li><a class="tocitem" href="nature.html">Nature</a></li><li><a class="tocitem" href="energy.html">Dynamic Energy Budgets</a></li><li><a class="tocitem" href="species.html">Species</a></li></ul></li><li><a class="tocitem" href="crops.html">Crop submodel</a></li><li><a class="tocitem" href="farm.html">Farm submodel</a></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><nav class="breadcrumb"><ul class="is-hidden-mobile"><li><a class="is-disabled">Core</a></li><li class="is-active"><a href="simulation.html">Simulation</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href="simulation.html">Simulation</a></li></ul></nav><div class="docs-right"><a class="docs-edit-link" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//docs/src/simulation.md#" title="Edit source"><span class="docs-icon fa"></span><span class="docs-label is-hidden-touch">Edit source</span></a><a class="docs-settings-button fas fa-cog" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-sidebar-button fa fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a></div></header><article class="content" id="documenter-page"><h1 id="Simulation"><a class="docs-heading-anchor" href="#Simulation">Simulation</a><a id="Simulation-1"></a><a class="docs-heading-anchor-permalink" href="#Simulation" title="Permalink"></a></h1><p>The <code>core</code> directory holds source files that are important for all submodels, including scheduling, landscape, and input/output functions.</p><h2 id="simulation.jl"><a class="docs-heading-anchor" href="#simulation.jl">simulation.jl</a><a id="simulation.jl-1"></a><a class="docs-heading-anchor-permalink" href="#simulation.jl" title="Permalink"></a></h2><p>This file includes the basal functions for initialising and running simulations.</p><article class="docstring"><header><a class="docstring-binding" id="Persefone.finalise!-Tuple{Agents.AgentBasedModel}" href="#Persefone.finalise!-Tuple{Agents.AgentBasedModel}"><code>Persefone.finalise!</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">finalise!(model)</code></pre><p>Wrap up the simulation. Currently doesn't do anything except print some information.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/simulation.jl#L136-L140">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.initialise" href="#Persefone.initialise"><code>Persefone.initialise</code></a> — <span class="docstring-category">Function</span></header><section><div><pre><code class="language-julia hljs">initialise(config=PARAMFILE, seed=nothing)</code></pre><p>Initialise the model: read in parameters, create the output data directory, and instantiate the AgentBasedModel object(s). Optionally allows specifying the configuration file and overriding the <code>seed</code> parameter. This returns a single model object, unless the config file contains multiple values for one or more parameters, in which case it creates a full-factorial simulation experiment and returns a vector of model objects.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/simulation.jl#L34-L43">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.initmodel-Tuple{Dict{String, Any}}" href="#Persefone.initmodel-Tuple{Dict{String, Any}}"><code>Persefone.initmodel</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">initmodel(settings)</code></pre><p>Initialise a model object using a ready-made settings dict. This is a helper function for <code>initialise()</code>.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/simulation.jl#L54-L59">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.paramscan-Tuple{Dict{String, Any}, Vector{String}}" href="#Persefone.paramscan-Tuple{Dict{String, Any}, Vector{String}}"><code>Persefone.paramscan</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">paramscan(settings)</code></pre><p>Create a list of settings dicts, covering all possible parameter combinations given by the input settings (i.e. a full-factorial experiment). This is a helper function for <code>initialise()</code>.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/simulation.jl#L85-L91">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.simulate" href="#Persefone.simulate"><code>Persefone.simulate</code></a> — <span class="docstring-category">Function</span></header><section><div><pre><code class="language-julia hljs">simulate(config=PARAMFILE, seed=nothing)</code></pre><p>Initialise one or more model objects and carry out a full simulation experiment, optionally specifying a configuration file and a seed for the RNG.</p><p>This is the default way to run a Persefone simulation.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/simulation.jl#L8-L15">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.simulate!-Tuple{Agents.AgentBasedModel}" href="#Persefone.simulate!-Tuple{Agents.AgentBasedModel}"><code>Persefone.simulate!</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">simulate!(model)</code></pre><p>Carry out a complete simulation run using a pre-initialised model object.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/simulation.jl#L23-L27">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.stepsimulation!-Tuple{Agents.AgentBasedModel}" href="#Persefone.stepsimulation!-Tuple{Agents.AgentBasedModel}"><code>Persefone.stepsimulation!</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">stepsimulation!(model)</code></pre><p>Execute one update of the model.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/simulation.jl#L113-L117">source</a></section></article><h2 id="landscape.jl"><a class="docs-heading-anchor" href="#landscape.jl">landscape.jl</a><a id="landscape.jl-1"></a><a class="docs-heading-anchor-permalink" href="#landscape.jl" title="Permalink"></a></h2><p>This file manages the landscape maps that underlie the model.</p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="species-dsl.html">« Defining new species</a><a class="docs-footer-nextpage" href="io.html">Input, Output, and Settings »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.23 on <span class="colophon-date" title="Thursday 20 July 2023 16:01">Thursday 20 July 2023</span>. Using Julia version 1.9.1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
+<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Simulation · Persefone</title><script data-outdated-warner src="assets/warner.js"></script><link href="https://cdnjs.cloudflare.com/ajax/libs/lato-font/3.0.0/css/lato-font.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/juliamono/0.045/juliamono.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.13.24/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL="."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="assets/documenter.js"></script><script src="siteinfo.js"></script><script src="../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-dark.css" data-theme-name="documenter-dark" data-theme-primary-dark/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="assets/themeswap.js"></script></head><body><div id="documenter"><nav class="docs-sidebar"><a class="docs-logo" href="index.html"><img src="assets/logo.png" alt="Persefone logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="index.html">Persefone</a></span></div><form class="docs-search" action="search.html"><input class="docs-search-query" id="documenter-search-query" name="q" type="text" placeholder="Search docs"/></form><ul class="docs-menu"><li><a class="tocitem" href="index.html">Introduction</a></li><li><a class="tocitem" href="odd.html">Overview, Design, Details (ODD)</a></li><li><span class="tocitem">Developing</span><ul><li><a class="tocitem" href="developing.html">Developing Persefone</a></li><li><a class="tocitem" href="adapting.html">Adapting Persefone</a></li><li><a class="tocitem" href="architecture.html">Source code architecture</a></li><li><a class="tocitem" href="gis.html">Maps and weather data</a></li><li><a class="tocitem" href="species-dsl.html">Defining new species</a></li></ul></li><li><span class="tocitem">Core</span><ul><li class="is-active"><a class="tocitem" href="simulation.html">Simulation</a><ul class="internal"><li><a class="tocitem" href="#simulation.jl"><span>simulation.jl</span></a></li><li><a class="tocitem" href="#landscape.jl"><span>landscape.jl</span></a></li></ul></li><li><a class="tocitem" href="io.html">Input, Output, and Settings</a></li></ul></li><li><span class="tocitem">Nature</span><ul><li><a class="tocitem" href="nature.html">Nature</a></li><li><a class="tocitem" href="energy.html">Dynamic Energy Budgets</a></li><li><a class="tocitem" href="species.html">Species</a></li></ul></li><li><a class="tocitem" href="crops.html">Crop submodel</a></li><li><a class="tocitem" href="farm.html">Farm submodel</a></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><nav class="breadcrumb"><ul class="is-hidden-mobile"><li><a class="is-disabled">Core</a></li><li class="is-active"><a href="simulation.html">Simulation</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href="simulation.html">Simulation</a></li></ul></nav><div class="docs-right"><a class="docs-edit-link" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//docs/src/simulation.md#" title="Edit source"><span class="docs-icon fa"></span><span class="docs-label is-hidden-touch">Edit source</span></a><a class="docs-settings-button fas fa-cog" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-sidebar-button fa fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a></div></header><article class="content" id="documenter-page"><h1 id="Simulation"><a class="docs-heading-anchor" href="#Simulation">Simulation</a><a id="Simulation-1"></a><a class="docs-heading-anchor-permalink" href="#Simulation" title="Permalink"></a></h1><p>The <code>core</code> directory holds source files that are important for all submodels, including scheduling, landscape, and input/output functions.</p><h2 id="simulation.jl"><a class="docs-heading-anchor" href="#simulation.jl">simulation.jl</a><a id="simulation.jl-1"></a><a class="docs-heading-anchor-permalink" href="#simulation.jl" title="Permalink"></a></h2><p>This file includes the basal functions for initialising and running simulations.</p><article class="docstring"><header><a class="docstring-binding" id="Persefone.finalise!-Tuple{Agents.AgentBasedModel}" href="#Persefone.finalise!-Tuple{Agents.AgentBasedModel}"><code>Persefone.finalise!</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">finalise!(model)</code></pre><p>Wrap up the simulation. Currently doesn't do anything except print some information.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/simulation.jl#L136-L140">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.initialise" href="#Persefone.initialise"><code>Persefone.initialise</code></a> — <span class="docstring-category">Function</span></header><section><div><pre><code class="language-julia hljs">initialise(config=PARAMFILE, seed=nothing)</code></pre><p>Initialise the model: read in parameters, create the output data directory, and instantiate the AgentBasedModel object(s). Optionally allows specifying the configuration file and overriding the <code>seed</code> parameter. This returns a single model object, unless the config file contains multiple values for one or more parameters, in which case it creates a full-factorial simulation experiment and returns a vector of model objects.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/simulation.jl#L34-L43">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.initmodel-Tuple{Dict{String, Any}}" href="#Persefone.initmodel-Tuple{Dict{String, Any}}"><code>Persefone.initmodel</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">initmodel(settings)</code></pre><p>Initialise a model object using a ready-made settings dict. This is a helper function for <code>initialise()</code>.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/simulation.jl#L54-L59">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.paramscan-Tuple{Dict{String, Any}, Vector{String}}" href="#Persefone.paramscan-Tuple{Dict{String, Any}, Vector{String}}"><code>Persefone.paramscan</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">paramscan(settings)</code></pre><p>Create a list of settings dicts, covering all possible parameter combinations given by the input settings (i.e. a full-factorial experiment). This is a helper function for <code>initialise()</code>.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/simulation.jl#L85-L91">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.simulate" href="#Persefone.simulate"><code>Persefone.simulate</code></a> — <span class="docstring-category">Function</span></header><section><div><pre><code class="language-julia hljs">simulate(config=PARAMFILE, seed=nothing)</code></pre><p>Initialise one or more model objects and carry out a full simulation experiment, optionally specifying a configuration file and a seed for the RNG.</p><p>This is the default way to run a Persefone simulation.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/simulation.jl#L8-L15">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.simulate!-Tuple{Agents.AgentBasedModel}" href="#Persefone.simulate!-Tuple{Agents.AgentBasedModel}"><code>Persefone.simulate!</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">simulate!(model)</code></pre><p>Carry out a complete simulation run using a pre-initialised model object.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/simulation.jl#L23-L27">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.stepsimulation!-Tuple{Agents.AgentBasedModel}" href="#Persefone.stepsimulation!-Tuple{Agents.AgentBasedModel}"><code>Persefone.stepsimulation!</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">stepsimulation!(model)</code></pre><p>Execute one update of the model.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/simulation.jl#L113-L117">source</a></section></article><h2 id="landscape.jl"><a class="docs-heading-anchor" href="#landscape.jl">landscape.jl</a><a id="landscape.jl-1"></a><a class="docs-heading-anchor-permalink" href="#landscape.jl" title="Permalink"></a></h2><p>This file manages the landscape maps that underlie the model.</p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="species-dsl.html">« Defining new species</a><a class="docs-footer-nextpage" href="io.html">Input, Output, and Settings »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.23 on <span class="colophon-date" title="Thursday 27 July 2023 10:12">Thursday 27 July 2023</span>. Using Julia version 1.9.1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
diff --git a/docs/build/species-dsl.html b/docs/build/species-dsl.html
index 4eb65d9..dfca881 100644
--- a/docs/build/species-dsl.html
+++ b/docs/build/species-dsl.html
@@ -1,5 +1,5 @@
<!DOCTYPE html>
-<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Defining new species · Persefone</title><script data-outdated-warner src="assets/warner.js"></script><link href="https://cdnjs.cloudflare.com/ajax/libs/lato-font/3.0.0/css/lato-font.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/juliamono/0.045/juliamono.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.13.24/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL="."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="assets/documenter.js"></script><script src="siteinfo.js"></script><script src="../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-dark.css" data-theme-name="documenter-dark" data-theme-primary-dark/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="assets/themeswap.js"></script></head><body><div id="documenter"><nav class="docs-sidebar"><a class="docs-logo" href="index.html"><img src="assets/logo.png" alt="Persefone logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="index.html">Persefone</a></span></div><form class="docs-search" action="search.html"><input class="docs-search-query" id="documenter-search-query" name="q" type="text" placeholder="Search docs"/></form><ul class="docs-menu"><li><a class="tocitem" href="index.html">Introduction</a></li><li><a class="tocitem" href="odd.html">Overview, Design, Details (ODD)</a></li><li><span class="tocitem">Developing</span><ul><li><a class="tocitem" href="developing.html">Developing Persefone</a></li><li><a class="tocitem" href="adapting.html">Adapting Persefone</a></li><li><a class="tocitem" href="architecture.html">Source code architecture</a></li><li><a class="tocitem" href="gis.html">GIS data</a></li><li class="is-active"><a class="tocitem" href="species-dsl.html">Defining new species</a><ul class="internal"><li><a class="tocitem" href="#The-Persefone-species-DSL"><span>The Persefone species DSL</span></a></li><li><a class="tocitem" href="#Implementation-details"><span>Implementation details</span></a></li></ul></li></ul></li><li><span class="tocitem">Core</span><ul><li><a class="tocitem" href="simulation.html">Simulation</a></li><li><a class="tocitem" href="io.html">Input, Output, and Settings</a></li></ul></li><li><span class="tocitem">Nature</span><ul><li><a class="tocitem" href="nature.html">Nature</a></li><li><a class="tocitem" href="energy.html">Dynamic Energy Budgets</a></li><li><a class="tocitem" href="species.html">Species</a></li></ul></li><li><a class="tocitem" href="crops.html">Crop submodel</a></li><li><a class="tocitem" href="farm.html">Farm submodel</a></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><nav class="breadcrumb"><ul class="is-hidden-mobile"><li><a class="is-disabled">Developing</a></li><li class="is-active"><a href="species-dsl.html">Defining new species</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href="species-dsl.html">Defining new species</a></li></ul></nav><div class="docs-right"><a class="docs-edit-link" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//docs/src/species-dsl.md#" title="Edit source"><span class="docs-icon fa"></span><span class="docs-label is-hidden-touch">Edit source</span></a><a class="docs-settings-button fas fa-cog" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-sidebar-button fa fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a></div></header><article class="content" id="documenter-page"><h1 id="Defining-new-species"><a class="docs-heading-anchor" href="#Defining-new-species">Defining new species</a><a id="Defining-new-species-1"></a><a class="docs-heading-anchor-permalink" href="#Defining-new-species" title="Permalink"></a></h1><h2 id="The-Persefone-species-DSL"><a class="docs-heading-anchor" href="#The-Persefone-species-DSL">The Persefone species DSL</a><a id="The-Persefone-species-DSL-1"></a><a class="docs-heading-anchor-permalink" href="#The-Persefone-species-DSL" title="Permalink"></a></h2><p>In order to make implementing new species as easy as possible, Persefone includes a <a href="https://doi.org/10.1016/j.ecoinf.2015.02.005">domain-specific language</a> (DSL) built from a collection of macros and functions.</p><p>Here is an example of what this looks like, using a hypothetical mermaid species:</p><pre><code class="language-julia hljs">@species Mermaid begin
+<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Defining new species · Persefone</title><script data-outdated-warner src="assets/warner.js"></script><link href="https://cdnjs.cloudflare.com/ajax/libs/lato-font/3.0.0/css/lato-font.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/juliamono/0.045/juliamono.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.13.24/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL="."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="assets/documenter.js"></script><script src="siteinfo.js"></script><script src="../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-dark.css" data-theme-name="documenter-dark" data-theme-primary-dark/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="assets/themeswap.js"></script></head><body><div id="documenter"><nav class="docs-sidebar"><a class="docs-logo" href="index.html"><img src="assets/logo.png" alt="Persefone logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="index.html">Persefone</a></span></div><form class="docs-search" action="search.html"><input class="docs-search-query" id="documenter-search-query" name="q" type="text" placeholder="Search docs"/></form><ul class="docs-menu"><li><a class="tocitem" href="index.html">Introduction</a></li><li><a class="tocitem" href="odd.html">Overview, Design, Details (ODD)</a></li><li><span class="tocitem">Developing</span><ul><li><a class="tocitem" href="developing.html">Developing Persefone</a></li><li><a class="tocitem" href="adapting.html">Adapting Persefone</a></li><li><a class="tocitem" href="architecture.html">Source code architecture</a></li><li><a class="tocitem" href="gis.html">Maps and weather data</a></li><li class="is-active"><a class="tocitem" href="species-dsl.html">Defining new species</a><ul class="internal"><li><a class="tocitem" href="#The-Persefone-species-DSL"><span>The Persefone species DSL</span></a></li><li><a class="tocitem" href="#Implementation-details"><span>Implementation details</span></a></li></ul></li></ul></li><li><span class="tocitem">Core</span><ul><li><a class="tocitem" href="simulation.html">Simulation</a></li><li><a class="tocitem" href="io.html">Input, Output, and Settings</a></li></ul></li><li><span class="tocitem">Nature</span><ul><li><a class="tocitem" href="nature.html">Nature</a></li><li><a class="tocitem" href="energy.html">Dynamic Energy Budgets</a></li><li><a class="tocitem" href="species.html">Species</a></li></ul></li><li><a class="tocitem" href="crops.html">Crop submodel</a></li><li><a class="tocitem" href="farm.html">Farm submodel</a></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><nav class="breadcrumb"><ul class="is-hidden-mobile"><li><a class="is-disabled">Developing</a></li><li class="is-active"><a href="species-dsl.html">Defining new species</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href="species-dsl.html">Defining new species</a></li></ul></nav><div class="docs-right"><a class="docs-edit-link" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//docs/src/species-dsl.md#" title="Edit source"><span class="docs-icon fa"></span><span class="docs-label is-hidden-touch">Edit source</span></a><a class="docs-settings-button fas fa-cog" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-sidebar-button fa fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a></div></header><article class="content" id="documenter-page"><h1 id="Defining-new-species"><a class="docs-heading-anchor" href="#Defining-new-species">Defining new species</a><a id="Defining-new-species-1"></a><a class="docs-heading-anchor-permalink" href="#Defining-new-species" title="Permalink"></a></h1><h2 id="The-Persefone-species-DSL"><a class="docs-heading-anchor" href="#The-Persefone-species-DSL">The Persefone species DSL</a><a id="The-Persefone-species-DSL-1"></a><a class="docs-heading-anchor-permalink" href="#The-Persefone-species-DSL" title="Permalink"></a></h2><p>In order to make implementing new species as easy as possible, Persefone includes a <a href="https://doi.org/10.1016/j.ecoinf.2015.02.005">domain-specific language</a> (DSL) built from a collection of macros and functions.</p><p>Here is an example of what this looks like, using a hypothetical mermaid species:</p><pre><code class="language-julia hljs">@species Mermaid begin
ageofmaturity = 2
pesticidemortality = 1.0
@initialise(@habitat(@landcover() == water), pairs=true)
@@ -20,4 +20,4 @@
@debug "$(animalid(animal)) is experiencing drought with $n neighbour(s)."
@respond sowing @setphase(life)
end
-end</code></pre><p>The two most important macros are <a href="nature.html#Persefone.@species-Tuple{Any, Any}"><code>@species</code></a> and <a href="nature.html#Persefone.@phase-Tuple{Any, Any}"><code>@phase</code></a>, followed by <a href="nature.html#Persefone.@initialise-Tuple{Any, Vararg{Any}}"><code>@initialise</code></a>, <a href="nature.html#Persefone.@trait-Tuple{Any}"><code>@trait</code></a>, <a href="nature.html#Persefone.@respond-Tuple{Any, Any}"><code>@respond</code></a>, and <a href="nature.html#Persefone.@habitat-Tuple{Any}"><code>@habitat</code></a>. Other macros provide convenience wrappers for common functions. (See <code>src/nature/nature.jl</code> for details.)</p><p>The top-level macro is <a href="nature.html#Persefone.@species-Tuple{Any, Any}"><code>@species</code></a>. This takes two arguments: a species name and a definition block (enclosed in <code>begin</code> and <code>end</code> tags). At the start of the definition block, species-specific variables can be defined that should be available throughout a species' lifetime. Code in this section has access to the <code>model</code> object and can thus reference the current model state. In this section, the user also has to call the <a href="nature.html#Persefone.@initialise-Tuple{Any, Vararg{Any}}"><code>@initialise</code></a> macro. This wraps the <a href="@ref"><code>initpopulation</code></a> function, and takes a habitat descriptor (see <a href="nature.html#Persefone.@habitat-Tuple{Any}"><code>@habitat</code></a> below) and several options to specify how the species' population should be distributed in the landscape during model initialisation.</p><p>Following this section, each species must define one or more <a href="nature.html#Persefone.@phase-Tuple{Any, Any}"><code>@phase</code></a> blocks. The concept behind this is that species show different behaviours at different phases of their lifecycle. Each <code>@phase</code> block defines the behaviour in one of these phases. (Technically, it defines a function that will be called daily, so long as the species' <code>phase</code> variable is set to the name of this phase.) Code in this section has access to the <code>model</code> object as well as an <code>animal</code> object, which is the currently active animal agent. Properties of the <code>animal</code> agent, regardless of whether they were defined by the user or by Persefone, can be accessed using the <a href="nature.html#Persefone.@trait-Tuple{Any}"><code>@trait</code></a> macro. Within a phase block, <a href="nature.html#Persefone.@respond-Tuple{Any, Any}"><code>@respond</code></a> can be used to define the species' response to a <a href="@ref"><code>FarmEvent</code></a> that affects the species' current location, while a variety of other macros provide wrappers to ecological process functions from <code>src/nature/populations.jl</code>.</p><p>Another important macro is <a href="nature.html#Persefone.@habitat-Tuple{Any}"><code>@habitat</code></a>. This defines a "habitat descriptor", i.e. a predicate function that tests whether or not a given landscape pixel is suitable for a specified purpose. Such habitat descriptors are used as arguments to various functions, for example for population initialisation or movement. The argument to <code>@habitat</code> consists of a logical expression, which has access to the animal's current position (the <code>pos</code> tuple variable) and the <code>model</code>. Various macros are available to easily reference information about the current location, such as <a href="nature.html#Persefone.@landcover-Tuple{}"><code>@landcover</code></a> or <a href="nature.html#Persefone.@distancetoedge-Tuple{}"><code>@distancetoedge</code></a>.</p><h2 id="Implementation-details"><a class="docs-heading-anchor" href="#Implementation-details">Implementation details</a><a id="Implementation-details-1"></a><a class="docs-heading-anchor-permalink" href="#Implementation-details" title="Permalink"></a></h2><p>Due to a known <a href="https://juliadynamics.github.io/Agents.jl/stable/performance_tips/#Avoid-Unions-of-many-different-agent-types-(temporary!)-1">performance problem</a> with multi-agent models, the underlying implementation of species is rather complicated (see <code>src/nature/nature.jl</code> for details.)</p><p>Rather than creating a new type/struct for each species, all <a href="@ref">Animal</a> agents have the same type. Instead, they are differentiated by a <code>traits</code> dict, which stores both species-specific parameters and run-time variables. Note that due to a redefinition of the <code>getproperty()/setproperty!()</code> methods, variables from the trait dict can be accessed and modified just like normal struct fields (i.e. although <code>phase</code> is defined in the dict, not the struct, <code>animal.phase = "newphase"</code> works just fine - one does not have to use <code>animal.traits["phase"] = "newphase"</code>.)</p><p>Under the hood, the <a href="nature.html#Persefone.@species-Tuple{Any, Any}"><code>@species</code></a> macro generates a function (with the name of the species), which in turn creates the trait dict when called. Thus, adding a new animal agent to the model involves instantiating an <a href="nature.html#Persefone.Animal"><code>Animal</code></a> object, then calling the relevant species function and attaching the returned dict to the agent object.</p><p>Similarly, the <a href="nature.html#Persefone.@phase-Tuple{Any, Any}"><code>@phase</code></a> macro too works by defining a new function, which is stored in the species' trait dict. These functions take an animal object and the model object as input, and define what the species does during its daily update.</p><p>Once again, <a href="nature.html#Persefone.@habitat-Tuple{Any}"><code>@habitat</code></a> creates a function that takes <code>model</code> and <code>pos</code> as input and returns a boolean response. Functions that require a habitat descriptor thus take in this (anonymous) function and call it internally.</p><p>Finally, the <a href="nature.html#Persefone.@initialise-Tuple{Any, Vararg{Any}}"><code>@initialise</code></a> macro is a wrapper around <a href="@ref"><code>initpopulation</code></a>, which (yet again) creates a function that specifies how a species' population is to be initialised at the beginning of a simulation run. This function is stored in the species trait dict and accessed during model setup.</p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="gis.html">« GIS data</a><a class="docs-footer-nextpage" href="simulation.html">Simulation »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.23 on <span class="colophon-date" title="Thursday 20 July 2023 16:01">Thursday 20 July 2023</span>. Using Julia version 1.9.1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
+end</code></pre><p>The two most important macros are <a href="nature.html#Persefone.@species-Tuple{Any, Any}"><code>@species</code></a> and <a href="nature.html#Persefone.@phase-Tuple{Any, Any}"><code>@phase</code></a>, followed by <a href="nature.html#Persefone.@initialise-Tuple{Any, Vararg{Any}}"><code>@initialise</code></a>, <a href="nature.html#Persefone.@trait-Tuple{Any}"><code>@trait</code></a>, <a href="nature.html#Persefone.@respond-Tuple{Any, Any}"><code>@respond</code></a>, and <a href="nature.html#Persefone.@habitat-Tuple{Any}"><code>@habitat</code></a>. Other macros provide convenience wrappers for common functions. (See <code>src/nature/nature.jl</code> for details.)</p><p>The top-level macro is <a href="nature.html#Persefone.@species-Tuple{Any, Any}"><code>@species</code></a>. This takes two arguments: a species name and a definition block (enclosed in <code>begin</code> and <code>end</code> tags). At the start of the definition block, species-specific variables can be defined that should be available throughout a species' lifetime. Code in this section has access to the <code>model</code> object and can thus reference the current model state. In this section, the user also has to call the <a href="nature.html#Persefone.@initialise-Tuple{Any, Vararg{Any}}"><code>@initialise</code></a> macro. This wraps the <a href="@ref"><code>initpopulation</code></a> function, and takes a habitat descriptor (see <a href="nature.html#Persefone.@habitat-Tuple{Any}"><code>@habitat</code></a> below) and several options to specify how the species' population should be distributed in the landscape during model initialisation.</p><p>Following this section, each species must define one or more <a href="nature.html#Persefone.@phase-Tuple{Any, Any}"><code>@phase</code></a> blocks. The concept behind this is that species show different behaviours at different phases of their lifecycle. Each <code>@phase</code> block defines the behaviour in one of these phases. (Technically, it defines a function that will be called daily, so long as the species' <code>phase</code> variable is set to the name of this phase.) Code in this section has access to the <code>model</code> object as well as an <code>animal</code> object, which is the currently active animal agent. Properties of the <code>animal</code> agent, regardless of whether they were defined by the user or by Persefone, can be accessed using the <a href="nature.html#Persefone.@trait-Tuple{Any}"><code>@trait</code></a> macro. Within a phase block, <a href="nature.html#Persefone.@respond-Tuple{Any, Any}"><code>@respond</code></a> can be used to define the species' response to a <a href="@ref"><code>FarmEvent</code></a> that affects the species' current location, while a variety of other macros provide wrappers to ecological process functions from <code>src/nature/populations.jl</code>.</p><p>Another important macro is <a href="nature.html#Persefone.@habitat-Tuple{Any}"><code>@habitat</code></a>. This defines a "habitat descriptor", i.e. a predicate function that tests whether or not a given landscape pixel is suitable for a specified purpose. Such habitat descriptors are used as arguments to various functions, for example for population initialisation or movement. The argument to <code>@habitat</code> consists of a logical expression, which has access to the animal's current position (the <code>pos</code> tuple variable) and the <code>model</code>. Various macros are available to easily reference information about the current location, such as <a href="nature.html#Persefone.@landcover-Tuple{}"><code>@landcover</code></a> or <a href="nature.html#Persefone.@distancetoedge-Tuple{}"><code>@distancetoedge</code></a>.</p><h2 id="Implementation-details"><a class="docs-heading-anchor" href="#Implementation-details">Implementation details</a><a id="Implementation-details-1"></a><a class="docs-heading-anchor-permalink" href="#Implementation-details" title="Permalink"></a></h2><p>Due to a known <a href="https://juliadynamics.github.io/Agents.jl/stable/performance_tips/#Avoid-Unions-of-many-different-agent-types-(temporary!)-1">performance problem</a> with multi-agent models, the underlying implementation of species is rather complicated (see <code>src/nature/nature.jl</code> for details.)</p><p>Rather than creating a new type/struct for each species, all <a href="@ref">Animal</a> agents have the same type. Instead, they are differentiated by a <code>traits</code> dict, which stores both species-specific parameters and run-time variables. Note that due to a redefinition of the <code>getproperty()/setproperty!()</code> methods, variables from the trait dict can be accessed and modified just like normal struct fields (i.e. although <code>phase</code> is defined in the dict, not the struct, <code>animal.phase = "newphase"</code> works just fine - one does not have to use <code>animal.traits["phase"] = "newphase"</code>.)</p><p>Under the hood, the <a href="nature.html#Persefone.@species-Tuple{Any, Any}"><code>@species</code></a> macro generates a function (with the name of the species), which in turn creates the trait dict when called. Thus, adding a new animal agent to the model involves instantiating an <a href="nature.html#Persefone.Animal"><code>Animal</code></a> object, then calling the relevant species function and attaching the returned dict to the agent object.</p><p>Similarly, the <a href="nature.html#Persefone.@phase-Tuple{Any, Any}"><code>@phase</code></a> macro too works by defining a new function, which is stored in the species' trait dict. These functions take an animal object and the model object as input, and define what the species does during its daily update.</p><p>Once again, <a href="nature.html#Persefone.@habitat-Tuple{Any}"><code>@habitat</code></a> creates a function that takes <code>model</code> and <code>pos</code> as input and returns a boolean response. Functions that require a habitat descriptor thus take in this (anonymous) function and call it internally.</p><p>Finally, the <a href="nature.html#Persefone.@initialise-Tuple{Any, Vararg{Any}}"><code>@initialise</code></a> macro is a wrapper around <a href="@ref"><code>initpopulation</code></a>, which (yet again) creates a function that specifies how a species' population is to be initialised at the beginning of a simulation run. This function is stored in the species trait dict and accessed during model setup.</p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="gis.html">« Maps and weather data</a><a class="docs-footer-nextpage" href="simulation.html">Simulation »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.23 on <span class="colophon-date" title="Thursday 27 July 2023 10:12">Thursday 27 July 2023</span>. Using Julia version 1.9.1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
diff --git a/docs/build/species.html b/docs/build/species.html
index 161e671..15c5bae 100644
--- a/docs/build/species.html
+++ b/docs/build/species.html
@@ -1,2 +1,2 @@
<!DOCTYPE html>
-<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Species · Persefone</title><script data-outdated-warner src="assets/warner.js"></script><link href="https://cdnjs.cloudflare.com/ajax/libs/lato-font/3.0.0/css/lato-font.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/juliamono/0.045/juliamono.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.13.24/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL="."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="assets/documenter.js"></script><script src="siteinfo.js"></script><script src="../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-dark.css" data-theme-name="documenter-dark" data-theme-primary-dark/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="assets/themeswap.js"></script></head><body><div id="documenter"><nav class="docs-sidebar"><a class="docs-logo" href="index.html"><img src="assets/logo.png" alt="Persefone logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="index.html">Persefone</a></span></div><form class="docs-search" action="search.html"><input class="docs-search-query" id="documenter-search-query" name="q" type="text" placeholder="Search docs"/></form><ul class="docs-menu"><li><a class="tocitem" href="index.html">Introduction</a></li><li><a class="tocitem" href="odd.html">Overview, Design, Details (ODD)</a></li><li><span class="tocitem">Developing</span><ul><li><a class="tocitem" href="developing.html">Developing Persefone</a></li><li><a class="tocitem" href="adapting.html">Adapting Persefone</a></li><li><a class="tocitem" href="architecture.html">Source code architecture</a></li><li><a class="tocitem" href="gis.html">GIS data</a></li><li><a class="tocitem" href="species-dsl.html">Defining new species</a></li></ul></li><li><span class="tocitem">Core</span><ul><li><a class="tocitem" href="simulation.html">Simulation</a></li><li><a class="tocitem" href="io.html">Input, Output, and Settings</a></li></ul></li><li><span class="tocitem">Nature</span><ul><li><a class="tocitem" href="nature.html">Nature</a></li><li><a class="tocitem" href="energy.html">Dynamic Energy Budgets</a></li><li class="is-active"><a class="tocitem" href="species.html">Species</a><ul class="internal"><li><a class="tocitem" href="#Skylark"><span>Skylark</span></a></li></ul></li></ul></li><li><a class="tocitem" href="crops.html">Crop submodel</a></li><li><a class="tocitem" href="farm.html">Farm submodel</a></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><nav class="breadcrumb"><ul class="is-hidden-mobile"><li><a class="is-disabled">Nature</a></li><li class="is-active"><a href="species.html">Species</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href="species.html">Species</a></li></ul></nav><div class="docs-right"><a class="docs-edit-link" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//docs/src/species.md#" title="Edit source"><span class="docs-icon fa"></span><span class="docs-label is-hidden-touch">Edit source</span></a><a class="docs-settings-button fas fa-cog" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-sidebar-button fa fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a></div></header><article class="content" id="documenter-page"><h1 id="Species"><a class="docs-heading-anchor" href="#Species">Species</a><a id="Species-1"></a><a class="docs-heading-anchor-permalink" href="#Species" title="Permalink"></a></h1><p>The ecological submodel in Persefone simulates a range of species in agricultural landscapes.</p><h2 id="Skylark"><a class="docs-heading-anchor" href="#Skylark">Skylark</a><a id="Skylark-1"></a><a class="docs-heading-anchor-permalink" href="#Skylark" title="Permalink"></a></h2></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="energy.html">« Dynamic Energy Budgets</a><a class="docs-footer-nextpage" href="crops.html">Crop submodel »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.23 on <span class="colophon-date" title="Thursday 20 July 2023 16:01">Thursday 20 July 2023</span>. Using Julia version 1.9.1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
+<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Species · Persefone</title><script data-outdated-warner src="assets/warner.js"></script><link href="https://cdnjs.cloudflare.com/ajax/libs/lato-font/3.0.0/css/lato-font.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/juliamono/0.045/juliamono.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.13.24/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL="."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="assets/documenter.js"></script><script src="siteinfo.js"></script><script src="../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-dark.css" data-theme-name="documenter-dark" data-theme-primary-dark/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="assets/themeswap.js"></script></head><body><div id="documenter"><nav class="docs-sidebar"><a class="docs-logo" href="index.html"><img src="assets/logo.png" alt="Persefone logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="index.html">Persefone</a></span></div><form class="docs-search" action="search.html"><input class="docs-search-query" id="documenter-search-query" name="q" type="text" placeholder="Search docs"/></form><ul class="docs-menu"><li><a class="tocitem" href="index.html">Introduction</a></li><li><a class="tocitem" href="odd.html">Overview, Design, Details (ODD)</a></li><li><span class="tocitem">Developing</span><ul><li><a class="tocitem" href="developing.html">Developing Persefone</a></li><li><a class="tocitem" href="adapting.html">Adapting Persefone</a></li><li><a class="tocitem" href="architecture.html">Source code architecture</a></li><li><a class="tocitem" href="gis.html">Maps and weather data</a></li><li><a class="tocitem" href="species-dsl.html">Defining new species</a></li></ul></li><li><span class="tocitem">Core</span><ul><li><a class="tocitem" href="simulation.html">Simulation</a></li><li><a class="tocitem" href="io.html">Input, Output, and Settings</a></li></ul></li><li><span class="tocitem">Nature</span><ul><li><a class="tocitem" href="nature.html">Nature</a></li><li><a class="tocitem" href="energy.html">Dynamic Energy Budgets</a></li><li class="is-active"><a class="tocitem" href="species.html">Species</a><ul class="internal"><li><a class="tocitem" href="#Skylark"><span>Skylark</span></a></li></ul></li></ul></li><li><a class="tocitem" href="crops.html">Crop submodel</a></li><li><a class="tocitem" href="farm.html">Farm submodel</a></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><nav class="breadcrumb"><ul class="is-hidden-mobile"><li><a class="is-disabled">Nature</a></li><li class="is-active"><a href="species.html">Species</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href="species.html">Species</a></li></ul></nav><div class="docs-right"><a class="docs-edit-link" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//docs/src/species.md#" title="Edit source"><span class="docs-icon fa"></span><span class="docs-label is-hidden-touch">Edit source</span></a><a class="docs-settings-button fas fa-cog" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-sidebar-button fa fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a></div></header><article class="content" id="documenter-page"><h1 id="Species"><a class="docs-heading-anchor" href="#Species">Species</a><a id="Species-1"></a><a class="docs-heading-anchor-permalink" href="#Species" title="Permalink"></a></h1><p>The ecological submodel in Persefone simulates a range of species in agricultural landscapes.</p><h2 id="Skylark"><a class="docs-heading-anchor" href="#Skylark">Skylark</a><a id="Skylark-1"></a><a class="docs-heading-anchor-permalink" href="#Skylark" title="Permalink"></a></h2></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="energy.html">« Dynamic Energy Budgets</a><a class="docs-footer-nextpage" href="crops.html">Crop submodel »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.23 on <span class="colophon-date" title="Thursday 27 July 2023 10:12">Thursday 27 July 2023</span>. Using Julia version 1.9.1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
diff --git a/docs/src/assets/deb.png b/docs/src/assets/deb.png
new file mode 100644
index 0000000000000000000000000000000000000000..23607ea7e0793e10791de31929673369fc880cf9
GIT binary patch
literal 84309
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
literal 0
HcmV?d00001
diff --git a/docs/src/energy.md b/docs/src/energy.md
new file mode 100644
index 0000000..3bac2de
--- /dev/null
+++ b/docs/src/energy.md
@@ -0,0 +1,22 @@
+# Dynamic Energy Budgets
+
+Persefone's nature module uses Kooijman's Dynamic Energy Budget theory to model energy
+flows within individuals.
+
+
+
+*The standard model of the Dynamic Energy Budget theory. (Fig. 1 from Sousa et al. (2010).)*
+
+- [Sousa et al. (2010)](https://doi.org/10.1098/rstb.2010.0166). Dynamic energy budget theory restores coherence in biology. Philosophical Transactions of the Royal Society B: Biological Sciences, 365(1557), 3413–3428.
+
+- [Kooijman, S. A. L. M. (2009)](https://www.researchgate.net/profile/Edgar-Meza-3/post/Is_there_a_toxicokinetic_model_for_daphnia_magna_or_other_zooplankton/attachment/59d62cf579197b807798b396/AS%3A348547653357569%401460111644286/download/Dynamic+Energy+Budget+theory+-+Kooijman.pdf). Dynamic energy and mass budgets in biological systems (3rd ed). Cambridge University Press.
+
+- [Sibly et al. (2013)](https://doi.org/10.1111/2041-210x.12002). Representing the acquisition and use of energy by individuals in agent-based models of animal populations. Methods in Ecology and Evolution, 4(2), 151–161.
+
+
+## energy.jl
+
+```@autodocs
+Modules = [Persefone]
+Pages = ["nature/energy.jl"]
+```
diff --git a/docs/src/gis.md b/docs/src/gis.md
index 3a26343..ee5979c 100644
--- a/docs/src/gis.md
+++ b/docs/src/gis.md
@@ -1,8 +1,9 @@
-# GIS data
+# Maps and weather data
Persefone currently requires two separate map input files: one for land cover,
-the other for field geometry. This documents describe how to obtain and process
-the data needed for each of these.
+the other for field geometry. Additionally, a weather input file is needed.
+This documents describe how to obtain and process the data needed for each
+of these.
## Land cover maps
@@ -71,3 +72,59 @@ the advanced parameters, set the output data type to `UInt32`. Finally, enter an
output file name and run. The resulting TIF file can be passed to Persefone
as the `farmfieldmap` parameter.
+## Weather data
+
+Currently, Persefone uses historical weather data from the closes weather station
+as its weather input. (In future, this may be changed to a more detailed raster
+input, which could then also provide future weather predictions under climate change.)
+Weather data can be downloaded from the [German weather service (DWD)](https://www.dwd.de/DE/leistungen/cdc/cdc_ueberblick-klimadaten.html?nn=16102).
+The relevant data are in the folder [`daily/kl/historical`](https://opendata.dwd.de/climate_environment/CDC/observations_germany/climate/daily/kl/historical/).
+
+The description of this data set and the list of weather stations can be found in the
+Persefone repository, in the `docs` folder (or downloaded from the link above).
+Using the list of weather stations, select the one closest to the area of study.
+Note that not all stations were continuously in operation; make sure that the selected
+station covers the years of interest.
+
+- **Region Jena:** station number 02444 ("Jena (Sternwarte)")
+- **Region Eichsfeld:**
+- **Region Thüringer Becken:**
+- **Region Hohenlohe:**
+- **Region Bodensee:**
+- **Region Nördlicher Oberrhein:**
+
+From the link above, download the ZIP file associated with the station number.
+Check the included meta-data if there is any important missing data, or other relevant
+information (e.g. the station moved position).
+
+Then use `data/extract_weather_data.R` to process the data into the format needed
+by Persefone:
+
+```R
+library(tidyverse)
+
+## replace this with the correct file name
+weatherfile = "produkt_klima_tag_18210101_20221231_02444.txt"
+
+data = read.table(weatherfile, sep=";", header=T)
+
+weather = data %>%
+ ## drop values before 2000 to save space
+ filter(MESS_DATUM>=20000101) %>%
+ ## select relevant variables and convert place-holder values to NA
+ select(MESS_DATUM, FM, RSK, SDK, VPM, TMK, TXK, TNK) %>%
+ mutate(date=MESS_DATUM, MESS_DATUM=NULL,
+ mean_windspeed=na_if(FM, -999), FM=NULL,
+ precipitation=na_if(RSK, -999), RSK=NULL,
+ sunshine_hours=na_if(SDK, -999), SDK=NULL,
+ mean_vapour_pressure=na_if(VPM, -999), VPM=NULL,
+ mean_temperature=na_if(TMK, -999), TMK=NULL,
+ max_temperature=na_if(TXK, -999), TXK=NULL,
+ min_temperature=na_if(TNK, -999), TNK=NULL)
+
+## replace with the desired file name
+write.csv(weather, file="weather_jena.csv", row.names=FALSE)
+```
+
+*Note: for calculating the reference evapotranspiration ET_0 (needed for the AquaCrop model),
+use the [FAO Penman-Monteith equation](https://www.fao.org/3/X0490E/x0490e06.htm#equation).*
diff --git a/docs/src/index.md b/docs/src/index.md
index dd5d19e..f613750 100644
--- a/docs/src/index.md
+++ b/docs/src/index.md
@@ -82,4 +82,4 @@ cropmodel = "linear" # crop growth model to use, "linear" or "aquacrop" (not yet
combination of parameters that you entered (i.e. do a full-factorial simulation
experiment).
-*Last updated: 2023-07-20 (commit 0fd9917)*
+*Last updated: 2023-07-27 (commit 1e6e7d6)*
diff --git a/src/nature/species/skylark.jl b/src/nature/species/skylark.jl
index 9f90b57..0f5cc86 100644
--- a/src/nature/species/skylark.jl
+++ b/src/nature/species/skylark.jl
@@ -8,29 +8,33 @@
*Alauda arvensis* is a common and charismatic species of agricultural landscapes.
At the moment, this implementation is still in development.
+
+**Sources:**
+ - Bauer, H.-G., Bezzel, E., & Fiedler, W. (Eds.). (2012).
+ Das Kompendium der Vögel Mitteleuropas: Ein umfassendes
+ Handbuch zu Biologie, Gefährdung und Schutz (Einbändige
+ Sonderausg. der 2., vollständig überarb. und erw. Aufl. 2005).
+ AULA-Verlag
"""
@species Skylark begin
-
- popsize = Int(round(1/10000*reduce(*, size(model.landscape))))
- lifeexpectancy = 365*5
-
- eggharvestmortality = 0.9
- eggpredationmortality = 0.1
- initialise! = initrandompopulation(popsize)
+ eggmaturationtime =
+
+ eggharvestmortality = 0.9 #???
+ eggpredationmortality = 0.1 #???
habitats = @habitat((@landcover() == grass ||
- (@landcover() == agriculture && @croptype() != maize &&
- @cropheight() < 10)) &&
- @distanceto(forest) > 20)
+ (@landcover() == agriculture && @croptype() != maize)) &&
+ @distanceto(forest) > 5)
+
+ @initialise(habitats, pairs=true)
@phase egg begin
@kill(@trait(eggpredationmortality), "predation")
-
- #TODO dies if parents die
-
@respond harvest @kill(@trait(eggharvestmortality), "harvest")
+ #TODO dies if parents die (due to starvation?)
+
if @trait(age) == 14
@setphase(nestling)
end
@@ -40,5 +44,19 @@ At the moment, this implementation is still in development.
#TODO
end
- #TODO
+ @phase breeding begin
+ #TODO
+ end
+
+ @phase nonbreeding begin
+ #TODO
+ end
+
+ @phase migration begin
+ #TODO
+ end
+
+ @phase mating begin
+ #TODO
+ end
end
diff --git a/test/nature_tests.jl b/test/nature_tests.jl
index cf56846..ece53d7 100644
--- a/test/nature_tests.jl
+++ b/test/nature_tests.jl
@@ -172,3 +172,21 @@ end
@test Ps.insectbiomass(p5, model) ≈ 0.01443 atol=0.0001
@test Ps.insectbiomass(p6, model) == 0.0
end
+
+@testset "Energy submodel" begin
+ # DEB data for the skylark (https://bio.vu.nl/thb/deb/deblab/add_my_pet/entries_web/Alauda_arvensis/Alauda_arvensis_res.html)
+ skylarkparams = DEBparameters(0.0, # F_m XXX is unknown
+ 0.8, # y_EX Sibly et al. (2013)
+ 0.8075, # y_VE
+ 0.04761, # v
+ 0.0, # J_ET XXX is unknown
+ 4699,# J_EM XXX seems awfully high?
+ 0.9886, # k
+ 0.95,# k_R
+ 0.0, # M_E0 XXX is unknown
+ 3.4, # M_Hb
+ 25 # M_Hp XXX this seems too low?
+ )
+ #TODO
+
+end
--
GitLab