ALMaSS ODdox Documentation

1.0

Chris J. Topping

Department of Wildlife Ecology & Biodiversity
National Environmental Institute
Aarhus University
Grenaavej 14, DK-8410
Roende
Denmark

3rd November 2009


ODdox

ODdox documentation was created by combining a modified version of the ODD protocol (Grimm et al. 2006) with documented code using doxygen (van Heesch, 1997) to create what we term ODdox documentation. The original ODD (Overview, Design, Detail) protocol divides the model documentation into defined sections covering aspects of model structure and functioning, and finally model details. The new ODdox protocol (Overview, Design, doxygen) broadly follows ODD protocol, but is completed and augmented by extracting comments from the source code. The details of the model are therefore described via descriptions of classes, methods, and variables using hyperlinks to the relevant sections in the source code. In contrast to the ODD, this means that by far the major part of the documentation is placed outside the traditional ODD sections, but linked to them via hyperlinks. The ODdox was specifically designed to facilitate documentation of large object-oriented models with many interacting components, and to provide a flexible way of building documentation as the software is developed. It is therefore structured following logical divisions of the model entities, primarily base class types. At each subdivision there is a class or set of linked classes in focus, and six of the seven ODD sections are written for these classes. The "Submodels" section of ODD becomes superfluous since any links to sub-models are covered by class descriptions for the classes in focus, and submodels per se should not exist. However, there may be important connections between the focus classes and other ODdox sections (e.g. other species, environment). The section, "Interconnections", is used to describe these and provide html links to them. This approach permits the documentation of large models to be built as an expandable library, and rather than rewriting documentation for additions only requires judicious updating of the interconnection section, doxygen performs the rest of the tasks based on software comments in the new code. Our aim in developing ODdox was therefore to provide an easier, more complete, and more flexible method of documenting large models together with a more user friendly interface, benefitting developers and readers alike.


Using ODdox documentation

This page provides a starting point for stepping off into the ALMaSS documentation by clicking any of the blue links. Here we provide an overview of what the system does in broad terms and a set of links to important system components each with their own ODDox description. Alternatively you can use the Classes tab to get a list of classes and step into the documentation from there.

ALMaSS was written in C++ code which is an object-oriented language. Objects (e.g. a male partridge) are termed 'instances' of a 'class' (e.g. Partridge_Male). Classes are arranged in a hierarchy whereby information contained in a base class is available to descendent classes. For an example see the class diagram at the top of TALMaSSObject. This diagram shows how TAnimal is descended from TALMaSSObject, and subsequently Partridge_Base is descended from TAnimal, and Partridge_Male from Partridge_Base. Understanding this basic concept and terminology will be an advantage when traversing through the code using the hyperlinks since methods (functions, behaviours) and attributes that are not modified in the descendent class need to be viewed in the base class. This method of programming reduces code size and eases code development. An example of this approach can be seen by comparing Hare_Juvenile::st_Dispersal with Hare_Female::st_Dispersal. In this case the female dispersal uses the juvenile code, then adds special female behaviour afterwards.

Please note that this set of documents is intended to document the ALMaSS system, but is a work in progress and not complete. Links are provided to parts of ALMaSS where currently documented but for further information see references 4-9 below.



Documentation following ODdox protocol

Overview

1. Purpose

ALMaSS was constructed to be a highly flexible system of models for use in predicting the impact of man's management of the Danish landscape on a range of key animal species. It is typically used by constructing a baseline scenario and ome or more test scenarios, and then comparing predicted animal numbers and distribution between these. ALMaSS was designed with realism as a watchword, hence highly detailed management of farms is implemented together with the potential to use high resolution topographic maps (typically to 1m2) and climate data. However, this input is not obligatory and scenarios can be constructed using much more simple inputs such as geometric landscapes and simple or no mangement. Applications of ALMaSS have been in landscape ecology and population dynamics, applied pesticide research, and decision making at policy levels.

2. State variables and scales

ALMaSS is typically employed to simulate landscapes from 5x5km to 10x10km, although there is no practical limit to the size of landscapes simulated except for computer memory and CPU speed considerations.
State variables at the system level are the number and locations of the animals under study and the variables describing the state of the landscape. This latter set includes temperature, rainfall, windrun at the global scale; at the level of a single habitat patch, patch type (termed landscape element type), vegetation type, vegetation height, vegetation density, vegetation leaf area (green & dead), generalised insect abundance, and history of management events. Pesticide and other chemical residues are recorded at a finer scale than the habitat patch, typically in 4x4m areas. Typical state variables for each animal model will represent information both at the individual and population level, see Vole_Base for an example.

3. Process Overview and Scheduling

ALMaSS primarily runs on a daily time-step, although it is possible to create animal models with a shorter time step, the landscape management is fixed to the daily step. At the start of each day all landscape management events are simulated for the full day (see Farm) and the response of vegatation and generalised insect models is calculated. Subsequently any animal models are executed.

