Ladybird MIDox Documentation {#Ladybird_page}
=========
## Introduction ##
This document will follow the Model Implementation Documentation with Doxygen (MIDox) format (Topping et al., 2023), the next step in designing, documenting and calibrating complicated models after the “Formal Model” format document (Topping et al., 2022).<br>
Here we describe the implementation of the Ladybird formal model \cite chuhutin_seven-spotted_2023 (Chuhutin et al., 2023).
The currently documented implementation has been calibrated (ref, Calibration paper) using pattern-based calibration (ref?) that was set up to replicate the basic ecological patterns of the ladybird population. In particular the phenological curves were used to fit the parameters of development, reproduction and mortality, the spatial distribution patterns, mean walking time and average movement speed measured in in field were used to fit the movement parameters. Information about the distribution and popularity of hibernaculae at different points in time was used to fit the parameters concerning the diapause and its timing.<br>
This model was created within the ALMaSS (Animal Landscape and Man Simulation System) framework (Topping, 2022; Topping et al., 2003) and therefore by design has the ability to connect with the other animal models that share the same framework (aphids as a food source, other polyphagous insect predators as potential competitors).<br>
Designed in C++ using an object-oriented paradigm this model is made generic and easily expandable on purpose. If new behaviours of the ladybirds or new interconnection between the agents and the overall model will be discovered (e.g. in previously not modeled habitats) they could easily be introduced as a part of the model.<br>
The division of the code into classes and methods was based on the overall model functionality and does not necessarily have a biological meaning. Thus, we combined the pre-pupa stage of development with the pupa stage since (due to its immobility) it shares the same basic behaviours. On the same note, the method that performs a long range movement is shared independently of the movement purpose (whether it is search for food, dispersion or aggregation).<br>

## Aims and Purposes ##
The purpose of this document is to both document the model source code, for readability and future maintenance, but also to record the desicions made when the formal model in its general algorithmic form (Chuhutin et al., 2023) was translated into a source code.<br>
The seven-spot ladybird has complicated behaviours (Hodek et al., 2012) that are intricately connected to the landscape parameters. In an effort to build an agent-based model one can only choose some of them for implementation. The behaviours that were chosen to be implemented in detail in our model are those that either:
- According to our experts provide an important driver of ladybirds abundance or survival on the population level. (E.g. the cannibalism among the early developmental stages, the local dynamics at each cell, and the cannibalism of more developed stages on the less developed stages)
- Are an integral part of an essential processes that are well sampled and documented in literature and therefore provide a tool for the calibration of the model as a whole. (E.g. tracking the abundance of the ladybird in hibernaculae and the spread of the hibernating ladybirds in various landscape types are closely related to the distribution and mortality and are documented in literature (Bianchi & Van der Werf, 2003; Honěk et al., 2007)).

The purpose of this model is to be used for complex scenarios landscape-based risk assessment together with a set of underlying prey models. However, it could be used as a standalone model (in the ALMaSS environment), provided the phenology of the aphids, and therefore implementing only one-directional dependence between the predator and the prey.

## Model in Brief ##
The model aims to represent a population of ladybirds on a spatially-restricted landscape. While the model is running, agents (that represent various stages of ladybird development) are laid as eggs, develop, forage, move, reproduce, overwinter and die. During each one of these activities the agents interact with the landscape (through temporally dynamic weather, crop rotations, farming events and vegetation growth models), the other species (the prey they are feeding on) and each other (cannibalism and collective hibernation).<br>
The life-cycle of ladybird includes four main stages: eggs, larvae, pupae and adults (females), while each one of them is implemented using a specific class (Ladybird_Eggs, Ladybird_Larvae, Ladybird_Pupae and Ladybird_Adult, see Figure 1). The larva stage is composed of four instars, all of which utilize the same class Ladybird_Larvae. Our model is only implementing adult females, while adult males are ignored (the reasoning for that decision is provided by Chuhutin et al (2023)).<br>
In addition to classes that represent various developmental stages three supplementary classes exist. The class Ladybird_Base includes the methods and variables which are used by more than one developmental stage (e.g. method Ladybird_Base::Cannibalise() is used both by Ladybird_Larvae and Ladybird_Adult). The class Ladybird_Population_Manager is a class that includes variables and implements methods that are utilised on the level of the ladybird population (e.g. Ladybird_Population_Manager::getMaxHopDistance() that returns maximum hop distance for a ladybird adult, which is the same for all the individuals on each day and is a function of mean daily temperature). The class LadybirdConstantClass includes all the constant variables that are defined in the start of the simulation, its instance is included as a member variable in Ladybird_Population_Manager and used by the rest of the ladybird classes.<br>
Two important additional data structures were created inside Ladybird_Population_Manager for implementation purposes. Ladybird_Population_Manager::m_LadybirdDensityMap is a three-dimensional array(\ref hibernation "1") implemented using [Blitz++ library](https://github.com/blitzpp/blitz) that keeps track of the ladybirds of different developmental stages in the landscape. Each time, when the agent moves, dies or is created, the map is updated. The variable type used in the array defines the maximum number of objects of each type so that if we use unsigned char the maximum number of objects is

\f[
N_\mathrm{max}=255\cdot \mathrm{Landscape\_size}_x \cdot \mathrm{Landscape\_size}_y
\f]

which for landscape of 10x10 km equals \f$255\cdot10^8\f$. In pracise the number is much lower, since not all parts of the landscape is used by the agents (e.g. ladybirds avoid locations occupied by water or urban areas).
Ladybird_Population_Manager::m_LadybirdCannibalismMap is also a three-dimensional array which is updated at each cannibalism event and is used to remove the individuals, which have been eaten from the simulation.
In the \ref implementation "next chapter" we will provide a detailed account on the implementation of each one of the main behaviours, describing the data types and algorithms employed.<br>
<br>
\image html LadybirdFig1.png "Figure 1. Overview of ladybird classes. The inheritance is denoted with an arrow directed from the inherited towards a base class." width=50%
<br>
## Implementation details ## {#implementation}
### Oviposition ###
fdfdfd
fdfdfd
fdfd
## Scheduling ##
## Interconnections ##
## Inputs ##
## Outputs ##
## State variables ##
## Scales ##
## Model parameters ##
## Details ##
## Discussion of implementation ##
## References #
\cite chuhutin_seven-spotted_2023 Andrey Chuhutin, Danuta Frydyszczak, Elżbieta Ziółkowska, and Christopher J. Topping. Seven-spotted ladybird Formal Model. <em>In submission to Food and Ecological Systems Modelling Journal</em> <br>

\anchor hibernation 1. Hibernating ladybirds have a dedicated row in Ladybird_Population_Manager::m_LadybirdDensityMap despite not being implemented as a separate class.