Started writing skylark ODD

docs/src/skylark.md

 # Skylark
 
 *Alauda arvensis* is a common and charismatic species of agricultural landscapes.
-At the moment, this implementation is still in development.
+This animal model is one component of the [`nature`](architecture) submodel of Persefone.jl.
 
-**ODD?**
+The  model  description follows  the  ODD  (Overview,  Design  concepts, Details)  protocol  (Grimm  et  al.,  [2006](https://doi.org/10.1016/j.ecolmodel.2006.04.023); [2010](https://doi.org/10.1016/j.ecolmodel.2010.08.019); [2020](https://doi.org/10.18564/jasss.4259)):
 
-## Life cycle
 
-*TODO*
+## 1. Purpose
+
+The purpose of this animal model is to simulate the abundance and distribution of a population of
+*Alauda arvensis* in response to farm management in Central European agricultural landscapes.
+
+## 2. Entities, state variables, and scales
+
+### 2.1 Landscape
+
+The [simulated landscape](gis) consists of a grid of pixels with a resolution of 10m and
+can have an extent of 20km²-200km² (approximately; depending on the chosen input map).
+Each pixel is assigned a land cover class. It may also be associated with a farm plot,
+in which case it will contain information about the type and growth stage of the crop
+planted here. [Farm management](management) determines which crops are grown when, and 
+when disturbance (e.g. mowing, harvesting, tillage) takes place.
+
+### 2.2 Animals
+
+The simulated individuals (a.k.a. agents) are mature [skylarks](species#Skylark). Each skylark 
+is characterised by the following variables:
+
+- **ID:** A unique identifier for this individual, which can be used to link it to its parents
+  and its offspring.
+
+- **sex:** Male or female.
+
+- **phase:** The individual's current stage in the annual/life cycle. May be one of: `migration`, 
+  `nonbreeding`, `territorysearch`, `occupation`, `matesearch`, `nesting`, `breeding`.
+
+- **position** The individual's position in the simulated landscape.
+
+- **mate** The ID of the individual with which this individual has mated this year, if any.
+
+- **territory** A list of coordinates of the positions in the landscape that this individual
+  claims as its nesting and feeding territory.
+  
+- **nest** A coordinate giving the location of the currently active nest.
+
+- **clutch** The number of juvenile (i.e. not yet independent) skylarks that this individual is
+  currently raising.
+
+
+## 3. Process overview and scheduling
+
+The simulation proceeds in time steps of one day. Every day, each individual executes the function
+associated with their current life phase:
+
+- `migration`: The individual is held in a separate data structure (apart from the model landscape)
+  and does nothing until its return date is reached. Then, it is re-introduced to the landscape
+  and assigned the phase `territorysearch` (for males) or `matesearch` (for females).
+  
+- `territorysearch`: Males return first from migration. If they already have a territory from a
+  previous year, they return to this. Otherwise, they move randomly through the landscape until
+  they find a contiguous territory that satisfies their habitat requirements. Once a male has a
+  territory, it changes its phase to `occupation`.
+  
+- `matesearch`: Females return later than males from their winter migration. If they already had
+  a partner the previous year, they have a given probability of remaining with this partner.
+  Otherwise, they move randomly through the landscape, looking for a male with a territory and
+  without a partner. Once the female has a partner, it changes its phase to `nesting`.
+
+If an individual fails to find a territory or a mate, it changes its phase to `nonbreeding` once the
+breeding season is over.
+
+- `occupation`: The male moves at random about its territory until the breeding season is over.
+  Then it changes its phase to `nonbreeding`. (*Note:* Skylark males actively help with feeding
+  their chicks. However, feeding is only modelled indirectly here, through the process of habitat
+  selection when the male forms its territory.)
+  
+- `nesting`: The female selects a suitable location within the male's territory for the nest.
+  Building the nest and laying eggs takes a number of days, during which she does nothing else.
+  Then, she changes her phase to `breeding`.
+  
+- `breeding`: The female checks for mortality. The probability of brood loss varies with the age
+  of the clutch and the nesting habitat. If and when the chicks reach independence (30 days after
+  hatching), they are instantiated as new individuals in the `nonbreeding` phase.
+  
+If a nest fails due to predation or disturbance, or a brood leaves the nest successfully, the
+female resets her phase to `nesting` and begins again if the breeding season is not yet over.
+If it is, she changes her phase to `nonbreeding`.
+
+- `nonbreeding`: Non-breeding mature birds move randomly around the landscape, keeping close
+  to other individuals (flocking behaviour). Once their individual migration date is reached,
+  they are removed from the landscape until the following year (see above). Mature birds have
+  a mortality probability for their first summer, and others thereafter for each winter.
+
+## 4. Design concepts
+
+### 4.1 Basic principles
+
+### 4.2 Emergence
 
-## Patterns
 
 Patterns that can be used for validation with POM:
 
@@ -17,6 +105,79 @@ Patterns that can be used for validation with POM:
 
 - *TODO*
 
+
+### 4.3 Adaptation
+
+- habitat choice
+
+### 4.4 Objectives
+
+### 4.5 Learning
+
+### 4.6 Prediction
+
+### 4.7 Sensing
+
+- habitat quality (type, height, cover)
+
+- proximity of conspecifics
+
+### 4.8 Interaction
+
+- mating
+
+- flocking
+
+### 4.9 Stochasticity
+
+### 4.10 Collectives
+
+### 4.11 Observation
+
+## 5. Initialisation
+
+## 6. Input data
+
+The general input to Persefone (i.e. maps and weather data) is described [here](gis).
+
+The following extract from the [source code](https://git.idiv.de/persefone/persefone-model/-/blob/master/src/nature/species/skylark.jl?ref_type=heads)
+lists the species parameters and their values as used by the Skylark model:
+
+```julia
+@species Skylark begin
+    const movementrange::Length = 500m #XXX arbitrary
+    const visionrange::Length = 200m #XXX arbitrary
+    
+    const eggtime::Int64 = 11 # days from laying to hatching
+    const nestlingtime::Int64 = 9 # days from hatching to leaving nest
+    const fledglingtime::Int64 = 21 # days from leaving the nest to independence
+
+    #XXX predation mortality should be habitat-dependent
+    const eggpredationmortality::Float64 = 0.03 # per-day egg mortality from predation
+    const nestlingpredationmortality::Float64 = 0.03 # per-day nestling mortality from predation
+    const fledglingpredationmortality::Float64 = 0.01 # per-day fledgling mortality from predation
+    const firstyearmortality::Float64 = 0.38 # total mortality in the first year after independence
+    const migrationmortality::Float64 = 0.33 # chance of dying during the winter
+
+    const minimumterritory = 5000m² # size of territory under ideal conditions
+    const mindistancetoedge = 60m # minimum distance of habitat to vertical structures
+    const maxforageheight = 50cm # maximum preferred vegetation height for foraging
+    const maxforagecover = 0.7 # maximum preferred vegetation cover for foraging
+    const nestingheight = (15cm, 25cm) # min and max preferred vegetation height for nesting
+    const nestingcover = (0.2, 0.5) # min and max preferred vegetation cover for nesting
+
+    const matefaithfulness = 0.5 # chance of a female retaining her previous partner
+    const nestingbegin::Tuple{Int64,Int64} = (April, 10) # begin nesting in the middle of April
+    const nestbuildingtime::UnitRange{Int64} = 4:5 # 4-5 days needed to build a nest (doubled for first nest)
+    const eggsperclutch::UnitRange{Int64} = 2:5 # eggs laid per clutch
+    const nestingend::Int64 = July # last month of nesting
+end
+```
+
+## 7. Submodels
+
+
+
 ## Sources
 
 - Bauer, H.-G., Bezzel, E., & Fiedler, W. (Eds.). (2012). Das Kompendium
@@ -25,20 +186,24 @@ Patterns that can be used for validation with POM:
   Aufl. 2005). AULA-Verlag
 
 - Delius, J. D. (1965). A Population Study of Skylarks Alauda Arvensis.
-  Ibis, 107(4), 466–492. https://doi.org/10.1111/j.1474-919X.1965.tb07332.x
+  [Ibis, 107(4), 466–492.](https://doi.org/10.1111/j.1474-919X.1965.tb07332.x)
 
 - Donald et al. (2002). Survival rates, causes of failure and productivity
-  of Skylark Alauda arvensis nests on lowland farmland. Ibis, 144(4), 652–664.
-  https://doi.org/10.1046/j.1474-919X.2002.00101.x
+  of Skylark Alauda arvensis nests on lowland farmland. 
+  [Ibis, 144(4), 652–664.](https://doi.org/10.1046/j.1474-919X.2002.00101.x)
 
 - Glutz von Blotzheim, Urs N. (Ed.). (1985). Handbuch der Vögel Mitteleuropas.
   Bd. 10. Passeriformes (Teil 1) 1. Alaudidae - Hirundidae. AULA-Verlag, Wiesbaden.
   ISBN 3-89104-019-9
 
 - Jenny, M. (1990). Territorialität und Brutbiologie der Feldlerche Alauda
-  arvensis in einer intensiv genutzten Agrarlandschaft. Journal für Ornithologie,
-  131(3), 241–265. https://doi.org/10.1007/BF01640998
+  arvensis in einer intensiv genutzten Agrarlandschaft. [Journal für Ornithologie,
+  131(3), 241–265.](https://doi.org/10.1007/BF01640998)
+  
+- Jeromin, K. (2002). Zur Ernährungsökologie der Feldlerche (Alauda arvensis L. 1758) 
+  in der Reproduktionsphase [Doctoral thesis]. 
+  [Christian-Albrechts-Universität zu Kiel.](https://macau.uni-kiel.de/receive/diss_mods_00000968)
 
 - Püttmanns et al. (2022). Habitat use and foraging parameters of breeding Skylarks
   indicate no seasonal decrease in food availability in heterogeneous farmland.
-  Ecology and Evolution, 12(1), e8461. https://doi.org/10.1002/ece3.8461
+  [Ecology and Evolution, 12(1), e8461.](https://doi.org/10.1002/ece3.8461)

src/nature/energy.jl

@@ -3,6 +3,9 @@
 ### This file contains structs and functions for implementing Dynamic Energy Budgets.
 ###
 
+## XXX THE CODE IN THIS FILE IS CURRENTLY NOT USED AND LIKELY WON'T BE IN FUTURE.
+## HOWEVER, I PREFER TO KEEP IT FOR NOW IN CASE WE EVER DO. (DV, 29th July 2024)
+
 #TODO add units
 
 ## STRUCTS

src/nature/insects.jl

@@ -3,6 +3,9 @@
 ### This file contains the submodel that calculates insect biomass
 ###
 
+## XXX THE CODE IN THIS FILE IS CURRENTLY NOT USED AND LIKELY WON'T BE IN FUTURE.
+## HOWEVER, I PREFER TO KEEP IT FOR NOW IN CASE WE EVER DO. (DV, 29th July 2024)
+
 """
     insectbiomass(pixel, model)
 

src/nature/nature.jl

@@ -112,7 +112,7 @@ function updatenature!(model::SimulationModel)
     # Update all animals. Dead animals are replaced by `nothing`, we can skip these.
     #XXX I assume that keeping all those `nothing`s in the animal vector won't lead
     # to memory bloat, but I will have to check that.
-    for a in model.animals
+    for a in model.animals #XXX randomise the order?
         !isnothing(a) && stepagent!(a, model)
     end
     # The migrant pool is sorted by date of return, so we can simply look at the top

src/nature/species/skylark.jl

@@ -120,8 +120,11 @@ adjusting it to new conditions when and as necessary.
 @phase Skylark occupation begin
     #move to a random location in the territory
     @move(@rand(self.territory))
-    if month(model.date) > self.nestingend #XXX check that all the young have left the nest
-        @setphase(nonbreeding)
+    if month(model.date) > self.nestingend
+        # once the breeding season is over and all the young have left the nest, stop breeding
+        if self.mate == -1 || @animal(self.mate).clutch == 0
+            @setphase(nonbreeding)
+        end
     end
     #TODO adjust territory as needed (e.g. once a week, or when a brood is done?)
 end
@@ -211,7 +214,7 @@ chicks are independent or in case of brood loss.
     #XXX Schachtelbruten - sometimes skylarks start a new nest before the previous young are gone
     # wait for eggs to hatch & chicks to mature, checking for predation and disturbance mortality
     self.timer += 1
-    #XXX this should be habitat-dependent!
+    #TODO this should be habitat-dependent!
     if self.timer <= self.eggtime
         @chance(self.eggpredationmortality) && destroynest!(self, "predation")
     elseif self.timer <= self.eggtime + self.nestlingtime
@@ -220,6 +223,7 @@ chicks are independent or in case of brood loss.
         @chance(self.fledglingpredationmortality) && destroynest!(self, "predation")
     else
         # create new young, reset timer and clutch counter
+        #TODO first year mortality
         @reproduce(self.clutch, self.mate)
         self.clutch = 0
     end