Animal models all use a common algorithm for carrying out population management each time-step. This algorithm uses a hierarchical approach to scheduling to overcome the problems of currency between interacting objects discussed by Topping et al. (1999). Although the computer is operating serially, the objects must be scheduled such that they appear to operate in parallel. For all ALMaSS animal models this is achieved using a state machine to move objects between behavioural states and by dividing the time-step into three sections, namely BeginStep, Step and EndStep. All objects execute their BeginStep code before any objects can execute Step code, and all must be finished with Step code before any can execute EndStep code.

Inside BeginStep, Step and EndStep, the order of execution of individuals can be controlled and be either random (default) or ordered e.g. w.r.t. their co-ordinates. The first case allows prevents the order of execution giving any one object an advantage in for example a competition situation, the second can be used as a way of optimizing code speed. Step code differs from BeginStep and EndStep in that it is repeatedly called until all animals indicate that they have finished with the Step code. This allows many linked behaviours to be carried out in this one step, often necessary to generate flexible responses to internally or externally generated events. The BeginStep/Step/EndStep structure allows for a very flexible combination of interlinked behaviours, and permits efficient use of resources e.g. by removing dead animals in the BeginStep before they waste CPU resources in Step. Handling of all scheduling via BeginStep/Step/EndStep is performed in the base class Population_Manager.


Design

4. Design Concepts


This section uses the headings suggested by (Grimm et al. 2006) where their rationale and definition is described. Note that the descriptions applied here describe the ALMaSS system at the system level, for individual level descriptions more akin to the aims of the original ODD protocol please refer to specific models selectable from the menu to the left.

4.a Emergence

Due to the potential complexity of any ALMaSS simulation of so many interacting agents and agent types there are a larger number of emergent properties, however in typical ALMaSS usage the primary emergent properties we are interested in are the number, distribution, and physiological state of the animals being modelled. These properties emerge in response to the interaction between the behavioural decisions of the animals as a result of the local information sensed from their surroundings. Details of these processes can be found in the animal model descriptions.

4.b Adaptation

At the system level there is no adaptation, but individal animal models may implement this.

4.c Fitness

There is no measure of fitness at the system level, but animals may measure their fitness in reproductive success, longevity or physiological state.

4.d Prediction

There is prediction at the ALMaSS system level.

4.e Sensing

There is no sensing at the system level, however all animals are provided with sensing abilities depending upon the animals type and the detail to which it is modelled.

4.f v

ALMaSS is designed primarily to be mechanistic, but stochasticity is built in when handling probabilities. Typically animal or management decisions result in a probabilistic assessment e.g 40% of farmers may spray insecticide in winter wheat, but if no information is present to determine which 40%, then this is determined probabalistically.

4.g Collectives

ALMaSS uses many collectives to group objects e.g. a number of fields as a farm, partridges in a covey, all voles as a vole population. These collectives are primarily used for code efficiency but some are used as the lowest level of precision e.g. a vole litter.

4.h Observation

There are a number of standard outputs from ALMaSS available from the PopulationManager. There is also the potential to write specific data probes to collect data on individuals or populations as required, e.g. see Vole_Population_Manager::GeneticsResultsOutput

5. Initialisation

Initialisation of ALMaSS is carried out using a text input file called TIALMaSSConfig.cfg This contains a set of configuration variables that can be used to determine what landscape to use, the weather, type of management and provide parameter values for the animal models. A segment of this file is listed below:

# ------------------------------------------------------------------------------
# ------------------------------------------------------------------------------
# START LANDSCAPE DATA FILES SECTION
# ------------------------------------------------------------------------------
# ------------------------------------------------------------------------------
MAP_WEATHER_FILE (string) = "foulum_cjt.pre"
MAP_CROPCURVES_FILE (string) = "curves.pre"

Standard landscape for use in CIPE:
MAP_MAP_FILE (string) = "Bje00_10x10_060712_HBFB25.lsb"
MAP_POLY_FILE (string) = "Bje00_10x10_060712_HBFB25_PolyRefs.txt"
MAP_FARMREF_FILE (string) = "Bje00_10x10_060712_HBFB25_FarmRefs.txt"

FARM_FIXED_CROP_TYPE (int) = 22 #1 Spring Barley, 4 Winter Wheat, 22 Winter Rye, 206 Oats FARM_FIXED_CROP_ENABLE (bool) = false
FARM_ENABLE_CROP_ROTATION (bool) = true
FARM_FIXED_ROTATION_ENABLE (bool) = false
FARM_FIXED_ROTATION_FARMS_ASYNC (bool) = false
FARM_FIXED_ROTATION_FARMTYPE (int) = 0
# Combination for mono-crop: true, true/false, true/false, true/false,
# Combination for normal field rotation: false, true, false, false
# Combination for farm rotation: false, true, true, true
# Combination for landscape rotation: false, true, true, false
# ------------------------------------------------------------------------------
# ------------------------------------------------------------------------------
# END LANDSCAPE DATA FILES SECTION
# ------------------------------------------------------------------------------
# ------------------------------------------------------------------------------

