From bece892e743d2b153eb3dcddfedf314a9c62b273 Mon Sep 17 00:00:00 2001
From: Daniel Vedder <daniel.vedder@idiv.de>
Date: Sun, 28 May 2023 23:21:53 +0200
Subject: [PATCH] Updated documentation
---
docs/build/adapting.html | 2 +-
docs/build/architecture.html | 2 +-
docs/build/assets/logo.png | Bin 102828 -> 103208 bytes
docs/build/crops.html | 2 +-
docs/build/developing.html | 2 +-
docs/build/farm.html | 2 +-
docs/build/gis.html | 4 ++--
docs/build/index.html | 8 ++++----
docs/build/io.html | 2 +-
docs/build/nature.html | 6 +++---
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/builddocs.jl | 8 ++++----
docs/src/index.md | 2 +-
18 files changed, 27 insertions(+), 27 deletions(-)
diff --git a/docs/build/adapting.html b/docs/build/adapting.html
index 7c32e86..b110e80 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 Persephone · Persephone</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="Persephone logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="index.html">Persephone</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 Persephone</a></li><li class="is-active"><a class="tocitem" href="adapting.html">Adapting Persephone</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="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 Persephone</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href="adapting.html">Adapting Persephone</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-Persephone"><a class="docs-heading-anchor" href="#Adapting-Persephone">Adapting Persephone</a><a id="Adapting-Persephone-1"></a><a class="docs-heading-anchor-permalink" href="#Adapting-Persephone" title="Permalink"></a></h1><p>A key development goal of Persephone 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 Persephone 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 Persephone 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 Persephone 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/Persephone.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#Persephone.@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 Persephone 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#Persephone.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>Persephone 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/Persephone.jl</code></a>). Of particular interest are the functions <a href="simulation.html#Persephone.simulate"><code>simulate</code></a> (set up and run a complete simulation based on a config file), <a href="simulation.html#Persephone.initialise"><code>initialise</code></a> (create one or more <code>model</code> objects from a config file), <a href="simulation.html#Persephone.simulate!-Tuple{Agents.AgentBasedModel}"><code>simulate!</code></a> (do a simulation run with an existing <code>model</code> object), and <a href="simulation.html#Persephone.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 Persephone</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="Wednesday 8 February 2023 12:48">Wednesday 8 February 2023</span>. Using Julia version 1.9.0-alpha1.</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">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="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="Sunday 28 May 2023 23:20">Sunday 28 May 2023</span>. Using Julia version 1.9.0-alpha1.</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 0f2dfdf..76a40b3 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 · Persephone</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="Persephone logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="index.html">Persephone</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 Persephone</a></li><li><a class="tocitem" href="adapting.html">Adapting Persephone</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="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>Persephone 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#Persephone.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#Persephone.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#Persephone.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. (Persephone 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="simulation.html#Persephone.Pixel"><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 Persephone is used as a package rather than an application). During a model run, the <a href="io.html#Persephone.@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 Persephone, 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>Persephone 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="simulation.html#Persephone.FarmEvent"><code>FarmEvent</code></a> struct is used to communicate farming-related events between submodels. An event can be triggered with <a href="simulation.html#Persephone.createevent!"><code>createevent!</code></a> and affects all pixels within a <a href="crops.html#Persephone.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 Persephone 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#Persephone.@rand-Tuple"><code>@rand</code></a> and <a href="io.html#Persephone.@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 Persephone</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="Wednesday 8 February 2023 12:48">Wednesday 8 February 2023</span>. Using Julia version 1.9.0-alpha1.</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">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="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="simulation.html#Persefone.Pixel"><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="simulation.html#Persefone.FarmEvent"><code>FarmEvent</code></a> struct is used to communicate farming-related events between submodels. An event can be triggered with <a href="simulation.html#Persefone.createevent!"><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="Sunday 28 May 2023 23:20">Sunday 28 May 2023</span>. Using Julia version 1.9.0-alpha1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
diff --git a/docs/build/assets/logo.png b/docs/build/assets/logo.png
index 5fcae1bfb8df8bca2a249b69a91ca68db4f7531d..fc674a581a663494ece51f4c414d13c1728a6134 100644
GIT binary patch
literal 103208
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⁢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�<V#56ntCun!BBVNiW?fBR>;2<e`R{?
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≪h(s}wBo&WSH$*n&4HYbK7r1ibgF$uOZ=@Tm+
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
PU|{fc^>bP0l+XkKI-@In
literal 102828
zcmeAS@N?(olHy`uVBq!ia0y~yVBQGA9Bd2>49dz1kqitBEX7WqAsieW95oy%9SjT%
zoCO|{#S9F3${@^GvDChdfq_A?#5JNMI6tkVJh3R1p}f3YFEcN@I61K(RWH9NefB#W
zDFy}w22U5qkcv5P?v~eFeR}u*$Ln9u`YEWiuyC}9mN|s5urJVXcAX>o`q1sDt+%3X
z@3xohyH#;NH#K5s_ttaUw04Ax9&s#S%nSJ@5b({1BgJV_@!x+x7F}UXoAbo#@!uMo
z3YPt9&-Yw>^5O5C*SqZGn>#u@R8Ff;tB4ZtmNH!;=xsGkEaH;ElBCY>Ix8!VBzZDF
zYDg2Cv_T~)qfPPMgZ;+;Kb~0WaHf2oE?>qsW=*fgRqta~Gk*Jf+&-G;XvC@wQyv8-
z>P)>~vv%POhO3N+?ReNXys`fA^C*jkT3ga8&1Kq0V_bZl|4r`f=x8ze{CK{Sl9G^;
zoI+oc(Z>u|-rPnX8zWoqY@M}h6@@*Rqh$WfIL0qNb>cb^jeq^|)xD|WZL*Aq`Iz1u
zN>*=sE0Z7|`bKGf*7k|6E-qQ_u4_6vc1-Vg7s~x`LeasR$8w%3dq%pV^a-0EtEb*x
zAed{uf%`^kg7ya0gc~iX!gA3Z8#=kRP4+)f=qD)HS)`TZ>ayhH)5#vjy8?Xm+Rn{W
zWcRM-w*0aG)}#ERQ!j+I#y`k2+Q4~uT0^SvH2uz0*`;gL=X+gObaheLw6a4~aN>g<
zlS>wG8<rfrbhKIT+9g(J@dd&UcJgZYrtr6YJ+?_MLf&A_@eT8`t`!@<j%^nfocLk6
zQkaWN)_cjMA6<GZFL=LvS}^_Vi`J#m|9%EfRKD4qxOU?jjsso^s*GV1PEXHrQ&m#h
zx)h{k-+RVK8cOWWa&7nIo<ut5>+Eevx&Be*Q3&Jg22r+Y>^j;Tbkgm$PcFYxY9T1d
zsSEPjqPr%SZuraF{HmVzkG=b<okP>>456=C4ZH`qxVty#9D1C5Z1dex13|$;P(XT^
z%=9sv_D|xM^b7tkY`b>!sRp^<-k@XNCdznPDM4`Rnvmxyf)igXPzrNV3A*d*&cyRY
z=XkUPhYYVtxvck+iBlNnOCEM-{L#T6Z#1!YopWc0#|Ka#b+Sy(>|1*OpzgtD9UjJ8
zJNi@~MHo)=Uz4af&GpD9JM)dVOEm-qGbKbfDk(iwlkXS#CGa4HpG__%^=)6=W!Ji%
zqZ@8T*zrZ!vD{la>FKRD9VMZ-lEcbMLa#n`sy5agG5GO7>$SmxrLQBD1Q)TKZojrc
zpr3Wh#)cZL*mfboiHCy)wUvajmQ8ZvJ)R(uqI1}ghiOvGaiLD3P>E?0-i`-037lri
zOY46fprlmP(G?*mc>R;7+C;^9i8D;+v^~vGI9947$hbi2#~q1#JO^w}MJ~9xRY@ri
z<g?7I^8$yh`i>?4I5_p%L5D@JBb0))uS$qXdpjOj+z@i_p?JtnK2;?l-;g6+9VV^T
zFP(S}+nz4qKHOMxeWHtshS$cL1YTAajRd9nNgF@`=3)d2gx*A}l_3U~HqXiAO=q~d
zPPx-Vcteh1+jS-b_8F&Hykgvi1UpSY@!RzDLDuSxb9j4L9>ux~2`<lS;MX~$<iKdY
z`9!IL;6x8lR4v)}$y25EU|hq)YXy4K=7CJ}_<iZXorZ-CMRBV0gRVEaxEz|;6(Klr
z*AL;fosVOZE!i!2d-n-W{H4i$Z_Bjloex!yZM+OJuVA54n9GyncU;|>=A<+A95WE<
zD3$eeQSxFqoPNz{w$!`_V%K)?sVE7Z0{QpP1kWdl61fj@9;ke&(p2(2y6KQa8mrFc
znJ1X87rMAO_2!*&abfuM(c=lr`NuWcmhvY+hOtCs^XRki{C}oqcj1SeprGhRC84)}
zM6VmN9b<}(IW8z@*>sjIjw51TDie3;g)WaRL4w*!7oP__tm3?Iw^T-OV%3d=2TL0s
z1|Ivo^0k4IlCP)hnhuxt^|Or+M(F&FJuWE7DRr7FyCTeYp^Hk?iVo3<CroGN=!i@A
zcW>k=kac%i!da8T>mPVD_|7S_>xnKdQq5fvf}J{-Jr~TGI4^Nc>*tFWGJ>6cj5_&I
zGaOaVPxRmU+CfR_;3B0k7p22<zkIh@x1m7u!YPnb1U6kiaGJ6I_>RuXEDlwrhkmYW
zI$GB6&U6=@F1>@xG($*mWv{8&yd#eTk9}MUa_m=703SMiS0(Uh>#+jWX$u>kTTSZl
zkoZ-#`{QEv?b6}9_*9gFqP3D-Rcw5gwX@rA{!qLnHo`?^#y6=7s|SVpk0Tyg^>m!*
z4;0i^T9|Fc8B)~8S)kjN_`=lNWl5o=SY*Y7qO?_#Q#x9-?h15yytue(bw@{b)LhYt
z6F`NGle1l?is7*XTMs0FqUeeA=e18A=gt+K7yxqEonOMaolnKt>RQ8MU0s}R#xeJ^
zCGD6!`^E#So(>m%(Tz%v+U&1?H5b!kOacY;#3*it;x)(PP0PbvVgdxUm3-5!IH!CL
zPW~Z#;e4r#pkSuLVJ+_O!RMT_SX7mKU0v67nCv^5!hAjJ^o9<PBbUOG1v8Dbl3bU3
z^hw%a_{Y3JPvEgtUq^?@t}Gq>$Q`pg_dEw#tOiOVF+VF*il!O*u=o|py1Tf@80u_d
zTz0wj_|6Wg>xC{VMWBd&U{P|fRO!NLkky=$uh%@3ORAi3Kk%VdPe+Tr=tiYW29q-y
zk54^jBzK|=WQfx>Kkn~=hi&gTEqraDB(yK&NSDXoJD%$2AMe-wBjZsBQgg^{X5(?@
zw%rov#n&C~@c01=_)_Dkc5w~SIz5h`V_jXA{9DCqBir%t{GB6Q*Arb-YCul8HS<(p
zT*GXgm@X^c?hcO+5f4PU%MBX+W7-8LUI5h)eK}n2)zhMNVmjiCU0jwJMsnrwY&Y!V
zk98NEcwwn@kl@e6e?8YZ4`f^qba7F6rL%=G?|It25?L1)r~a-8!JpeadCWer^Bj(K
z7ZjYhV*7<CHRFkq>zX?}UVtKE-^m_>5B3K**Ddbo=%{HAOLKi9t(D}u=x&Ig$u#>U
z%d@2-f`Sv}H(rp+OSO5wgHK86-HHy;&alZZUQ5>17lib6ba?#OAQExfB`<B_YYnAK
zUqX&_xy(NK<<kScQfV>4i3ZR6pKZKz%tdTBpR$s#yZHvCi;wiIs!Z=BJ$#;VZgoe8
zOJ76dbLM|$kM%)bKDJybOy!dAvc2rvqjv~(6oW!`$;1%J!}iS6{wFd;$F>VjJhoUV
zOeN^)<sOx~)CXn@X1=yiQd06=a_4|8<LS9RDeFN|RHK#Ts&tn5$j0gOB~SlnSPM#p
zf`v;i9178z;bzAUvg$#gptg{wTH!XsKddjFS#@=EcyvT0^KLindu|YMJ<(;!Ly%XR
zR?6fv`LMR_=u;9pC6pxO;q9ZWtJo{Xsk`szjCnKsx?9AKRBc?Mwnf2CZQhg}B9oFP
zd-V7&sjMkZ+8c36_|pE$HD8W=d2d^{N8I15=G1omD2>%xj~&i_7jOC&^6uxe{71H;
z)ho7Log$;LaMQ9$U9Y<G_vPLHw>N}+)y>`Y`qf(BH<bU6>-sJpyl4N7|Fx-xzq7xw
zf89UT<H*LE4BKOd^M0;d+~IL}MTaP7di}E9;)mr;_1qVQrWL8p^qiTZmVQZXDR1P-
z$Sq#ymXvyBN2zaDGq#-Ev!o}V>)MeUF4reY`=*wv9u++*5-t`T5_x3Zr`R_d_Yd}U
z$-dFMfArj^xjFi`&w&J2-8j1LQ|vnB?j1(A*?#2brLBFfpcG`k>!m2Cd-<eyl~1B~
z$d$@W;}Cg%^y0S2=%QKACrqB@ygTh}#{5~%exGG-ndZCueU{lYX>-Tdq*!;}=&Oxc
zWz*iJT)yX<qj~etvP-@>dUuaZ+oYRwYkQ}!>g*d~yLwkSOntpVsrO++<9=41|BIjb
zD?M~~UE^VK^0@NE)4hpW6P{Z2c{rz-pH?&1oqlIa%&sN!e`Z{3o%76ci)UtYy3KXL
z#c>DNZtTmqmhLv+w6DVU_4jq@wI{8vy^TG->rrWr?o|<C&g#}{ANH3#%8zmBeQlr=
zWUZCtdZ@MjU8$A9g;J4;x3VT*YP+|#>hk7P|6MXV5ykvsYdkl4u6yjs92ye3A@94@
zHPN50Z+Gp@j*Q(j>*?<4n-}M_zphX!{W#O~kK6N9*F()+5fcN-&EM|Pdbg#(^4H9%
z0#onm%)TeN_vNH(t@qY`dU1D^d2RI9rKMfVY+P4A`jm7{bY1e%b)suDqR#!g^mUC!
z)WK7Srn2N5D7Be*cxG<$jz&;1+tDF2FR#PZ=_;s(=w-`ep0%@2ndySkLe{^VeqGex
zEdMu3-gp0*x-Vy5czVU0>aX9(5wLB4PpEa+$DiNMM{X)MoG)H`?$M&7Z>%?*FEyFC
zeyaQ&ed|t8LrHMr`(QzBp{_rb>+4yqcK0b=eEs_B)jeUAGPjr6|GoWXdHU&jR;#so
zlWyP3)w#8$!}Ye<#zhsD+TYeDxIW}sbF8Y%diI*9W@?{iyjD>9l&h8G>U45$iK$#Y
zvtPNa>mu*8A~ojQd?^mM8~+_QV?N<=szBCzQA}c{qI~X;j{a?RM~++DJzBh||3>W2
z+od|4cKJ7@>Q3seDUx+@0p)5ZN4t+IAMdk$YCIvEqN%8OuKV$dHH#(g<b5#LUbEMz
zD)CErQ%hs+(SKcU5BYLO>_}Fe|L*6MPp^uuZ&djtYha)o;J9y_ME8#6)?$L!)rwac
z{*m?ezaFS!wAC;3?1Qpq$vMU?2j8+?)?YpU*=nyND^{&c`nc?<&W|ES?rmq%558l4
zW3%CMsZM81_S&axYM*w!R#3X=<GQ9pyMEDH@zW{X$+7MePfWV2Gu!bko8gMT32a-X
zk8I5CyQ;O?W$IV!>zhBEZq>Q7r=itaeAAwkov%HFD$}BO%;U@{lXX#%db!SR$;zjX
zC!V>gb|8dj<+{fnKVDzl#D3U{FWKYVNuEsmmN#jjW?;({UDxOt`^)S;o9{clNB46?
z@J_dK2O*y7wGa8>Y5Agy{zE0-mwtVQa^IPmW8Eiym^yXNQBBL`25T-C_`R>Ok`1=r
z)u$p9woN=g{ok#hXQJZ|tezd88hlmluArxLO`7exbQ$?wd`d#PUnc2Z5?MCs(bW&?
z**{Dd{8R~2*DTbWGox1NuoZ85#qo!?<aC5mUYD<1o)F6Td7n<gyK6f|j*IN>Q+c@j
z*nxOv(LeKQu4MWwnfOxAW64I}M=8k_5}-1-rN1unuf)|<k@PajqntO@R|rn_5MH@%
z<+Ht}??1jeWx40q)zvzh@k}4r1$#>Tyi^r)+JY;FU9dAnE6G*rv`SP(o2J-0NBitg
z%99>Xvef*o;#O`u`}3~3?(J9j)+u*#Y*<{up088id~<dB$6wE`-<-a|fBlP3$!i*C
zHd@r3ey>p^>!u>~GBsj}q0b|o<Q?)E@2$F8)~$OPYq|P#<eZt-UBN|uii&CnOH~9d
zn@+9rx)=G8Z~eMChqa~S5@XL=T~On+-1Anf?kG!Kfvk(lB~U56Y-LI%<GV{YWGv_G
z39F2`k<7EW*!}W;-}>u?E=w4%y^lEmMs;&#-qX!GI#C_I+tw+2au|KcIq;b6*h0o*
zN{)+^!c-!b861oF$G4?O*43#!-NrAgTqyl%-?OH7;umyd-50wmT|9PIx-$1<_MS~?
zX6tindsj`-x|@2k{#G)tu;lsXb<G_vOndiqnOsTP#B0OS12V=rDMzXKHg8(V_02n1
zJa^sVnfcgiQisXHLzA4I)!4P)T%Bf^{#oYKq*GU>$L%w_9agNnebd=efr$mnl){!M
z{<(VncLUG$z$0rVgb#PV^?UMZ&&HTLuaklv2gkY#O%w>&w|`E!U3Kfs?zA7;Th6Xh
zI994vxaP*8UY~@v*9uAxy<FFL)cPo&UHwQdd*_`}k;3P%*B%o8CUN-aUOhE!%hRPQ
zf}Dxfr@k3fU(A^o{YPhgUggwRVpp{?7SCu*XEu#FuPd_aoRUyp$dRrqS4GYlFv=af
zaIRFOP<ef*-1O(YsX6x|HqB1m-KVUSnBjd<Y~KG5mGh#1>2P<8Ck3zFCgZ+bR%~4=
zlm2c#B_ThM8P`gJ_Hr$Y+HtK^B(o~^@@^xu_gs4Cch5PeYXveyFy(LG*E4hMCrftA
zC&zxZ@^CKC2t0P6r@_8&`H@nwi3JO$drZ7F<B&pfCCiIfR$V4@ulxu(_qt4O`gh6G
z8~P3#RGk!==(a86uTq-cjDu&M8f*G!wWM6{T*8^V;e)Z-hiR`BlotAxrzp7>nS0)2
ze7B`7esOPH;KSF&>!v^NeY)x1^oc^#A6ZT6a9Mb2l~-D=QTNRE=Rcf3zimyM#r2g-
zI9YgnxI+r0e}?ShQx;kka->V<T<jM!QyWg1r&e7i`{qg7{#<VtUQ~JS>6YwekIyLy
zS(%CFr9IniT>0g(dqnJBsi;NULzU;IwzhiDJdt!g(8XzDSH#5kn<SPM^=|ZWmfoop
z<>bTkyu`LWyKi6E?N(P69i6EC9qrF-Pk=m=AINu0N9d&1+C-(tGx`pK9N|@RT<z2R
zcZ;TSe(={x-`%IwyS)1JyFY8*hsIp}u4OdY7}Wk+x%ttiq<NL^CEwM4&evHR!!^@k
z&Fhd$9&y{-v?b4%U3YYGYVC@cxc=_R%wx%H3ubBxdaPcjB(zd&ZTu1EV)>M3mzq~^
z){Rl0<hJ2)g5vL4pip!uFI4(@WYUpbwz_^lN!K}dw#2Nne>VM3`27D$%9@8keJ{7o
zyHm{j_kGp)zQ0)hHPh=YR??Mg8mpN^dz9xhuRGkaV~JAOqT3->vl;rC)pzwN9W>qX
zH=*wCe>c4sb&Q5;$3SMN32$J$7xPQ)`yQ*gH>J~(jn|$#=QhoM&BLH$pIcumD6L!3
zG4+LMt9I{Gxdk&{YY54leKfl;bG`S^(*M#Yv!^}>bykYwbAC6~pZm?uuT#<R=t|NF
zhw}P~3y&OHKjQ$;bw`(&3#Vte%&!sJtMV`FVbt|N6^o+FMLT!hH;uXcUMfm$TZyc@
zi^`KJAyYm)X;T0B`t|?gr~Ya$G!=MnHPvKFqhur3I_3FA*CSnKP3ns1)T>{%yYpeB
z$!}97p7$1W?(_Y~Klh@BZQjMgG{K4T!W$Ul{(cGl_kL>TncFt}w-)^MczABpp<_mE
zvm+i_b$J8_3Tj_W)_Ojh;lER@^x;|QHs?;+c1Qc~>21tq-_@tAB(zPee(Q|P&F`Ld
zo}a(KYO~a(i*plyXl-oEmN<WTU2}&C>)sI0C$s&U!VijYoA2sV`uhEA<@NvOAJld&
zEeEyfRg!A9e%6+&cwG0c{(0Ruv-_{hO~dT>Y)E-<(1CS-*!QH)60IcFO}>ko4Q+Vm
zJh1Az;vZHdc3u9ncb>&Jw%!whf|)MAwZ45k5#4X_^y$f*-kY!defx{&dc8Wc;l#B9
zLG#V`N<}6fTci}GbY10~S)2Pua}UoMFQ?t>oz2#loO3TiC|MYkBs-<1hEBEl^=<K=
zr%!iBL~j+l#pJmz*i-iH*0%Y^^Pb1D3uf|YC8>UTBK%s_@Z_QQ7rs~AcscjtY)*Bb
zCzIl)3%ouG4vwu%W(PjY+xY*xT%VA7(`)~XP~jB?NxVLsCC|e279A^<n3!;hcc05N
z`^kw(6;cw<th%oF-aoVNj!A*c^l$s7NGv`ap`^4>DS`RS&l0|Jo4Mx~#diPcJ9g`_
zh~K@fa>)|M{jNK@G`YI2ap}{P$<@(knj7Oj@s_pK>x?|Rk79an3KiY-J(ZLc*Cu!}
zZnrJemVf)>gnruP3wKj0Zlo~(X_@`=MybHWgbSzpT-r2al63f)Pp(_+@s=mcyaVKu
zHFq|L?CI)gnc2Ep>{I*l{O4y&^MCO!Fqx+=6B2d!YtM7R>y9o`Ui#)j_x^ldU%$oR
zV5!K;xx$<MpVYVg(LZdJb$ok=$Bx;%EA+P8f33E=^Jigwni=!m*ftAhezr?H8sh_=
zT6KHWzD#vHbUk*9k*Q7Vx&3Xec58oq`0cno`}T$o4;HP6paVx{3jZj%z5D{-+B0qY
z%5zP{3$?9d*acVe@7?23ap~vv4Hu0UtDDa+;GX_<AJ6%Ub&oqbJd`(H`*er>eBtlO
z`_sS9yQ-Dud_PV40n^;cQwx?%7v;2{yyJ?5oYV7o=cx88e0Pc-tp$}wy{7~PJC)-5
zpY8nmF*+i;s^Hw3U6Soub0<&Tu*6bK$WEs%<x_8>mB4eWzCRn@q}}w9vudrM_fwy3
zo9v3K;er!2l6w^O)%)Xn_VjJjyjipFg|S!J6bGdV53J_axUXsayhm`$mgdUl?HkuI
zcV1}=OH#FYa`}vkA+yE#QjwpDnuVHo3f}O79Ana-{|;0%v~+y>`}EG|SGIS4{+WMM
zd^>+pgUI!jPuS0F^o%*w`=(gd<;n3C9aArqo4@rj)lYo+-m0r6evSC)(AxD%^&e!x
zwRvAhN6U)4s=I%l_AWQf{bs_qM6Ti6kJX!nyrxB*zUh;)__czP`y!<<r`sWY=8XS(
z?So>S&V1-QytDd-$*(Q19)mi-EuE&(*FXGL&wsp=fBxaLi2XCJDlQDzboNlC&jaP_
zjxK!eu4`J>Y4#XSb8l3+9{A)o+cwz~Qx*nWT0T#?9_Zqt;#2$MXnRk6j?CxlXWDZX
zm@Y8mTDa)ap{qU*3a>l5)OB=4aN3F;7C9!pL%6oTZOWZ3F>1VX&#>Orzpy4;P%v}D
z`s1H`<`_2Wcklml{L>bv`rqwr*$G|=Hs;A!K6pBH$0@07@lijx`bi?V8DXhnsW-Eb
z`MB}JADk-3UNKDW=wP|t_=@??|6_mu{5yGD<D=J~XZ|bK1#>nurZW}BoP58cV6N+v
zY^@~Kl0Ti-)TT{uY+Sdv<9x!74aZx3Y`^MREhz&H{JALIxwdHSolif`o~bBj+t%93
zx8i4TM#cSW1$x^zoGuj*3=q^_n8da7*e9(EXG=vs%HIAJ@z1Kps`(agk*uqW%c3*K
zv+bXm|KBr_f8P&=O&@04AKl?6`t@40#8H;8-F!-ml)~<OwiY<gWEATzc*5h<gYW8h
z&#mwKD{AOg&ZDICsBP=CneWe~{OKutqjCG8_$Dj;*HIHq=NzsO+r_7J(YJiXqiZSW
zjHgX+G`SwQD0Ytc@%;YZy65MAXIlPbPE-07r63oVJBG(DtPi$dCs$_r`}_OnlU?Tv
z+z@U^QMgySYsJ)*2SIL|+IFrfkab%${oZMz@?{^glV`Tw^C`?L_<it>^`rM+&c1mK
zN)RXbqc$aS?yvb!buaqwy!}eEo1dND6`ZWQKT+vB$Ss~nn@w!H6=&8kPrm44vHX(o
z<(Va?QvTU}vb(ip3wT)U$%d%qTc4#bk9EzP9V1q^tKrkxr~l^Wa79hateR)o^U3YP
zCBA38_pWisWkzWwEzNu?{J!=~@`3fS?wx6Dhea#HKYa2}D~vjR*}$#-cXx-!i{Dk<
zAJ4b{o%5Id+vkt!^2y&Lat+I#R|vbyHP1YHJ7hPX@<r$Jb(cz(O-x%=A$U6Adf=kS
z@6+z?EI)Ez@>=1H*BVMnO1wt(PiyMFUeJ%+RycG2(H+bJudPBus!m6pOINCnWe3k}
z%sQ5`iFXg*mqJ<9DAnVt#(57a^6Va_JxcykwzZ?frES$Lt#{Rb?eeN0g?VLr{oTAt
z@`c{^m%1C<E`!@LDxY2+kCwU*YF6Yk#KyXJhN(ZFbH+K{#%Fs;??X|+i6_21J*U6(
zU1PjK`Nx<Hz7nQMGVNV<@wXV1ch20puGu3cSWvq+Td0yP?)ZgsrBgDdOq+0Q$->Dy
zm)$p&_`9RK!$YLv+u!t`Pn)j?M?`Vlbcnv<wkb1r`!wSjCz7r^suaCk7bbN+g-vQk
z^Zu3Yvu?b&bMa5@liDr$_wIp*^whTQt+3u-_k(TT{|A-zrrV4!oGD$kV$<;`H{*%l
zW7sF2SfUgrb$sreG@F0D`xm;;3V1!`nvbN_)Qy$Nppitu!mMwLZpQpSP@1E8i)rSM
z-uWi87q6TWdAPObx#@LBl}|5@M>ORdJ(oP({e$=YQqJC&hHW>+_Z{lI32I^~DLsn$
z{^ngw>8;Q=nzs)xKW*3Q^k?c#m+L1NIqhlemN+NH74goh$3<-I5w8N@XI9ML7hP8O
z)mmQ3$3O3*!18jtyI?;|_;M?Kec{``*Ej4e*nI4x$y%xGAF7WlFO&*&%0zWeeK7M3
z3-jdw#@kDdeUUi4hCBVT`R4WD_*Yz=eS2Mu>6_<oG<B0MZgSlq?cpHXBRxMo!9>|W
z<iobt211fsgtQ$W`ld~4<y=?nGI`Atop;uM>(0F|+XprwG4<T?;vLWSt-iS}U3$wA
z`QwX2Z@Q)H)bsf~3A=8o@+VU@OzK$D9+h|7+GfYNcd9Mk)$?d7_j7{<Zy7)ZrOP3|
z?c453RG*5t_BP`9s;#U4ghtMtnp@MRc#mV&ZKit#vaW|_hb1ljr*mxfq5qLPE|yNo
zxTv&{b#lAk!&`ONclCiLP6g-H{*PQ&|G=uttNY5q9i0+8><#9{Cv8}_*`p#zQ2T4L
z;k}S|8>hwZ>=V*;E0H>QIQ?JqoM)Ecp<b6My}QjneXd@gbnjB-Kg*kX86FAB#vcL}
zG`&8d{=llcMSkyjmD1_`&ufp^>ttAN;8Z!LR`fmd@(jBgD_x<e9ev75N<xKED%%s@
zXeN7ldp>@vnjgG*F&op5)-}^=q`d3(`__GnihC5f_Jr5n7srEMJ(En@qyMwL^?#A9
zs??WLFOCYQ+k5U`QwMQP>(klOieGN=j@VVW(*EN<?tku?B5d=xLJX$Wtcp#a_+jDH
zh?RTOJ3j7vB*-1Uqfdx;-HF{z_3<BsELYyL(@|2o6tXEQrSR#>@Sw2BQ|;PzEwMii
zGtXZ5bpEl6$GaCVmp$x#=GwKSm9l>|yx!V4%+Y+N`GDzqpi*p<lhpUQb@ujee+Gl2
zWznr}`F$t0evfxf^i*8Jw9{eE>kz^0ZN873@>2G{RuK9Xa^zHhb%Vv`>FFEiyteXM
zB7G}Sqkpbx^S86NcY`8D>A<qPvv(x@intf~u`m8W8QZ0p<y`@7({s3wec)ad<391i
zvbRTyQqBuJ&P``4Som6FqRzGMr=arxaJrpORMWpS5kW!Di3wshu(bf9x|5;{j$Y8t
zxM|Z|Isd%!25W|^KeRVT@o{aNx2(yo=OJsZ?lk3#{qtnz)w6vw%-(sWbc)Bc%Qo%H
z&(+Qn-t1ojs*zm!5+1H<jWK$gWG0^XZMJPGt5EFnE|2p!x%2`zt6R#5Zv1rk)5kq3
zavKe<l}_<6Tl3f;t*>s*HO;l)%sw&dM(n29+ROT%Zap9OS=z3YDaw*hw2{X~_{Eu}
zpn+2zp{gx&Blew7+S9-D{Grfwi(OVp2p@ji{O<s$#QR*~8!Rp;$SHo3^JI+G6QfB&
zlPaoTM&D54{{3;gc=fu=u2XFC`DNcEq<!4>?8K?<nW|y?&L-_yc_&-<`tClVm76AQ
zo?%#}rfk()0QQX3gSn#b3tn#VzOgNR_Wrdyv}b8br?CAKlsIoHA-bukBP{8uK=;RG
z26qpwk8$q|S^i|sp*!=%F6ghG56-)n9OfEX8-AOzvF6{^=WFh7k}G58Trq)nUGiSm
zEn8Ukyt3+O;S=5XiC2H7r&!%{D|ZzmiMq@G&Cf{KP8Q?T1<gDPPE_#p^m%wmar#5a
z{-3As+iuyrgZ0*D37xjbdj*%=WQr@7b#-d)ieNl2`-}>=aLn@#mzSL{ZR-DV-zj**
zTjAE8>f+*})SGV8_KbIF{ky_Fzi!HCeGhXo{AYPH;`&RaW1RO29_2FT@8VN>_wuh|
zqvo9?o%$kKWudQUUYz89zSrY?&%AYuJ3Lx8iS7HrWR}yi$!Nv8wpUsf0i_?lUlow%
zHZ)|nuM&`EKRe5DvxtY~kBzQUDO<kS`@6i#fBS7~jKR~IX}K}a^u<frqIUU-TI%?u
zFinnqF0ei1h}-UyG3gKNt{W;{w2VFfaN|W|k6!;$SyvaO5MSOs|EzNE3C%hF*(PHq
z-&&)ErD9K>IBYuit@BD`W~yfR-QULZs{dR5cT)SOA$PZuy?JZfYYFgply%j9(^<Yx
zYmzHjOk4Q1niCIw6s~x2rropWB1?&2rj7Ts1E)d{R@-DR+{0A%zKvHp;bhQ{EaoXw
zooZ~BEMa-S(?uz=CdWp6p2acw!<*me=FDsrQsBK?Yd*)YKukIEY|OOXe9Cz*{w~Nc
zo%&GiK+YezDj}7XA6MF#Rk1xUu{~ZYBG}3F|DXArJ6B82U*Dwq<qc!(Zl|P<z3$<$
zyi1n`M6o?h4G?aam9=7BqXTaR`}W}DN1bBk#7{BLW;;7On|rIty6bk;y{G@Z5BfIc
zZDYj(=>_I3O$$#&ol9M`OUzwabmPSgt>d#9SRIV72P$=*+u!98T>a3s{_2*MM~^u4
zzq_!0emslW(pggf&&Nb?w7UK~{wT?!V8OrsnUfy<x4d*|fiqvpE0HZblp5;&zNrW6
zCA>Vg^xxg`^aWF2hX^jb6Xln##2v#vaoJKOvs*rk)*J5WjpAXs+G?x!B!01+qN-p1
z+AfdFky|*#YG1wkY0JOs*`dPYKUdG{O}(ynV-xGPoK{)uKcUx;UD+wjBmM0EPnV{p
zTQ*IZ|M#sIsP_NgbnYbE>9}l(Qx$gQvM#gw%r3Z0)_fvWA$+1pRyC-m_TSfi6TeRu
zSUmTp(xok%HvKuYZq1pqpQB%|Z(A3`+So8(J)-sgx3?QgG|$98nE&_gCQ&c1KhHCB
zjvf`5&#*Sy{9m!>myZ74^fR5w2FE_U>ndNsGj}p?p9`~ift0>+zti=^C7Cbw&d)HM
znZwNe!F+><fXWe-4-X{y4bAe`yw*?>I+~T0aMbI@4#98lzn`x?cI;QW-Q%Rci!MFN
z-@f(Q|A@$!^X2dEx8D&NH2d&{g%_6j{@u545!1CbjiIX(-``u{wtDj#9gFud+a*<s
zZ1;Z1T(|3cdWg)554$IqFkj)^v+&yOEVg3p+cE4Dk1ba+lk!nMEAt?B!TQ%46BmUB
zY0tC&&)T*{{*hHzhsWN~@ZYOvySi@3Hh**PY5kg2tNtfTF}r_lWn|9UueCd0zUH6h
znxBg@!=kd4m6_{`8efYDowSSi%=p~jvS0S7^&d;YoesNRha~2AZk=<+MP@&*TCcBb
z&XUvW_f$S{wLM(7*rjXV%-YJI>YHE8xOK5qL~!B)Zk9i5_eh)nOfGx1Tj|y^-W~})
zPtW%Ma~|#e@H2fwS?mju_3^LEMP%ytycQ99X(pcc?2hO24>zaJ|0!P7u+2}|wW&Nu
zXnC=+<GpO9g)Y_~lxH5TkpHO9^L%%okmk8JMQZDNW;(x4k)0wm@kC0`{gvBmt6xlh
zUT<>XUTvwiiMMy+U90`K-<Kc%_(r?2_5Hyn*1Gb<?B-wY85^d({I@Nm_uj-~(`L;%
zm8u?p?33^5$i1beZ<zTW%%6NUD7d!t)2f$Q?4OnLg_G9n3F-X$*pYBgWLeZ{-*v?<
zUH8BI=dHJVn`g7QY^st_?YH;ssizZfZrU|>sjpYlX1AZlY0QifdnD|B+f>N5J%0T6
zc-~E+SxbLBE}CU(ZNdF5VgKGA7WHvCrKTa_Kc6?9KD97qetf|6DL>9`eDrvsGkd+L
znVz1-PnWF4Y5|9H{qLN5Qt$sw--LY^(=WR<=E*ZeB+j2*SM2dPKu~(6TJhY*-!aEK
zST@G#)XP`Ohs&341=SSiWGx<uFZ7;%tuEEfP>_wULDl>3x&6Es_gJQ+JMYffUtJJ<
zex+!p&-eX>_MoP87L#e+;pOiR2yT0FdSc|^-k#@j*DY0kgdA~O<T)poM}N`VN4(R7
zrXQO8+~(+uI~Uh2?&xTlvbXx--15JlH}|ehwJLeX6l>+YOX|KyOLg)`>7JdhoxHTX
z{#fr^=fHh^<)N?xha}WKG`&_3iqT3^KAXZORl#kVmA~Pd=GvKGC*PF0{>%c@igB8>
z_1~*k$K~1g8wS_dJbC7{e%^&up#}2MDpzXvd`mvJuh_);`@1jiuURwyvRtvAD_ioM
z%e`V*mnL`D9F>_)>o)FTPubZg^seY~(M;oKq2M7qR~MBhxwqMhx&Qp!%sX`gL+x*e
z`F3@R+Cpph-TA4y_+Q1c`yV*}tUGGyr`)>PiMx5mfvoF}Di$F}+`8;1XC_5-*y}}0
zJ@~Qh_~%dlX%lD8c?rr-H#GFx!k_)%o%BlCP_WO6>r>V0m6J|f@AB%l$iK8xCt~Y?
z{TI0EL&M5HeBF32tXOFKro*KInHF<r_OO&sPSMF{a0fZ_+}koe{n!sinVp&75S@C&
z<;4}jeYYN%*RRq&|GE46W%pmavrVqKJ(;lNhl-wLk!JR`b%{rxi3adZVS3rnrg|lG
z*GGvn33AVKo36;m#$1dSeRwWu533E+oQGCkJ9htCvAXihn&TcFzM$5JijJzv59O?D
z>sn{clK=n5Ecd~e%L}8!_s<ZW_`bWh^J$Z?-hvfNCiGvg<N4i~^v5Zz{8Q=Gd)<rM
z=bkRU^U$ixq-EdN!*iw|krm4;n5%rp*P@Q8Ue+$wIKkCLO2hDC{*f<7#oPbSnIU2E
zu)?CU!`?m2rSFWf+~Pi2*Q6Su&(lO4OgFIa&)&H0{`F9~_ksy}phX#9mn)gg@lE6@
z;J1<t%x61%ce(H5ZIkngWnEoVl9nuU%G4AQtNVZ7)Vp!Bo8$9yzVp3R?(n{|oN?xg
zPTcP|ra4<%l@?eoP|GMyO3*m`vx#Ziu5(IX7b}^?-1V$auHf98b2WO6_-Ro8;dS4>
zbD(mm<MJ}zHF3;W{}+DJv6Xe}Z!_5{E3k4qV=ViHt-0o)DGLW*2Ck3n+G@M}#KL+E
z=N#pD7I+}-dg79IAxGL4pG=Xi5O!{Rt?^JxQLS<L`P#Pb>ex4+G~v?K`_=tP&Yc(k
zi_5m{XIlOCuoCa}?aA?dZ;N#P|9j!OYW3>BqBmLoB!y*ZUptU-?uq2Rg!!)xg3NEV
zN#%XYOq&$J@TFK*HD;;ml8>MK(+qd~O#tNyrCD1)Tsl2r64UaztIi!(I%rn^wC3E-
z&pF?wz5l9T!f?x?SESEwyC{$1{GjWOOTL91X`5VQGx-d6#JN&g)fmv!@ap8a$1m0_
z2DOJfxt>0qu;!}bM7Pa3kB!d#c>FR)_tvZU4DKf&W1ihOH|MbHl|}1!wJ>c>;#H0_
znjCuITKw@VeS3;e?$%0hb(uARD`MiYtIM6`@BO|1^U1c8U-fgC%^0qwuG(OH>h~o3
zoqUR0mruP>U^sIln_RK1a!hI7#hI1j`#qP7&5dyv6ciNX+~vF5+)(Gg$+f)r*YO#w
zC2r-vOA{UzseRb-TISQ^FS)XO%L=w^)Nwif_4QKs({ds)HvMI1Z|wwkQ7&a{6VFdS
zB6~P;U*^twMcEUs)%w}%FC7w4`_TDXp(sTw$@%X5lLm%0J^$loT?stjGf(7CiQLVz
zn?QaS6wEBK{{Ainq<z=N2OL+PIh31BUh>WCmQ>$kv9g_fO6|+Pr#eO2ZB%PZ4`hti
z|GVke$8)OhS2c)&)*ns0s?^=|r}E3|l7b1YoEzA#Y+7;6YDUC7rTG!p9iMy%InrjJ
z-?^V*`L1(<eSMj=JjL}<4rxWpK&7#glCPGr>16Zw72S=o?7zfAPF(AKYNFrixi0y{
z!%XYK6|>HyvZd|n6YTr7{pI=B;(HxWADIR!5jr|7f@8wYtgxSZl0Dn*gZ>f*TZinP
zt;xLh$u|8v&MDqsu4E>%a$@k_xmVt)JnN~PdgVt5D9yMmaw|1`bC)~yX+R|7Q_+CJ
z58<h*OU&BW-Cf|Decf}he`c!Y^E;Jh`TF&@_fO#Y;?kP)HslsV^Uj&B>zYq&U)jNH
zn)M_kUwx}}XZZ0wZl8ZV1G~m$jcxUU4FX-?4$M>fKmYsGEAO&@%X9zzZJuZMbKj&c
zp>uy8OYYhJ%l3a0*Ueow5|S<YX5V;g)giM;$!y9K;p|Bj%yXO9ZcdJtKYeGu*o1jA
z-hl?{JX~&WX5W_Ey!Q5=eo;~0>OIBhE_SWq{;l=R@Kc{)&6aP<|DBXBaCa2X)XF)t
zS#*x0-PLu?9sXyxId_<Mojj1buDE6P;>~?&?~bxsF>5O+39(!|^zH426wN)q^>pHR
zq|JXG%_$Ygd-(XV;_}+V^6szH6!jVn)nkwBQDx1!yIFKq<6Z~v5Wzn?^x|X+w>4CP
z4A<VcFo|n%@6*&T|CjjnowDfyC1JOqHgIGn<{syZ*e$m257(*F((fxjeM-3C+57!R
zQOeQOqdfbQCFZaDe`WuKmi<br*B-S$7Ipfk&lA<_jxMah89TcBmbJMyXl=B5ad8uS
ze(Wc++@M=KKq*^j+NxC#y0>m9T3UZ@tLB_SwvrQ>vz||q-<Ew}&+qr)l{)vg+}Xdt
zc+=Lc$E&`i%f#>E6M7qRWS7}omf(|4I$6a5?02Kfp0Dk`zbtq2HgH_E%$+0@vFV6@
z0>4bguIF#>$+peARB~RueS7hHKah!QZtOX<e}U7sZFZYLWry0IlM~+u3BI0TKC@c)
z&!y77f=i}*we#aY@xgKrr}pn}2h-;t7LRvOxbWk=xHNZX=Y(l&cXv5%U)TG8PEd7p
z*EWMM--08y*Uqh9DEUt&a_&T1rR1O42}=7*=PJ)y*-@G)BrbXQ^19@f$$q+4AI~j)
zKk0JJ?+Gq0E?KMB@Ywx3V*gp{%%iKH6--5=wzW)qS+{Z493D^4f5$CK_wiOrm*+p3
za)17rwpi&u+*&EwM?o!$Ij?0ddbzIA4t|lwRMVt*wRB3s#F=wW?w)>bx%+83NI<l{
z%8J-?<h_AR&$&aKoENs~rfhFD%l&)k>Sw8cJ04xT^)}n`=QhP0{d@1?Gx$o}Ti;Ba
zdP|C}fO~Zed#9ULQtS!!iz*-O3bwq~c(};biThdXAGPD#?5=^w@iuIzv#t5SIAxmY
zn?fU_1>WNOC4)~-ODOp+F>zW>#G#ej`BVLG%KdlZ26ekM`%+e}eZcZ5^GMyjPtISA
zo-~+u)<+(mx~{mTd&v!zxZN*Gq3!h!j}zMZ?X27nSFeBdU*hG<e?PCDo4e4pdx7g@
zf$#rjeV42}&T;CSe9d!Z-u)9oj}}C*$#MBSh`MgMsCS?0>{}x1Os3WE>=V>`w8tXO
z;=k*;Q?{qU&Ykf6sQ8C_zc<v^-`#)h^Pfdq%k}F|Z*W<@v-^3`x4DZg18O(?%+p?A
zyh^I?K-4j#i8I#~y9n1>n=RFRB6T|bhdS>Q_ljf5&t4qgx#Rj#Q0RJytXS2wNNIm_
ze&o#kiz2H&Bv<bI|NfwTbX4%;|Mx!sdFIObQ9zvk<HrkocHV#U;&r_4<-dA+dtV-4
zjM%_%ZQbhM*N+`{o^Lnd`tAG^DxZ%0Q3nk`F?~xA-*C;refdPE*p+J++Hc=*taL)g
zLZxjhZ5-y@JY2(be0QIa-aETosr|NocTc;zsQl2<PJHgCq0@3m>Hp(>wF$W&=AZuj
z=k3nO$O~57n{GR9p7Ox<-?~_Xe7QH;D{o&{RdKj)SH~zVFTck|Nb=vmTlaT9d>Ajg
z>w?^clEcbBkAxX`d`_O-R@G-Jn9niUAm)jc`;H&?73)*}e0&^xTtILlM_?>(^!7tt
zQ$IX(|M0N=-;SAUqZ7~1`<1(Yt#0<hMWBIz^=1byE!~jFJZ0+dqsc`@f90#sO3jFV
zApUgg)5;6m^?PI(-`;ladB^sYo#%xWL$b}ixPRN~6XgZiSw8a4;F$dOs8BL@#pTio
z84IS~SXQ9!+<V;S%Kf!rb%kH_cjQ0$yDqt-!(+zn{qkY!+j?gw9Pe|EZgBRkvikDk
zp?T1%w`FnJf6pEEo__W1POGv8VZVUQYAg5N|MS`H-OS?i3%PeXv~9LnsF#qaB0S@{
zmB*4`!P__f`7G;9G+ZFYxwW9|`sT`qf5bZttD+-ZTwdj$m#awatDj~XQ!y|8#JAV%
znVIeX_c$=zs}a6dANl*ZpI@6}^Mc~#ZOf))1PiZtxV(O6hqztM!Tkvzti|LXR-3Gf
z+;$_P@0nWJ?mnTDAxF&Ax($PWm>2ZD)_9nZaJ%u$?jOEEkGA-`s>})v`*pUo=VN%c
z)TXOJi>`C)A9&|<UGvp(i5FKm*?1bZyk9dTEc~!^apLD^x9sD#=M`M){3jVP@z)BA
zfP)>@ZJ+PG`u>Mo?gDqNuH7EXGMmMQCWkbu8AUhtW^?T~oAz>Da!d1_Eiqzo|KuW1
zMuHNsawEf@|8{F)p8o%r{qf_!RUuJQTTV5E&HQ)#*t>6953}FLRs52?t|@iy^MZ7L
ziGn%t4e##ruiyJFzjs~lj|vGJiCxdk^87maT2)(l_LT~(-oEae{t>3VjV{wyI!$kV
zJ+tB5aZ@4DjlHQtmB&69E=c=ouVidFnRUAElISY)>wzvu7XIW;czWtq?K;DMmWRx8
z|5Q%Py`6D1j89Xm>G?eVbIC`KJ9}|0QE{$eI#SVo&%tos|F+YO%moSdGAo)cU3!q8
z=;zhc$o%K?dRN!2zh{N5P55C@f27}I!<zdW=Q(blcckx8^ZO+#55zYW>IJv1@p@fo
z16p72p%Nr`TjHJC$&inR6P{ant?=&iUiM)5XA8yOEMQli@|t0|Iq|XYrOS%y>{d^H
z99_FStSazyRK+9D`fJ&_rulr5k`pdo`afeD+u2!H^N;S|bxXc{^LB}{cc0vUzPa@@
zKA$Ug_o0){TcRDMj;p`6d$`4Zj#p;t%6diC7oBPI{%lyft*P-zaQnZ9LDE`D(v9Xb
z_ebrxSlSmLo}5(iZqIYe?YDP=;wRa<{Lub*u6vJ<9(Qi%`)79Q+uP6!Zi{_qKlp0C
zZ?Ea!>|;M#vv%iXTt7Ge{;eCuLClOd_Q{&%eL4Q-&F$+J=Zzm&SUj6?tTJcf`m;Yv
z_@4XPO@B43`TdzC56!ECQa{?V{S%sT0Mx0Ms$I=`Tcl0m^zDo}=lZKY^tA8zwPJPb
zae;{f0g;@>^8X(;EnX-jw7@(4#YN#wM$P|!2<_tHPW&izV=wm}iTx3|_xUz$R=oJp
za-Xbq!dIz?{rB$o-3d5$;DO_X)!~Qby_cBD&G^l5-M--NLhhLk>FI?|kq6i$j-B1}
z*2+UAP*B?EvZtx24x`nsKA~5~cx8@1Sr{AxvV2p5;+lwyJI+s>$hf!a*WIYcC2ihL
z2O60-B&q5|hyCBYWgh!-zSbDif=O!M{>%N8y`1K6U82a&JM~Xue56Ge=ae0MLYiBu
zZ9DcXyu;2@I$P<>+?!8*<m^7nSGaXwRVwoM{jDx}&fVS8WoF+zw6qc)t3_<(%3`Vu
zlwQ1_^XS4E690M1-`^9EeqR6o`jspHUfc4!^<DWBUYP8%Ul241-EJlJ{_y*-HEz}S
zr#^Gkjy|As-BGDEEU7tFC|&yS>2=91yY5Nut$hFKyQgo!ZWqCyiNC-9_AU4(;#|1#
zzRdEB{{2raZajLdxZeEB+t+o~D>;6w-uQkm`|JIGKAtyaYn#g!yUV0bZ{lIil^TgB
za+@PJJxmaeYrg+t<<8R~3r~Wk{K8|Ncd%$BH9ypgnkhAnDL2NQGj(ln)aQpc`d>`A
zb+A-KkkeUJ^`F+&b$9EU=ghTkE^jk4yJqiQQDR>|r?VqF``VA_H~m*GR(w#XXAM8H
zm3OyU!J)Iq<)!v6mfY07`Rug|)1x&?WL55D3Wo|*9R49*u;;bRLLEc1iI&N6OZ`{d
zfrhhZczJv{{$fiuyKU8hK=+^f{XH93Y1OYTsAXlU3*1v>dgS;|W3%3S&qUjej1~l|
z|9GYS|M&0RyUN=cnP*u|J;Cqo?U|f$FCcB7_2u^wG7R6CBv)L0x!u&fEl=dbme&do
z{akaLeIEt!Y~S4{c#5a3zPG9+FxCy!DH1&L`OnRHZ*MuikE=_Zee2NvhwD$*T=*Xn
z{CNJ%yE`uGD+L8L&5m56H)+y><m2zfH@$pW@XMpOZ_<THca3J}<?jCYhyDC-@l}mQ
zf1JYdx#W^w9Q6n@oc?s(;ud4kjl704bCPGUW_-RWc&F~t+dDVnlZ#!K6dpbPTe+m_
z%ZK`<D$bdaf6rZ-HvRWw|5IKIOS9{DZ|vai?7Xn?@IoguGqH10OU)xxOrAb{5*QnN
z^v~4Kf4P4*O8v3i^of`Gu;jtVA{RV_7c0;2y1{0kT)|~=s<bblEU};a=j{{KhE?2t
zF0%q^_Qcmbd-~JZk=Zn0&-Qn*{pI3^#Iyf~-VFJ=SlC@i`0u;J(q;!Z)qiZxb9K79
zveqy4=d#o_clKP`AJA6swr%F=5JmNi4&_`Gmr5rTEIqYopITw7q0K8RH;va*FLr;|
z|L-uj!&OCP%9I0_Qa2Q(-gTQ%v({hU;$cPZLy>YV?W?ZQhnzE0HP!DHDV;Xc`>Zdq
z!1}_W)KwRfp<UL89<DjHKkjyfGt6AKxMkIsBPDh+zXfA2?*`3ue$o{c-B6;b6J7V@
z+<JQz<ID1yi$Ws>Co2EWdLGU*qd=xrm0kMdu?OWk*A(~s56Q5tGVYtZuDL}zSA89O
zzC=I6E6xguc^|<AqFpraY*&>pM~?nHyP)b@3p4wI4Sdafr%orH6|eiAB)UmSseSsi
zNyiN5_CGwy>YuQdmHQ2I)WW`_?JCvNzHMuG9?Q;Yu9fsUODH}0$Kux#3*Veye&^)W
z+Vv%}&Mr?n9zFVVZoRCvLt@}tYpLs34($3`_xy&>ThLy$HFwN*9;q<gv-OSde<#xb
z#w{+t9r<6L<`4@$pmp8xP-oYTT{B#`nTrix{QZ8|V*l-*e@btZ^swo4dCc(ev$L3|
zF1js${avx-?7xOKzxf^f{2r%^2y%uySMerZoi<hHeo4V1AJsa>)w^HjOIWmS{=vRJ
zxWDe#MNiip*$U+y{D)7jD{fg8C%JdV*U2|kj;(s#($ONG{D<$z-Cd4>f^W1}-o5_z
z&P(&2R~HV}^9Tz5G)v}5mnl};Y&Y}hxxMWDb<-Zq@4fo-#(LB5Ss9t!Gu~Qx?6?rW
zb8D&ka>;(CFZbWDubeo!!(~$H=?BgHiUKR{J}-aw#=Iuzd6M8n`EN(J>08u2a_BnU
z^_N?2LOa(@=QUp?PFirquye9Ub*}BLndECz{Gt5A>GFzWkAHrS2Q_Cv)fS6u*tGq=
z6|ci??Ein<e*X>$FRz8c?rTqUb^Mvo^Gxzd>5Id`-19%_uef-*Tryem&`X;$F{@(Q
zIZL&YvJYBM-rZmv`<x?m``i-g>tA*sE9DWKxWLQv<96})cQ}_Wwg30i)iogOm3eoN
zqPEhf+Pj-~Z{ELZ66<QQAL3VDyxe{1zkT(0S-H@e-|PR>s@V!~w5SL;X)J8LXYIkg
zNF&z4<>0wr8tZaPW4YJu?q2Zd*4?XL1H)=u-t1D^73T6K-8q0oN8wVnr;~^EetWi-
z37#G^Ex*s4dH(gT9VXvr7N1jBO!;J6{@G#6U%vM<_#TyMCHbfF*>3!y{%iTu%MW@E
z{>gqaxkAU*NqFJ~VM$J1<A)CzZ)|^mW&Qol$9EfqR8>9L+}Xjh_@Hdthm*IS=G@qM
z@b-e%d4AVsC+<17JI7r1$k~v}kQ6hy(}$g3ynYg#wKha--d7z#Ia_YQi5El#84tHP
ze$Sg){dZO9hrMQA0)ihk4+$SM4%c52xYzBt^mc~dy{<*GIkcPVKkTuR)?V~zjZ$F@
zXU3xC{Boxc?{~L#UVN+9?{AXeM1c!?t-rjA+<9Fu{@vYm?k+B;ynKD0&Ri`%?H$KY
zP7MRGld(Bfn;6etUEQGd=hK<R3t9CUZs{Luw`Tv_`cih;>^?=MM=RQR_hwJbxgGZL
zb&j;zU#^+D3Rbr!W+*8+F0J$`X0ZG5jyb=X_X&e%hLC*1L5H>vChr3~LnROOcikwe
zX#1?cVE0Rzyb`x=;|i7Ef;wwsl#~)Rba}hH{qA0l3SqG>b9j9%>V>Dvk?D<Z**@Lm
zpa1dlxA}W`Ssge7uBT{S@A&F6A#4BP)61H7Ozet?e`d(E<8%p+dDf&0EvnD=xUPK>
zwQO-mhs5O_hEJYUi5IQ%$eXvl!PmQ3ZF+}?!A6~K<K1&lE_&K+F`@jx?HSBR7XMA&
zYc=ug@jugfmo@L`oyR->4P(-p!!^uX3}uhzF0u)%DR|fZCHKzt5)nbc$6j6!djHSa
z<$mpP<L2{CS3=T@WGByleRsE+zIdOALn5PySk=|5P0L|x0sf1KRDE`riIr5g`jwHt
zk#(b?fH?owY{!~C<*OH-@JQd>?NJfAuguapPu?f6aN>4Fri^~Iua$ojj$fP@8IpAU
z(}#uImrkzuwBzQskORMpemC3%4M+BUs!*u5*z-wC#wz6BYcH<{&HRavSl)Xb{}&SU
z=<cud?|C=&vh&G&NIQA5@ln$MyXtDkqR(7g&(AC6(5&*l-t>OB%b$hyxBuNS`WTj`
zzw7Sp0G>Y_Tbxf{aMJ#?lkrFQONG2e^KJ;AT|6~)Gnegm&E$Z|j(e<s+U71-Rw|lw
zclX}b98b@q>tA2vt-4aMwDnKTjcu~q@>=IwC%%vSFSa@~ba~(Q8NPmP$1*2OS@Ltg
zQjo1`8RyM%p67q_@7v#-!DM1Q^+YJ&Z86!O%=R<+9*I@0wrngFf1hA@r-X0&O7ZCa
z_33L=7W=im)KF4dw<Sxo=2zs=^_?9JoWcqlxwxm@*jB#dlm6_4(_;A-vu>N7mh#xR
zal$nYBcna_Nnbr8TvjD~o_Drn=Q`u+;%{>KIh<F_#ZLN8yJ23m?4>~7!o01?&kFlk
z&1dyJbUQ!qZ~Yg)*SS`09Ua+AmsEr+t;>kmn0xqO^MzHZN3UyXHlCgRaCYd19LbvP
z$Ex2RZvQ*mQlP6V;eOqXAKYvHiEYdKyiHXlBW`WSoT#}!thVG_>3VKo`LE(J;{wK2
zQ42&5N1m*YOt<QgesP;I!LBgOa6Lokvc)^jzTfq)?{!sNI>_GDveAtdZ*O(Ai^|(@
z^j_NIdiUhFcVETU$=9*muYWJQEG9%`$C<{o+xHgLU0#2$sqDMl2N#FCR#HVeN>5LF
zoliPFPq$|4Lv2uod!(Ck_)mI!>cwuxKa=@69+k8I4-n)wm|`DkaIJ)Ad*<{jeMghy
z6tt91fztBz?!Iq)lK1xPe02Toeg53rRsZ)dVX6DYY4?l6?*F0NkE0?aeys7^ocsRy
z-_Peal+FEK?Bmm-v3GAr2mfI!-selt$0dDVc=ui#(;n6w*~u$o7Rm)a`513!CVOOy
zLH#_&Gpcu+wl<jA**f~T@XVk0Uvh4+)$BecB_R_puLnz~@7=pfRML>?+xzDH{mpx9
z(l^aLv1yO%cfn?9vkIFFi!8sqe0=wmyUP=o)#huLeed0SLjTNnvj_*VfZHir;U_ld
zZrai5yR3PJ$T!zD>3ZEcGg7SDZ`&CBaa{MNZ0So0B_+r7&uJCKoinT5-JJGT-FtY7
zbL-y!Yv(e2EWEeKRO{65=TCmF+{VkwdhfrS-J83~X8Qa^egD2+P`t5O-GH_HZInTt
z%#ou%|KCy)y7R93vE91rSGOMXUUXnTR5v-`^rM-R><jk2lu>If7qssGH|?y^p}(&S
zCO!0R-&}I(cEqeLDoR1R`G1b@=Jivkw7Iu7Hz=s@{oPqJByRj%R$1x(eTnTZ{kQ94
z?=@{-W>wa(?^auki(k@hv-E#od8Vz4soJwq?!u`EmF*jHyD$G>KJCM9s9Ljn%FT*3
z760VTOz&*f-*TmQ<>^)2;g^^A311F$acR1CE%(DQ>3{q4f`m-+-rSwMHPN~JjON|_
z^4oI0esjpb8MOE4ilCr`HxmETg(p7PUU@#vD*kq7?atqQ=GzYJz7SmT`;?uJe_C-@
z>?!BqA9`;}*rrDptb8ev_xZ;Ob%`4(3&26Dt9Wqt*&h3CM?HPNehcA~;E3JrP-S&x
z?dw>VQ@lyZimH-PX->!cE+|MU+1yh+A-eWT&7vj0E_@P+=I`{VSS1|aKIMo=-0weE
zANR6<cqc1;?{Js2;90eM53?^j`f!||cf<0^W}7wc=L@_fFK6-S_g5b+;SroT0X*24
z`1PExN5i$X3qrG3JWjTrmk<!bB5iiym;4^*)w#R>T<4R27yHE1Wr@x6JH`{m?Q1_)
zIOp!+wrx!}Ek5ISdzq<u;eir?<vX8PuG?&*JcFCZaPDE>NslN0Jb%P|rR-YO`z|hj
z6b%Kht!aGp=+xeOn-+Kqzqrr;>-+b2*3!blH+mYMe5`1<-=6pM?b5Fmdz}0I|5QbY
zmAvPBdwb?-O{Ig09_@;MejjFi@=ShiM|{KfNt~D1YwLneCkv+jpT6Cfy)f#B?d~7a
zYu9q@V~sJGe8N_&zp{}tS8Yb0qLNV1z1s7;`Ey)#PFqjemL2Y~=CzMra97uZ>G6A_
z1&$tZaJzir{~XsN^>KgygdRI9TfOHX(=FzQdws(jW1Xu1o#<cIY@zw4Drs$w-0?+w
zU&`be?LA!b@5cAE%Z4s4PJV@kId@+Co{{R<EjD2;Z)EP?VsGcU$C<yrt`=YJ<;&ZD
zKGNmS^4!PU{%rZH9`<+BtBPd4dz?)VubY<pv>aEu`cGef2H&G4AAY@_=Pl1|r+CNi
zJ(tP4yE8(?*DZ^Su?3|*r*jjPH$1qX`n=i9qp6X3Z}gLn4v(j@C#)TwXIpQ~{J!jQ
zZ>GbpjUIUkx6PP$bo%?S7j_*lVNj1O;MYp<u6)!}zp_D8kaNNeiTB?OkGr@zt&cOv
zo5K|$IPujA>G<jH`t@r{9)~@cFwr6}F;c92Cf~y)A0+*3rgw_Pq+7MkKJ&t$`E}Jx
zZzUxmk9Pj*@aJbwG#I;8{m*_`xT?cr>(;C*UGvNT#8gFmR8*L0@OqK<QcYO7EPUv3
z?iYEN$lpKtGE%L&qD|IZosh5ptM6CgS6_EQLC(zI-w*Gry$}<9qNC%-*?G>@FA99C
z%ii2C++!%3k)<<9dd+6xmnWWz%;FQuc=&P6BL?F@#^_VchvkD9wUr(<9B~odprrI~
z+LQ@L?(6T_U-FpmP;Eq^^ta-TF9rNK{?5CxQzha9^SyLqrk*^@S>ea_XMrk&jt-Ar
zpB>dU`t{#FeQb+Z!2Ix1==0Nl)_q}T9xZsO&?xe$ey`jQWvztzVDn{q{QUJtN_aq1
zj1#4*UrcIW8UDJ()$8*|y)PpBf@~@m?&k~0(0^kx|Jalb0v$%OM|I_7KT0$kvCZsL
zR8mq>3QFcI<W#xp`RJ>Doc+BS%qmP5mjy|tUF^=8_iX>d+tSjPY&XtxN@M=Gta!)K
z3(K5m-b>sCDhrg9l<JB<Ug$pgZcgo<gKTwnzwUn!dA@PS&5{lWuDg~Si!(ASBbuuc
z8CQsgc3%~*^WJ<U4b&{_=;-)y^}Kc6vddd#Pg+kZ-(x82VJvoXi_`9wZGR@t_hsj7
zneevrYsHLSt{eC7Tzg*z3PB|$p-E9owmo>pS+8|>2dhPnN}se#rB0rytWto}X7z7+
zx1z;Xb39bqt98pf<9zt#{c2iHrh7X&IyzdGH7#P=6?=cG>Fnz=`D=Jn1XqQgUnz3?
z!bItx_euonxlbycZ?fjRcz*3F9UVEDZxgs8Ktaiwd2!-Jo2sA55!X0Hv-vh$j!?O*
zWK*#Fr9h)VRqH*OUCD-^3U$YZ$E`ehRyUyG-yl81bi!x$x$(OSjRP`N`U=f_lH_82
zo`2XrK|4v8zg{thooCLHx}4f)JiAUq^avimW1VcrD<mb8ufb*}*_}Kq_2!*KtCsz(
zVW5iTfX8LSJ4yE*?DkwYH3yP5I+7;|P1;fXD&EWd9pg9Y&c|$vXL`$DR{W#6q$`5^
zU(u`Z*7kqBzl#%(bNe0_0C}eH&eFsBOY>jvTPj`8=+$$?@Z6@ImrK~{x#lXB$tiD;
z%&}^dcBxXT%=mG5sruG#aIkUqKYh4y=6{X7J6;MV%--mc7Ri&Y=j?O*!}JN7NzR39
z%1h6_GV4CKaxT;k!)3{C?&~BfU0)ts+w%6_MzMv#`mJu^cVjl`R@^S(G56^7PrR%8
zdZlzUxEU=dD7ctU&d%fZ>RTIX|9^YjTiUSgn37~_G|w~snhYy<-&Pm@HLTlboO>Wv
zFKyw@x(4JZjsW#_e4EwhUtz2ic<<z&cw*Det0ipp9RKFs*!?0sQpa5OFz>FVWsm>I
zez26&R+;Au($sM!qBGWM{_LvHNB!ev@_U%97zLLF%}l<{^F+<gZ0=&UrhT_Kmu|dk
znwa?UyW;oN4WghRvur&6>BIN#clvu@WGW`^J~27<qx)saEUg{d^LD@NJz8+t@J>S1
z?@XQ(5(&^)dHp5(a{tM{YSZ)XusxCPOujYq%);d_1xy96xULBml1ko{y{fDv_ZiO~
zSj1nSRetd9m9CYgdk%sle#+B_X_qCllq$M!RF*KFGm$;aoA>Us`lVM(pgHwX)JxBo
zcMQJqFO~i-|5v!~Sb_OmpY|2&7U(9e70Oc<5nHxu;h7^o>s}W2LNn;P^20NvGp1cy
zQ}S4C&)!WBkA9l+LH)AgDs7AI8`T-@M<qbsc(<VPh|4ihJ*1?h^r))vV&R{+dn}hq
ze{Pg@dnA#1*ySClPPr;L#dXc{8POb<-u%0=J23y)R!MN<wWGu1!i+olMzzu3b?@$A
zecyHT;nBw%cU&y#c*U{L=|kSE+Xa0uCGrZ+FR1p`7u5rmI7*_Mbh<4s`$dUtmAH|k
z(idnp=d`Vf>D<Mun$~rEol>AHkZIMP`8c|FdHv;o%aXy7$THXQEn8t(|7LIVcT7dS
zM+`MD1s}P(%sC{qp!D(C<@-WU=sV<I4)p2z;_~S%>*^C;Cyl`Cj$KqV*52OL*LS^S
z!HOL(Dw1Ot^ltQ6_T<)4lc#ClX7B|?9=s|XePn7&B_nr1<?_>^2f9GkU2&Mb#Vp3=
z%cD!Z?0x?@^|y9BFuJU`N~xkMDP1`G=tjnj4682Bt&6iiA3kb7Y1V`+(0qPJheyEe
z$^`Yb>vB#mJlx)AevJ7o=Q6L8@?|&LGmqtb@?~Gy^WbG?Z!%kA+ySOLH$JODN;ajs
z2|?zq+2{AID@m4PIe#E(zo%;7XP@>JYaUeWGm!2VJs!1S>Pro^rC0ru|Ek&x$jjzK
zt@Ai>^8CWHp=)n$%fJ2cSjGb3gIAtD=YRd?@RnpV)n(0dybAtoJz_Y`KtF*o?`7?3
zNXaH>ze+ZGwte6Joh8YP8xDKOOui*>TH~^!ma;}y1ot}gxd*qTmCh~<eBSK?DLptX
zr>DldeV+1csq}UxSG#z*O*-AuKItoXzKd`CEWz=`RQB+en|t3YSQ*`d6loJD2+K;I
zJuCb#WY<QC8%ZjCp3FOM|J^$Mb$7(-mTaGNgSDl9ulc++xe8NmntX!imRVl(u0r*K
zBOWrzHjV-HJ9l^N?dH*Oo86aqYi{j7rzPr_V9G@wc0RaPoTq&^<FRa*j9ZSx@x3O7
za~CVE(@V0I`^Vm4F!%71zLT;uFVr<b^MPW1(f^YrdDnK9Jl1=#VWPz{mnyEAnN}{Y
zccPD+Q$M$D=ZzAc%m1$B^U0mwTki`_qYDouSMI32^kx(Lp|$4M9vM9oPPcNeyb~=e
zYQXDZBzt(tJl^V}wAaSa;*V20xw?00`RaR1rN1*&x;>h4sljR448B0Q>tY+H9i6(&
zc*eKwb;TQWpqYQ-2BYdvvZ>OCbCxD?r_DSUAXhH7u~>qq1Z48Q%v#B7MKhpoPkjDG
zZ~5i@x&JTq{%(*_F7$a>RI)qxdSR+ycIA#!C2W`T-kaVoVF49d6E~Dz-eEs2muK_6
zi2k?dcAcqpeG{AFP?5j-vh7yun`<}092>oOSN|gSwEj!I><!Ltk0c&mds`M0exyog
z9mAoj;48PQ?ycLo0UQi%e+&PdO_e^p+T83?@R9dE?G`h4Yc2hGB(n97m&AInJC-|*
z<Inzx0-fa7(b18(E%)-*UwUhPrG~y_j&x|6=%Myz8~^2&n@?u*74__{O5&dBAtAnj
zVf&XIp^zfIgF9l{)7|D~d%pGNI>-q7v|CJE-4(&DXFT`dk~O~~dtMuygG9Ta<*PY$
z&oAur{0(w+jB;U5LG;{b^OVZ;A|3t*@6&6!d+BkQ&9v%&UM?VTXzuY(AKEvXPqP(>
z+q<!OM|;^aXPL*dx=u117v7eMW#8(Rb99N{WM~qfIC+lsgBT;}v}t*F*q=ytCbuk~
z(e0aVaZJ|rP0gd68EIB+p5`TgnFZ%@fSS}UE-p`0CJIiBG5_^z6Z@eR=GWR@o>9A2
z!dKue7=6Ifq4u(&k7uWUV$}2v>mIs-oD-9KY=WeTPfo<HLj8wVq-Q^w#yT%1@JQ6O
z-D+Icxnb?AJ9~?cI`e`eQShUpnbx$K%YWZ6D&74#(r4p?pv#g6c#8v`Pf9&lzV1Yl
z!`c;5IeWf{Ps(cldd>+POY63qr|X|hGgDQ!e_pYewS+0jXKB$iS;y*i>Afd;j#Vce
zu611QeLHRyQy9oKDjZkV$Ih2@PMeaqg>&`22y>keDcdUM_|FMFk#?xWE@z4QBze6*
z6PJ1V`hu6P2~PC7v7wkbcU_imVBy7&Zu}QmJ4~jY3aox}c!}}snqbB=-;RhGO*GI=
zU{u>WV+quf4io>(b3g7q_BNl!VBLGfP_eV(*i4>;Egf5R(q`=0pLzY;o^z0NE4Xse
z>*IF<wiUA9OETk$FuUw~?|zJ+_4JY)KjX6c!<#N|etB)lY-oN6a<w(8Hdu0a!lmBU
z19HlRJ}1)jUM|baTi5aR+aWiJ-TM>wzc1>2$pH?SAm9D=r;oq?eEWmm7m;5!2P)O_
z^IB4k&tBQ<n;p4bb$R;SJZSYDa(TtO#V2xRMD8+_zmc!f_gH7gi7R{0ifk;u$e)q?
z<epwZ>h9GaB94`t3xQ&3V%Db!xw`USqN)5j#dh6_YiBz93!9q-c~<Id7H;(Q>hMaa
z`o7`s7jW!59aBB5ztAsc?xkK!_x~-7{w*_io%^X&X13AHr|8c<Jww}KtJ24>XF(d|
zN~R&|>-a9S{hXn?^YBj{wHs#7KQS2k-M{`*$!yw2heeOSmojp9Yghg2hla=__04Xv
zy{VB)rN1+=x;?U3Yxi@`(=WcV`bldI<h*Q@a#?bvx0=d2gQDK$&yv!p?6z{LxLp_7
z$|O4<TW~*rZJpkIW9Jgan|=2#yRLgvG!+_nkJ7{EJ$(HA&s>Mj$ANRwi`hPBym+EJ
z_g$y$bc4InX2yz>jc?6QgofXbn~`_VFDi|CeW|y#qFuCopGU%`$>t@X*gjYKsV?u+
z?y~TVXjyRB38X}dO;3%F`*xu0`Q{l3H+>4f)b-uXl$$y2Y=7U~^R7uYhB>?5gim^{
zG8?o;Oi4+Jal`Wqa<gKl`PC)Xy<~pdaLY}}^5iz#lp<#7IXh++$2OY<%kG|j+9$^-
z5K^vqaCm!pB*nZhOyzGmUS=(J^c=5d*_w{6GIHu~)uxy2Jp)a7oEyA1*Z#S;U;O=_
z8v^N(3&W1wb9G;^SNVI<%xzn58*RAi0L}0!2iUgD`-D}6y>yd)?{#$HdhYKR&UH##
z1|6xAS##>{vrB7EpUSJ#0jD~}mx~sPPtU#6x_t(3=~17eM`nE@8_mwu8085kA2nF}
z+XQOn5k=#+GYV!}+e(rd3l4b5xJO!S_9}ePePibrrYP1wc6ud#$1I~Rc!DBMrDw|S
z1HlzMnt6w1cCr0ZW7JQwg-W>`>Nw9jkMF_TiM)k!{tsU7KOnZzY#OgHa~1#etmxgk
z%+cA7>fnGcD302FIb-s*WhIMy%ky$NHb0EXVcMk;kN~oh)rhHzfBLM8znm@$f^2j-
z!f<-ij)V_iHnAT{Zd}gu?4t1mbB+wb*Bd3|PrTke_4qe~t+zv9UYWqn7VprazNjR5
zhR%m48$TFo-sr#1|Kw<{g!GBmyF<&Gb1uDJ4w^dvg;1Nxy8AN}W!t9M3b1k8+%ywr
zs{DIEbYuBt&J#R0zQ(?3;<Ibx12x1tJR&|?F8RR_@S;Lw`PN5rw^(02YSd2hK2)qx
zD7%_3c~_4iG+pz|zL3sT`uO#<ye*A)-5y!2wkUA!Vh%eJ#Zo4-CEEAg44)dGJ<tr3
z6cJM*BmC=!M5HvE>l)Dml^Yv1lb&DTc_A_(d-omISkoyH-~iZD!>4J-^TbN-Xr$TQ
zowJ`c?kGv<ittZR|FkRg^owa<vag<pR!)VTjgibJb6zB`Tww5`_h?#)f}ZpQC9{}z
zq51cJG3jV8`27pqu=EhvsMDR<d``bQfj{6;g^YV-S;8x)|Kc0#RYhOC{{DK`oY17g
zxbL5#^^)Lp%lrxbRtq}{ZWxy_luv&2zWdkyj^2bEhjp)u_P+kI%r%P}76GYIW;vec
zr`evC<M^w1RB%ecw*C6Az9(JY^he%E!Y9x6C^W?vuJrt?Ha+)F|8{q?mdGFVack<;
z3(l#Z(@HTH2&+C*(Pi_;s93o7wYeFj0qqi#@%rA{l$d)hLcf=EZt!gkQJy$wQnvgu
z#?2?cUuXS$TR8fNz@aq_tQNW-O`t8>pmke*Wq!%Oz5h+4?YZ>A2;E1LPtJ4y+S>8;
zz|4Pp;x^2<<LBH7E*h64P5$*;B4`e?OrcHJVjI<eYlZ(t9l2$u{I_y%f<UOq(Uy0K
zJ9XEA(?ZC>C3TZKdOCEf6^>LV=i0BI{baw=H@RDkc4Z%VbCsof6f_l2!Xjkn6RVRv
zFAbKwY1|8P0r#_ur{cvw#|uV_%yaHk-}>E9#Q_}0N7_&Rt@Uv|!^~$bcQmtZwfNt#
zBT->LL^p11-PrTe>=@KMPNBzD{mNEGyWTVkyzkxm$3p*_z3Ut1D~vTdTSaee3f{C*
zIQ%$V?bocU$r;BNrt-J^*b|}Smu$B6Z=vRYk&W$=j6W*o2;4fhO)}l83G6ABnH%@k
zToL>UDl^wfJo*s0H+*h<*NuWZQR<HhSkg-^p)E#1PNU?iKE*@Af!`cD_%*-%$mGg8
z+Z`c&y6y7c392i2*4R&YVs#SQTk@FT>FWdP@Pk}1A?fxrp8A;O&s^W^O<~M5?H7tU
zw(VL#5~xHFTsd#!-r6g|?hP@=7h7l^mXCgWWlx80T1D@A!IU+J#gcdT!zzxZD?jc%
z-l((sP2=Bl>4j6yZkQFPv}u|6h82|^377Yll^aQ=%;-~mv_m&~+lQ;+@f-8*TJ_0T
z9$M(!-qF*eVrn|Ir-x@(>1(&iYQ8?lMFa%}3-_jJo_%p=i?O!(I-S}C{R=ldRNNyB
z&a@rRD(amjx^Z(Si{I*trcD=agh_enJbZrt|3C9?G2KVg<LeS1AM1Vc<jIekST{Ge
z#qRxSx3*+{d3X2r!zrNB<zRBo`@+=j8;9NhADQX#q$APBpJlSfx_7KuW^;Ck**5Mn
z-Q~7Hv!U>A$Pup}mhbm`esN``@a=86+S?mgZ*0jF=C}PKQ2Xmk;)Ml{I`RAN9E2J=
zXMN>HfmhC5uRjXMW)(Hg65UuQab6}Tsw!&I)Oo2^Z5@wo<oN4<-@YHQHA__4y>HDG
z%hS_zlOG&tjH&&4^~uxLZ^zO>&I`S2xL8>?D0+(RhVwsl`aWIBiCrosy78ffd|Alm
zz-7uE5*tfjhw1HnA{4bH<6w0D-q4qyb8bItWS3izeSKZc->=sheKbIu$!pHNd6xY8
zip+uoA2s?`X39qXRVp+4c;m;7I~pyb2WQHL9Pz4{WnXVM+bs9diHXWrt?K{&`pP3^
z(xK`-?T6*ej*bqG4_1f61-TdAleV7l^XmMs(SMc9rZqbFY(3BKw6!SPP$PT7O9>@6
zpZRukWv$DuypXcAwCs^IZsWK6aln2dDE~CwnZW1V(ch_Gt+1v0Mnqr8e&;Q>T-O}u
z+Q0C~;md8p!lGfNyEz#C|9Niz^4?zS)nRK_ecZ~$%{|j3Q^@|`kHzwnIy*W#Shn9-
z5z$s65%leV;(`+&E&5h^+D5)ry0%Rs>TYp!5a*nW%jT@Bn<((@#o~UW;%7cw+}wZ5
z&c^O8ySO@B|JnKZ=kM*U{#zC+C@45Fp~Nj*zO;>3ro^Tz`Hj?>?yajzujOP#7rt4%
z?DrYA$;=x*&Wb;gF(J{avm^Ol&1c_pR<Ct(Zu8x+O-f37aeu%4&6_uQWUZ#Gi`^|G
zDk{3+H^_ZE&Mvz<JHu>q=1pc^2KjFB_711p&bE09+gGWFt?$^|eOb5rl)k?dla+Ys
zv)8l3=lyC`QcOBMO}FIbrPjN<%dM;K-?$O6tNgv+`+IvO4H6g@yZ5UpDIL1V14<8m
zuRr|$w&v!ZWhKcX7g}G1<*rMgZqQ@@DK7N<>T3l_{YMYHnj?P3ZR?d)M}*?m?faE=
zoI9f7&!3uU`tj%f{QN9wUuX08_xI})l0lnHD($x4(q#E0)Bi}u|Ldz$S)v=w62p!>
zJAA?~eTJXnqZ$16e<p~>*IX>&VX*uC##nFn8zV>s!nEqn+Olufvk!ZQnZ7=?N_-=~
z0P~ks=gu~T9(u@9wfz-nhBW!#m*w^|`x;Usw`5*!dwF@eapEDC%Y~qHz_hCV_P;BA
zYh%A1V0^yWVuk+Z&ULRmL*r*?&X;q@nR=c($yu6TRm+L{tVcz}wj9aR)Ah}Z-XA&Q
za?a+n&#@lK!y6J0dw6*nO#-!2kAMbWdCo|kn6!TS6uSw{<q?G$)096RxybsXKGbsM
zE7u%OX6MqRjs8asOpM=bJ2KV4to~ok@%NSq2N?AB|0z=Qo8ys_6Je_?EGQ`W^X!Gb
z!>7bHK6u-k`=CN*InR<V*PN;C!qE@6t+?zcaV^kwO-p<3?QI|D|NnD*<L|F;ZcgU6
z`_YhkdYWPGEl7nXbgivi>fLV#4t~vbezlQXmCDTI7Q~0<3!Ra=*s<nV<g(-ri$^Eb
z=P%i?!QjDnPamHrGt=ii+<e~d@s`Ufh5tBUYXSVYfBXdnR+HoMWph1zeRQiIFeF&Z
z9hWp??!Pv3YS>mKvuS+}NmI{p79F0=cYM>K%s*RNv~O>#{Pl7<bKQI~-KY;o#p4U^
zRX%@te_BUJ#|ciI(@7q`6;t^|1W!f3y|UaacXg3dXuB}~ibt=TqZxT}S1&vwBp0?O
z;vm2MAAt+iCK(qR%J0`sKXc|x!##Hw7Z;TX-nSuse+w_%l<Cu2b!)<-Ri(G9UIcG7
zaeSx1^VZ->374R|PQ(U<2j6%6|Mxrd+M37%@0CGi&zeovslV+64!N#5zR2tM%&?Um
zTi<@TCBMx#MtYV>Mv_&V$APEMpKs2%xTxWtva)h>@p)VG1>ZrV(VS(zlV?x5dExkq
zt<Daej|*iIZ#QZsy;l~@2)*jyc)Bgo*K|sR)BW}P|DC$AG5O~H`g(`=#wjNR&NhMu
zW>>a6l&xJ86vG5+l}U<4y1zc_wX#OAy5*jLoAr@rhZk&%G7WXQ-f#c!#G1&>8FzP?
zdQaEm{qgtJwYAb8szEhwOH<=pwx4zayQ1Glh+NpaNxyH+q13}!8iwo%4!1u<9rrqP
z__%!i8D@T)1K#?3T?z{~CV&6?VsXFB?&+Ws(?B{TPEh*L=cLBC1G}eICN8Z`(mk}g
z<804Km9=%VUP>s{6+Ss3`0soD|LN!ES{oNUa1hgvdy~P)y`ku-ms#GO7cXo<4WFjK
zsvs-h$+M@~PG~OQJy#%PYSm^fZtJgW+@?K9Ieef;YwahUM_#+j-#<HF|IgTWw%OA~
z-Fit^SB1KL-t*~{w%dDsP%P-MrA-a)mnkx9Z`RtoBlv084NDW|pw*IUKb{<HFw;s>
z-C_IZ!{IGiSG#WK?*|p(Gy0ehMCb2K1vfrC0we_LTyvD)Ee(o39I~#1cl*x`?OGL|
z6dx6}^T{S%TN4>m`E)8{eBq8&pt8ct%c&%{0@P}-=Q=zuLSt1-e$LXa2>%(P8&`&D
zt(9s$pXVfG6<7ba)T-pgfo6WY4682x-{0S--`!OTX_xGXyL~LzbLH%yZw_(~-ds}a
z`xsIb2QtI@&a=a2f%<D$rt?ah8Dw42aO;;lyUcgC&+(NP%<tDEgPq&)I&zxpezU))
z<TiZN`ykSkvtM-M=8p__v!paKo*Zttrj?{xp%by8!EdhB$7i$iXY~bX-rkmLEb9nL
z=NeP2_03$mBNp7g_-nJ%a=oO*nVeU?xi4BUVe#KYRg0XPn_4F-yBpR1Dk&;zdai!+
z+uPf|?%?Fg_4Hgf@7=#i!X3+hu8b>rrF6|%eE$(np~9bqB{{b)mhepE+WX~_cgdR@
z6PJ2VpVb$X+S=N>Oc|8aSX%YY?iLW24gcn#C$K9!b>60bYkb0U)BmS%^4*m#Q3ox<
z;1QhP)z!7*<+9l`EDDu=e|u{zyFBXA<Hs=D0|f(1@}4c0(LT8QKrqLr8_U<(`$rzR
z6(;fZh?v9rw8X6fn^`96MsG97xS;Ut+}!Tm+sht@L?<OJf^^~?7niRtDx1rBac!Aa
zaD7->>7x&tN&JrIr)eb}tqofr=exh|Z^Xu=)|VQl*Y?#`gL{54FAuWIr`+0-DPtwF
z=xS$(_s*}LE9z$7Fx5@^?`AaN*?OCG)0y{1t?UpjkKB~P`S<tt^1s(Cr(WH-_}QH9
zj*dAw@9yk8Gt0EQm0SGMVt4+xtM&G4ZnrymaQ9um7nz4_O;)^M6&2q&vE*yE%yjQ>
zDwl1ZPU%kUw0QRO`TX=VGYl0!yKD<x9kygSq`R2pQdegOYWHnEZ>N2AU-EIjyxniN
z-M5R|UuXOG_xI<M{p|{^7VQW~%TnVNs<~3)dO+~_V~fQ*9#w7>72l|uXfkC7OO?4^
z`ktK~jND>639qiKRNOl2eTSg34=92S7p+*)vH6@;w`TCN3(NiG-TGushR4^kR^0#0
z&Bf)lx9<Er+a3u+r`9zIkz%&d-@eouT)(Nqw`v35+6^6FD-LC(KC(I6F8V!UPlcg)
zY>D8}qequ5{&Dri#l_$lG<?*^F8APW`Tf6dA20Quera!Y`KC>qc0BI0u9-J^_UzLu
z0vAW@ELs|Dcywvi)a^Th`!-w7DOx34q@|Pew%}Fg+15C%q@%3&>VD@g^PMeL#F~?p
zrFFQC*BI36JyPi2C-d;#?)Tp+bKc(C`sCTP`*XL||F3iFkvRDMe!cvP3L%zLbH$|>
z*={V`TAd`Xz}9`O&i_f+&I`($+h2+ZJ-fCp_VkmJlTY(#a<K+4^HEe%It1>*9N+ul
z5O>b~eS2>`e}8Lhx1h4yhTPj`_RA(E1U)QxB;>x>VyW)tPQCXDKV5U=);6ASP$^ox
zY@@HImxqz8^PwB}_Et;UR+;?%{@z?xRpFfN_ZV=p>WSD>QP{hFW98>GHUD`sLD{Ju
zPfa~C9452*o|4<pc)0I)p_52q%Czzgf0V8{?`}9!xLE1MC5;+4zwX~6qN0YGmsIM0
zJY>Hd$fRU!JUMQ!Nld(p%OU^5!orn1H<)hBxoMQQ>!sTM81E+k=gXe@2=iX7+!*on
z`r@bJ8_gmaIUl?2ys&d;SA^m7S=sA8-j<#t?K{^>^z<fhSG(}etE;O|p8Oa;)v*3w
z&HgWMygs}PirXu+=yTG-KUG`qC|wIa=&7i_y-8hKiSgT&VE>O7ocU+=2^s_j2F8@#
zOa+&35`~}UZTMI4@u>Lb#KUa+<HPT)4W9A!NLWb!wCE$ZS}qnmy2CXur-S8!`uv(h
zXJ#7v9_Lt5e9p4{%a;;x8?1-ph~4^jKG{c)y7iB3%iSLzeP{KZDph%owZ6Ix8{V$s
zQ?HxHu^@B-(@tO6-F#;!&7Rq(n3#5XnQxD@d7rX--;6$?fX!)VjX)*dkr@uTy`TU6
ze*gJ|azD$HTaWx^uAF(LbM@oj2^o6tu6)agjcR+Z^v&I<afX9hQE$?VS=T~8e?1cT
z``g>(D=Pxu+}U}#WJ<%SbLW<ozb`U-E+#0*$-MvHuj~Ws{<hoyX_T-3W0-JVynLfh
zcb~8IFS{AfbHv(@d=mDpmHiNVr0P(HUCz8Vq3+F}K7F$I{buveZ@2S(-8oluba1@e
z`#lcgTTLAuo)^ro_w2FJ+yCcNLu~w=<=&f%UQN58lXUP??DSuHN!k(TES@}ZTAmhl
z#dFTY>C=zDxVSiSU(L>!8jR&PQ>S0tm~83K?dsxk=)g4HXbnwG&KI`#s^8m+=|+iM
zsP3qq61}}8Pw@3-y|0l++OD2D(!MbGvfr{`4+)Ec2Mo&YeLOGMmh`O*UoTgFr?4G7
zH01X7-rn02f5(*HEtRn<IWe)iGjguBR+4kU-1VPc1<iL|lY7x@L*bpnlb<ileZ1jk
z$<YaCXPX;Wd`Ot48=Yp=r7TzZL~zpN$>3=g!&57-HgC_ld1!9=y_YBU9$8cN@@>uf
zr@>9-Qy&Q=hcE3ox-8Y<@{U$s$*o2!M1xP42yrH!p02;#y<cuk%+5<CBJMGTM@4;R
z8iAHT2?{>8nO9W4`OEJ8|Np*U6TSW1#^0TiTa&XV&kH$st#zU0k{ju<QQzXP)x2W<
z$~5<wC|~vbv<{Z0+}n5R|NrHYG-{ExE}PN!xPwpDs^GlsckpcQBQC#pb%7BPCw$HC
zKDqJt$ecCDo}T%`b2hh3szAO|-F%vE68GUH;$jN?n=Tzr|FzyC{r9)Gb4ss8{`vQP
z|MCqRE|kc)FIlqW!zu0c0^;K7;7Lhs7k78-s{P?{m971DzfN4N?)rSoRCBqo-u0U@
zeJ7XyJn5U-9ntOMerU(R#Ej^BlX)g){rbNDzwhsFZ!15aHTQKd^l@@x`v3EM{fRR?
z^X280l$4fV+EJK%{C(x$uh-dA^xj>MuRq(&Z+GJ1;e|Kviu;^e8}IaW{juO}c3({c
z>}%?{ZDS5j=9#E<YfGkZ`utim@t6X}>hJGNWse(ja&qcKZfcRUt(pNER(_=Q_0?5n
zRn?;xtLy&#d~WmoPI2ANX}PySYA!Bz-<)w#NpIheq~0AxjYaO0#2AkDxfPyT*&X5U
zSs}VHYGy>1mc9La>-T#muUVsWui`Q9<wBXMbLO0}e!s{0|G&TBnUg|Q;rA1_-znl|
zWo5l;XK!ymUwvLh)4#vJKi{i<|M7^hf5G+GazT0d_s6FM#fq+bDcqzjQmqwy<kmx@
zIXhUSj+!ruTl*p6u-BjS+j8UTex}~qnteQX`(3xVxC}kc@Of+2=-B=J5?uBDT`oBA
zvu8$Z{QrD@{j-h7<yL>H++FrI>D`^3JyND!ckaZ1>X3K)e&-#pp1d^4lhbp_72W6W
zRan|Zey{RBtur(2Y%2GJXC6wEKP9X%o$~+QzjZHFgi?x%iYmU{Ot1WKkR6<dj~gaE
zI?`$L@rdx1wa|qe;o4eSNf#D4u8G)q=;CiRb@k7W`|X34`_1KwPrq#@U-N<S|M&X;
z><3uIV-7ShGSBJIFg19x?O@H0XNNbjUuq~Sd%&5r|AzUcH%Hn|1hqdGc3143<CAhG
zG2?cSbLY}eb-!M!%hmlzoLBS7lTXGX!KzQt)6?@#`Tg2C_5Xf?7ZmNdwXywP{+^F)
zudlB!|MPEm+1p3&cE5ji&icJh@tP$|TA+R2iM`V1Mnz9No}HcTo|H6muFsLBn=Wmx
z5#PAb(qIE8zrbOgKACKd*dt;Wm{#Y!&+$0be#Y(L=GhZM`g3pZ`FzgW=EsBPJwKn#
zo-$?1jJ}kX<Bt<>ZOOb-eBM??U41s_aJ@%Ss;a6s-)<z|DLSqD=JxjU8Pk5h+ug6d
zZby?_@1EKaS65e?pHC)(a^#oS*ZaNo_fCo1TP1l`<Lc!_iI&C=&INut4;0&%9mw}@
z_7dOt&`4hFfkDc$w)4xiLxTeX4jgLb-ueAr_0M;^-}@Xl)Uvjoz5Cs+?!3FZW`dJ*
z7Aq@jOu<1`ov1A*N<<inii^QxTQ@c;=ic7-bY}WIMP=pY`oFK^zr4JByu@Z@W6|pw
zH49koS6^T;es5;|RAl26xonwBe9mc={st;JqGDp7emw5~e0~4FscWOR&+1F|Nl8%=
zR`YrA>-GBU*DRHkl%|?wU(>lRvf=oi|Nnl2aKrb%wMV-|*F<gY%HQ|1?Zk=6-i(}L
zqSp+6I;_xD$-VgJ2)}pj^D2eI|D%<6PvE^K*!@iNtpDFAPHAbgoCj+*pG!JB%aq~B
zv160w%{%w(?Cg{0`On<wN&fEP>-#tN{?<i{l=x(=j`Yb|-`G{Uda?5i>#{c|zP!8)
z@@K}44GWXMiwX*Imc`foRQ><sxV_Ku6#;>Pf(+T$)+D~Xw6sUc^i+Y;%5`EZbvNj6
z-~JZ3S61ywS46+-WZ`;cyPqGuU#v}idRj1J%8ia6GX#F$o+{<(>6v)2iPgo;?b3=s
z<)EOT8=KSl=USD1ie8`N<HO_J&X@Y;#zxSHTG-ksK|#U5cdxm*xNhtyRF*c&NjTib
z3+k%r#O}JHAITsjEd28NdU<8{zLYB~0=HybJd}SORI93=xBI>3B}eF|$Nl!R`V>q9
zthbqImImM0Snqzb+5MCmtL<zx^*V{jUlA{x6<>EeJM0y?HS6l4>hJIN*TzIdocQ^C
z{`=`n+hTW@-6=TC+aquPZ;JQb`5IPMv#za;zPzh6n?cQIhQo5dxi|LJR`-4aWtuxB
zmwmV7-WKauzoG_OB4v^P`PtcJ$|0Vor$s$5xskdo?U!DXb3vi{?<ME1O|Gxz?Vop}
zCgWzn|AM78KY#x0k++|x>OJks3#+@k%bzcu9+&j>)zvdI3>SN`uF*ev^5mXhuU4z5
zs{XXGD}NXB?95E(y;Wbe_MCH<uXV}FS_NK&Vt?`s&pf_Ka<)|kzg~ix`KBT7_S^_~
z(`mbM^Vc8w8_o+eCT?<nGm&fB(rFu}&z^ny#l^*yk9*Bm)%LdWN`C^izkWWSZ=83>
zV!v4T-m0&Uy7l)hh~HnA+NT?}rDOH_eX~kmUo))y^rUG0$J6@z4N6`Fl)d@z@r$2}
zi_5B<FE1`GQw}-x;9zs*|G(e2t_bGH2)xL3bm4NtZy(nt^#4!WJG0GUN~cSo^`fbr
zN4LMdy}kHW=JJo{tlx*c{<C6*#=4!)q(DvQFE1}|Tyr32_nkG7#&-XHB#Y_AcuZD1
zF7H$O^=kN>%4ai=96R>uPVxDVm%R0-?smAmDs;7kO@%@9wj53mH$lOP1(%ll&tD+1
zsQPiQdC=~%+{=bX_)o1(=lYnpSvV@`hqUH#JBzp@V(ljbk{W8Z7;T)gG3~6>uWxTp
zPmiyQT>JU=x3{Oo<7*E7`T2Qe^!9c0FHcR46boMNm-_bB);opAWse-M7T5aypqby|
z?Uu_C+w)`}AM1U*`~AM;M@KsC)^99(8^y*eb)=0~nrU9Ri;K#Y*oud(%alV_RDOOY
z<tF14wIpnVLb?W@<~N!3;r*bV)TR}}2L!=Gr>#3q?0&!RbOR&vjU9!_Q_rsrUoY2h
z`%MDWECl6``W?X?{r%6k-OfwCyQ|a(+|K^->-GAV*Van++x^n``s!-($45tPe!W<{
zKlgF*qWSgzX4=*M+EDYe==kRDj*gZ|GmX=OR)^_cHaumTe5|LTS4jAIXvF!JM-!6H
zf2{g?q_gVbMd4_Uz%Y@Oohz43?(nwxa>2Pr#&S~a?{A?$@2m`7{^{@c`^7(>PM3~X
z(X_Rl+sZBe>Em(v$y2Ag#>L5n#}u+Mv+*Q6JvH^r9Lvf6_J60WS+mCI`MWziCnp|m
z`}pOuzqE&*l9G_rtLy8}|NnFT|BSxCb<5}1&4P@bew^&~RZ37Y@Z6ne0dG3D)`)DJ
zSD=~nd0}Btvdy%xRNit>QC#(MX-w(W(EYjpVk32<w>^2g{eIfRL#<1e?RwqlvA^!`
zk5{YL@A!5rd!tUbzuiwzv*g3>`+xh`c%?r4d_MoT%)62&Cj`^Z%sA+4e%Hm*^M&sc
z0YSmSLubwJ`*?YsS{eUhgQRiVhJuGqX1TYXymE@x(my2Zc-ZBB_WYJ4|2LgqvwnO%
zBG>rk*Tau1y?*w6wXyqnL^#w+-^yxMbl%R^tE<B&&z&o~pu|*MTKe?f@Apn`K5yq;
zQ)6@V=uuD|wk7B0B+#Hy<>zM~&lsPdFkwQ#vpYMBpBv@fvEY-l$xztY(cw|BI(oZa
zzum7DFC`e}6dsf8kuv2vy~*PFoZ=Ukm-8nd?_2xnaCPB&HP5GKICziFi@5FXzed*W
z_G^<&0lUlfOV_O5|8Lej+iFnEgumP~&$fC~(NnK?dp`RmB_}gaIk$hA&&)%o_4oUf
zl$bEI^UFWGSN(peYq!{%=<R)=Va&X{yQW&c-+Dc6arpYUn(ueZ{oFxCYSrW8{pr`%
zM7q6`m6q;KjRXznUyrNqHNRKU%&oVh;m8pe2GGdATaQGd%IqKUJ4<~z#5S7!x%ReZ
zkNUMkwU6bP7BXC#d_`D#-MspLm25l`2bTHH)~fAGjRcjkpgE!EH9^~@4U<^<Z9aLd
z+~(ZQSNMExxlzrJ0yaLG7oX4O+}&0B<=x%c>GNx^tz4m`q@?(G-|u(Hx3*+5?sZQ~
zQ|q_?XYuyd*2j~)^%M;aCr*#6>U{GiXI|Z}m-oLl<=)z&={wtuHR19yUmhtFjRiZ8
zSU$aG%6jfuK}WxC*_#iVNz$u3c&$}cRqs^2Uh6Z{sCCbtJzn#t&zf~=lB)L%^L)9$
zz=OMcKe>v>y1c))_w*Kdn~Dj)-|wHl{eIo;=aoBm?wnJ8uM(6tMMPSj`8x{=PIUNC
zVFMaFvwpYZ@%E%k^V|4jPfd@nJE=N7=FpXu!IghL9)EdtwYai-pNg^Z<S$<y?|;88
ze*ZkT-aXBF%1TNeetzGo<qVbg?s<4b)!{|2)c>_{U;lOgVh?<?eBMS2zaamd8<rIx
z6fQ6Gef;%${Q66kH*ekq+1JK<dZxkqB2`t@H4z(|K#{clURC$i)#2g4qd?Pe@iiY=
zK~0vIS5^vxYU8~w^?`+gx4-2ouUF`w^G7D<_OVSmLP^3MeLc$p_qrW%IXa_HQz_`w
zzdL`Q$evW*Z!rJw&fl6Fz3YD86crYAp8LZ}<%rsp{kK+z%uJ2EQ+7KSG@EsEbNc67
z+3SC%emwH#O-@|x*Q@upowF`G`|xmka-^7{;nMrfMMXt*w_O!=b=MyIF8+PRhIN_`
zBDRWaO`74WvRU&}UDR(+wnLB2FDd9G*++dAwB~!m@xu1i)lYVZJvu(`t6X}`S9NI~
z*Tsn!8TaP<*6jKhTzB_#cI*0^yE3)Q?^l>d*WC<y`P$9J&EV-K&7OHyvr?s}9c-JW
zX1n#)#;ul%UrS!KtN;D)t<LW{Nrv{%e4C4odhPr1gZtb2yYFiqc}iYfY@Fhzxn#-G
z54VihPn<nDdTDjdub0btq|JC5R;<uiHpjg6`2UX<h8Gvcu93B=nUI=2?c+`U`JZ0?
z^8cCn+yBq5=iyylr|b7*Mv7&Ay_7NU(ws8iTNihi%KzH-&U^M2vtwQV&G%PLzM~xa
z+q!)9vXj0quWkz8dOm)0CGY*eQa66yJI>X(<Ap`i;^dXm@zb|dWga<xg#F7t(~pn8
z$^Wc6e0^$FZcK?xda1qkfzCgtx8=tD_|odNe_#FVe@m|NpNs!y{_f5R_xtrn%4hF;
zy8NyE$IE^5e`NmlfAZw{oKJUFbZE>{GgsZ5s5W!u%q^LBrq$*CzPL0}T**d|Z^`%l
z;r8`Yn-*PK+-Wnd{fX7dEuPtrPi*U+YhC{A>Gb%t-{0Qq#O|5`YKz)de=GR$A(27K
zEXN}%N@{KN_GRAF^?YU+G)~nH|F!2@3#V|!vzh62(esnf&$F#iveAj#I3sH2)`&ex
zhW77&%{;0t_P^}h!9~p=@v5z_e#Ttcxa{7qU%Grx<v;x{_4V-gTAu%U-?HS8sMhSi
zA`I_pZ?ELz4^&~a-m~BL?84PgA8K!&DHFg`!#Vr^PSq9nX1Lv}w92o4T)iWGf$DWn
zHCxTOe3G&+CS088=WBg&e{Ox&@oQ$2p1TCUx1Rodntk{`?rn{KEdwH2yRR{=77y6p
z_HfmT)Wg%()W2xYn!mr~Y0$YJr%#-kAHeg5spz0xQ~9TQxefhY;!GWju3W$TDq-R!
z?U`aLbx&l?ab3OTT1oD`sdc%(CJH?NZ|=EVL`3w%rF8v`FCIUS*j1$Yv-Mx(a=W#4
zQje?q)06HOOH435aB=OvsF;g$dacc^%Jw^0{onGr^4BWXt9Jj-cmF^0#&!E|!@#Gi
zM^q=wo8q_oOWBt5FC32d^nn(D{LvMX`SM^kf6>>;Q=>aTzV!XS;)mj*+f#0+y37my
zsr2TlbbO-Ec|%5@C-&^0_&$6}*Z+J!^!<m6v-)rBN#A_`{X~K34*SjiN?dtoqV{#R
zOWI+d{r8mvCM~<39>4DW-UqhR+PT}~P8^<Y_h=UT_xm-Ud1H5#XkL!nU6z}-|8Lp4
z-S2h<@w<etjXHX2tM<%~f4)4{|Hqh7`p5Zq^ad-3?_zg<p5Cy(=-12TzfFs;t=YEb
z_O5g5ubVubv+wza7rUPO9$&FVw|e`9C!30_Ud(b_;VZE<*Q!u>^<LYJiCb1oKK^M!
zkhzUrZ2gVW0`c8^@3g*_*l8(s*{%IO;cg|1@Nd5*xsSK82~T@my<tE58{u1z`s!lh
zY%ejb>1(;Qf&0GFkKEerMt_@rAGpVp!|3;J$L5d!49+kY9r$-G?fAjDZ_eC0x%{>L
z-?ym~1t*qdUTb}G?q<(h(>}SGwoOSt3jON%`1gM`;NSaGA^Ka`zVG`sZF_h3l(V<o
zqlK#c7nQcMhR-V$73baEVO3cAr%u0cxpO=J$G^|s|E&A`eb0}V-3{BH?{l8a$MfD~
z&c?mR4Hvv^Sn%V!QktlU=!a+F`JdiwYTfhksB~TRjj(yn?fe@{o(4@@7jtU<yuCB+
z*8VPd*Ray(oxSCX`t@2Hy?<Qa{r{1}Jw~zE-+Q$Gz15A}wB*WhNl8hcxmHuP*YBBh
ztXFz^Wo=lPnEbjQ8%iE~p3hz*T=jU1QDKJX%Gph+kvF!*eoN5MOE21z$Gcl;Tix4V
zvt9=}w;pW;6?v!k#UIN(f7k1~*xi|Bw|>T$d{O$mH{aF0I)3}S3u2sMuNT|)+5faq
zms|6$<<8_)S*zK@Y!@hR;C|D4?|+c=dnLx*4Jmu<ZND+kKJZU8gDI?9;huH+m+txd
z9(2#&mvGLz*u&rJ`J#p5g+DuHnyh-h@9rM2H$q}H8ycejz4y<#yZh@E^&bb%Th~3i
zwR~OTw?(&iK6{hBGw}@XI=L*Z#^l>(tIgM@eO-3-&i7-rCcb&6t~3VEw0u;4OUUok
ziIe9ae*ABDu6F%-evkg_)Y@J5tdBn8|G%$MvN^rr?+odtRpsAO^w(50TI!#F`0S(k
z?7l;m&*wPj<ml)|ZCMbzyDTLwEi59&-PP4F>x{;_y5}tuMb!D<ov`?~KTqSz(fUP7
zi&liMma8uQHqBO|%XN*fmQ4Iy3!A!HeU%mS#dcktZeM@W^#AYbS!Z)j<(|L$>bLwv
z;i3a|^DnXHutn4!xYzZbX`5xlVb1CGjG@zc!u&U!W62hXXg(;#By;39Tjci_uY(w*
z-~4B)J{6btdEVJSl^^G4nr+q;x2;j!|E}!3!IAj#|ED_a(~B=277tt3u=T^YSL%=c
z?vZAE=`eY5{iVKbrVOtb3`2H2I&knX`_9KdZ*JMS%9MM$?wX6wl@>mn9=qS*`BKX*
zyEdtUOnkk4ow=-MjDos-yY;;N&Cm8{A1n2bjo!>;CiK4fq{<$CRq026Z<fA!9+AAq
z{&>)be>&a_rzA70mwe#(U-4Xi%iODNE5FY@eM>ic_59NtZqMJ{`#o%bx)s~ZnKMBH
zmg!$!T-=g#b5oFO`pm2S{&i}r{>`2cmRBp><@%=6cB5RkNWAR@#pfJLRM--?UJ}T^
zDBy9lqP^=@#d906hkuXhFSs;Y_5JC)$K&IEaQExh_E=ti_vp|<akjE^@mv@F{AmB?
zE%V<hwc)D#4W4i64sSf4t2LM|`tsB5XL4?Vy4`f4J+|wb?K;z7YXLM9_VZm+*~8B}
z=_B9ee{yd^-MM4sxw^S4U;SMkv86`vdhfozXtjG;C484|-`{g~=jY{9ti!oJh%G4n
zAogZ!V^m13<Q}0t&Kvj{Ee|v<&Q-s$shs=yef!>UyXu+8_5QPaa(agD@l<tr{P(HJ
zji1@+9Q+rq_+Pi0nrxrkpIaHw@IC$Q#`&A=KxO}x-~J!pY)aqx?M?R2%SWO?gV8hh
z6i#`2(lYQaS08J4#Gclu$`})aM@RkRpWIr$Zsk4Z0~vc<Gu|$)Ptr8LvgMMO#lE&f
z3m4b#c`Xze6LhBd^!(3hw!fqDET4xx-xt4nv0*CL=cF#n_pK{yW_}dSENxDIJB91&
z!QUGmNi4t5TvIbQR-ePWb;>Tyeew#e34*UTdg?vAQ9M&9=ulGbqb7y7ool=Q*JZBm
z6WWs>bo|~HzMzNpU3c5dieE0CzTv~-^onn@{&U}HQZ3c^TDtKZTQzTlZsV;4d-gZ%
z*)}(<8~H!(EBwx$Es@F{J^7EJ>ZOzKC%PSQ+jD>R@ntTz9jqT*TztIv!?~4TH%>nA
zu<7uhr>*-pJXx)3^Z9oxs5Rm6;?lqGfB&aGOP(Ga5p(WT{6+_@d*=UV*&X~=@JHO^
zL!Iw8=IW1n%SsP99}%~&ohbS`{KKEp?w8k>#q;LZO!7GMPv@g}{n@CF1G4e`Nqg+$
z{r^Z-A9{41)s^+m*H5uJQTsYvuiN_fpOI@kFXDSNe)fad?QeGk*Y@fCI9mPqTyM<B
zAMYz(zuvy8EJ=5d{q9!}WqBXz%kAN}cw`YLA^Nb^VEggk_YXaCdbZDKdb)kxG<LnZ
z3wyhhRUdx--XQxX;Z(ia=XX=ScYI=b|L?>8&c$E8@4PIXb?tB{e~XqX$MlsP$LB@x
zH{@PCkR#PD^5}%oE5+l@-+2usGZ;$_TE`p7zUMz)RP*63`<EZi<#v(ZJDC+5w=8yU
zo-O-!YA)Y3-h}suqYrFjd@Z%X?cq8mGml7RjlbXXAI9FTWVrW!s?GxG3%_0*x2qHX
z@#(q#%i`dCyC3hG9ggd!9&G2{@nm9mt@wtI6~^U9qK~j8aZF=>&viq$@mxjw$GI1b
zH<i8*+w@-I9JjXCe%TI|jU0Pi6SeNW?_B3ly@$WqPh*MMn>z;<M6-Q*QtdCrq3Kus
zxBL3bI_K@D#5V+1RPVKV`1fCCM?LqAPcDyiIl$+_+za_>R`6$b$$QV6t65W;-z;n}
z3Z16Fp(k==Z$RM3Qf)20IrfE0T`P1XyB;MdSHBM}YjpY^ck=gf%?p=$CYz~${udLj
z@A*mP`MONMbANk&XEuG>ew%?KY+BYGn^cYd`ri?)Z*ybr&I-<+vE`Fxdb?sv)>Y**
zPt4h-^ab%JUD3R2B>ue0YFGR*%dUk{JEZ%L>{_HSh5LP&gZC6uV>P$WlY=I|_#PGi
z@9x+2&WA7e22Tootd$`C;vL)Fh?wLnM}u1ytl{1pl&#mV^wRsbiOb7B9uGccq^#_@
z!;@E$%+PJFe@*Agrhj+7sek{MA9GZz&TeVpHiyoeft!Q>1X{J+S`<?<P0oD1L4Tn9
zombahpLS85TE-D5zI5_p$?104KV5&``Mtkz&;A#+%UjjAgo3iM@%+>mQxvC7w~7&I
zm}Ifd(KBi8P0!ceMxvWl3q%E$<=nmUxHa3d?%xh!=FNAn_y*6cFW9&Fuz=IltZ8Yp
zZf&}{#M(fs^7T<ew&3ZD<{jtevfkR6?fiV!+}yf2H%B%}R>>5xw76g2U#__<5x6nJ
zN+Pvo8{es4C!T!be=hdK=*L<|oyv#&Rc7xqi*u$vVxH3QPHO@GkKez9A3fidU3`dH
z#=P9Mz3*f0vD;tf{CQNfse98&of9gH4VvE^%JEB^tFqf*cT#fk<+c)yy<ZJAF01-4
z@R{$T$zxRYO5<N`s^nbh+yB0=zShaDzT@*_YYjb3z5fmtr|xf<`m(ukUt>)4^C+up
zFFa~Om<$^YUD#cPpUJz`720L~%v|zxd7;{Kp52qmH+_2I)tA0%Pr+x$m2#5oGVDeR
zUWdlc-P9U7Azz?z-#Y79#T(}fi!ZNg4@vh>zP;S}naI-+i}mx)S@}*pcx*MN>?w_0
ziBp^Uf*quM{`||V`C?~d_<?hFvhX_X^#=XX_hiq>-~PAZ-VOexi<Q|z=jJ)?b5wCr
z3((&qr&y=h!rt<DaqzN+6p@sGfS?02-x#Z;sTA3LuL-T=b#-~^Z<b@TaiZV(vM2rG
z|CYqo>|V8h8?%I=(YyYQTUK4`Iu_Ww*4}Z&vsd>G*VXLJ=sWsn*^NKWd0I?*Y8%~@
z_9pqR5%*D-yHLQ8|F!0}-ukJrGtTatQoF`>@3g1t(>{LRxc{X7whjDq?Y;5~Os8~z
zF#72mmnf%vU;5y(a<gFlZSzhpzkT=U5(bG|6&m*Z|Bf0SFD<N^J1_I^{uQ5IOBha?
zG4I5>&%1Aw)`_q7TbFY6WaulsONRs9Z1flWSt~K+T;Iarwhf<~V?(&N|DUk)V#bqo
z{qI#&Uw3^vX&Ru%qC1B<Iz0RAW7&BLM?#f3zVe&iztFPw`8K24>)ZeAc<z3Q`_fu_
zMS;|)dzKZYSF+7yPsiPRVK|dhR?Xt+jdf~@MhErgi#I4a3$h3EZ~Az~Eo@%I!S|i}
zCr?UWG-tb|qeJqPukFXDx@?P_oAxFD_I<sNoX=04I-T?(x;bKJ`O>FtR#VQcvznoM
zVTrT*Z>hI01GlqZzxL9xeU|JB*;V@%`G+Nn?LPND>Fdg?Yizf+iK>Usc()})StNt)
zx&EBx-=DnxnfvH{N&c<9MeCm?NU}=yL=<rUzq|3=!nx`5-nHiG8?8L8lHUF>P)BX!
zJTswas~@X;)UQ<@^jPEg^WvjNH-cM#wO`tp=05Mm2Nv#j-A88*r~h2^e|n5)?otka
zj#FQ@Yp=4Kci!fF$M?LI7F=p~Ch^H~PUPgtwV5Kmd+&+++y5Qj=|1`Aiu1=`Rjn=6
zkd<3neVS>GxBYSDc-u9edyK=*BwW20`t<#p@L$PljkzLMJM7){Qh(c8?^u4-)=Yf^
z!`oHcA5XTMU-W9>WuLcy6|Xjh&S@^WusT?OU4G@>v&V(ko%Vn4-hD&t&gEBf`*vrt
zdGgOse7M2&%c|?Aw~2Q#L^*hdaBi=!m>v9`OZ3~sd6WI_hyRZ7PiPJ}H}k9E%mZfK
zna7^U<rh8q=VEqmYv=cM)$<j5+iy%cz|``y{o>j(^LcOo=ybQ~KYMfd`3%z+>TKpx
zJ?r-gwK92~|1QZX$@626{r@+Aj(@veFlp}d@=qu3->T8)Ow^Av6N;X7q^?ok>(;}Y
zUe$_=oEOiPZkO)n=t!uU{qc?D_UY@{YJ5u;wEmxNHRa;kV^h2Z%w+E!SzceWs&L7n
zNF`>a$}M*ngVgE&s`m_8(Dn42qsCmhrN*nCubF-L(p&GhQsHrla_9e7xUSES)yY#d
z+IBT!Ti;E${cL~V2sv+vH|XD9Kj-jw*@rvz&PT4T`uWQAoMfwL-{a-qlLHnz>PT;$
zQ}3?3IJ1X0_;_sti$||t>Y<XEL2u4+b#qI8J9jq6X3xc<!x5)Se@(r*w#;0NH~!4K
z!s;1UQiXVxq;8lVOW2>_W-5KODUthT{d>lD*~RjVc2ieKJ>|CCS}bAqJ8hfn-L&fx
zTff|W_x?xK^XupMoH;fxa?**(ue|4xW3l<;#mSFY7jGzd$=k#8u`fQ{yK3&d!nMaY
zX1~eXb?sHw&O(t>S56q+KDzJI>C<z3?N_IE96DL^bze`u@x0jN^2>X-b!8^oY1FGP
zt@ht%_B(X<vCnTe<)8k4_Gn^Z{fW-GYM;LH-Ve!oa&?x$e}j8(K8i`dzvXg#maOl#
zm-jc=U%$5V+PmXo>t64wy1udWjM=-)(*9ikHH@FnoqfDswmwsM#)T;tGgAIM{~opO
z!a8S7D{=pw?}HlH1bHJ&Y7DdU;!huFX?!8G!A!@_2vov6IPjyHCo^W}+u}`!H%pq-
zE2sx+ZG69Wvdy>ii*u}>+jVaLpeOcO`n-2isf=Pw|9X{;a>`r39CyrWyOwhE#nU@e
z3MM~o6V$lvHs#cr(@!4Xx4&evjf+dB+G61f(WvhI`G4D`ALVbj7t#NzT!`m2-@4?l
z`>vLC9?USA_P?6@;iag|;JoZQ>HP1rlBOp|Us7Ag`~U97KK^y{y>|S6dMM7+Ir~;F
z@3I2@#(j-7#fP`=x$-yl_Phw*dl6rEnK^R$?lpUES{L!N`6pY|l)XFFN3<?*K7M)b
zytMB(Y<YYnR-|^MUFBYXe7(8;gX^=!18k3ct5Wt<_2ijlKjF<EuXS5XH~e{2<EFF6
zH8z)7QRYli-Q&v3od>6T*dFUnmX}*6!SsiT<4f_~tc=iUyiY8?O<=TRJR@s${#Qn{
z%Be4BgD(G@<rWq<ZP~`Dj}JVFn<D-~`otT>;tb*I$EuR$r)a*Y`jL3_dzt0GHfL#z
zl4lc&oZC-c?CDNwPWrj#{eKywS&R=Be}34>=U<TU$I<TfZ+p8Pbz0HKa+cOr)V9mS
z?^qVTYyY9gZ{@eYw9Ni=ZG&FnTsJ{Z-8FZ1PrCj*BEsxJ^P~f9Q}<hI8FaNC7XRqC
zzC3o(jSCZwIp45J<BrWL-S~5-_2sfpPmI26Dovj;@5J5x{ejzyn+5npgan%A_s>lA
znrAM=ebnXE#p?4OYux(}Sp_!uGwkP?>6;U<=4qSh4wG0DTlKk>ub*ei%`V_otW&J1
zzs&#Rcf`%ZY*TFcUmv{lwfJoiOU}JtJE!MgafxisKK8$~y0L@d`1jYL{438jhufbJ
zmYui2t)sPd*P-k^#dmj?tiF48+4Gvs@z>t$>^`%{=iSdQc|2~-FWL5KY-L&(aZx~C
z^8B&gW|p~MuFko&aBHMp73+4>{b!#&uiN`OTTH&_jNQX;8(w@+x_9$K-{!*ti<mZ7
z_Nl9FtWx?au}7s-x9vp2`yZim7lvi%F8i{nDCqjakPsbN*4cmO=TtuSjS9^^dLu0P
zs_8nmmu)4xMgB!>tZx0pFR!z%nfELI(|=~)!+%yd-DsYFuRrte{tZzKYu3c`|MyDt
zT-X-KSzY<)_HoN;HD|swTTPMF4CmQo)|Yjr>!P-2htCCzU8guda3&n{y<eQ(ZJk^9
zuC~5c-BSH#m9zNAN3X;q3X@tvu9eyBnbVp4xPZfUV%7Q^aqJ6R+>*AMEqf~Q`l>1O
z&M6*$c7KjH`fOy{@4cf>-P&$x-l}zcD}0aY7UoQeo^bkG^6jb8rUtv0D>>|E`x{gB
zx%6Re)Uj<_G!;Eg`zIegDSC@l<xSGldsAz+|FQne`)H*>>yEez+iAUVeseciMYV;c
z+F8jjyZ=L0d3N8HmzB?p&KYK2EtYaktv}k9loxF?%lKyc9N8{`=`+q2+Z6h)af}qs
z{{LzAx)m%+O?#7nuHXEkv`Q|2ebVaoR}FGqUR@F84%Z4QC%Xmqz6jYodDpSP4eFWY
zQ~SzaoKf`RSsFV*Y+C^Hi~9u*Q~Oj~#MEN`F7bVPea;qtN0WuTi!YuyBI!RnKR~)e
zvp#%7yuto^dk#F?8#mW={pHVZ8(wZ%eeK+`=e7HPSC`GZzcMi7+EwoL?lbCVd~I8L
z?%ABwFOLF6q-_kH1>T*=5z1!Zk2xm0%soBpxFNra@<zVG)1liV=Kp)vz3IN}hx`Aw
z&N{9V<Nf~E-m9ip4o+-R4z&t<wA1CO{KJN+_NRXd2KjjIm?vf$b>Y_bt*^di`=7SF
zI`!|CXX<A1H*<a+G*}RJboYL_54_>w`=c)Jc%ys6envdIzJi;0^4`LgLdl%xb>^=~
z44LN2;_~4t!|iKR*IVuE`XBvukDDN8qICCZHQRiz!U=Kt8$zBPY4#9$Enw(qShDWw
z&8owf-ZGWRmB+1LUC_su_RY=o>5_$6)f~&7Ps?jfNaX*}y=1|pf>86Y{eneTx0XKh
zn6_cfiX|Q5b-(N{^S=sQCK$i*R??ABWr?dfQ?4z{T$JY%yR7VIz)efXrThE-9^HTZ
z|5ZH=?n|F9OWrI|>EBv^X4&(-+dtZh$wVy(3~^fVJoWY)mdf)UIfgB4Rmaa{rU!=x
z8nbX{7ze5CajU7=^J?2oyU^SA2G;Ap{Cqg=HY3aLs^cpIcFfoF-F3(?#FyRsq_^Vc
zfGpk}i+;X-K3o4;i2PEcYDq&!!<swKh1VXwbVc_1y@S1u=1siTuWC2EtbNP0Nny9g
z&wUlkukSX?6;C;G;)d$?0+qd4#_cUDw7M(%+Ix?@QjF+7SM8S6%=|>@s^Ge=Z9#Wl
zF4C}=RTFYMq2=^Su?XMN+ixDNQr)=EZl9N-y6D$gDa_RmSIxSbxvVEGbwzf)N$k1R
z>t0M&m7iUwFvZ(D=Tz0o-={<PSFX$S>HBceR{nAM4gaq>P4>e7pCr6;%xyMWcw)gD
z=SS}!ug|-Ez~~b9CCQBs#6ER>-ooY2v0CSurJSWu_Lq4RZ#dMyKXHBT+PWR5wzeit
zm^<G$uv0xRLG=vhH}0_5gahvB3+HT@mCVYb&AFzl=>&Taf5^)Sr;Md>IkqKMvU5VO
z$62MsoPVY~`{(-u^~>bfc()dZ%-vwslW!aMd54VRLN})JuRFN;7G>@CQg*Yu`|5|_
zi%qwKukx-wea6v#k@+h{_q(6BtLHzzxL^LFhLz%)%`=`?-0;wGYx??tRe9sm(49?x
z_bSJiZ|h)~8oIzc-S)|o)qmOq<Q6Vi;ZWLNvmySf-R6gm4_CP*GKS4xbF0kGDMR&u
zeuKk)hZ8QLLK9*mwo39G`nT`TYwpYZE`f>GvJIZG^S-ap-TyED2ltPuKMp2_lqQ|K
zVSD)D;#qFVKM(veeQ~_|`W_bd0NbvwZ`bAjEW5t_8^0fis7~LJswkn=${zV^Hq70|
zu2uUu#cE?R%g>c>#6Jeted0>})oXt8#Mywmn`3o7{$5EAeigoYy@*d>;<-l4Ct|D4
ztZOaUu%O%ajn*=e(^K582gL-PSub60`ZwWjSGg;TOF{VQ-CKB19h5p^nh?<Lc<R=T
z;%m3lMbkEZc@cE>@up`-^Yo1t9A)ru`O34%{eNAH>`7~rUT==zJ(*S;1E1?EZ(Qn`
zGr>o_tfT1>)7M^Rg$wtKt7f;Bx=-$JI%Pj`RbKVw4OPxpJ#(V!q=M_}cY7TdcG6~b
zT`Dgn+Pr3-Nz-%Aus4y8USVEG*_8|}gHuX2Uu^l&njtrRaqs);`JeiOSN!6eQC~1`
z*~b+NufP2HZ=(E)=h6OOOaAS7WaFl@r?rP^YWI!S4Z_`(eFqB*Em|5CZ0{KeMgKZ>
z(qm2XjSxv=1}7$)_ot&~Z2x^E@2YLn*`!&aFCzjK1CJbEvA)eF^`*$P_i=GclerS}
zT~%GDr*l4u&VS#@Il+4N_Plj3+0R_bk-A+qr|h6b;C-{&sW%PTrnp?|I@&HiJ$m^o
zosEeb|9rZV^XL4p)$2CZSiCj(uCr5m@vVo^if;})+T`i)o#gGFWNW`!yY_L4$~D8j
zRGHwrW*P<@_3`y@n*{aJuil%w%75A1tW`IPZ**k~uM54q?ZW;EiSO^6x%D@Dbxn-o
zo2N&93QxcOdZom{pxEgS7DpcGc5C00>^Ql0|EspEOPzc9W*vXRQ#E(qL0NWf^Pmk;
z(u#`}ny)So%a)riHCMX)+1}mv!moW<wZ?Vlg9}Xe?!TDxwyCB3)2fLPQ&g^fel9z;
z?)zzvHOVp-`{PS*|FHPFIOWja)TgN*&!4Lg3FW@_`b$i-do5GexnAA8p!*g+k(+P-
z|61qsJ3DG>zix}|8~fO2b5=caQn3p<w|d>9A3q<fEL97wQQ({W{GhaO-W40Q^j!~M
z8STHH`TFgD>)d6FHVfMn9aipnW#Uy@sMYX1+_z|^OH74bcV*vm)s2o-2R^qSOz~ag
z{I}fe?{vS#JKUt)lw!`F&#qV7t`L56_th>xQ|mzEEooExEmxdXSj4pWiYXuaAI0qo
z)7$seOi;|{SF=>!dCHI@Q1tbwyt7G552fS;=uBjsc#BOXB)Ys{?o0MXzV~aL_oS<D
z+#B_6SIxq?Y!Nec_b6uWeP(#`(P{Smiy~c&LoY96?BYGz6IG&}UL2ygLUa+=o*b2H
z{{5>?dzy#;I>!2|^525Zo0mRcviV+{{@gIr=uC;;0##R4*FBpPx{8z!RQ(P->vsF;
zj>fviJNLiUmG+i8%sp)`o*(D)*j?)5rStleX3fo-UeU7Qs{HMLJ8BMlE!;HiYE+hV
z&xVt2&1(DjoeiyPF6=EU_kCQr&0)X8Ez_LxpM9UF-Ojhzd~oTtscmd+M$cdFY+2T-
z<++0^ebf1Z+m9}aNZYKjSyNys#=W#EPU!XO<1cJI*Yw}}TpyY~dw-%`tJ~LBiFLj&
z7ABe;n!0EAhuFS3wu|m;FxqT?#eRyR?(rLMZ}^wbSy5M_we8FDkgzzh{4=%9KiH)|
z)o-4s{xN3J-A6))X8m3Mee>HF+fJ89{FHhf=zebHx|GWgeMR4!7#l9BtEf$CO4`DE
zf^|!`{^TQZ2OeFyGi8rR-xAr2Hfqr(>o3pIm-`WPv&`Lfp=pDtdf10cv&2n%y*VH;
zZ&y_kH{r;%c?znXSEpUfc(Qn@{HlAGj@&;!f8EE}t-M}4T6){fKOLKMeX6w8l!+YN
zayh>j#CBhHVR!u;<}bbNe5OMy_t`UheD2NqFXk(k>2p8)_lM87=BM^2FWlK*_j|)1
z*|0RjFDq^b?@nkr%QxRP=A)nS-^{nGwj2L#XwSU;;nit#t_@KSUV7}xR^7<3c)jG=
z!?p5Z*N(69;aj$5{-H;Q)w*gp6V>lcKT>tL<k2Nlmq|ymvcJ`DzFAr~{nfX>QeTu!
z4tSX<--&y))1_^1vGGsWrLorpBi_8|;OTfW^W6Dcwtc^E-E-g1_V<eEHRj%iTOk_z
zk_@DNlwaR}$E?((@Owz|mn(s1qV4^Kq7uv7&&xgAEqZ_I{>z7QHf9~Xx?@}3)$WCy
zzfWkMcv$mH^mA&h!Ed>39k~lDeby~V-K)K9PxMW{uNlVz-!`pm`u_f3gWp!GgN3DU
zdnI;OpOg@~oNCs8p>6%W>wlW%W*v$8(QDh{qkb(W%1_GwY=zLFEB4Q~J=>lwKB0iK
z+V9=M>)y7f!=JB7`)Qf~eb%CrQ><jI(s=)Q);<lB^%A<xvw3m6C9CD1P2a@b_LOs9
zJ$|h4_LYlg?i<7lMFpn1EuQGUuWClqBJFQiHWu{B-Yik6tFq5!7G5Q5U;pRRH4pLD
zq-|E!b3g2wb^Hm}t0Px5>)WTQeA~f$`<vyY{p;;F&!6Y)Q`cjp8`ZkykBOU}jAPx#
zQ<W#2ZXCGnmQ-u_XmQ$Z?(J%qJ55s!q$ECnjP+V{DdukRqo&6amnu58HBK!wdaF`=
z?QG$Vk3Kv1J^gy5rSe~udVt=6{qa9-`|JL4-28cSx;)3RHz8I5ZqJWzms}qibFuN_
zAIl`o>;G$Hmv0K0Hl2qxYN3dNW%JFfSvP;){Ilm<dR^Ra<Ase2dES~#v97x3`95s#
z-FJ638&|Ry^POq*IpDd~!>vU2;T-1O9oy?`XYVij6Z+3jR_(i3sN5yPbzk?+I<9)f
zy6W5!jzz5}-AfO>no)nD`H1V0hwoqeCl<auX(IiU>Gl~O+30Wc%C}T){QBeJ#+f`d
zztwmSvaS9q$FObQ?Ng8c+Z_}CyZ?%vgZS3xhw`3UKl5UB=u1wLxR+{CHTTrl{JcY_
zCq=}^M+$4Ndh{scV19I6@G9N571j49%g$FialJ5FZmspEzS7xeb4nj5{NKCtoc5#}
zzU}58-|(N`kaWJQi~rj3HySQ`KUAHO`J!yqTYXi^)imkoi>W+w%7uRihrG*N!@g>9
zkJ5bhNsQdhYj6I%c_zkm^32s~LE5{-w#QdnfBz=w|9DpKYMK4YXKvUwOYTlTP&dWp
z+QAYlS><OH`9i<{o_b&Tak;pbodDkq$qd;W849_NZ)Hh^M=sywx3GTsne<ZiRo!<g
zx~IIE(p4VyqwmW!m9X`fgSB^w9iP;%SuPQHZh6|j`!OeiEzi7EVO}S9fctRVgRQRX
z9lb+zFa6Fs9$vEg?%j2)Ja<p7*}Hkh*7C5U?B|&IX4%gBU(EP#-@L7-R~)rDUfNZ2
zyL<YYPF+>cHMLL0pBjJLTs`C4b(5!kQZsx5PIYnjJzlt4{*sB=!-$`*KS447YtOCO
z=gyZJ%{_4K$eWN8FAijg@&E6=u^{3y?;Fq%Pigs@?X_kHj;3rAJ+-DeD?&GA+LT#G
zc5~lfdNbKq^2ak@oxA(CJQ8tM^s4>x+r8&^jt<-6&b-gBmd#&${bl9G+upa>)N-ap
zCoD>u*lK$A;lH%Do3;TJ7ex23Zhhou>B=WHYjx9fw|zeMm(@<~I;!RWp8x+}0qgVc
zubAjPjIF7)sc+4YwA)wVETo;C^fvGL$GIRYqJ_3=l>bOBUHjNoKE{4(K)vRRC+oVr
zyDTS{wb`nF-|+YcU)cNDqpS9=KIJdHFG%F+w|HG`D}!0~Zht&iXZ77Rwop=NiqDTb
zaNT<Uvz?;nC(X)#Y`0<IQv0ug*GiTydLx~YcB=1SM#9N!sya7!wLB}G_4(C`>k`*0
zC9LKyU;kVnOC??9^9}QUqu={)E|YFqB;soPuyGszg@tbHXOo1dCL48bHTdxO#7)n0
zVlo9s_e67h=HyMB`st{i!}`m{pFhfH+HaIyer{fnRqomox~Ec)G)3PqN!uJ=n!xe4
z;<m?{a+QrsYijm93%}|UlqD1_w&(1YrI$6dG<W@RunqaEdRL&HdAsR;-_1W-O4$}S
z_T`r~lzcsZQva0tdV~HsO)`^=C*?|e_Aov&wDh{Ku!zw+?`QKeL*J|W=gqx)`&V3E
zUXAhkwY5{%m(`_KALO<5nk3gc>A)(FjPLVqo$mOax6s*%{oamTqrbOSteK@_<Co{C
zH(&qnobC0s-BWagFZ(<Gd}DIpN%{)E2-$mYeoku>>^ik-!jWIeh0ok3%>S;k(eYpS
zpLJr}rk~d>`>P_hAgaQ&t}@GPZ`>=-z>JBjoTj&5;xo)U8Ii_6ck$04sfR!J<ZL*1
zT|89S;cm>!uiKXEJ}8^=Xi`$x+t{ODQtum;|Gm?7)#!0U#_RQ$6&5iX=lzPCEU}jB
z*`+XVzsE}RO_bfX$=qj3TQ~i!Tf5P(th8A_7q~V5_}2DvR*2HJP@e!E`L91`cs^`l
zdk<R+5Ig_*WL^2sZ`b8pPA@+9O?;QpLSOfv|L63bjJt5w-OTvG*ME14@7mTBy<aZs
zu0H2%<ii~&(p|l+``<tLEo%Iu?&$ZJ6Pq?YTQ8?}zuV!y!!w?_+KVmpRxNnZ#b>Bp
z{fF&GMCJoWra$X`#OkVStaN=B{C02l<aK+BpYQgW@v~)<U6|{}50&iC4NEVF%zN`=
z$+M3;ZS2p8trx!b@~hY<ne*CjmV9^Jx#iOv@3u?b?vt~7Tr4GbO3v}JJle^vexopl
zeKvo7(#?0NOP<e=+}7<f(=XF?MZE@S1SBzAPJ6}MIfth`_N~>Js3Cq&?OMGno6D!L
z^V@f>e_N|}{d0`+61K_JdrqFd8~^aS^Zrjyzv)L5Cb1qnb>{HJ#U<}t7Ki-sb<~VX
zObST+_334f#g@kT^ZzV;B-eE=<or#>9sBnjvhiCw=TXQh&9eD7&Td;A9l0%AQeAIO
zz;~vrhC9W=+WXG`_FY_j_FP%-_DfL@>Mmb3vHSZYe&&kE$aP^6K`%@@-z+_KWcoXU
z`(_ueA96|(|MJ7PfAhNo^=IzcO0RRedjIB<spl{53`^g2{oT6C8a-X1Zfl7fQ?q01
zZnPeJ5L(%HP&~Efl(yb_Z?8GFBFp#o*ZuF%|G#Z-PPLz--%)+h?4*Xa2wTCHU+tfM
z>w1F*QlIT;k^boDd1F;_(UlYa?~l)zmR#|5*7X&VtC9{*5dQi5M{)M$=$%_%u9Z1$
zam@dBUDCCC@;8eU{h!8Nn11@ChnQFC<B(IaU*6kpovt_8%J}z6%R4vT9b5H}>yV$>
zyqg|pjxP=N<x4L0Ki$pM#qG1cbBn94PuYQ&7d{5g?~h%*X=V7?q+s<M|GR`2PW|s*
zd9<?S=j{zQcS*1QaC1XJrP!P2NyZ@|KVBVNfAixTKE6423ESjcB3;{*+;sO$)h*9g
z)wA&X&Cu$uWf<{8VP~}Z;?kqylOxXGlimBJck_>DRULm8)qGk%=TJ(1)dIaV?bK<a
zvJz(xJ?vgmeo^@60+rQ@8kg%28Qzo?dnbQxuI~FMoqWO`9X<sa9p5e}EMlCz%O@#l
zy5}34{gZ#PKl}K4Vf@X~y6~rQ25Y`7*E_Xu^T`-1_ore{jNZ(hJ=46<&V1|slX@S!
zS81AwOrAD>*_{(d4XY)7EnL&syXwb;_4lUt|E@X2oGV}8ps+|wONW1hQOtz!H+GlP
zR%@;Q&~^W6!_CS@#X7C;?}`-@9TU$~R_Vp6mny2O9DkDj(`)%=|Ki(^F6zks6t}Z_
zDJry0TW{lrjk}+#Zd4VY9I^fZujiU)Nr6?Op*d@>s;%Sw+;&dg&M5BniZxkMm!~N9
z=G^f+dM?ZLTG6YIr&so^(!c6mq9LA8H6_s1UdOMO`wQ=q{N{Z;`9<7^XYqWVk#%M5
z>aEL4w_e**bau6jr~RQn&7UI+K7^aixtZ|0h_!yo${(hU!45AsojCN!$<1H(=qvMU
z7nU^^r|HMU|F5#T_Tt5qWafL(8zcLJp6)eMvyb2Cxbct4kMyeR@83Q+;B(w4`-A^E
zzQby6izoiuEF11}_L_>><^!CwjjTP>)^*;$>Lc{JPkAGQ?(3~jKL1``cs;#b>veMI
z8Ikz18p-u*Dra6_U+et&$DEbvcjuL?yn1w{VMUUlivH<huNuRkN1dM!o&LCJVubIH
zg+8)<habt6i@z+blH2u5@!mVjqpAC9qQbM!M%&&mE0b8~ym-#1SFgf9`>ij38Mb@&
z@qF=#0y7UB@e`hTBU34T)A<b_J~-9g{BFG3f9*Eig<suQ-jiXMVdPS<wx4}5*nQ*E
zyK6;PS6ChJ<z$|DA+hOj|Ld(x0h6w0&6q2Gb$??0z8C*hzaENBURbmsU!nHZ_rfv>
zv%-?to*5goyRJogCi$n&FZ&Ued@jL6%G1kx)sF_o$^ZM4nC8a+S-<Jsi$eDQZ{tsI
zF}*xx@6k}5d)3*0qf1s^ojO~{rrgYLf7{=gS5hZ!KK#KV&TQ@umwrFDBv(nRDcq|(
zrd(`z<`8{G?B&i&SFf&5JNq{K=Z^F0dXo=u9lu$YC;gf4%-3CB4@{l2KRMiHkFcv^
zb${poq*rcorpVP3+r&9tU#``cRlHwcWxxJx-PL;wxzaB$oa4PXaM_gYEVmY{sW+W?
z;2PK3qx{V2pN@Cf$Er1ozA{;HZNVSeu%Z`}XR4caADueqyiI)JbY_F-_{EMc%)XB=
z-nvq4x5W7@UqMW4b@RmoGw#2C6miVZ_p#8t<4N-#S29mKx=*9j*f#p5^z)CNIlNN@
zgQH{TXuWDSYF#T-|04JCtxrkcr%T+bSaCXZj_A{urB(l~zc232<#A)ytkj%y-Z#zj
zkr3Z<*|5LAE^qUHoN+8rj5oe#{=Lo9Z_f_0-(z>aymDT;wf*TedpB1+-hbV4N}0#q
z$+Zo~G_q6uwOVh<$$Sv_nxtA;$oX|e%+k-Bo<~fT?~GcwwPM-l%{}?X_a3L4R;*$x
z<UMsiQMJ={ZmHMih?tWnMT}4Gnz`@%ue^Cj*nY4Y{9b8UQnAc-rFhWP)X1<U&z2h%
zJ>&?xzwcPKR#^9{&p&LI+vrCMzt;6!W54R!s$1R@@&yjBmpZrO+V@L~^Y}gE?zZsB
ze&4#&zw|eMb^Ve4>iQ=S_sc154!ApO?NayYpHAH8|Lj_STRXLyOMWhY`L-RCFP?S#
zeD+*^Mc&iRDIzO$a-)SWIRE=tb1(Xbo_zmrm&*~YUQ+MBEWG~mW$b?Q$5HoBPdMiM
z<k8i$t!!;V(qh$>@(J3WIZId1-#v4$`uDIs!R<HszO)JQn)V(S1PuWmTYTU6$=rhy
zO}wkVJ-Am>W-R=#_E6UH%>v@0(mFlfRrge@I^`CNt883qW7k>QQ1$TZj_qIfo{=+Z
zU($a5!(U(f3!C%&ulpzXo{159b@$$%vS)W~?k}5ob^W&bqtB(Ep1vOb{`BA6_vz1X
z#BN!CG48MMYUZsE+Nau22!7BpX~!YSMNEr#JY5z2qv$}mO!Wf`Z})#kPb^bbZM=Hw
zqLF?2R{I#IUL(<)YgIPhp0qtvx~Ka_SxNR$Yuz;tg{_Y!d@Bh4J$r^p$)ru8(@&kg
zn0b4-Vexq%P<lIjdYSO_A5}+ZMdV9%u2qts%m0w^;g6SpR|p0*?|N9eQZ%aj#|f5o
z>*`E%S8ZKb)zMX38WXr`Gjl=x-q+vLyw;aj6wRF4WUuL9HG$JVw|>&Q{PN|cf3Nj%
zTwHpUclGI07gtLd)f@bm`yYOHa+b4O7+Zbb@5v8i+p?t>TyRNoP^p?bPfF1gG;tfX
zaBGIZ%?a18MqM^rr^~A>y{k@rfx2b<v-=M<P8XP5*%;_<CUa}Soef2tMJ9hWGJj^e
zu-*!?y7xE7*JR?6Su<V5Bn3PluQ+y#?TN$sJHNC*Gry6Kj51nQ9eH$czubb{uiLit
z<gTo&IkdMja$fM8(94~s_wBE;+T8vbx$=;<$>)mp<3FF@xUb_Gle90;pg>BaspgZU
zZK;U#@*E|V1Ao8$+Ppnse}Wiaw99w--5ZrF+rO&6XsGy6e%*f35i8H_x9&z1|Bgy;
zSG*Il{Mg)w{r*#>!_rtJ4L9j!%9<a$zoIt5FDM}7z%=D(ExQD@&bJ|(C%cPseYyDC
z;C1Kx3{dm_{M@jsos)v69PVJ<zTx9K-<F^4nes~tqJOr6T6wRvbuTivp6fdlsFkx$
zw`D^opX}xQKYg<nnw~Z1Vv1r|dVlM0zqgM+=F1hkROBh%(4S%H{A`u}HDLznOJ*6;
zQv{rZV`rD_ty#>l`gY8p#Ffn#nAhCfe(TF84r9+Xo4*TPb&7G3vA6%pUFTUhVd*<d
z_8@+Pf9I>W^7`zsg$zfzf(9bhz3=b1(-iakm|_e23bB}8N%PwLo#lU$rry1jT6<sb
z_q52>>6S`1+b?LW67(;v@hbi8Y}aleWt%_QT+t@B=4-_xrAJew-PXKg-}s~>U43JH
zj_K#$Gc{*jTUr)=nSaO5cfPwnUwfOcUEM6cvijVczngz%oOYjeO!dy}qc+DsPr6}a
z`{3uy*q74k${U?-xX=GpJL5*?qNi^A9E9~m-&DLf&2Cu}_BYIS-n+)t@<-gCFJ6^f
z=4mEgq?aKxQQ*+M5-VBrZQ91RH%?7?v{=&ps;+5)v)kf{uCv8w)?GM~HCbT4K-IOk
zD{}+<OcEckv~8DOr?N@wx5oTPyNRWquT6Trcj)V%E-u=u)j4%ygyNg$TeIVr2cPwu
zCe6yoJEcDDS!&VkD;Gt?s?Tz<b!W9+Tjbo!x9WDf=*l_eYApqthfl3b4-d@vb9?Un
z4DlXe-P?P6l+*iX)Ll3-&Di|N{RbDTRbH1^?W_C|E!A!k_R3>LK#InrYpu$b^Q-Sw
zB|j`J;@+E~a&3jm#(DF%#rq`b?%g?0Vdkf);;k1Z%)i$!&wf_vj{TjY!x4J9@AmyX
zkv8vt;iP99cXCH>yK_?S+%*Fs#g?#N+unIs1iY*aauu>Je(&?C%l7@HH>>xbeIqT`
zVO0E_>+r0KI>X%`78E?Qv7P>4O2X1r`?;2H@+&-^zdhL?>gHz83fc9u{MM-Zum9XO
z@y4Z>J(aBUzAp{%v%9z9P~?sYEhkv)UVpcL&HK7I^X%m-_m_S8J?*|}@9EepJZqNj
zTB{!VLgdhFmLIGJ8xA`>ZR_F`&HR}ux83~3NpAJX4TX&_*_E~KiN26N(aSk6dg;zJ
z*S<!7zWL+7=H;$XzmQ+QZ`|Lr>zk<VVWGSek4lpGceh+P>9Iy&(W<=sI_u=9zKwTI
zuzN6+oZ7Ww<NUkML0OZO4;5!7vcB5x&GB)vZdXe|_~YOAmj7AI5ZYREFUEZ4A))h;
zRfd)Kq@PWnG{Ymw-BdQUc3MBX<mGIh$Lpo}+Zm=ZubF(^_gViDd%e5gF0Nj^QNd>V
z(TNfMzdsvHTJHWFG#i#5v#(sYLhMkY-OJA_zw*9xZrF9o{(Snp=jZz0f7sT$Q~SjE
zbL>+$w>bZG+RE$3v2f<Rv(=ZjIYvKqTlV$aapV5aU(c=I%6rPOPfb4c*QS@t<gYNR
z6<s}UWwS2RXWfg%h4PozRasjsT(|dN#)EbD-#@8%R><(D=8s8_-wx*P%D&~k>enW&
zKK=sa6z3N~H#|9VTYj}0Wnb|B@q5P2H}4m{a#-@|{L|gjKR^3pZrXo#>eAHZPOH9_
z9jrTegzb2i`~(3f<NmuLvu3RPafW%%re~@B8V`&Ue+i3BogrD*xA2h3@wl&57tPkK
zeO9=0mcxFBG<(zb6>~H^0>96hvPUE@)?!lAB&I)q*VO#y>Q6U3|8c|1BM$TA7K`^B
znfA>t<+*pFh~kz@``oJ4zHgW`<yAw4UT)6+TW`W6_vUZCws7Z~BgLJo+>)f-OkAE9
z-d*8TF+K2l&!V&t-xCZWK2AF)ls9soo_E1UPxtSpZ{lLPMw{32Ic)7J_kHnUNg3nL
z9Y0=utoi<er{s9aD)HaBHk&6dpKkA35ny4raGqIu$c;lu^ByPGOR=4}D*ff2vC!;!
zi#L6lEwCtP-kTpP%u;+C?wk-$t<?!g(s<a{pQo<sow|K<`^}n^%~xxc8D||gxo#(+
z*s_f2FH_~yYvEH(`?Z#dFrT?)-CfE4JX30V*rcGz6>ny{pEc)TTNj~P=sP!C;!4JZ
zWraI;Im)tqeDffE>er20;dg4beKoGT`Ja2^+9X@ONWoW;XNqms%ir;KOY*kAFzE=_
zLS0!a&=QHO&a0yHB-pNm{j2<R$n)Lb`xZTJQ+MyJ?odweFEIJ3ArhT`duy5bTV^4r
zjJ!8rlQSdNtHx}2XzBef@%&HQTdYePn-($URpwhfH`euOUl;pt8K3O?xbO3}HSX-Z
z?zY!&eM?+{&)?#A@m2Dzb*&cyR<CGT?R|dhgy$7cN|HiZ@86AiDLsAS?1y(OT0Ssc
zbzb%PZm;ng|N6D9lg==4o9jNgY;Skf#w`5P=Uekbx4(_sy}NB9hoa0;_xFdVSl@3n
z2|0U+;e^(iN6%QDcTUK4e)ihMZSh3V<kMI7>$CGk&Mf`KA>Nx~HR+tGb+**(-5<Vw
zOug1Je?{gB&h)Fc>bnhQZ~0@=!Im|p^1$w2?R#e(J!s|com86g>f*|~aW{KUmLw_4
ztg1i!&*th&&C|Ul8kf7g&3D#6Ywygl-gWlf#y9qR=ZB~7Kc((%r>K42^w%4%F0L8d
zz7#)gTmN*MsdF|c1-@+-a<VwW8-D+QZft&I@vHg87H<u%|Gm<^`K6Yzl)9k=ug#aI
z%|7vY%cMTKe$_DFYp7-5<(9ZUKzS3Jz3&gn`zrBQL*MAHJiXK}X>0U1j_;u4z9sXS
z+oi7(do?<@nw-&V*|6Gt-CUn`DOnx!PwtvuS|;7-oo97w9qWyMH@>mIRp0jb>do~Z
zer)f*_+{hjAGxRV%c}pL`t_vW-(qf6)Xv1E3!ZFHJAC1_&06kIj`!bw)?Qu_858_<
zmV1M3X7!7&q5gfU@|Shit<uoaOuCbv{PWR!eI4^PZmqecpp{&&TCQHyF)P2ixRPJ3
zzfPEMan{R|s^Zq2e>c3$_t{~-UaHe{!n)%RSUuOQ=@dQm@K5cZnWit)5B)i;W8U-R
z(v{`Sp6r!RR=2+``V*|Ve8<<n6Q4}IY5vydmL%JL(~jSE^6$4~J!PNF_vw}X`j~yn
zCyIVsN8MSOY2(CkyqmN8;q2f0U8m<nZ=KqFthuCOv90$uy^9)~PI-FyKKeC%ee$s`
z$!XHR3N!bA=mxF5TRf}xl8#yV_b(5YOWrEekU6+*<-va%ooiG!#vNYmmQ?F;{qbW}
z&ozFMFHh>9Dlao}s_1nK?ESIjefl-&Ym81)>g)D@s;-Op={&Xn?~`)jGis~i|Nl0X
zo&R#d$uFtimx?b*{(EOo#8sqsUovmsU(?cc6HSwxDpoLt^FMg`&A)l3Zpc~BwG&T0
z;AaC3_D9?kzvL*E8|BiTert2t|ESZvr4GucbQkW>`lVHRUog&R`DMeu6W?cuT;Z6M
zQ&VJd>ff6~kDrP>nQ^~g(nh~iS25OqqqxdOg~c14EKbhVefOkKtUMxbiTg`Ky}xtp
z{#<pI@v(|{nXGqr-;|xNpGD;qE4*a5JMaA|_HO$F30LYa21NNunfvW)v{gSHB6&4%
z;SSHp^Cfj*pLetfoC7t5jMv;UxIOO)cbgmAz1Tl`y6Rgt?BQSC);Hh&+yzZ%39HnO
zU0ZkY?%3le+`-%RbbEB2y3v6{o&gL3f-(o+EPpOgV#hIi{jJ3&oSr)*R{!js`b#=b
zeL{(CYsv%Ot*2EwMGs|y(vOs@>83jx0#B9LQxCtp80;Pxuw+wBy5vvSpEkd~DvQd0
zSnTAV;uy&2f4-vY-TCt5>_=g<`<GtZw)pmoPchHCu39ZN{C)J&@;Z4oHJ&RvYKkqN
zUzS$wlmE;-cahc2Z$}aq7|QG}=vf%tcH!;Mbvn1UoKTFODr;HY@_YH+<Dva#f%6@%
zyG3$GYh5s(z<OA0lEBObo;~wc<Th^ujjB%I5V5kBdYHB5nfW|Zp=^a_AKUc-JWnEW
z-@Ws?zvs%E5Kwbeoa;0H<KvB+KV1GDnJ2+~MC<>ZvJ&a@|337bJwEHxYZ1QrwlzQb
z<R54~$XXy9FrSN+&rIf)!|`-$gICSbHw$yx&mK2XSJiIqyl?M2{kc`~i!%$mc(Z2J
z&D-B^A6#9ZvE8CYV4b#w!VK5#ddo_4vTx6mXe`RReE3)MYe}nA4&8Yf=Ux}bo7e7J
z*|cVlPTIOzCm(EQ184PD^Ve(Wgw6E4y711t4UBe-e@tGa?>hPKx|wwK--u)1Bvy-5
zO<Hw$5zp$Mz3HkOXYOfw_(;ORO5oL*43qF*v(?g7tj+lp_k<juC0n`pc*?xkL{-DJ
z{hQ`G><c>j{a4st$vcG`UOoO({-CQgGQ9BTn`O?C@*<2fOYi92bXz>}=Kr&4-|9EN
zys|>L{HxUA1ANRY#iRYdZq(m*4zxxn?`KKcx>=cZ(eqzvEY?)>dG}FGH!1o?NsMC4
z?=J5C<ew`<@0k2|yQUs_BmS#bqC@cmfq(@$n%_R1*Z=tGy#B>aao+1Pt9b9uDqEhs
zxX+{~yJP?QsYNfAP70cQqclnUHQ%4(v;JmBlqbaQRH|I{A~5axk+^-@SL~<!H2?24
z|5t5JwQk`__3w43t{qvMW4|-@=ROf8(VxBPzUqGMr}qb0dBx9suJyKYg32{(-5dKF
zW*A;P$9H&5mf+PJ|35OOw=dke+{*5#{qcX#-Y3`3&VSMz^e4H0l0e_@`w`prZl7yq
z_{uNv^ZcJvXD{b@I)Cnejm||Y-|ci*pjp6X;oHh8D$Spt^7vt|&8M%2x2(B7iH}ou
z$Evbmsp~mD6#*833j=@r{xx~(bXTu1u9Y`e&hfN9eC>$tnw#5?{ra^bK`Z3No{WS;
z4xl0VRrf=+_1FBezxU&P>C;0Nmsc*FVe;S=<DVZ#bU+)8VqIC?KVCnvf9KEZ3;$IA
ziT~=)!xpum<jm68ebwJP@4m6yI6Jf6mwC#{)1^tTE-0*HY^-Z^VR09DAnxE8$hfn0
z=M(W~lc!8Oa<SNbbsUSaz*C#JWsCK!3})TW`#D!{>#mTuTldCHs22du6dzBwnlN$F
z!ZQg)#`%A~TfNV%+5U)Gyx}n)|MI4LYpX#6(x9Qnu+P%xr8?J6I8tRM+4(iA^=PZe
zvmNi0CNb=1NN;~2P&Id+q<O9X?U%V8=eB-`<Y9Zoczmkn&h7OT(x>BM`}*(winLHs
zXmOn^X8h}MppH&V#=eDoD_Vp0e&k3<`}y`Lx8rWk2bV++XqT?JIWe-i&Z#~3cHWKX
zxI($gqm`$egvDcW9&w3Awq9^rQLo|c_UB-+_PnQu&&nr-L~lAGp3yVuh}`ifvpkzG
z9_Zv&w<vtr@|S7fB)$%3NioghU3u|~ZTIuc^Q}qQQ+E8DQg4<?(l6!vhJXGhN;LO|
zZO<w;oxU$w%cjA*=J}H+yB!3~HqE&I;^Ugyq*AYYRUgAY{ZaXL$>WVBsL<f7+N(Y{
zR%f+fQ1eUkx^&yX)#sM3>RSDM?X$0z>sQ*jEr?h6Ja5kV)3$Mr>o<S;Zzht_S@dw}
z)_^H1>(!>QZSTlEn18rl{mT8#;bk|P&1>UYzJI*@`{Tc_@&@mp{oEG*u9qol;Tp%%
zFDJZtPVL-M_cPi4&b!2GclLz|MOaJU%GB`ZuZfD3*RDQzYpUP#JAF@1S>$VWeq9q7
z(ZHkOn^anGZ|6pf1|M}Xy)!qJ^ZUx2|M1#ee8~BlS9(#-4L+ZF<}*dB!&ca}#VvpS
z^qv0ZiXZt$SR!ZUKW*Mrw%Stcd+u5j*;B5m!9HpmY+rp#xSG3qrC7|`N6m|vR?7-I
zRWvN@ZQu0t-CCXuiv!!#e=V4ke`}FWG{=_uoTq)F>|5M!s;xcKk#Kjzt~2|8hTFaT
ztjTD1&+zt%i)#13so6?>Ye+uVcVzR9$K^gn%f72@v{F7<P^oh5v+?dr-0q%9t=gZC
zO<ZbTz0Y;`tG7DlpIjrumo^JIbC%bYu#0cfyHPSn`cZzu`5k-jT>E48y4N{S=<G9%
zqaLe%ZF>=@_u<xpn2=c&dw<`)cYeO|G$B!q**{l4?c4jrDa7q?N1Kl1NA}|ObBp74
z<hnll;JC8ko>Xef7O_*7>sHCncbM|FXx4&|+I)wdE;sKVpZ|Q9&GCEH-wn5Xyr3oL
z6Y=Qv<J11ab<5m5c_(zXl|AmeZz%RzT3gzA$HEkiSj{YhNpITTPtQ&9T~prebo<^5
ztxK+zzt}e{Vwlg6#`~+2@BVi6-3GU74hKwO`5-dK&-SeC{Cj5?Jr}$EMO9c_=J=UL
z`y%&l>&id#k6TPhOa0w>;nMtH8m+yTc7_<<d?mEC;nH)rY5!)tWbEbcd))mm-e}23
zfvfx54<BVvJjb_4sdmfv(qA0!&DNYW_+|d){FSr8KPx`F$DG)_*0?`GPdw6S!5Zr`
z`k#Y?ekD6t9)B6QZuS?A=UW)2yuToDCQjh@t6I?dTm7=?&ee<7Z_>33%rsq`Wt4r$
z|4a2={iBLU-|fBbVUV_cUa?AT&+ppf5ohvkRvQ_%ZSvGH64JJbUGr7#+!Frs{ld#^
zO*-=q9j~=Zd^4$9$9zraB%icH@1yIUAHHv&a_9i3nS8#(VMfq?o0-+=MnCtPTTH4u
z@=3TRz{)|7Z<16Xm%~(sqcQiE`}Z5Yy(z!?av4(%Q^lUck8SRM{m=3JdeXa1vO8bA
zNvmB`UKiI=&i#@5Ve2}5gN27#_TBqwDxXs`e{!UHZoQ)IscSZg-#WD~m`~Upeedk$
zxoW3&g{!~3x=4Ke-CtJc&(B=avuk(uC7~wok~y!E?&c>PT<w;0+E@KrwZG8pS#!M#
zJvSC73qInyw@q!^8juM)u07T<zqD}8cCEiM{<D6{%<j)wcjaTv*L`>He#-lHclUgG
zwsTK@{kpz7{{N!KpE6unrVHQUn6foNOz6gm1`oBeStl0$=KEZBUUS|21G@~$W7ey*
z>}~nc`k~_Yam$kXiDEp_Ctjp2=KNUvX6pX9<<D<fUH_DM|GdS&1Dv1{de4NpZ*DF;
zZ?x-j#?o8+PA$52$fW#tpQe_klCJvM8fJdqq^bL)n4jDHliKx#*F=I>C0!+0d)Kt$
z$AXJ^%B>S`-QMyqK0tquoqXOruc&=9g*VCz@XG{j^VyaAD#L95?$!?rPN_EUtBMDW
zhio_BKUa9B`j5o({C{TtV3$6hv*biT$jkdn*D%ay_+|Fuv~GBBLd4|6pvoJ5dv;!S
z@96$h`$zIlhC#D5uiA2r_M`3MpWlD1k0{RKWe<A0|9!>Q2U#WS@6Mg~waReKNrP8y
zGjG0$vS{^N{&=^0y1@5ZnfdR3%{e5sZui;+tBbe4pYfz8rN@oiR{WinQGVb0Nk_Ea
zUrNb(RpVKd<<Pf*)8Npr?dBI&2CApKFTS;E@@k9etCNn_>6!FqdabTnyM_N0>l**4
z_?;_5^fa#MPmz9<zv9d1^ULO^e%*O>)vZ?-Kr8M;enmuSX=o-~{~4>2sva1Sl=k>q
z%oNiYhu=TG9SPr_|GwTYkT2VRed^nlrZPUZCl+pTmhrRpNlRRI^f~J<wo3+!6geky
zmaMoraoyHkmzIW!ANupwBz=9?w47KczrsGFtT)eIwO?NzeD>7*l*Wcd3=9eko-U3d
zhe2x|=1s1ilJB7XbxRUc@{WD~zD~89W^GyX&ER%lUU1%z#KK*f6Y>R^h1slB^r{V|
zde6k#fBz)AFJg_`y}f1SS*^R$+sljcj6jb2{`0Pkum2N|UxGrHg*{LCZQAucCnQ1S
z<HV0g+>Z#$OZq>4p;of?>eMvDvoa!k|LWe^GU3o8?Mb^hPMw{1@%0y;e4{%H3o}(s
zt*6?Gf1409qvv3T#`lPj1d-ZT-#7j?{D0@0dgRYYQF)HzZzrv=N-TX5wR-jD!vVR6
z7xI?Oy>hgs+09|g;X@ba1p1e%O<JR}as7kU+>02_-{RW7=&geyXwLQU?uuibUK|f4
zKpTQZ(<X+`aZhWUbm7;FT8{7h>NoUfNGY1mky$9<6fr$`igR6|og}NI$P^KQ2f_{;
z;td-2HEw(Ft=&?vYv=1{MxXu)K9e>%oR|F|)}eEwB4f`ImzUC&tx3x!v;}ovD*nmX
zTA=lG%4TIjryVmp8aR}gY!W1bIUZhh`s2j$k$dC5`fUP-bm#0SI8?-JF3q`JsdeHM
zho2L}&+ESn`K2~*no1alVvB$i$HQl9o|(=Iz40<=->X>9oR_mJjE)*#3*-VzD(;zn
zbdOv6)wTccbe(e%THU<)T<5XIKU4poC`p1SXxY7a#`PbKvqht~d89uHT6+7m@<uD0
z`if7FJl?RL{~y{a-~_T~-r1x$;Rib`WS(4Ndf@H3hS8?JV$+viA207kM*<$*i2%7o
zu|;6fB+xRW*?EaZYxh4+Ds0*G^VQRd5#S-ReG`wW9-ZSIzVZDkh>=b^6jn1A&kMb>
zGG<@Ywhfb?_aB+|vUkEGKd^;P9ObE7&-H`G{APP4b?;43xi;N<f8nE@F3a1Lptemd
zeey=|G_OsLRpHH=uSG)9M=Tdyko;&7@^W_OS6^|cIpU>H=7g(mWc7J;=&1Dc$v46c
z7}DnmPIR8SZ)WGUdnM3dC<yGlXDU?9C3~#f{7bmai=V+=sfZxfd1h=iW$Bc8kGkF_
ze0?hadEO(xu=e}VusP%!c_#f&pim_LLgOfpq>rGnVy)QpOXns;Pk0RvnnP|kf8JC{
zSDBsvATqd9JBK}5uhX>RqQ{zx8Ba1k1wKCp^Of1AT_#2s3=1u~9FM=;wEcAd5vh-V
z)~q`tt@SzyYU8_OuP%A`-&PKD-}yK2wED(<6?I|ZX>~i+bc;efy+e9+bK$&cM}qA9
zb>|;Ro6I30BiVcS<qngjKR(QK_TzO0#i<jAVoqvlwe0y>elbpZ$4}o2wCk*Gt?7x|
z5T5gLc9p`*hT_N2sN#@*Yrpq?5%YPePTP~(BGdLhKK1Izg3nEwN0;Wmx;MFcu5>$8
z<&BK@n%tE={PVWD>xh27%;mY}oQraQu$54?*<YQNH&>qPh1nhAb<*o$&9lnSyf)cd
z8&Ce(;v|&)p-pAmnGd_JF06n>i(s|iyN!1a9G(=x{8U@GdF9I^ZtuO4boq{QLsf9!
zEU%jXlx^NtIk77}N2*+fqL-B?{nym4XMqF-$3vwx&-CTYgt{Glg`^*_dajx0Z7cFy
zr4trZoU4sJZFM`ZuAJ%jM`fkMEagXqt1g*ee^syt>ZKhVtD6fP`#KLh>V1%r48NDT
z?#Cy^1(UaZw1^a#z<B(;y!vv5_6ZFF>Fz2m8=9}Y37Pl5P>7+~n(yJUGIJ|SCB-?5
zS1jpp-(SblP?!7Lc+F>nvwdIhetI8KUm&}$D&9`^|ID=GAI<jX|D1btwm9R5do#Xs
z^751xxj1p8pFVT?Ny)3s&%A#Ex83+C)9!OOvQS0rg5<|PllCsP6>(b}xJ-n5yLs|a
zo?SNAXU<l;f1)qhdX8*gaO(5)&rk2ie|ma9ev@h8>dl7*4`p_Fcj?!PnaSQ-@p5C>
zyU2sn>+4UNpWb)zi^aV(??=<T-zU}u?%RA=&}m0Q?ecGlCQ@h3KWtce#7bFB*mSb;
zMz$NvFPq6d*ET-0@9_;jE0vOhI31^ugSY->Oa8uTJKZk>v<B=#dOPQr&l@(+00-Xm
z+m$uTpR&y}ohre+Y;we8<&7^s{HaYp6?6Z+&AYqG;fMCFy|a5$O#hviS1w=s&Mz!F
zMZ#-_$!E)Z|Gws?w}W#;;-$XDw{^`wY)}!~`*P2f7@^lcKWEo6+CQCtd+lFCj)#Y=
zOttpc*qZ4~Tefw!m8R79sTFz?HMy5<D0s{SH-ay_Ie*@?BePC=`>Jo`^<c57|LFR1
z_MXQ#_)Zs}ZY@Zxjr#uZa<%>9)V<SUZoi2Vv;RL^L~C`+l{X>j?FyjMCUM%qj16{k
zZ)^^m{B+Xc!eIUx>-=mc2`ww&$XJ>h;wR3Mq7}MN=)CHr0Of->1vvvX`FSfk+SzQL
zyfL^lOJyS{DHf!*pO;b7)<0d-Y-H?fdxSCWV8ScL%gP%Y`1B*hqtkZO{x+N$q|;*V
zefry<w;MrO{o%enxmp{S)?CRE%3dcl#hr8CpYwC$_UU#C+|$!_pA-Sg0z33p|Mc4M
zwEb=`SY7u_+e(|Ro+Dg}UZD9RCl1A!nOAF$9-b7THT6i<VUIQZ)5Yw)g|u7By{Auv
z7+|p4dX<L|H%qaA#x*6W=|NFPzCLN49CKpV15n}RH+kOVcW(qhfuQKKYeH$`<(13N
znqPRBnVr<#@npkJcHeMywu&C6WgFx(R=S4hEj}}Q@6QiuY%#V6DmQXm^;<e8>Fht#
zIewPDL9a4Db$?nZ7T4P%)w^TiUEU*YM{hl~m{~b<&Ar{Ta^1I2oK)Jl=a9{z=0lz9
zCpv6jz3bwxy4PO&zjbn}UwHlHO6SVphlYzUo@jHHj@VainSN=~g_k8)`qmxxeVf0?
z^{$xct@I~p6DCb%a=3eA*N>ke`%GdV?R2^JCjRiwFU50wt(*JrweL9b>PqiQ@AudC
zhW_7w_RQ%gPRlMChNv&&`?v4k)V`M?r!={`xj8>@FDNT{>$Sg6H8fT@Iwa`GNp5w<
z4!&MBBb7~;)=!-^w@P#6y7;wrc2)A5b9vpEk5B3s6ccgV`XNj0an#0Y)@=SYPix$a
z80#31g!?CCEMKVh|C^8JNw374?^5UZS)SebWwVHgxPW-z+!iU$FL_sIzqs(?)ZayA
zQ|8V;`>J-eWz92#lakLZ=2y-;F~K9t{rW=x*LEhWFQ0jK{fz!8bxqUG6&ExXIW6+p
zcJjp8groCB-`MP%yyZ>E7c1M153gnfZfCu|eb>Epw__!H*tW^uJ$CKLT9u`06Xz86
zO=u9va=pGR@T^<R^-osY@5Q}#xWot=84Su2dVcAAP)v|dPK9aIwQSG-+x~L$@@)NS
zdVcAA<?RO3t2TZ;Q`c8E_r}p(%&#q`)l6BlM`w}q;?C|he&?UrW=5XhH{BuAGIPzH
z&6AQ(9{2FF_4RY)D-^uCQZ%-Eo$sz&Un|77KZ@9#&-?t+`AHLJJEnN3TwG{al5wT+
zT(5Qb%iWI_2|07V=3kfo{p8&_-uCWUVO)X-1&_2GzqBdOdtGLk@6>buBP%0MrT>1D
zIO+2FLdDlifr^1w`c^vcH~X6rw7T=``pS=+b6>{Pemdki?S16Af5E>!&ibiZD9qT=
z@oLMe>s|NORtvvKzhCQfsp!&=^5^^Kcv-p@9kcw@{i&08y_?flmf8ENbu|sAY)~!a
ze$BV$agCeN%*vTA?QX)tV&2cy=4Q&@zxU{SZ^63WcC)BFfsUt^+uo(?e-BQ1=lI!E
zXTjx-cQd|xP}z27!|yg{X_d~>LhtSRPtR6Pj@+BS^`@C!mAqTL@vM{E_j=yFv1_W;
zxr0lZ_n7|ot&93B+<LS%?Y8Oa%RS56eV(kFSAMhR(f)T!<79m8PVMRZymRO0v(w+j
z@2j>HUS^+IB){Q#n%(K2FU31JyEV)I_lO!-Ji2|H5i~+Ld;gVgudW|8FQ5Cwf77+r
z5#jxC@%M$jndNG{)${)4{*JCWD|tE{G%3Tl;c@faEvv$R%I;>{YdS&pc-e)ep5p(i
zi({9@KVS4{Qc}?7VEw;KQkNILIHTy`sqlQw?BtI>ubb>`n-yq!`fmBBL!MH$YjQ4s
zefBp0<DIkTL#_6$?6yz%wC5zloZn_QQ;Mnr)AH1M<@_9$UoQNyS=po~yW-`>_tWZ+
zpWeTxM02O!>%Fb-i*jb2Tzg$Fa!013{NHbitG};Zb|fHaQ*Zyh_I<g(KHXYz{pExU
zj%U}Whj%^~s?7bi`pmz4v!AZdwwve6-=9~0e2@EjvArStzk!D3|J9f;a$f8?uTF07
zyH8gS?hF21QF|`?&#sT*TwPo~cJ>$aCw#0u{`pbI^i?H{Ste3HU(H`%k$zA_=)CHz
zTyZgxW6Xc$9xR=xzuVU++eB*S&MdX}`c>y2-D_v8W3;*QUolSN<D#2<tif{sUMW7y
zpK<>6;`<N&xBb7r^tU&UDrieMXz3OEB)%E7b(e4XRzBW#lIOLJ&sRfV%gTo;|IJ@l
zru{d+{ixjQHd}7x?{k`8vM;Z{bX-eMGwoLV<r%wvF!!m+o8HzlF_==g_xQ&z6FR59
zlJW8KeRQ^R^32_JdM71MrrmC3Z8h9<+XJ+7)TASO!LP6U^KH+p-oNM2ov+1b>y9y4
znZG-;JNe$@S<9}ksC)aB{d)1=)7J&X1&`m%KNni@=4pJ~qxp0HCzwe2+S!{JOflSh
z?8B=S*H_)?+@A7UXqn!>hN;!zK`}{HOiTLjwZD#vJD$BbZn^hlJu`Xb{TlQ8>;8B6
zPpk0>%9?buEKo7f=Ei@=c@icE^O_kC)tSj{n{;H?@yvKr*&Oq~oFNfDNxW=jFG}tt
zKA#ceJ=45q@>YAkhbG4-^?y9_<#^<lOhJZycKb^5?#wLv__l+u_h5p?!y~Q2f3`l>
zKeuFV;<HsVLCk+Og_^n2TeiN8xIEqe`Nj3}irW>$?d9#+N+n$SpV_XIj-EcDK_F;T
z@Qu0>X;AB_cKJ8Mcbhl%{LWc(^ZM<-59MZE&&>PwakA!g;hz5KHD@MYR!=a{icb3Z
zqPByhPeEJ1d(kANLrsUYR5pZeP5UqP?stvNZ~yn~4(l&pe!D7fOYV(nS%QV2Vex5m
zK|}UyZtZ?`$$!7u-yaV@&J+{Y2{+9?tMl$(O3%sTd~+?2tbO0V<;S1<^ZxI35_+BE
zws_)XalcCj>lE1*H?r@qXjuR6=c`MP|LyzN!qzrv-sHZ685=4LD|LQKJhtCIy}tY}
zw}VRo%iid(%aR}afp!P2{;q1NJhQjm?8EbK_CJen&)2!TZ_4q!nx5~+_Pn1k@6Vq_
zHEQQ;o4<?it=Fu~4O)G2DPJ4Ieus1EYMZm(Yn92|J~-`&?w7i!Rd$l!|G&9gUJ-m%
z`oPEhOEceH3Oc2=n!_lyyCG*LQ<sKCfTJr5%gv6QI<6HwjIM!_L98k7?>gOd{<duC
z7S>(g<#z73ztkpnOD*%V3h(pJHnkb2PwrLsEt>p&&i6g(GtX6P9alLzVaBYE&2x<>
zsccO7F0|~2kD9IV+^%(^m0RzvzOpKS+d8^>k?^7&QZ=IgXa8H0x@=>~`Jip{Zk}p<
z$-Xjr=el#>jTLkn6i?fqGcUNlC#*Q?dZursI=_r)pG^;+s)5af+Uegu{{8m;W=)mx
zYq#GQc2p(LJ)iC&{yskC$tl4(yB15$2#V0o_?;B}DtxWKCA;}0<I6ifzu;?MC!=I$
zIn8yq*v9AkZDr;Zdc4+Yict(aSh<fs@q@p7!Ixu!PmC<}_kS=tn`L(R@KUD8$eA`>
zwJrBc?U@cS?fCjZEWh^teEnUu2mR;koHd`YaIGkNn8C~Sov-%F%8K@t)UUKQ)xL7%
z@>V6zm7F$xl}A=uFW(_j(kWNG+jz-kfoZjyVxAY<_SK$=zW+V^zprhq&C9E6#Ccbn
z9`bzX5|t*!nE2hI=BdH-COuHN)!Bcs*0%dU_4}>8%dc9hcs^>EwKsTv|E9`PRmKNP
z3KnHQURSZR`r*T%#++0${>9Fgb)PN5o7aCj{?Pu%>lg7gpRbuL`!>JJM@{?7kCl=u
z&-^Sm>n_s`VqagXb#>v}?%a<hACKHR)pp_sM_-)%sjClG&)Hes#&`MF=0~67e=hl~
zZuNJs(j#S$(>{l<otl=DYF7Mj?%6xO#erU4uR>S4&)${0B4XX7Rk<-1;!OGlb`NYk
zGd*?gZ=b`fZnmNFk=U)hH~f}=ZqhpZVzcP{P46GsIegvo;?4$R-R$j$l%MZ4SF&p=
z{(cT5!53?JWTAGu#JyY#@3ucJOI;_*KfKCxh^eCZpmYrHKCXu8yT$j;`ugao*4Kg!
zr3$LHt=9c{#ScC)=GpE!x;=Vd>d{8gHIiGW#htBsS+l?8Qt`KUGZ#tE2-h<7l60Mx
zr1wiS;o#Dy?bA(_!z|-xuF9<PoYb{v2UlD9pKFEp=KN<1><o;Ej{5BR-2ca}{~=mW
z_iTJJb?V%s=YQ9yJ-Wr|a>V^Ya$fm5y<N+`c07`A|NmgK=zJwlA=}yCQhqMC4_;fd
zHT@QEp8X7YyFU}Z9=~p!^i=%F@*~WvF5dj)_q4FQX!#sx%RRPxKYsh7_i0Y1<SPCL
z(tbG)R);2U*tFr%Wxe^I9NQ0?tiLL=)2A;eNJvW7%gL)L?7MTc^|`kR4-S=s!vEH#
zS%tO73|Bp$Ua_k}?1r6@;w00$?1&AecI<lc3*KHai;1sser+Bcd~sh~^}ZM1SR+rV
zFTOY1KVQwtP>MgD|JT+x;ZNS~y|dSAclXgr(r0Qve-8<hi|SmxS9@`F|HHT8_rll%
zX5O61;>sc_l@Z6i&+YrpyA>jzImD~Qmwo%+_V8|7a(ZyV){Y}rT<Y%pRQ|mET=L0x
zsw}Q78#50*3*t>t7FMcEuCw>MXUFNVylw6b;|#sE@fooR)%#!9@x<D-{1*H!`SrNR
zs;TRjeQw|UV@kyu-L;j!k2Aj6w_*0Pt+R}?ALQ)Xdu8o`18PQ!lh)TR`*8fBJx4F!
z($j0s#Y9$wE{~jDo%sEQ!QQ=9&z}4Zzn^~Ww(-iRk*g1U>s;CS<Hv7<;=??<&c8f%
zZhiU75_#Ut!=1b}d)_EtGP+z4V(}^T{rVrTzHYR*ZE1hm%+hw|&j05U|84tur><o7
z_5H8U&a6x?^$I-ed)~g}slfX`Kg>?PJo&0vOibYY?j8LT_xCFp*i4xJ{lAap@uD+w
z7VgV`TmHU(^UNIsW(NLr{%7?Y8p?0&3C_@Zb@jpOGq*p<*30~Bp0Pw?u2F<gknjt$
z=ceme;}0La*7#FiCn4kc!q$It&)u~?{%7sy8%1f{^16Q~n3dkjn4?)+)vzY&XI9Pk
ze>R}ldQrQp;=hvp`{;A4lvmH#S0|<U@?_2Ld*!U#c>B4R-~Y33&dHw}=FNV3aaGxB
zrrYxSs%9)a-7X*_dS-*@{J_06rMpaC1wE;)h;s5`iZqM-GWR<B{p@{T@~+Lk+5Akz
zia}0D^pN>~pVYe>OI=jmE*9tUm-*j4y!vb0)n9YA%iUY_drlsUJL}^m1xa52*Gt|^
zPFW}^a`NR#oqJnn<eUHRkN@`n(BF>VIrH~8CtFoS#7M-Zmn&*0ahSWCi`DL#;h4)V
zT2=dP|I71te2XnAek#1zshK_DzEkO`8Ue3<70)@l%h$bddlq)ZbI}Q{FxUD|XPzjX
zch1@)E3iJwpw|A8ovHQ}ld}F6nY!zLUl?w;emV1{$@;5v>i0#(zhJirID4V)=4WrM
zU13k=%HLPB(VKI!-uKaW{eKrK)>-$z`*1Y>@I;l)@3;0Izoq|QtH{AwZ}R87-Q}4P
zYZc!v+oq~$+PFPx|Izu%VJ}PMFB@Iv=;luTkw5?O%SR`_owT0kd3ws}Csq7&YS#ZW
zdeFZ8#F=wTR#k_7tJ}Q(gk*BVC%>nX_tR~fZ}X>pI~KWR-EXg%+zF0f4`$z7{xjY3
z+#Orzk|YyTo2(5<H`cqoiafa_ZAsCiYn);^(GHhq`QEgvJZ_xX6ebpSWnIMX1Gn2<
zS}zp3u`d!{yfS*H-fi{w8e4Mp+*_56@6Ypm-ZuB8`Fj1^=X2AawMm|lGzriDuD$-q
z6_+Ug%9#f~IK;e-{aO4(>({my(NA)%uDow}pJN~8o99^(V=@1~RZsP4<_#M+UHr9Y
zBIiV&|6hy0#osz_o?m<T3!`yY&AaL4TIWwa+#h^#t5UJ~*{6YLl-1Tqo|jktcjZ-0
zU}s>-yqlfwhW#5hZhAO>{k3eFn3KNh?`|*B-@E^<>;1~wE&J-*w%jT=b*`6dQt<>O
zDtq^JT15*k-a9t${k{3^&4(st{;xUwbirwzJ39lGPx<>}N`>DYE64pmYgfLAn)vrJ
ze}+%}`+G~Qk3akI`PG&(mNs^y{MR=3vTPk*M{%6~t{cw2;cZ;b@oS#9P56>bzGQWr
zpRxbttska#f1e8X#n>*oE6b9WH{;;e2iZ5GZf>go)#$`tTD0{;-oa&@vp?>BcYN^-
z_o$`6`hFH~v1*XLP{pv?ZJl08gLe32Dc=aoKjn6>ei(Xx|8pcgwq5jwo|)yeYw`Pi
z0$c>%^}Smox3z7aZ?#zEn{&L@kF9U_Pn#SiFjwO2^8Gc3=BAdHM!lAvD{=PtX}d>1
z&OX+W{3N`%s!wZEZRqz^pbE&3*V?$`r@*AklPk+VDy-Ar7x+No%;iIm4!y8g%>1zM
zVMTS-=Gsquz1iR1=DwMEt6poablJ17@2fVye`L38&FnM$^8X^9ygjyF(mlXMK<}I0
zkF$1B3BJ91ZtcC%_xCd2hTn(sHcg3CYA{t~e8~9fmU^qv=8~jMnl-(gv!?y8^EDAz
zb^hOsCCjfJ<yyA5F`W5T*t*jz<}Lm(zk1IJ2D9~yYuODJd}Uy$`BQ7M|3l-;*UKl)
zoa^a&z3Y!z&C+YepLq95ZA$p?y&)?%>)kD{+@+~YjH(~&Y?^xW&EK^7j@LwwEk9zM
z^7D8~TKc1xk2>G$*!ME##L1nL)A?Pp^V-Ywro<(wOAHg=R%C^(IJqzLcWKn~WmBfq
zY<c4hO5YEH8vkDA%iu})ob^4)I;=OQ*GKK~Zr%G+Z*5EM<8rsU^4{Th)mzK|e_4AO
zbM*Af_4mpDVP@b@mfQ66OWNFXzb{_m2gU5X{BK6p4`kM|=cnzlojmQHE@MP_j%;FK
zV$|JttL={q2#Geus9o1;IJ<gLwriQ+&D2e=lcKNXdA{x1`t#e~_c!b++po<untXqT
z&*fRZj6YKUpKo1vS?|Qw2iaf#Z4+OArLvX#{{Q7)OSc8>^jahH&w9bBFOi$FH->HJ
z=HO1a6fewpwd&2>`1hAG#r`eslQ(?-_vb4ed0(Mm;h$d{vOeV2-2W)Wd}EK*mG=jB
zzrA<$M&A9SwL15gOZ}-{d{z2K&(G*&hS}k>cjZRdmpLyyxM}rX?cCSfmIfd8oAdu)
z(=i6KaNd5YGu8EW4E##+8~(m2Tl<^k!^!i`AfNBc{B6p%p|bYIL+7tOpBB$>ulf8v
zgm-(u*=4+u{|p}%KHOosYh(Q{#<^YR_Wn6^dX4nk<`}i~i|btH>?_`NVcWus3)k51
zlWUmy{>&wb1JACmj?`bfer;1?MvwoRizcR#*KAI7I&&{Q`-t!JeTUFB-KLT6`rgI-
zc_`%F_GiiEHJk@l#I0K7^m69QHx~OBpV+4PQuEEO1zvll@4e*~xwcDJ=f{rA$ETEQ
z^{aUPDgGlrH&0qf^ibCQtDq`NbyeA#?wiu-9~FW^ucY5xe%ke0<4lW+pA6~m<~{5e
ztbY|V<?!<v{QIugFh*GZ`JN=|`ug%B{`_rK!b_Jt*?so@tD5TEzyFTP|2X&Ubodc3
z>GxYI+qv{a8E!0DSaJO_s13O5qMeoaosAQs4L<gIHfT+?{_dO_ShN1;qsQ-=4_r9s
zT*{SD9I6%G=__2qeT8>v+|;T&zh0V6zCUBl<xjHQJ6YpP<QZ42o9$ZLP=D+2jCN2q
ztvn<)N5s$S>-Oa4zE=wh4xi+86-zty^{M>gE2W}g{ZWfQTQVN|D(U`z`tR(k*S^ov
zUn#kgf#+SohpPXRPMkXT=yQC#qNmV2y?JY7{#CC`dAR29Cw;!N7Hf*1UHrX%-+DQf
zAK#z2&CRR+^)B<D%*L)hUaMCn)(soi_lJg0`S<z6d?|KWv-$Vd#4-OqovvN7uZ^*!
zdZqOHZPntQlYZoRKfHeP@APkrr%XAKT4blw`n)9};<-tvn%P;y(~~rcY;`gOkDM}j
zqCC6RCiJ)IwDn@Adct4rS#)ob<K^!EkN$QqS+blVW6iE;0c~#WU1smN4y>G0T6ODI
zNtN)tb@OWe-Fj{{f4jw`OOt+l?$BDg(R;C;>bhN;Gx+4|<*Q8JhOSXk?k?A53VGdH
zZT>p;ja|>nzoH9%Z4jF&5c%fu6gF*cZL4eHwE<Tno_^E}{_TG@+%-mg@9eK(>&0z~
z!;2qm&3PZ>Fx4sI#x2KOiL8J#6F%`Nz4#<?>*kG(uV3G_(30scz4veJeWnoRd9I-a
z?4gA_YNv-Zp4xD|?WGCxw=Hc^c5MqU`cHaRqFc4JH#dE|;GAHY>~jlts%=~w7H1Y_
z_UhE*=S(JRq-##yxPJVT-|X_P(l~E!Z@2GK%qyl9=U8oBdE(p7>o>!;MrYbO1Wvf~
z`pr7--Jfi~RX+W9@8mhp)h6i&w`9)gyjsg{G<litpOuCkS3@LE=|n8nde@>g<K!8=
z5^tr2JQGhpdBxA~n!AwUiT6kC6%!_#t(v}`FCgXTucjsG%RXmLKhLwxe0Kl-{;Dk%
zGa8xF4;oxDzWj5~?Si@a<<H(p>fPJVabS6@y>_5{+{({fPv@RmJY~wOSI3sAm}^vs
zeD;Xd4U@iFazpA#=Cx_pUNvl5k(=TW8e8`K=Uj#_^*i_9TRm}lY3Q9*E3Uu1TN&}C
z)K=d*+xn|cO`*x^t3H2g^QK-u^rtRkX;t<#|6MgvZ;D?XI{EITPkw;QgnRw_A05zd
zSQYeh!M5fvbv3moYIE6LSwwfLp1(ZnN=DS8&-;FUn*Hig<ZgYDIG?wtnzdggmCP^s
zxy8lRg~?Hs8MYQ+_O%=@(d}9ula3tJX6MeC{CiG^f2aOOyBAG`sVS)$af_1E9M_nA
zT>h*i>1nZnF!w8VdsF4m#~P~x%63?<4AM%T+_kUa`C7fGI|)YSTfMHEt7Us<x0Pts
zbj#IRmqdPTd%mJzi9h#coj*z<{-yn|j^280wY|dU-LxQ8#mOf#g17TB9A77|dvT+e
z^SuQI+mqHRJ_!rHzQykUgQ?B0_A0T@%Gi*Qv-A4b9U_Nq>ng8L&#vP69(RX(MV6IB
zmYGey>fQI-buYZ$7;GE_>NPX`jrw*uQ+AD_<m;_(v)-?|cTTI^V1vTW>ybNs;@+(3
z+f(%YsO}r9+dF2h@}H!#G2!(eq51v>^SZz5XUWYlJUc!0W2Rtz7GILOa6?Po_pb)7
zl|?6u^{+YIOiy2175e;LYWR#jum8&(v(dS>vnaT{<gWdfsaET!WVAVi?^HhMn`Lrw
zWz*t>U!ca^np&Oy=WiUNmKV)US|0su>hH$=JJv6~l#>7ZNz(e4yB7HGd|5N=+L^g~
z7kf!gKAE!T&!N*x@2%gYVcubM>@oX<fFsE>X3RR#J3*RZPt5It{&?o~Y+Ke}mkW4X
zYM1vlV(qneS&wTDRDRtUCAR5mujYy0xBUG4&0g%34hdb`&D+PNS8~nxyH)h*&C}v8
zZPeZ^T08gcg$2!4(zyq}v7WhW623esqv_=ZiRl^#)|5@2=#gOb-PH8*9<BJcBQ<)A
zxAGf8#h!8}{gu32-ShF6(u>}0n-^`>zIN==p-F4r=+vzLDVF`^&ih^R3~OKSS#<er
ziEc!wP-0=CO<yg~3avD*XG?dSUwWscTAN$D&iY4m=kG#$r?2;tv$B)st0_vpiP<SB
zH_Of?j$;qQ3axd!ZtR{?wf~foWZV7Iw(lQI2nrIr_3qK%?pOcwgEpsRuG;mh_=(mn
zzud!*ZyeXTwYB5z^KHg^Zj1B0wb|lwe(8Uv|H1Y5m$(VnmTbN9bXl=<SGk{Rx#y$`
ziN6~Ttj#Q1zu7FztZL`EXYX1BrV4~U_<uUJsOH!o-{UW3JAC_6fBnk*Q~W32?VH5W
z2Yk)G+p2bcSaXMQg44`MEkh$crOSWV)`n(U&g|JdDdm}C&OG%4AES>?R9WfrTC`=;
z(VORHzSA#Fzup@AXHUMR@~-|1D?dFt_t~10hu=kS^5-x=MuFfd-_M>q+^~6nQ)ahk
z7h{P00sH@3AK1!t9}alE=d7no4NHUHZDr17%HKaSAGU8ZwaF@YRImQ?!Se5xg|Ar}
zA2#|#SkIG`UUqr0C;zW)Z`|Lf?JecYSS&n$PkzO&idVaDrzyUl^`zxW(`51D^_#CZ
zt$+E|N_)EayxPkvqLlm2etq7o`o386g^;;(zERRsai2)@nQ>>UF0Q{S{Uzg)b1X}+
zf$b!f!bjIS7fH{&d04&q@+}_c%&(fUoatxn=4^H_m7Tw;N_f}jAAF@+R}IV7w<u|-
zs$O?qSN!^+?mOFk$M+sD=j`QFRa9+kxxyk8BvdksbCzj=8T)#fC+{Bb_WAoe`&s>h
zySo;3{NQl=YbO*i_2>1}{h`jMYlT@|wmLBeoaK48YzJSKbw~f#9d^;v|MGuTHL;qa
z&A+Zd->1}<gNMJS$k)SH!RX$W^!DOl!THy(r>B*vO@9~v=-uPpcWP^<SNFdcl9Ts~
zDU#t_$*HnT?HRX-ukXE(p!Dj)_H9>fR~46>Gc=oj?~MQM=>?y@c?MkyzEM+UJljA2
z*sV*m<b10PR@~ja=iZ;vwc942jt)LF<0hkGpkfT~zEyQ`clvka8?Ar4=d^)P5Eoxk
z@&CU3t##e!cfHc@s9ku8+x1`l-&J2Nt^do|{j<}#y?F|Eqqv8M?}Pb||9?3Du|6O|
z`^Du&{LQ!ad4E^Cd)0Ln%jJU44}BL2anH*QH{R@7s+tj66}Nk(nreE_guTfX-x{)J
zoBqlF)va)i<!M|6f6T4(7hk)7W=-8W=k1)r5Q|4S&waeAx~{!$nsp`P&?H6sk3ZKR
z{!#b)yUH>(P;1|{FCdO%&w<_DY=SbPK6|ykM*R4=DCxer^NG9e0s;9y6>aY8JQ0hC
zjF>oaYGeCm_E@P>!?Nimi>6F@^EY4L`dseu@3Zv3A9`nd*)4JHfs^Mr)mw$-&dI$h
zNe`YfXIa$g<*(zerbb4@NWAV_`}oAw!$0nS&@ZrEyn3&;Uzy(y%Uy!=h1TB_I(y}b
zUEPNzYRwBzrWUbnkvq_Ejk!YLX9H*`@#U5MF&ujw+``yEec|6b-|n#9W&G^xdWrk#
zH4_`X_kHKhKD;+SMSJtj+C=l+=iVRrzDu7mk@5VNjhi<f4t&@#`B3Mlb5A|{4BkZD
zh`F_7c64;q<Y_b8W;f41xPJ3Av1v6o9y;5-`Jh-XcQ^5G=hqy&t(~h6hI^j%NIl%i
zn`5!D@zhf-<AwKK+)CsXjWT^&_Ad)bvRvh9QJmD;_O~Tu3wM&b@R=Gp=3Sv{G_z$I
z<{a#MZ2ku{eCqbL@57PDH;$jVXTdFBFJEfde@is`^5#tcS=HMY_${>x`M$#M>!+)q
z*K*73_#kWcYQx8$>9O{QPhIK?+~1#av{5w2YHQ~~S+>tvd%uNf$Md#sZF;dJW1ZcO
zQ}4KU-zZHKpQLheS)TN@{<{f9)z58p-)mGQYWg4geEjIW){Y+>y{_#(o@r%j-rsdn
zZ{Az_O4s#{>|M}sv+kbgOBYrvnrdBH(B|G-vw4=?Kf9U@PimFFMj2N}S3jEc*yE(Z
zSq0zud2RPnt{t11W4*h#XARHSZ5g`R+n2PKd+)K`yE1SgTj<?Y&!X>LEU6Jbd)rsS
z^WGz;WgjHMwBvg_|Ed{nyzkPqxanqDnY1?lzhhq~ymnD_`*`+#@XeA>@n!yZgEImT
z?O8wn$CHYjSTFMlXHT3;IQdRh=l*V=z2>=<%Rhkz6{c;CzIb3Yqp3|+z}>}F`}VE<
z6npf-)3()L=7-<QI?-CoS5R7@s%Uy}LFiWQPfkn4XV@iJU1s-r9(Tib+njrcPC4%v
z6c9Ubct(5A&tj8kzx=e<OLAG)y%pto-Lh<v-?xM`;og49?yykBt?^&jpEG>E*Z+8B
z>Bgo^P>(YHpJCUICl;qHrzB_nU%BV@yS+i)p*7E^mft80GYyiRE_D3RT<*vn#fgo%
z+2L!>hOh5`dRcG&w9dfOd-6R}H4_BArmx<sE%;GTYCE5yXn6B_qaVxpcgU1Ta_?k)
zzqPvmpsd}J;KP2Yk4hs%+*_3kPZp{ym0I^{-9pbvNA|4!Jmc?solC}-KNfv|)csCb
z;!0V-KCh3d6DL19dCMcXnrH8wy+1ZRpWgGzu**4|&oKFLiQj$8vr89vm(2bwmHvFb
zwt@5Uql*83yJd!5-Y-(pdC<Q0z}5%Z5hrvd?$jAHTi1BBv&nXaR^AQxv~1#TD-oF=
zJ8$g%pzx{DGd6v%?cSL;@|7O{?n{6EbFR<-bgA&>^+j)v8U8x^`t-!eeX0LuMP19B
z)2aKjjcJ+dqb=KfxAG;aUfmV(nJ-Cn#XqG;0SUPihi9}e+R-*~?YG#o7v{GscnZmv
z{g@zc9~H4`^W2G?6HDgYYg}+b!K~-D$M)&F9+sc&Kh3WvJXOFm%1!EA*}0JKD;#f&
z-@bHUb))D0jdo`*Ulj(AjThP5T)1&p(B}yE)VK%V7T-=y>VIS1|L#I+TDp?3QfA0n
z!PV|-Pi}Wli+rB++=)ZcMP<gjUFRpw`gY#DX7|(R6eG#t-~LZu{|i2=R%?~N&AXyz
zhhTM(#Y`W!>&IeW-dLbK|KBIh>_68Ebbm;l{-&2)GymiHE$6MBtM%W^J7zlLXsPlS
zw%GJiMJvNu%S>l)s(K<NRbi?zwfN=j-U+W8v{H9O{mf$Bwla33+4N?;;-?2ioy&Z+
zi)PN*r~B*D+ogGXK0m(w#%90p|Jnb3{P=CK<8MN8`TL!sGNNaiPq4e18*N_XH)-1I
zM90~+N%JrKT97)er^cVHcd@+F%3bn>^Aol0oF}QYmC7EQuN*cti(&PYDPLw^pDw-7
z{Db6YbLJ@i1D+3E=8M(N_;$@?8qd$pc>Djotj+tMcfX6jup(-)k?4V@tZ546Y`^d9
zEnZr+ZcpajU$@p@m@@V0@86%e*D_v}PJ1Wjv&>_X%Dw16dJ{P(URfVCUwL!QS*?av
z^`jf!+3j0hS^V4R#fhuRps-{B4bK#_oi&}!AofYz_%v^h&(x)@s{484J$d`37;<bj
zE<8}S_R|~Q=&1M7lT-{d9y%-%UYr@T*RVZJM$ed0=RhmN)oT&@q4g^-R0;3A{oeJ6
z`;0fcYNEBHul0UAc=jT%#ve;XiMFu9j-6+ZoZ1r2&%KLfqfmO|A#-<Q@ydBT|IGU&
z*UK|`m+7h*TML`Jn?K`^3wRYRmutPdH@MsnR4{^C)2p5vEekKY=aJubPen&>&6RVL
z%iWaTS1A@x{r>OR^o_rNd)-y9mVW;;zhAIAXp8doz7^jC|JHrrSKH6F*Fq{ZpT{Ar
zOzgU^4Tn~rd|3_uif#W4j{m)}_s-rc=e>htx6htFwN*5K-ygLFryR6B{;v9Z_4@W?
z^S)_b_TS>}oWA;CHG|HdjKG<<lz+Z^yql$Eb(i1PmA98&C|g_1#?AQc-}dcSeuu{N
zak*ESz2y}7H%EZSIawyDJ*!;w^Fo({thv(J@<;sC<aR{Qk(;Vn*>vM@IKT9I`KGEP
z+rM(J{k+y#OV@q<Z^nRwH}`z^uie|471|IKwCPrP>B_mwgLZnodjH;LS8&#IL(y+$
z-(D#xm&;9G`}_8`yy#WcA?yiH58m&&JyYpPoUo3r&dVzsCQqymw)%9g>aE58#V*HB
zojRwLS^h=uyWyKlE4*i(PPrKNF8M|M;r$1=e(eg-+Wht6Ql*{NQ`x!hUyszAe0g=I
zKEt1NzeOV$_be%zFK!lQwkPU+=wA8#CVxvybSEvjb@kKUaBh96>zm5Fv%=T#9ysN^
zta>hMsG_bwb*=R5V-`p5q$NINi(gcFHE`}d$COFmg7>6OvwgMy)Li%SD^owR96lW@
z95(5uSnMUM;^2lq>weGt`uN`FO#iIPYfK48|HXUduI^GZowY){Yo3PV!Y!A}{ie@U
z*pd2n8pE8O#mjCmy2KR8Sf87!Q*m)>>zyXSyP?&x^Y@ldYo5+8_2tj4u2VO^-#mD2
z;f-p^w6xS$o4u>9FRWw#%5dS=<Np(4n-tRCyjuU|s_xzsr_Kejm+GmmsG2o1_g4SI
z1KXMzLhVae_Wj>do%lUsTlvg=yFypAUtGu#Qn)%OWA;Q_cg9s)?jN=Ox_@fSyX@PZ
z4@2G@I4QCI?TjT7b+#Y08O~;#F3&u>taaPe(@%O{{ZwU`-mJIz^&!3HFB>i7j;-iA
zEcSJdfY<fE9lu%gw5RsZWZh`wxqazsE7px(vY)1$UbFn#(XN{jj|<C7*fq)=c0M}5
zHMgnpoo^MxD)Xh&CP#gE+$Yb;!ynSWVHWpJpK~{^A7@;(|7{QNW$&jp-^{-4iTR!C
zFm+YzoU9Y(PWc~xmGAxhHaH?GM<+Bp%3J74dDacdh80IvB-J{2p7mJzevjR&EmqFI
zmYi09<y3aK?yt|@sZ%vIr*HPtwo}~~aenz}$LTX48Asl~dujEZtkVmmJpQhoVf?te
zTsQ6N#85TU+nJe(o!xV_d`*@}Trc&UG-F3u)5+zL`!BxYl@VR#KfU<h+}Jg5&pZl#
z^wN60|H|-*(^WeEPXER%GV|_*Rb|>=d0uugYg^R1zh+t#buzYDa<WM9n(XuSjsFeb
z&d={EeRp)XnCNfYv{SoIx;$ffu$k@LwHu%@+Lhe)wI6R6OunP4psd||I6P#2t+mOE
zj3@VO_VdMBF4;M8ChJD8oq2`J^4{ka&FimC|74@t7bEDnW+P}$wqf#ie<8W$wNu@f
zE=hT}Y-dlzPu6+s=0)9Km)zWUM#@5ZrjMIT4U6!#zT?#{x+2XvD{U{$=DU3R^8erF
zKQmso_x!3=F}~)Xe)C>xj@{mwleha%nlWp|=US6#iR*cT>lGsRWEXC{)D`}F-80Z!
zmgU|LXP?@?{H3{oi)Z=z`O7YU^uJ?uFnjavpo2S^<`y>{zVzhb8%76*3Wtr{uRsmg
zH9Bh;X8iho-AY#7MsLo&``;cpJz!n@Ch%>}^E0a^uAX=@g~gTSVtL&Bq}mxh-hIh`
zW)+^fW8nP0_RL;2k4Z<q72hu1wf26gz17(l5o(tnt9_fj#P9iRkb!I0PEqO1-(GY2
zhw0-P-w)Q@nR~~3_3WdU?nHl;c=t2E-*0{Ymop`H(H}Lt%XGD_>c)LJc<@@|%=c%Q
zLaOJ~?@OBDXZ(s^N&Z5no4Zi3@K&xKhC`1I-6$)YeXe<(-9NiKwKd{9ea^8<t-A2<
z+fT1IId1~Iyx8<=+@EiG^yEv5-TzXF?sDC_Xa8qC-Lq};)SGW?_6IM2EVr*}#yMl_
z#MI2Cm){o6<+nJWzQ1PG=lk!D%i3@Hbis?^UiNo6+ak6@-H#GpAD9)GJ@NFD7Pt0K
zzqaq~7CoW1OwB0uZpyxIGlMc_FX&MC7I&rg?b}bar#roR4qZDn&CxQFwdtYkMU&1n
zZjtwz`MXp~R;^eaEin6x>4Fq)n^R58(~{2Ss;yfiaphgCgQ=FqtNw`^s%J}&HZ5+d
z%q<H~%bjy_lA^ugvh8^<OD^A=)%IRzf6eceX(_1!0%8X?N*}*bm8PBDzb^IXzNcqy
znzZZxmpIxWe{a#-D`q?R$`(FdBBpb9^OP-TOzys0(|9tq2sBHwyj%U|sT{kXl^Vw8
z=dP@}pIDe!v!leod0PFMWtV4Ll>QD`n9IIR(&O<QC)3m4^`1}vyFbIGZky5UpSPb~
zE_7pmll#Wf;_-wk*}%+Ge+8yans?}Zd%gY!-z+z+%m02ZyYMB=U);ZR<E+^W%`59q
zR!1$}BEPR{#xmhqpl<IrpF3XjrybMOxwbS=JdJ-2bHjVncq^a$^FJFtN8L5EHJ%%~
zZ}kfEU#?>BVot1QufJODxSsE;^@{ZF<$pi-hBZgOocYox&b(94*!uE9NA|M%++D4!
zi*{P>+E{Ty$iY<OLTQ-zx7a(&Kb8e{2JZR$m|@?~YOTdpeMvR*KdOZ*Jij|9@>#nf
z|IDq0%fhzrlqs1xZF1Cxe?O|OzFxfZ<@;~utBz|#Rjr;TzQ%szJjZS}p{Wu}KbBSh
zyY1ZFd3L9K;e6ZR@0TvDUU=-b$D|_-^7kH{WzD}(n`d6CwL(ojZ|;Nc`)$kyTRsO!
zg=UAO{1(^Rd%)j$y3*v69DQ8N4uAO;WvlOKDsi_ch`Y}Ehje$DZq2j3%e)usy*k*r
zzING)bo1^>(`Fv~Vfy%m*>BUh>_1Ys)n1xyn7X=r^SwW{fAa6e+IXza4lAlMN)E3-
zdSt&E!>WT@m(I_a|Lt$q-td{<57wj@NgmIaUH*4V_||zh&z(4xaCc+r73sf9pSPcV
z{@r=M_>b+UPMlisef!=QU-!@B`SDP9?e}GOKi`*Iwk9}rb<b;KKK*k2weP1du=nyj
zIdQdnS6)im<_!)a!aJ9q<}Kk)N?*jn_5Vngo=m_}(Z#<G<h@$y{p{6LtMwlOkM}d&
zD9IB3E50Z4#fkS**~2CFr^)c{&pI%5fp*T!9aAUTy1m*mPuWy?>dDt?AAgna{iyZ+
z=rhh}k1w8&j!l{^GpkTyzG406(;GxV%N5kV&OS21&lxmqp}Qyg!HNPGO-)Prf_WF~
z>pTyymnwL@&~LqK^Xi9z%>Q>DUm3Yj&CB!To8HYCKSG(G<<CC9wtf4jwJ&{6`#iqU
zo6HmaQPQ+6{Q3ID^@-W3r(aFXesO7q_rm8Jwrxo}yJG8(8@m@wnF1<=Yxh;pRSxgB
z5x#S`f5-VrcfCQ$aM_yKKEJEpew_Q%-Sv9ct0vE-nFZ|!UzzR^zSi^nd9D5G%M8Yw
zj6hyLt7h`Fe)j+H6t7on8aH2+k29Zt&*$;R-iY#?yT+_>Nt2U*e!sH+%Z%G|*KOXF
zkePV$UnYCS+K<_6JNLJOCT_j$Bimxsp6@^KzoN28``)j8_ICg5Y<enZyss3TFVug(
z)Lw0ktpC;Xs|-qh3LJWLC?jgK=D*_p*R~CtwrvTk@8Ij?dU!SStwq64heqb!hlLM8
zIiD^5>ht5W_C^cev;33Ye^P;2>6gKZw+dpldn9K1xRoTC*#5uX9QXhA$z92>IXbxl
z?fEocYW}$Y<@xH+<PZNAiQPVzm;7$`|Kx}6t4h1qsYX;sN!exmXUu)QjWyxkwaT7|
zpRSFem!?jdG<mzfQOQpM&~kyIDkJx_pP#BeUtbx+cI{<kRK%w0S8`v)0%rT=E_%1Z
zs^+b6>*VeJ&t}(h_i?4Yy|@+Bce{80+o8KB=O!2b$$W6tVfFP1K5EGx&lhT}5tZ3f
zGr?+cT*8x6f_Lglb|3hr7^nyuiu5zKnlxpa%kQeUKQmtht$lZWf}eAQZ4vJ@v1vA4
zl}qa4e*O3@AUMB1|M7<%1!i+@IQ-6Bf2k}>I<M{ClDwz8WM&oqn3<a)a*gZj=f93m
znB)E~i(Pnnr`&P7w3F{tugJ&ttL~m|@bs+aALBCHd-Lu^-ECjan`7N^R9-*v@yXsR
ze>d?x4(oq<Wp41#O+A;4FYo;HfXmqY%z}R}s&wvcmGGRD@$&AZznA%6)U1`hpKi0i
z?w_<+5%)Tq9Zs`XuK#fCPu&{ZUDGbSxKMNbX3G_pzIzs@o|I1hAQd+CpnWZ9gu&!X
z)`^Wf|Giq%yJwBg8i`Al8ew8#Id*#`-wSS?v7?O1QP7d~8)#sn?f)-JP}1#L!*eg=
zYn#<<2ZKG@{OdC0P8jZ2_-0{LGRt(!m9IQPKTa>0zHYmAuucH$Cd-=(+t*K9`}fqD
zlU<4XCrz4n=-6cGn{|2C*5}_Zsk{2?%DM<??wza?IVaw!s__1+_~LHa`%Nz%AAQxm
zYn$Vn#WURZY+NA!{N3E-H?Nat{y)f6dMoknsnV6vJM$)P5BKu&yK8sUfA{nc?^o7y
za&SM`dNX$C#wTig+m`JXF4a9BHD_k|G|*~}Q_k9)9NY<~cAfNzG?(1z<5&6o(~|UM
z&!y*1JDIZQ@-x|Id+qmM@V)yvD`c(UzRiDL{Qo<frHy^l>qB~Fu{T=RPSt(q_wGi-
zO@XNbOaBEd-w?JT;luZy+S)Z$w(}Rqz6@W!?qOgvt9;G*9j3{ir+t#2yjPa^`J3aE
z^;C65Q^&c#Zmft>uKV%fxKn>}cIxSalI<1wA9ugmwW0fVf1dG=<@_5aL_c`<q_24`
zv*t_9pWl*YuapU#wu@cIXVGI@ZMNt)M^x4Jlsm6B%Iq(lqno~M!_zZj4qt!lzOi${
zlxbgl8t1-}yDE7<ooRmQUmshA1^M|~s+yn9|92*Q^|6BQA7gi&f9dwLXliEAVot7X
z){`$!uF};%#1!D=B~@km<j8jQtIXVGW@S4pcV*fdC;BX|?p?O3I`r5d%UKs*1bmCT
zGh5&G!ntF5_od#wlDm4-E|vZ5>#gDc&)qn`bot5DqHX>+9q+&YRq*FpA?Um;ZT_`O
zJbTqZLw=r<IQqGtSDh$Lnw$)p-rjXRBaMGf^W0w9fU>T$J1ln<R$LQQTRZo}eD{AU
zYMO18(a#O@U)wm8u03()T*z{%)2T&vuYL&H^Tw{KyMLif;L+ng`OBAft3JNoll*__
z-#>f)r`O&4Zyb7O)q}S$dsjDWb82$3xU#M6J_;Hux?Ih3f3LazeY@+kYA*bPEGN0|
zUi9tW&6@Mx(b~~--p=*(@jdhXPDzl($I|~Rd)}Gux=_rUV?1F+i^j3Fa;M+AZ+~gE
znmhE)st-Y5rw2r6dw6++M&Mc6*cVNiVzTbujNtoo!}N^{HkKa@d>FB2sqNybzD0RY
zcfFeO)pd7BvqK-3`x@P~^LNH+tP%B*Hkeyjdu-+O2`^qvJ~#iunl$5MYvsD{m)dWe
ze|uj3%$C)AwNJi0d7kG-Sn2vxJM11y-pj36_<Y*Ql%CpJowsp0%lGyD-|(2d?#4&v
ztG26xH#_;pyou@X?E@_+W}nE<aMj`A6Z7Q;Z`Wp~CcSLkc`3^_=ViT)k%s5-kR%N^
zf$kRjrMqL7XBIs26sUeGu(-O{EUSE8__b-**2wQ}bbNa+_2#^#pwc+&!_}JB{5`gN
zC2uCH$d^kwO_uWgba!9n+Gk(tch*mQJu&D~a0p}i3*I#TIfu>jU&hHe=}o@8EKmB@
zm0ag;S$l)Rw=7PJoqv8lF~4SJaPNmq-aS$Q=N8V1OKY>4W1A7SS(0JfHP-wsaT4b4
z=5_zxh`W80IeJW3`bK4)y17&Sgn2X9`CTvBP`V&+t6NFdjn2kg_Q3UCwsX&2+)<Uh
zPJiFQE@tf;6-mtL@8_!O8uwn9vuZ}s%sFgvycM6H{^P07{b8JaZ<oodL+?KCUJ<;r
z?^tnUbkyqqVxqCyudbXo+<QFW^k%Wm=I0*m|NURlQ)nXR#1kn-QCIVh9-rH0u;j8p
zFXODmhbGDfmu-5!-*%174{6Y<YfIaiA9fTR;tc=3wtVwFp6a)s)3u_mt&5ob&Ucrv
zr2NW{F=9pBU;nP1GC6BCzwVysf|7HFHS2$FdfoJDAB!u?#EDZKbBc5pa4nLmGF_7W
zcwI^LN^AZ7A2vDK{Q#|30F5@(-TB9S`&{1R#50F$G^ae3IrZ_`>3pLNZxw!-y#IXW
zenHKB&K$d~oUL0Io%n2V!)nF<Z97|^b)8;aV>;_<&a%(<pPvoO2MyExDgC0qZT{V3
zozd!7vZn@L3NF}IysUKYHJ%*nj>cRzyWp)q-<rJ_m@BdN`g1qORh1#jBhRKqh4z+h
zEk9bmO+Ne2wGX!&<97;FG!}n9w{m;r#tG2@>%DC4-hZ=nw&D#94?cf&u_ym7vv;em
zo{2uoWtthbIkL04(wqCV&Go5XQc?B~v)-S|KOAnf=ePKux9<;wCI&gU6{2VQMx{v^
z&Fle9A}sdgZ!7!xWagK|_g(kC<lLJ4VMl?^Q`dOzSK({V-^>42_~w|Q*_?>;@3?n!
z_Hl*9rx#yc8PcAoUz(h9KJe(gy*Ur>HU;0GoA$ka_szmG>)-nCpC^8CzGQUSqdRyh
zS9r-<5AXNWzGU2*%($NCf|i2(&14nXSLF}d-`?N+_z$1cV&~6w*Cu;2K+gsEdjIal
zxu7+b2evg=?EU%r{GNGg-)0}#W*lA0b*i{D_s-PS-Rm~~{E}ui@5X_Z*2_QfKCsf9
zQ?c<>_m`Y&-3#ZoJ-h9;ZU<<7YGUL*nZ1Qm<~}dm@O;1Ro&FvERcX6^S*_j>cHzKk
z##rgnr(37*`sg(`e2bh4$PdZIe{Yr-%Fp)CPx{_^m&KLk>FkM9Po|iB$Z|Np%vSPd
za>z_c6{Ga1we7lbjdhnpdlbUH7nG=7Gh*GiV%rVV_|5~qSGW6dsV@q1pML91(}KNM
zdP16%nmkT=I3})LuqryVRP@B7s2#<MkFWPEj+<H)6IZeHi2NZ{&qqfumhSxgf=_<S
z{|3{=*QULwI3_e(#yclS=UmyjSEnZa0#(zCZ@3>>eq`~6um?}yr4|`qyV!ZL#jQO_
zar=U<=&3@r9OurQQ?b#TbE3uLiIJsftoABy	({o`y$Mk3Y<L?qk_rbRy-L?9~u2
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∋FqmSs~rI`;po$sq7Wj
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
diff --git a/docs/build/crops.html b/docs/build/crops.html
index 1db59ee..d2aac0c 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 · Persephone</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="Persephone logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="index.html">Persephone</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 Persephone</a></li><li><a class="tocitem" href="adapting.html">Adapting Persephone</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="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, Persephone 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="Persephone.CropType" href="#Persephone.CropType"><code>Persephone.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="Persephone.FarmPlot" href="#Persephone.FarmPlot"><code>Persephone.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="Persephone.averagefieldsize-Tuple{Agents.AgentBasedModel}" href="#Persephone.averagefieldsize-Tuple{Agents.AgentBasedModel}"><code>Persephone.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="Persephone.cropheight-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel}" href="#Persephone.cropheight-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel}"><code>Persephone.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="Persephone.croptype-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel}" href="#Persephone.croptype-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel}"><code>Persephone.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="Persephone.initfields!-Tuple{Agents.AgentBasedModel}" href="#Persephone.initfields!-Tuple{Agents.AgentBasedModel}"><code>Persephone.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="Persephone.stepagent!-Tuple{FarmPlot, Agents.AgentBasedModel}" href="#Persephone.stepagent!-Tuple{FarmPlot, Agents.AgentBasedModel}"><code>Persephone.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="Wednesday 8 February 2023 12:48">Wednesday 8 February 2023</span>. Using Julia version 1.9.0-alpha1.</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">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="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="Sunday 28 May 2023 23:20">Sunday 28 May 2023</span>. Using Julia version 1.9.0-alpha1.</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 84b8ae0..a20500a 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 Persephone · Persephone</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="Persephone logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="index.html">Persephone</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 Persephone</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 Persephone</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="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 Persephone</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href="developing.html">Developing Persephone</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-Persephone"><a class="docs-heading-anchor" href="#Developing-Persephone">Developing Persephone</a><a id="Developing-Persephone-1"></a><a class="docs-heading-anchor-permalink" href="#Developing-Persephone" 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>Persephone 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 Persephone »</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="Wednesday 8 February 2023 12:48">Wednesday 8 February 2023</span>. Using Julia version 1.9.0-alpha1.</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">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="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="Sunday 28 May 2023 23:20">Sunday 28 May 2023</span>. Using Julia version 1.9.0-alpha1.</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 b3e0a96..b0c0057 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 · Persephone</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="Persephone logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="index.html">Persephone</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 Persephone</a></li><li><a class="tocitem" href="adapting.html">Adapting Persephone</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="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, Persephone 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="Persephone.Farmer" href="#Persephone.Farmer"><code>Persephone.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="Persephone.initfarms!-Tuple{Agents.AgentBasedModel}" href="#Persephone.initfarms!-Tuple{Agents.AgentBasedModel}"><code>Persephone.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="Persephone.stepagent!-Tuple{Farmer, Agents.AgentBasedModel}" href="#Persephone.stepagent!-Tuple{Farmer, Agents.AgentBasedModel}"><code>Persephone.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="Wednesday 8 February 2023 12:48">Wednesday 8 February 2023</span>. Using Julia version 1.9.0-alpha1.</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">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="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="Sunday 28 May 2023 23:20">Sunday 28 May 2023</span>. Using Julia version 1.9.0-alpha1.</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 80bb21b..d8d87ee 100644
--- a/docs/build/gis.html
+++ b/docs/build/gis.html
@@ -1,7 +1,7 @@
<!DOCTYPE html>
-<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>GIS data · Persephone</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="Persephone logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="index.html">Persephone</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 Persephone</a></li><li><a class="tocitem" href="adapting.html">Adapting Persephone</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="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>Persephone 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>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="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
20: low vegetation
30: water
40: built-up
50: bare soil
-60: agriculture</code></pre><p>To create a Persephone 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 Persephone 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, Persephone 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 Persephone.</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 Persephone 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="Wednesday 8 February 2023 12:48">Wednesday 8 February 2023</span>. Using Julia version 1.9.0-alpha1.</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></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="Sunday 28 May 2023 23:20">Sunday 28 May 2023</span>. Using Julia version 1.9.0-alpha1.</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 dbb9d14..0d2ef7e 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 · Persephone</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="Persephone logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="index.html">Persephone</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 Persephone</a></li><li><a class="tocitem" href="adapting.html">Adapting Persephone</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="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>Persephone 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">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="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:
@@ -10,9 +10,9 @@ optional arguments:
-l, --loglevel LOGLEVEL
verbosity: "debug", "info", or "quiet"
--version show version information and exit
- -h, --help show this help message and exit</code></pre><h2 id="Model-input"><a class="docs-heading-anchor" href="#Model-input">Model input</a><a id="Model-input-1"></a><a class="docs-heading-anchor-permalink" href="#Model-input" title="Permalink"></a></h2><p>Persephone requires three input files: a configuration file and two map files. How to generate the map files is documented <a href="gis.html">elsewhere</a>. The <a href="io.html">configuration file</a> defines parameter values and looks like this (see <code>src/parameters.toml</code> for a complete list of parameters):</p><pre><code class="language-TOML hljs">### Persephone - a socio-economic-ecological model of European agricultural landscapes.
+ -h, --help show this help message and exit</code></pre><h2 id="Model-input"><a class="docs-heading-anchor" href="#Model-input">Model input</a><a id="Model-input-1"></a><a class="docs-heading-anchor-permalink" href="#Model-input" title="Permalink"></a></h2><p>Persefone requires three input files: a configuration file and two map files. How to generate the map files is documented <a href="gis.html">elsewhere</a>. The <a href="io.html">configuration file</a> defines parameter values and looks like this (see <code>src/parameters.toml</code> for a complete list of parameters):</p><pre><code class="language-TOML hljs">### Persefone - a socio-economic-ecological model of European agricultural landscapes.
###
-### This is the default configuration file for Persephone, containing all model parameters.
+### This is the default configuration file for Persefone, containing all model parameters.
### The syntax is described here: https://toml.io/en/
[core]
@@ -37,4 +37,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>. Persephone 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-02-08 (commit d4e43d7)</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="Wednesday 8 February 2023 12:48">Wednesday 8 February 2023</span>. Using Julia version 1.9.0-alpha1.</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-05-28 (commit 60e9012)</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="Sunday 28 May 2023 23:20">Sunday 28 May 2023</span>. Using Julia version 1.9.0-alpha1.</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 b49def0..6928d33 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 · Persephone</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="Persephone logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="index.html">Persephone</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 Persephone</a></li><li><a class="tocitem" href="adapting.html">Adapting Persephone</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="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 Persephone, 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="Persephone.PARAMFILE" href="#Persephone.PARAMFILE"><code>Persephone.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="Persephone.flattenTOML-Tuple{Any}" href="#Persephone.flattenTOML-Tuple{Any}"><code>Persephone.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#Persephone.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="Persephone.getsettings" href="#Persephone.getsettings"><code>Persephone.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="Persephone.parsecommandline-Tuple{}" href="#Persephone.parsecommandline-Tuple{}"><code>Persephone.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="Persephone.preprocessparameters-Tuple{Dict{String, Any}, String}" href="#Persephone.preprocessparameters-Tuple{Dict{String, Any}, String}"><code>Persephone.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#Persephone.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="Persephone.@param-Tuple{Any}" href="#Persephone.@param-Tuple{Any}"><code>Persephone.@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="Persephone.@rand-Tuple" href="#Persephone.@rand-Tuple"><code>Persephone.@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="Persephone.@shuffle!-Tuple{Any}" href="#Persephone.@shuffle!-Tuple{Any}"><code>Persephone.@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="Persephone.DataOutput" href="#Persephone.DataOutput"><code>Persephone.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#Persephone.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="Persephone.createdatadir-Tuple{String, Union{Bool, String}}" href="#Persephone.createdatadir-Tuple{String, Union{Bool, String}}"><code>Persephone.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="Persephone.modellogger-Tuple{String, String}" href="#Persephone.modellogger-Tuple{String, String}"><code>Persephone.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#Persephone.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="Persephone.newdataoutput!-Tuple{Agents.AgentBasedModel, String, String, Function, String}" href="#Persephone.newdataoutput!-Tuple{Agents.AgentBasedModel, String, String, Function, String}"><code>Persephone.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="Persephone.outputdata-Tuple{Agents.AgentBasedModel}" href="#Persephone.outputdata-Tuple{Agents.AgentBasedModel}"><code>Persephone.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="Persephone.prepareTOML-Tuple{Any}" href="#Persephone.prepareTOML-Tuple{Any}"><code>Persephone.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#Persephone.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="Persephone.saveinputfiles-Tuple{Agents.AgentBasedModel}" href="#Persephone.saveinputfiles-Tuple{Agents.AgentBasedModel}"><code>Persephone.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="Persephone.withtestlogger-Tuple{Agents.AgentBasedModel}" href="#Persephone.withtestlogger-Tuple{Agents.AgentBasedModel}"><code>Persephone.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="Wednesday 8 February 2023 12:48">Wednesday 8 February 2023</span>. Using Julia version 1.9.0-alpha1.</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">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="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="Sunday 28 May 2023 23:20">Sunday 28 May 2023</span>. Using Julia version 1.9.0-alpha1.</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 d3eb982..7d132c6 100644
--- a/docs/build/nature.html
+++ b/docs/build/nature.html
@@ -1,10 +1,10 @@
<!DOCTYPE html>
-<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Nature · Persephone</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="Persephone logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="index.html">Persephone</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 Persephone</a></li><li><a class="tocitem" href="adapting.html">Adapting Persephone</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="#ecologicaldata.jl"><span>ecologicaldata.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="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="Persephone.Animal" href="#Persephone.Animal"><code>Persephone.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="Persephone.animalid-Tuple{Animal}" href="#Persephone.animalid-Tuple{Animal}"><code>Persephone.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#L52-L56">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persephone.initnature!-Tuple{Agents.AgentBasedModel}" href="#Persephone.initnature!-Tuple{Agents.AgentBasedModel}"><code>Persephone.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#L71-L75">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persephone.stepagent!-Tuple{Animal, Agents.AgentBasedModel}" href="#Persephone.stepagent!-Tuple{Animal, Agents.AgentBasedModel}"><code>Persephone.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#L61-L65">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persephone.@countanimals-Tuple" href="#Persephone.@countanimals-Tuple"><code>Persephone.@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#Persephone.@phase-Tuple{Any, Any}"><code>@phase</code></a> or <a href="nature.html#Persephone.@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#L374-L380">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persephone.@cropheight-Tuple{}" href="#Persephone.@cropheight-Tuple{}"><code>Persephone.@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#Persephone.@phase-Tuple{Any, Any}"><code>@phase</code></a> or <a href="nature.html#Persephone.@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#L341-L347">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persephone.@croptype-Tuple{}" href="#Persephone.@croptype-Tuple{}"><code>Persephone.@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#Persephone.@phase-Tuple{Any, Any}"><code>@phase</code></a> or <a href="nature.html#Persephone.@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#L330-L336">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persephone.@distanceto-Tuple{Any}" href="#Persephone.@distanceto-Tuple{Any}"><code>Persephone.@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#Persephone.@phase-Tuple{Any, Any}"><code>@phase</code></a> or <a href="nature.html#Persephone.@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#L352-L358">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persephone.@distancetoedge-Tuple{}" href="#Persephone.@distancetoedge-Tuple{}"><code>Persephone.@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#Persephone.@phase-Tuple{Any, Any}"><code>@phase</code></a> or <a href="nature.html#Persephone.@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#L363-L369">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persephone.@habitat-Tuple{Any}" href="#Persephone.@habitat-Tuple{Any}"><code>Persephone.@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#Persephone.@landcover-Tuple{}"><code>@landcover</code></a>, <a href="nature.html#Persephone.@croptype-Tuple{}"><code>@croptype</code></a>, <a href="nature.html#Persephone.@cropheight-Tuple{}"><code>@cropheight</code></a>, <a href="nature.html#Persephone.@distanceto-Tuple{Any}"><code>@distanceto</code></a>, <a href="nature.html#Persephone.@distancetoedge-Tuple{}"><code>@distancetoedge</code></a>, <a href="nature.html#Persephone.@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">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="#ecologicaldata.jl"><span>ecologicaldata.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="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#L52-L56">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#L71-L75">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#L61-L65">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#L374-L380">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#L341-L347">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#L330-L336">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#L352-L358">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#L363-L369">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 &&
@cropheight() < 10)) &&
- @distanceto(forest) > 20)</code></pre><p>For more complex habitat suitability checks, the use of this macro can be circumvented by directly creating an equivalent function.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L275-L302">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persephone.@initialise-Tuple{Any, Vararg{Any}}" href="#Persephone.@initialise-Tuple{Any, Vararg{Any}}"><code>Persephone.@initialise</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@initialise(habitatdescriptor; kwargs...)</code></pre><p>Call this macro within the body of <a href="nature.html#Persephone.@species-Tuple{Any, Any}"><code>@species</code></a>. It passes the given habitat descriptor function and keyword arguments on to <a href="nature.html#Persephone.initpopulation-Tuple{Function}"><code>initpopulation</code></a> when setting up the simulation.</p><p>Note: if this macro is not used, the variable <code>initialise!</code> must be set manually in the species definition.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L147-L155">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persephone.@kill-Tuple" href="#Persephone.@kill-Tuple"><code>Persephone.@kill</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@kill</code></pre><p>Kill this animal (and immediately abort its current update). This is a thin wrapper around <a href="nature.html#Persephone.kill!"><code>kill!</code></a>, and passes on any arguments. This can only be used nested within <a href="nature.html#Persephone.@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#L240-L246">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persephone.@landcover-Tuple{}" href="#Persephone.@landcover-Tuple{}"><code>Persephone.@landcover</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@landcover</code></pre><p>Returns the local landcover. This is a utility wrapper that can only be used nested within <a href="nature.html#Persephone.@phase-Tuple{Any, Any}"><code>@phase</code></a> or <a href="nature.html#Persephone.@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#L320-L325">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persephone.@neighbours-Tuple{Any}" href="#Persephone.@neighbours-Tuple{Any}"><code>Persephone.@neighbours</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@neighbours(radius)</code></pre><p>Return an iterator over all animals in the given radius around this animal, excluding itself. This can only be used nested within <a href="nature.html#Persephone.@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#L264-L269">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persephone.@phase-Tuple{Any, Any}" href="#Persephone.@phase-Tuple{Any, Any}"><code>Persephone.@phase</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@phase(name, body)</code></pre><p>This macro is designed to be used within a species definition block (i.e. within the body of a call to <a href="nature.html#Persephone.@species-Tuple{Any, Any}"><code>@species</code></a>).</p><p>The idea behind this is that species show very different behaviour during different phases of their lives. Therefore, <code>@phase</code> can be used define the behaviour for one such phase, and the conditions under which the animal transitions to another phase.</p><p><code>@phase</code> 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:</p><ul><li><code>animal</code> a reference to the animal itself. This provides access to <code>animal.age</code>, <code>animal.sex</code>, and <code>animal.<trait></code> (where <trait> is a variable that was defined in the top part of the species definition body).</li><li><code>pos</code> gives the animal's current position as a coordinate tuple.</li><li><code>model</code> a reference to the model world (an object of type <code>AgentBasedModel</code>). This allows access to <code>model.date</code> (the current simulation date) and <code>model.landscape</code> (a two-dimensional array of pixels containing geographic information).</li></ul><p>Several utility macros can be used within the body of <code>@phase</code> as a short-hand for common expressions: <a href="nature.html#Persephone.@trait-Tuple{Any}"><code>@trait</code></a>, <a href="nature.html#Persephone.@setphase-Tuple{Any}"><code>@setphase</code></a>, <a href="nature.html#Persephone.@respond-Tuple{Any, Any}"><code>@respond</code></a>, <a href="nature.html#Persephone.@kill-Tuple"><code>@kill</code></a>, <a href="nature.html#Persephone.@reproduce-Tuple"><code>@reproduce</code></a>, <a href="nature.html#Persephone.@neighbours-Tuple{Any}"><code>@neighbours</code></a>, <a href="io.html#Persephone.@rand-Tuple"><code>@rand</code></a>, <a href="io.html#Persephone.@shuffle!-Tuple{Any}"><code>@shuffle!</code></a>.</p><p>Note 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 <code>phase</code> is explicitly defined by the user in the species definition block.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L160-L190">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persephone.@reproduce-Tuple" href="#Persephone.@reproduce-Tuple"><code>Persephone.@reproduce</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@reproduce</code></pre><p>Let this animal reproduce. This is a thin wrapper around <a href="nature.html#Persephone.reproduce!"><code>reproduce!</code></a>, and passes on any arguments. This can only be used nested within <a href="nature.html#Persephone.@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#L254-L259">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persephone.@respond-Tuple{Any, Any}" href="#Persephone.@respond-Tuple{Any, Any}"><code>Persephone.@respond</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@respond(eventname, body)</code></pre><p>Define how an animal responds to a landscape event that affects its current position. This can only be used nested within <a href="nature.html#Persephone.@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#L226-L231">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persephone.@setphase-Tuple{Any}" href="#Persephone.@setphase-Tuple{Any}"><code>Persephone.@setphase</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@setphase(newphase)</code></pre><p>Switch this animal over to a different phase. This can only be used nested within <a href="nature.html#Persephone.@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#L216-L220">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persephone.@species-Tuple{Any, Any}" href="#Persephone.@species-Tuple{Any, Any}"><code>Persephone.@species</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@species(name, body)</code></pre><p>A 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:</p><pre><code class="language-julia hljs">@species name begin
+ @distanceto(forest) > 20)</code></pre><p>For more complex habitat suitability checks, the use of this macro can be circumvented by directly creating an equivalent function.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L275-L302">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.@initialise-Tuple{Any, Vararg{Any}}" href="#Persefone.@initialise-Tuple{Any, Vararg{Any}}"><code>Persefone.@initialise</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@initialise(habitatdescriptor; kwargs...)</code></pre><p>Call this macro within the body of <a href="nature.html#Persefone.@species-Tuple{Any, Any}"><code>@species</code></a>. It passes the given habitat descriptor function and keyword arguments on to <a href="nature.html#Persefone.initpopulation-Tuple{Function}"><code>initpopulation</code></a> when setting up the simulation.</p><p>Note: if this macro is not used, the variable <code>initialise!</code> must be set manually in the species definition.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L147-L155">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.@kill-Tuple" href="#Persefone.@kill-Tuple"><code>Persefone.@kill</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@kill</code></pre><p>Kill this animal (and immediately abort its current update). This is a thin wrapper around <a href="nature.html#Persefone.kill!"><code>kill!</code></a>, and passes on any arguments. 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#L240-L246">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.@landcover-Tuple{}" href="#Persefone.@landcover-Tuple{}"><code>Persefone.@landcover</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@landcover</code></pre><p>Returns the local landcover. 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#L320-L325">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.@neighbours-Tuple{Any}" href="#Persefone.@neighbours-Tuple{Any}"><code>Persefone.@neighbours</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@neighbours(radius)</code></pre><p>Return an iterator over all animals in the given radius around this animal, excluding itself. 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#L264-L269">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.@phase-Tuple{Any, Any}" href="#Persefone.@phase-Tuple{Any, Any}"><code>Persefone.@phase</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@phase(name, body)</code></pre><p>This macro is designed to be used within a species definition block (i.e. within the body of a call to <a href="nature.html#Persefone.@species-Tuple{Any, Any}"><code>@species</code></a>).</p><p>The idea behind this is that species show very different behaviour during different phases of their lives. Therefore, <code>@phase</code> can be used define the behaviour for one such phase, and the conditions under which the animal transitions to another phase.</p><p><code>@phase</code> 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:</p><ul><li><code>animal</code> a reference to the animal itself. This provides access to <code>animal.age</code>, <code>animal.sex</code>, and <code>animal.<trait></code> (where <trait> is a variable that was defined in the top part of the species definition body).</li><li><code>pos</code> gives the animal's current position as a coordinate tuple.</li><li><code>model</code> a reference to the model world (an object of type <code>AgentBasedModel</code>). This allows access to <code>model.date</code> (the current simulation date) and <code>model.landscape</code> (a two-dimensional array of pixels containing geographic information).</li></ul><p>Several utility macros can be used within the body of <code>@phase</code> as a short-hand for common expressions: <a href="nature.html#Persefone.@trait-Tuple{Any}"><code>@trait</code></a>, <a href="nature.html#Persefone.@setphase-Tuple{Any}"><code>@setphase</code></a>, <a href="nature.html#Persefone.@respond-Tuple{Any, Any}"><code>@respond</code></a>, <a href="nature.html#Persefone.@kill-Tuple"><code>@kill</code></a>, <a href="nature.html#Persefone.@reproduce-Tuple"><code>@reproduce</code></a>, <a href="nature.html#Persefone.@neighbours-Tuple{Any}"><code>@neighbours</code></a>, <a href="io.html#Persefone.@rand-Tuple"><code>@rand</code></a>, <a href="io.html#Persefone.@shuffle!-Tuple{Any}"><code>@shuffle!</code></a>.</p><p>Note 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 <code>phase</code> is explicitly defined by the user in the species definition block.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/nature/nature.jl#L160-L190">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.@reproduce-Tuple" href="#Persefone.@reproduce-Tuple"><code>Persefone.@reproduce</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@reproduce</code></pre><p>Let this animal reproduce. This is a thin wrapper around <a href="nature.html#Persefone.reproduce!"><code>reproduce!</code></a>, and passes on any arguments. 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#L254-L259">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.@respond-Tuple{Any, Any}" href="#Persefone.@respond-Tuple{Any, Any}"><code>Persefone.@respond</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@respond(eventname, body)</code></pre><p>Define how an animal responds to a landscape event that affects its current position. 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#L226-L231">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.@setphase-Tuple{Any}" href="#Persefone.@setphase-Tuple{Any}"><code>Persefone.@setphase</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@setphase(newphase)</code></pre><p>Switch this animal over to a different phase. 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#L216-L220">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.@species-Tuple{Any, Any}" href="#Persefone.@species-Tuple{Any, Any}"><code>Persefone.@species</code></a> — <span class="docstring-category">Macro</span></header><section><div><pre><code class="language-julia hljs">@species(name, body)</code></pre><p>A 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:</p><pre><code class="language-julia hljs">@species name begin
@initialise(@habitat(...))
speciesvar1 = 3.14
@@ -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#Persephone.@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#Persephone.@initialise-Tuple{Any, Vararg{Any}}"><code>@initialise</code></a> and <a href="nature.html#Persephone.@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#L94-L123">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persephone.@trait-Tuple{Any}" href="#Persephone.@trait-Tuple{Any}"><code>Persephone.@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#Persephone.@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#L202-L207">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="Persephone.countanimals-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel}" href="#Persephone.countanimals-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel}"><code>Persephone.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="Persephone.initpopulation-Tuple{Function}" href="#Persephone.initpopulation-Tuple{Function}"><code>Persephone.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#Persephone.@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#Persephone.@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="Persephone.initrandompopulation-Tuple{Int64}" href="#Persephone.initrandompopulation-Tuple{Int64}"><code>Persephone.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#Persephone.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="Persephone.kill!" href="#Persephone.kill!"><code>Persephone.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="Persephone.nearby_animals-Tuple{Animal, Agents.AgentBasedModel, Int64}" href="#Persephone.nearby_animals-Tuple{Animal, Agents.AgentBasedModel, Int64}"><code>Persephone.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="Persephone.nearby_animals-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel, Int64}" href="#Persephone.nearby_animals-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel, Int64}"><code>Persephone.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="Persephone.reproduce!" href="#Persephone.reproduce!"><code>Persephone.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="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="Persephone.initecologicaldata-Tuple{Agents.AgentBasedModel}" href="#Persephone.initecologicaldata-Tuple{Agents.AgentBasedModel}"><code>Persephone.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="Persephone.saveindividualdata-Tuple{Agents.AgentBasedModel}" href="#Persephone.saveindividualdata-Tuple{Agents.AgentBasedModel}"><code>Persephone.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="Persephone.savepopulationdata-Tuple{Agents.AgentBasedModel}" href="#Persephone.savepopulationdata-Tuple{Agents.AgentBasedModel}"><code>Persephone.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="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="Wednesday 8 February 2023 12:48">Wednesday 8 February 2023</span>. Using Julia version 1.9.0-alpha1.</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#L94-L123">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#L202-L207">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="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="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="Sunday 28 May 2023 23:20">Sunday 28 May 2023</span>. Using Julia version 1.9.0-alpha1.</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 7ba5715..c720476 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) · Persephone</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="Persephone logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="index.html">Persephone</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 Persephone</a></li><li><a class="tocitem" href="adapting.html">Adapting Persephone</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="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 Persephone »</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="Wednesday 8 February 2023 12:48">Wednesday 8 February 2023</span>. Using Julia version 1.9.0-alpha1.</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">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="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="Sunday 28 May 2023 23:20">Sunday 28 May 2023</span>. Using Julia version 1.9.0-alpha1.</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 27f5a5d..5d6c64b 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 · Persephone</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="Persephone logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="index.html">Persephone</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 Persephone</a></li><li><a class="tocitem" href="adapting.html">Adapting Persephone</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="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="Wednesday 8 February 2023 12:48">Wednesday 8 February 2023</span>. Using Julia version 1.9.0-alpha1.</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">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="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="Sunday 28 May 2023 23:20">Sunday 28 May 2023</span>. Using Julia version 1.9.0-alpha1.</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 287631d..b47f3cd 100644
--- a/docs/build/search_index.js
+++ b/docs/build/search_index.js
@@ -1,3 +1,3 @@
var documenterSearchIndex = {"docs":
-[{"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 = [Persephone]\nPages = [\"nature/nature.jl\"]","category":"page"},{"location":"nature.html#Persephone.Animal","page":"Nature","title":"Persephone.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#Persephone.animalid-Tuple{Animal}","page":"Nature","title":"Persephone.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#Persephone.initnature!-Tuple{Agents.AgentBasedModel}","page":"Nature","title":"Persephone.initnature!","text":"initnature!(model)\n\nInitialise the model with all simulated animal populations.\n\n\n\n\n\n","category":"method"},{"location":"nature.html#Persephone.stepagent!-Tuple{Animal, Agents.AgentBasedModel}","page":"Nature","title":"Persephone.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#Persephone.@countanimals-Tuple","page":"Nature","title":"Persephone.@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#Persephone.@cropheight-Tuple{}","page":"Nature","title":"Persephone.@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#Persephone.@croptype-Tuple{}","page":"Nature","title":"Persephone.@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#Persephone.@distanceto-Tuple{Any}","page":"Nature","title":"Persephone.@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#Persephone.@distancetoedge-Tuple{}","page":"Nature","title":"Persephone.@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#Persephone.@habitat-Tuple{Any}","page":"Nature","title":"Persephone.@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#Persephone.@initialise-Tuple{Any, Vararg{Any}}","page":"Nature","title":"Persephone.@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#Persephone.@kill-Tuple","page":"Nature","title":"Persephone.@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#Persephone.@landcover-Tuple{}","page":"Nature","title":"Persephone.@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#Persephone.@neighbours-Tuple{Any}","page":"Nature","title":"Persephone.@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#Persephone.@phase-Tuple{Any, Any}","page":"Nature","title":"Persephone.@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#Persephone.@reproduce-Tuple","page":"Nature","title":"Persephone.@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#Persephone.@respond-Tuple{Any, Any}","page":"Nature","title":"Persephone.@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#Persephone.@setphase-Tuple{Any}","page":"Nature","title":"Persephone.@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#Persephone.@species-Tuple{Any, Any}","page":"Nature","title":"Persephone.@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#Persephone.@trait-Tuple{Any}","page":"Nature","title":"Persephone.@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 = [Persephone]\nPages = [\"nature/populations.jl\"]","category":"page"},{"location":"nature.html#Persephone.countanimals-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel}","page":"Nature","title":"Persephone.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#Persephone.initpopulation-Tuple{Function}","page":"Nature","title":"Persephone.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#Persephone.initrandompopulation-Tuple{Int64}","page":"Nature","title":"Persephone.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#Persephone.kill!","page":"Nature","title":"Persephone.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#Persephone.nearby_animals-Tuple{Animal, Agents.AgentBasedModel, Int64}","page":"Nature","title":"Persephone.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#Persephone.nearby_animals-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel, Int64}","page":"Nature","title":"Persephone.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#Persephone.reproduce!","page":"Nature","title":"Persephone.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#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 = [Persephone]\nPages = [\"nature/ecologicaldata.jl\"]","category":"page"},{"location":"nature.html#Persephone.initecologicaldata-Tuple{Agents.AgentBasedModel}","page":"Nature","title":"Persephone.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#Persephone.saveindividualdata-Tuple{Agents.AgentBasedModel}","page":"Nature","title":"Persephone.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#Persephone.savepopulationdata-Tuple{Agents.AgentBasedModel}","page":"Nature","title":"Persephone.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 Persephone, 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 = [Persephone]\nPages = [\"core/input.jl\"]","category":"page"},{"location":"io.html#Persephone.PARAMFILE","page":"Input, Output, and Settings","title":"Persephone.PARAMFILE","text":"The file that stores all default parameters: src/parameters.toml\n\n\n\n\n\n","category":"constant"},{"location":"io.html#Persephone.flattenTOML-Tuple{Any}","page":"Input, Output, and Settings","title":"Persephone.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#Persephone.getsettings","page":"Input, Output, and Settings","title":"Persephone.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#Persephone.parsecommandline-Tuple{}","page":"Input, Output, and Settings","title":"Persephone.parsecommandline","text":"parsecommandline()\n\nCertain software parameters can be set via the commandline.\n\n\n\n\n\n","category":"method"},{"location":"io.html#Persephone.preprocessparameters-Tuple{Dict{String, Any}, String}","page":"Input, Output, and Settings","title":"Persephone.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#Persephone.@param-Tuple{Any}","page":"Input, Output, and Settings","title":"Persephone.@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#Persephone.@rand-Tuple","page":"Input, Output, and Settings","title":"Persephone.@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#Persephone.@shuffle!-Tuple{Any}","page":"Input, Output, and Settings","title":"Persephone.@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 = [Persephone]\nPages = [\"core/output.jl\"]","category":"page"},{"location":"io.html#Persephone.DataOutput","page":"Input, Output, and Settings","title":"Persephone.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#Persephone.createdatadir-Tuple{String, Union{Bool, String}}","page":"Input, Output, and Settings","title":"Persephone.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#Persephone.modellogger-Tuple{String, String}","page":"Input, Output, and Settings","title":"Persephone.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#Persephone.newdataoutput!-Tuple{Agents.AgentBasedModel, String, String, Function, String}","page":"Input, Output, and Settings","title":"Persephone.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#Persephone.outputdata-Tuple{Agents.AgentBasedModel}","page":"Input, Output, and Settings","title":"Persephone.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#Persephone.prepareTOML-Tuple{Any}","page":"Input, Output, and Settings","title":"Persephone.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#Persephone.saveinputfiles-Tuple{Agents.AgentBasedModel}","page":"Input, Output, and Settings","title":"Persephone.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#Persephone.withtestlogger-Tuple{Agents.AgentBasedModel}","page":"Input, Output, and Settings","title":"Persephone.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":"Persephone 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. (Persephone 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 Persephone 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 Persephone, 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":"Persephone 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 Persephone 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 Persephone 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 = [Persephone]\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-Persephone-species-DSL","page":"Defining new species","title":"The Persephone 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, Persephone 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 Persephone, 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-Persephone","page":"Developing Persephone","title":"Developing Persephone","text":"","category":"section"},{"location":"developing.html#Workflow","page":"Developing Persephone","title":"Workflow","text":"","category":"section"},{"location":"developing.html","page":"Developing Persephone","title":"Developing Persephone","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 Persephone","title":"Developing Persephone","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 Persephone","title":"Libraries","text":"","category":"section"},{"location":"developing.html#Agents.jl","page":"Developing Persephone","title":"Agents.jl","text":"","category":"section"},{"location":"developing.html","page":"Developing Persephone","title":"Developing Persephone","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 Persephone","title":"Developing Persephone","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 Persephone","title":"Revise.jl","text":"","category":"section"},{"location":"developing.html","page":"Developing Persephone","title":"Developing Persephone","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 Persephone","title":"Test","text":"","category":"section"},{"location":"developing.html","page":"Developing Persephone","title":"Developing Persephone","text":"Persephone 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 Persephone","title":"Documenter.jl","text":"","category":"section"},{"location":"developing.html","page":"Developing Persephone","title":"Developing Persephone","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 Persephone","title":"Julia editors","text":"","category":"section"},{"location":"developing.html#Emacs","page":"Developing Persephone","title":"Emacs","text":"","category":"section"},{"location":"developing.html","page":"Developing Persephone","title":"Developing Persephone","text":"There are a couple of addons that make working with Julia much nicer in Emacs:","category":"page"},{"location":"developing.html","page":"Developing Persephone","title":"Developing Persephone","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 Persephone","title":"VSCode","text":"","category":"section"},{"location":"developing.html","page":"Developing Persephone","title":"Developing Persephone","text":"See here.","category":"page"},{"location":"developing.html","page":"Developing Persephone","title":"Developing Persephone","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 = [Persephone]\nPages = [\"core/simulation.jl\"]","category":"page"},{"location":"simulation.html#Persephone.finalise!-Tuple{Agents.AgentBasedModel}","page":"Simulation","title":"Persephone.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#Persephone.initialise","page":"Simulation","title":"Persephone.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#Persephone.initmodel-Tuple{Dict{String, Any}}","page":"Simulation","title":"Persephone.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#Persephone.paramscan-Tuple{Dict{String, Any}, Vector{String}}","page":"Simulation","title":"Persephone.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#Persephone.simulate","page":"Simulation","title":"Persephone.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 Persephone simulation.\n\n\n\n\n\n","category":"function"},{"location":"simulation.html#Persephone.simulate!-Tuple{Agents.AgentBasedModel}","page":"Simulation","title":"Persephone.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#Persephone.stepsimulation!-Tuple{Agents.AgentBasedModel}","page":"Simulation","title":"Persephone.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 = [Persephone]\nPages = [\"core/landscape.jl\"]","category":"page"},{"location":"simulation.html#Persephone.EventType","page":"Simulation","title":"Persephone.EventType","text":"The types of landscape event that can be simulated\n\n\n\n\n\n","category":"type"},{"location":"simulation.html#Persephone.FarmEvent","page":"Simulation","title":"Persephone.FarmEvent","text":"FarmEvent\n\nA data structure to define a landscape event, giving its type, spatial extent, and duration.\n\n\n\n\n\n","category":"type"},{"location":"simulation.html#Persephone.LandCover","page":"Simulation","title":"Persephone.LandCover","text":"The land cover classes encoded in the Mundialis Sentinel data.\n\n\n\n\n\n","category":"type"},{"location":"simulation.html#Persephone.Pixel","page":"Simulation","title":"Persephone.Pixel","text":"Pixel\n\nA pixel is a simple data structure to combine land use and ownership information in a single object. The model landscape consists of a matrix of pixels. (Note: further landscape information may be added here in future.)\n\n\n\n\n\n","category":"type"},{"location":"simulation.html#Persephone.createevent!","page":"Simulation","title":"Persephone.createevent!","text":"createevent!(model, pixels, name, duration=1)\n\nAdd a farm event to the specified pixels (a vector of position tuples) for a given duration.\n\n\n\n\n\n","category":"function"},{"location":"simulation.html#Persephone.distanceto-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel, Function}","page":"Simulation","title":"Persephone.distanceto","text":"distanceto(pos, model, habitatdescriptor)\n\nCalculate the distance from the given location to the closest location matching the habitat descriptor function. Caution: can be computationally expensive!\n\n\n\n\n\n","category":"method"},{"location":"simulation.html#Persephone.distanceto-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel, Persephone.LandCover}","page":"Simulation","title":"Persephone.distanceto","text":"distanceto(pos, model, habitattype)\n\nCalculate the distance from the given location to the closest habitat of the specified type. Caution: can be computationally expensive!\n\n\n\n\n\n","category":"method"},{"location":"simulation.html#Persephone.distancetoedge-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel}","page":"Simulation","title":"Persephone.distancetoedge","text":"distancetoedge(pos, model)\n\nCalculate the distance from the given location to the closest neighbouring habitat. Caution: can be computationally expensive!\n\n\n\n\n\n","category":"method"},{"location":"simulation.html#Persephone.farmplot-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel}","page":"Simulation","title":"Persephone.farmplot","text":"farmplot(position, model)\n\nReturn the farm plot at this position, or nothing if there is none (utility wrapper).\n\n\n\n\n\n","category":"method"},{"location":"simulation.html#Persephone.initlandscape-Tuple{String, String}","page":"Simulation","title":"Persephone.initlandscape","text":"initlandscape(landcovermap, farmfieldsmap)\n\nInitialise the model landscape based on the map files specified in the configuration. Returns a matrix of pixels.\n\n\n\n\n\n","category":"method"},{"location":"simulation.html#Persephone.landcover-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel}","page":"Simulation","title":"Persephone.landcover","text":"landcover(position, model)\n\nReturn the land cover class at this position (utility wrapper).\n\n\n\n\n\n","category":"method"},{"location":"simulation.html#Persephone.updateevents!-Tuple{Agents.AgentBasedModel}","page":"Simulation","title":"Persephone.updateevents!","text":"updateevents!(model)\n\nCycle through the list of events, removing those that have expired.\n\n\n\n\n\n","category":"method"},{"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, Persephone 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 = [Persephone]\nPages = [\"farm/farm.jl\"]","category":"page"},{"location":"farm.html#Persephone.Farmer","page":"Farm submodel","title":"Persephone.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#Persephone.initfarms!-Tuple{Agents.AgentBasedModel}","page":"Farm submodel","title":"Persephone.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#Persephone.stepagent!-Tuple{Farmer, Agents.AgentBasedModel}","page":"Farm submodel","title":"Persephone.stepagent!","text":"stepagent!(farmer, model)\n\nUpdate a farmer by one day.\n\n\n\n\n\n","category":"method"},{"location":"adapting.html#Adapting-Persephone","page":"Adapting Persephone","title":"Adapting Persephone","text":"","category":"section"},{"location":"adapting.html","page":"Adapting Persephone","title":"Adapting Persephone","text":"A key development goal of Persephone 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 Persephone","title":"Adapting Persephone","text":"There are multiple ways to adapt Persephone for a new modelling study:","category":"page"},{"location":"adapting.html#Changing-the-parameters","page":"Adapting Persephone","title":"Changing the parameters","text":"","category":"section"},{"location":"adapting.html","page":"Adapting Persephone","title":"Adapting Persephone","text":"The simplest way to adapt Persephone 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 Persephone","title":"Changing the region","text":"","category":"section"},{"location":"adapting.html","page":"Adapting Persephone","title":"Adapting Persephone","text":"To apply Persephone 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 Persephone","title":"Adapting Persephone","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 Persephone","title":"Adding new animal species","text":"","category":"section"},{"location":"adapting.html","page":"Adapting Persephone","title":"Adapting Persephone","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/Persephone.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 Persephone","title":"Adding new crop species","text":"","category":"section"},{"location":"adapting.html","page":"Adapting Persephone","title":"Adapting Persephone","text":"Crop growth is not yet implemented.","category":"page"},{"location":"adapting.html#Adding-new-farmer-behaviour","page":"Adapting Persephone","title":"Adding new farmer behaviour","text":"","category":"section"},{"location":"adapting.html","page":"Adapting Persephone","title":"Adapting Persephone","text":"Farmer behaviour is not yet implemented.","category":"page"},{"location":"adapting.html#Adding-a-new-submodel","page":"Adapting Persephone","title":"Adding a new submodel","text":"","category":"section"},{"location":"adapting.html","page":"Adapting Persephone","title":"Adapting Persephone","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 Persephone","title":"Adapting Persephone","text":"If you want to add a new agent type, use Agents.jl's @agent macro. (But be aware that Persephone 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 Persephone","title":"Linking to another model","text":"","category":"section"},{"location":"adapting.html","page":"Adapting Persephone","title":"Adapting Persephone","text":"Persephone 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/Persephone.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 Persephone","title":"Adapting Persephone","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":"Persephone 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 Persephone 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 Persephone 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, Persephone 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 Persephone.","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 Persephone 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, Persephone 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 = [Persephone]\nPages = [\"crop/crops.jl\"]","category":"page"},{"location":"crops.html#Persephone.CropType","page":"Crop submodel","title":"Persephone.CropType","text":"The crop types simulated by the model\n\n\n\n\n\n","category":"type"},{"location":"crops.html#Persephone.FarmPlot","page":"Crop submodel","title":"Persephone.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#Persephone.averagefieldsize-Tuple{Agents.AgentBasedModel}","page":"Crop submodel","title":"Persephone.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#Persephone.cropheight-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel}","page":"Crop submodel","title":"Persephone.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#Persephone.croptype-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel}","page":"Crop submodel","title":"Persephone.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#Persephone.initfields!-Tuple{Agents.AgentBasedModel}","page":"Crop submodel","title":"Persephone.initfields!","text":"initfields!(model)\n\nInitialise the model with its farm plots.\n\n\n\n\n\n","category":"method"},{"location":"crops.html#Persephone.stepagent!-Tuple{FarmPlot, Agents.AgentBasedModel}","page":"Crop submodel","title":"Persephone.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 = Persephone","category":"page"},{"location":"index.html#Introduction","page":"Introduction","title":"Introduction","text":"","category":"section"},{"location":"index.html","page":"Introduction","title":"Introduction","text":"Persephone 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":"Persephone 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":"### Persephone - a socio-economic-ecological model of European agricultural landscapes.\n###\n### This is the default configuration file for Persephone, 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\nlandcovermap = \"data/landcover_jena.tif\" # location of the landcover map\nfarmfieldsmap = \"data/fields_jena.tif\" # location of the field geometry map\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[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]. Persephone 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-02-08 (commit d4e43d7)","category":"page"}]
+[{"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#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":"simulation.html#Persefone.EventType","page":"Simulation","title":"Persefone.EventType","text":"The types of landscape event that can be simulated\n\n\n\n\n\n","category":"type"},{"location":"simulation.html#Persefone.FarmEvent","page":"Simulation","title":"Persefone.FarmEvent","text":"FarmEvent\n\nA data structure to define a landscape event, giving its type, spatial extent, and duration.\n\n\n\n\n\n","category":"type"},{"location":"simulation.html#Persefone.LandCover","page":"Simulation","title":"Persefone.LandCover","text":"The land cover classes encoded in the Mundialis Sentinel data.\n\n\n\n\n\n","category":"type"},{"location":"simulation.html#Persefone.Pixel","page":"Simulation","title":"Persefone.Pixel","text":"Pixel\n\nA pixel is a simple data structure to combine land use and ownership information in a single object. The model landscape consists of a matrix of pixels. (Note: further landscape information may be added here in future.)\n\n\n\n\n\n","category":"type"},{"location":"simulation.html#Persefone.createevent!","page":"Simulation","title":"Persefone.createevent!","text":"createevent!(model, pixels, name, duration=1)\n\nAdd a farm event to the specified pixels (a vector of position tuples) for a given duration.\n\n\n\n\n\n","category":"function"},{"location":"simulation.html#Persefone.distanceto-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel, Function}","page":"Simulation","title":"Persefone.distanceto","text":"distanceto(pos, model, habitatdescriptor)\n\nCalculate the distance from the given location to the closest location matching the habitat descriptor function. Caution: can be computationally expensive!\n\n\n\n\n\n","category":"method"},{"location":"simulation.html#Persefone.distanceto-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel, Persefone.LandCover}","page":"Simulation","title":"Persefone.distanceto","text":"distanceto(pos, model, habitattype)\n\nCalculate the distance from the given location to the closest habitat of the specified type. Caution: can be computationally expensive!\n\n\n\n\n\n","category":"method"},{"location":"simulation.html#Persefone.distancetoedge-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel}","page":"Simulation","title":"Persefone.distancetoedge","text":"distancetoedge(pos, model)\n\nCalculate the distance from the given location to the closest neighbouring habitat. Caution: can be computationally expensive!\n\n\n\n\n\n","category":"method"},{"location":"simulation.html#Persefone.farmplot-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel}","page":"Simulation","title":"Persefone.farmplot","text":"farmplot(position, model)\n\nReturn the farm plot at this position, or nothing if there is none (utility wrapper).\n\n\n\n\n\n","category":"method"},{"location":"simulation.html#Persefone.initlandscape-Tuple{String, String}","page":"Simulation","title":"Persefone.initlandscape","text":"initlandscape(landcovermap, farmfieldsmap)\n\nInitialise the model landscape based on the map files specified in the configuration. Returns a matrix of pixels.\n\n\n\n\n\n","category":"method"},{"location":"simulation.html#Persefone.landcover-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel}","page":"Simulation","title":"Persefone.landcover","text":"landcover(position, model)\n\nReturn the land cover class at this position (utility wrapper).\n\n\n\n\n\n","category":"method"},{"location":"simulation.html#Persefone.updateevents!-Tuple{Agents.AgentBasedModel}","page":"Simulation","title":"Persefone.updateevents!","text":"updateevents!(model)\n\nCycle through the list of events, removing those that have expired.\n\n\n\n\n\n","category":"method"},{"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\nlandcovermap = \"data/landcover_jena.tif\" # location of the landcover map\nfarmfieldsmap = \"data/fields_jena.tif\" # location of the field geometry map\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[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-05-28 (commit 60e9012)","category":"page"}]
}
diff --git a/docs/build/simulation.html b/docs/build/simulation.html
index 7811769..568a07a 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 · Persephone</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="Persephone logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="index.html">Persephone</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 Persephone</a></li><li><a class="tocitem" href="adapting.html">Adapting Persephone</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="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="Persephone.finalise!-Tuple{Agents.AgentBasedModel}" href="#Persephone.finalise!-Tuple{Agents.AgentBasedModel}"><code>Persephone.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="Persephone.initialise" href="#Persephone.initialise"><code>Persephone.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="Persephone.initmodel-Tuple{Dict{String, Any}}" href="#Persephone.initmodel-Tuple{Dict{String, Any}}"><code>Persephone.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="Persephone.paramscan-Tuple{Dict{String, Any}, Vector{String}}" href="#Persephone.paramscan-Tuple{Dict{String, Any}, Vector{String}}"><code>Persephone.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="Persephone.simulate" href="#Persephone.simulate"><code>Persephone.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 Persephone 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="Persephone.simulate!-Tuple{Agents.AgentBasedModel}" href="#Persephone.simulate!-Tuple{Agents.AgentBasedModel}"><code>Persephone.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="Persephone.stepsimulation!-Tuple{Agents.AgentBasedModel}" href="#Persephone.stepsimulation!-Tuple{Agents.AgentBasedModel}"><code>Persephone.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 class="docstring"><header><a class="docstring-binding" id="Persephone.EventType" href="#Persephone.EventType"><code>Persephone.EventType</code></a> — <span class="docstring-category">Type</span></header><section><div><p>The types of landscape event that can be simulated</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/landscape.jl#L10">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persephone.FarmEvent" href="#Persephone.FarmEvent"><code>Persephone.FarmEvent</code></a> — <span class="docstring-category">Type</span></header><section><div><pre><code class="language-julia hljs">FarmEvent</code></pre><p>A data structure to define a landscape event, giving its type, spatial extent, and duration.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/landscape.jl#L26-L31">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persephone.LandCover" href="#Persephone.LandCover"><code>Persephone.LandCover</code></a> — <span class="docstring-category">Type</span></header><section><div><p>The land cover classes encoded in the Mundialis Sentinel data.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/landscape.jl#L6">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persephone.Pixel" href="#Persephone.Pixel"><code>Persephone.Pixel</code></a> — <span class="docstring-category">Type</span></header><section><div><pre><code class="language-julia hljs">Pixel</code></pre><p>A pixel is a simple data structure to combine land use and ownership information in a single object. The model landscape consists of a matrix of pixels. (Note: further landscape information may be added here in future.)</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/landscape.jl#L13-L19">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persephone.createevent!" href="#Persephone.createevent!"><code>Persephone.createevent!</code></a> — <span class="docstring-category">Function</span></header><section><div><pre><code class="language-julia hljs">createevent!(model, pixels, name, duration=1)</code></pre><p>Add a farm event to the specified pixels (a vector of position tuples) for a given duration.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/landscape.jl#L87-L91">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persephone.distanceto-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel, Function}" href="#Persephone.distanceto-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel, Function}"><code>Persephone.distanceto</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">distanceto(pos, model, habitatdescriptor)</code></pre><p>Calculate the distance from the given location to the closest location matching the habitat descriptor function. Caution: can be computationally expensive!</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/landscape.jl#L120-L125">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persephone.distanceto-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel, Persephone.LandCover}" href="#Persephone.distanceto-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel, Persephone.LandCover}"><code>Persephone.distanceto</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">distanceto(pos, model, habitattype)</code></pre><p>Calculate the distance from the given location to the closest habitat of the specified type. Caution: can be computationally expensive!</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/landscape.jl#L154-L159">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persephone.distancetoedge-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel}" href="#Persephone.distancetoedge-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel}"><code>Persephone.distancetoedge</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">distancetoedge(pos, model)</code></pre><p>Calculate the distance from the given location to the closest neighbouring habitat. Caution: can be computationally expensive!</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/landscape.jl#L165-L170">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persephone.farmplot-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel}" href="#Persephone.farmplot-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel}"><code>Persephone.farmplot</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">farmplot(position, model)</code></pre><p>Return the farm plot at this position, or nothing if there is none (utility wrapper).</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/landscape.jl#L109-L113">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persephone.initlandscape-Tuple{String, String}" href="#Persephone.initlandscape-Tuple{String, String}"><code>Persephone.initlandscape</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">initlandscape(landcovermap, farmfieldsmap)</code></pre><p>Initialise the model landscape based on the map files specified in the configuration. Returns a matrix of pixels.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/landscape.jl#L38-L43">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persephone.landcover-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel}" href="#Persephone.landcover-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel}"><code>Persephone.landcover</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">landcover(position, model)</code></pre><p>Return the land cover class at this position (utility wrapper).</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/landscape.jl#L100-L104">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persephone.updateevents!-Tuple{Agents.AgentBasedModel}" href="#Persephone.updateevents!-Tuple{Agents.AgentBasedModel}"><code>Persephone.updateevents!</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">updateevents!(model)</code></pre><p>Cycle through the list of events, removing those that have expired.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/landscape.jl#L66-L70">source</a></section></article></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="Wednesday 8 February 2023 12:48">Wednesday 8 February 2023</span>. Using Julia version 1.9.0-alpha1.</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">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="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 class="docstring"><header><a class="docstring-binding" id="Persefone.EventType" href="#Persefone.EventType"><code>Persefone.EventType</code></a> — <span class="docstring-category">Type</span></header><section><div><p>The types of landscape event that can be simulated</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/landscape.jl#L10">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.FarmEvent" href="#Persefone.FarmEvent"><code>Persefone.FarmEvent</code></a> — <span class="docstring-category">Type</span></header><section><div><pre><code class="language-julia hljs">FarmEvent</code></pre><p>A data structure to define a landscape event, giving its type, spatial extent, and duration.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/landscape.jl#L26-L31">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.LandCover" href="#Persefone.LandCover"><code>Persefone.LandCover</code></a> — <span class="docstring-category">Type</span></header><section><div><p>The land cover classes encoded in the Mundialis Sentinel data.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/landscape.jl#L6">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.Pixel" href="#Persefone.Pixel"><code>Persefone.Pixel</code></a> — <span class="docstring-category">Type</span></header><section><div><pre><code class="language-julia hljs">Pixel</code></pre><p>A pixel is a simple data structure to combine land use and ownership information in a single object. The model landscape consists of a matrix of pixels. (Note: further landscape information may be added here in future.)</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/landscape.jl#L13-L19">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.createevent!" href="#Persefone.createevent!"><code>Persefone.createevent!</code></a> — <span class="docstring-category">Function</span></header><section><div><pre><code class="language-julia hljs">createevent!(model, pixels, name, duration=1)</code></pre><p>Add a farm event to the specified pixels (a vector of position tuples) for a given duration.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/landscape.jl#L87-L91">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.distanceto-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel, Function}" href="#Persefone.distanceto-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel, Function}"><code>Persefone.distanceto</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">distanceto(pos, model, habitatdescriptor)</code></pre><p>Calculate the distance from the given location to the closest location matching the habitat descriptor function. Caution: can be computationally expensive!</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/landscape.jl#L120-L125">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.distanceto-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel, Persefone.LandCover}" href="#Persefone.distanceto-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel, Persefone.LandCover}"><code>Persefone.distanceto</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">distanceto(pos, model, habitattype)</code></pre><p>Calculate the distance from the given location to the closest habitat of the specified type. Caution: can be computationally expensive!</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/landscape.jl#L154-L159">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.distancetoedge-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel}" href="#Persefone.distancetoedge-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel}"><code>Persefone.distancetoedge</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">distancetoedge(pos, model)</code></pre><p>Calculate the distance from the given location to the closest neighbouring habitat. Caution: can be computationally expensive!</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/landscape.jl#L165-L170">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.farmplot-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel}" href="#Persefone.farmplot-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel}"><code>Persefone.farmplot</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">farmplot(position, model)</code></pre><p>Return the farm plot at this position, or nothing if there is none (utility wrapper).</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/landscape.jl#L109-L113">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.initlandscape-Tuple{String, String}" href="#Persefone.initlandscape-Tuple{String, String}"><code>Persefone.initlandscape</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">initlandscape(landcovermap, farmfieldsmap)</code></pre><p>Initialise the model landscape based on the map files specified in the configuration. Returns a matrix of pixels.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/landscape.jl#L38-L43">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.landcover-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel}" href="#Persefone.landcover-Tuple{Tuple{Int64, Int64}, Agents.AgentBasedModel}"><code>Persefone.landcover</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">landcover(position, model)</code></pre><p>Return the land cover class at this position (utility wrapper).</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/landscape.jl#L100-L104">source</a></section></article><article class="docstring"><header><a class="docstring-binding" id="Persefone.updateevents!-Tuple{Agents.AgentBasedModel}" href="#Persefone.updateevents!-Tuple{Agents.AgentBasedModel}"><code>Persefone.updateevents!</code></a> — <span class="docstring-category">Method</span></header><section><div><pre><code class="language-julia hljs">updateevents!(model)</code></pre><p>Cycle through the list of events, removing those that have expired.</p></div><a class="docs-sourcelink" target="_blank" href="https://git.idiv.de/xo30xoqa/persephone/-/blob/master//src/core/landscape.jl#L66-L70">source</a></section></article></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="Sunday 28 May 2023 23:20">Sunday 28 May 2023</span>. Using Julia version 1.9.0-alpha1.</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 8e835e9..70edc9e 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 · Persephone</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="Persephone logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="index.html">Persephone</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 Persephone</a></li><li><a class="tocitem" href="adapting.html">Adapting Persephone</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-Persephone-species-DSL"><span>The Persephone 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="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-Persephone-species-DSL"><a class="docs-heading-anchor" href="#The-Persephone-species-DSL">The Persephone species DSL</a><a id="The-Persephone-species-DSL-1"></a><a class="docs-heading-anchor-permalink" href="#The-Persephone-species-DSL" title="Permalink"></a></h2><p>In order to make implementing new species as easy as possible, Persephone 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">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="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#Persephone.@species-Tuple{Any, Any}"><code>@species</code></a> and <a href="nature.html#Persephone.@phase-Tuple{Any, Any}"><code>@phase</code></a>, followed by <a href="nature.html#Persephone.@initialise-Tuple{Any, Vararg{Any}}"><code>@initialise</code></a>, <a href="nature.html#Persephone.@trait-Tuple{Any}"><code>@trait</code></a>, <a href="nature.html#Persephone.@respond-Tuple{Any, Any}"><code>@respond</code></a>, and <a href="nature.html#Persephone.@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#Persephone.@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#Persephone.@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#Persephone.@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#Persephone.@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 Persephone, can be accessed using the <a href="nature.html#Persephone.@trait-Tuple{Any}"><code>@trait</code></a> macro. Within a phase block, <a href="nature.html#Persephone.@respond-Tuple{Any, Any}"><code>@respond</code></a> can be used to define the species' response to a <a href="simulation.html#Persephone.FarmEvent"><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#Persephone.@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#Persephone.@landcover-Tuple{}"><code>@landcover</code></a> or <a href="nature.html#Persephone.@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#Persephone.@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#Persephone.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#Persephone.@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#Persephone.@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#Persephone.@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="Wednesday 8 February 2023 12:48">Wednesday 8 February 2023</span>. Using Julia version 1.9.0-alpha1.</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="simulation.html#Persefone.FarmEvent"><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="Sunday 28 May 2023 23:20">Sunday 28 May 2023</span>. Using Julia version 1.9.0-alpha1.</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 a2630e6..929c889 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 · Persephone</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="Persephone logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="index.html">Persephone</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 Persephone</a></li><li><a class="tocitem" href="adapting.html">Adapting Persephone</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 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 Persephone 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="nature.html">« Nature</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="Wednesday 8 February 2023 12:48">Wednesday 8 February 2023</span>. Using Julia version 1.9.0-alpha1.</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">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 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="nature.html">« Nature</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="Sunday 28 May 2023 23:20">Sunday 28 May 2023</span>. Using Julia version 1.9.0-alpha1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
diff --git a/docs/builddocs.jl b/docs/builddocs.jl
index 9f85aa5..c1759e7 100644
--- a/docs/builddocs.jl
+++ b/docs/builddocs.jl
@@ -1,12 +1,12 @@
-# Build the HTML documentation for Persephone using Documenter.jl
+# Build the HTML documentation for Persefone using Documenter.jl
# https://documenter.juliadocs.org/stable/
push!(LOAD_PATH, "../src/")
-using Documenter, Persephone
+using Documenter, Persefone
-makedocs(sitename="Persephone",
- modules = [Persephone],
+makedocs(sitename="Persefone",
+ modules = [Persefone],
repo = "https://git.idiv.de/xo30xoqa/persephone/-/blob/master/{path}#{line}",
format = Documenter.HTML(prettyurls = false),
pages = ["index.md",
diff --git a/docs/src/index.md b/docs/src/index.md
index e9de026..3a783f5 100644
--- a/docs/src/index.md
+++ b/docs/src/index.md
@@ -80,4 +80,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-02-08 (commit d4e43d7)*
+*Last updated: 2023-05-28 (commit 60e9012)*
--
GitLab