ALMaSS ODdox Documentation

1.0

Chris J. Topping

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

Last modified 14th January 2011



ODdox

The ODdox documentation (Topping et al, 2010) is a hybrid between the ODD protocol (Grimm et al, 2006) for describing IBMs and Doxygen ( http://www.doxygen.org ) a standard software tool designed to increase the accessibility of program code. In ODdox documentation provides a set of html documents generated by Doxygen whcih form cross-linked documentation of all classes, methods and variables used in a progam code. This allows the user to browse through classes and see the inter-relationships in the code. At the lowest level the code is presented together with a brief description of what it does, and including the comments placed inside the code itself. The ODdox thus provides a powerful way of documentating IBMs and allowing others to choose to see precisely what has been done or to get an overview quickly without the details.


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 Skylark model - see skylark for a comprehensive description. The skylark model simulates Alauda arvensis and was developed based primarily on Danish observational and experimental data. The skylark model interacts with the landscape via vegetation and insect biomass development, and is also influenced by farm management practices both directly and indirectly though altering vegetation or insect biomass.

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. 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
2. 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.
3. Grimm V. & Railsback S.F. 2005. Individual-Based Modeling and Ecology. Princeton University Press, Princeton, NJ.
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. 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.
6. 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.
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.
10. C.J. Topping, T.T. Hoye and C.R. Olesen 2010. Opening the black box: Development, testing and documentation of a mechanistically rich agent-based model. Ecological Modelling 221 (2), 245-255 doi:10.1016/j.ecolmodel.2009.09.014






ALMaSS ODdox Documentation, 1.0