6. Inputs


In order for ALMaSS to run it requires the following inputs:
i) A valid configuration file (see above), which will determine the parameter values for species models and landscape input files.
ii) A landscape consisting of three files a map file (.lsb), a polygonreference file, and a farm reference file. Together these three files map and describe all the structural elements of the landscape and list the farms and farm types.
iii) A file describing daily climate data.
iv) A .ini file listing the species to run and the number of years to run.

7. Interconnections

ALMaSS consists of a many interlinked components, which as they are documented they will be appended here with short descriptions:

The Bembidion model - see Bembidion for a comprehensive description. The Bembidion model simulates a typical flightless carablid beetle, and is based upon Bembidion lampros. This model simulates movement, reproduction, mortality and developmental rates of beetle life-stages. It is highly dependent upon weather data inputs and management events.

The hare model - see hare for a comprehensive description. The hare model simulates the European Brown Hare (Lepus europaeus syn. L. carpensis). This model simulates movement, mortality, and reproductive behaviour for the hare and incorporates detailed energetic mechanisms controlling growth, reproduction and mortality.

The partridge model - see partridge for a comprehensive description. The partridge model simulates the Grey Partridge (Perdix perdix). This model simulates movement, mortality, and reproductive behaviour for the partridge. The partridge model is unique among the ALMaSS models in having a collective, the Partridge_Covey which is often the primary entity being modelled.

The vole model - see vole for a comprehensive description. The vole model simulates a typical small mammal, and is based upon Microtus agrestis. This model simulates movement, territorial and reproductive behaviour for the vole in terms of male and female voles. It it optionally linked to a simulation of predators (TPredator_Population_Manager class and TPredator and descendent classes). The vole model also provides the potential for using population genetics via connections to GeneticMaterial.

The population manager - see Population_Manager - this class and its descendents control the population level internal management of all model animals. The population manager contains lists of all animals and is used for output and population level inputs e.g. catastrophes killing x% of the population.

The farm manager - see the Farm class. This class manages farm events via connections to models of crops based upon the class Crop and its descendents e.g. WinterWheat, and farm types e.g. ConventionalCattle. The farm class contains code causing simulated impacts for all farm practices modelled in ALMaSS.

Management plans for crops - see Crop class and descendents. This class' descendents simulate specific management required for each crop. Events triggered by these management plans are handled by the farm manager and are available for inspection by other objects, eg animal models in the system.


8. References

1. Grimm V., Berger U., Bastiansen F., Eliassen S., Ginot V., Giske J., Goss-Custard J., Grand T., Heinz S.K., Huse G., Huth A., Jepsen J.U., Jorgensen C., Mooij W.M., Muller B., Pe'er G., Piou C., Railsback S.F., Robbins A.M., Robbins M.M., Rossmanith E., Ruger N., Strand E., Souissi S., Stillman R.A., Vabo R., Visser U. & DeAngelis D.L. 2006. A standard protocol for describing individual-based and agent-based models. Ecological Modelling, 198, 115-126.
2. Grimm V. & Railsback S.F. 2005. Individual-Based Modeling and Ecology. Princeton University Press, Princeton, NJ.
3. Topping, C.J., Rehder, M.J. & Mayoh, B.H. 1999. VIOLA: a new visual programming language designed for the rapid development of interacting agent systems. Acta Biotheoretica. 47: 129?140.
4. Odderskaer P, Topping C J, Petersen M B, Rasmussen J, Dalgaard T, Erlandsen M. 2006. Ukrudtsstriglingens effekter paa dyr, planter og ressourceforbrug.
Miljeostyrelsen, Bekaempelsesmiddelforskning fra Miljeostyrelsen 105. Available at http://www2.mst.dk/Udgiv/publikationer/2006/87-7052-343-6/pdf/87-7052-344-4.pdf
5. Bilde T. & Topping C. 2004. Life history traits interact with landscape composition to influence population dynamics of a terrestrial arthropod: A simulation study. . Ecoscience, 11, 64-73
6. Thorbek P. & Topping C.J. 2005. The influence of landscape diversity and heterogeneity on spatial dynamics of agrobiont linyphiid spiders: An individual-based model. Biocontrol, 50, 1-33.
7. Topping C.J., Hansen, T.S., Jensen, T.S., Jepsen, J.U., Nikolajsen, F. and Oddersaer, P. 2003. ALMaSS, an agent-based model for animals in temperate European landscapes. Ecological Modelling 167: 65-82.
8. Topping C.J. & Odderskaer, P. 2004. Modeling the influence of temporal and spatial factors on the assessment of impacts of pesticides on skylarks. Environmental Toxicology & Chemistry 23, 509-520.
9. Topping, C.J., Sibly, R.M., Akcakaya, H.R., Smith, G.C. & Crocker, D.R. 2005. Risk assessment of UK skylark populations using life-history and individual-based landscape models. - Ecotoxicology 14(8): 863-876.





ALMaSS ODdox Documentation, 1.0