skip navigation

EcoSwarm: Tools for Ecological Models in Swarm

The Swarm simulation system is an extensive library of code for implementing agent-based simulation models. Originally developed at the Santa Fe Institute, Swarm is now maintained by the non-profit Swarm Development Group ( swarm

EcoSwarm is our library of code that can be used as an extension to Swarm for individual-based ecological models. (Much of EcoSwarm is also potentially useful for agent-based models in fields other than ecology.)

The Swarm library is written in Objective-C, an object-oriented extension of the C language. All EcoSwarm code is written as Objective-C classes.

Funding for development of this software was provided by the Electric Power Research Institute (EPRI), the U. S. Forest Service, the U. S. Fish and Wildlife Service, the U. S. Environmental Protection Agency, and other agencies.

EcoSwarm was last updated February 2012 (some components have not been updated since the previous release in May, 2011). Code is provided in Windows file format. EcoSwarm contains the following code:

/* Breakout Reporter */

This set of classes provides a data collection device for model populations. It allows easy file output of statistical summaries of selected agent characteristics, broken out by agent traits. With one statement, the programmer provides the name of an output file and a Swarm list containing the population of objects from which data are to be reported (e.g., the list of animals alive in the model). Additional simple statements specify what variables are to be reported (e.g., animal abundance, weight, growth rate, etc.), what categories are used to break out results (e.g., by species, age, sex), and whether the output should be the count, total, mean, maximum, minimum, standard deviation, or variance. Columns of additional data (e.g., date, temperature) are easily added to the file. Statistics are re-calculated and a line of output written whenever the "update" message is executed.

* Download the BreakoutReporter code (TAR archive)

* Download the BreakoutReporter code of May 2011, which produces a different output format (more columns, fewer lines; see documentation) (TAR archive)

* Download the BreakoutReporter documentation (PDF)

/* Time Manager */

Our Time Manager class has two main functions: keeping track of model time in simulators using daily, hourly, or other time step sizes; and providing a number of handy time-related calculations. The class uses the operating system's "time_t" format (number of seconds since 1/1/1970) and date-time functions. The user can, for example, set the simulation's start time, end time, and time step size, and the Time Manager keeps track of current time. The time-related calculations include (for example) determining whether the current model time falls within a specified date window and determining the number of days between two time values.

* Download the Time Manager code (TAR archive)

* Download the Time Manager documentation (PDF)

/* Parameter Manager */

The Parameter Manager class creates objects that contain the parameters for some other component of a model (e.g., for the animals in a population model). Parameters are added to the model simply by including them in the ParameterManager.h file.

The first purpose of the Parameter Manager is to easily allow model agents of various subclasses to have parameter values that vary among subclasses, even if the equations using the parameters are coded in the superclass. For example, our trout model has a superclass "Trout" and subclasses for various species of trout ("Rainbow", "Cutthroat") that may be in the same model. Creating one Parameter Manager object for each species allows every fish to have species-specific parameter values even though most of the code for trout behavior is in the Trout superclass.

The Parameter Manager has a second important function: it verifies that all parameters have been initialized. Parameter values are read from an ASCII file using Swarm's "Object Loader". The Parameter Manager uses Swarm's probe facilities to automatically identify any parameters that were left out of the ASCII file.

* Download example Parameter Manager code (TAR archive)

* Download the Parameter Manager documentation (PDF)

/* InterpolationTable */

This class performs simple linear and logarithmic interpolation, using a set of X, Y points provided as input. It also can be used as a lookup table from which values are interpolated.

* Download the InterpolationTable source code (TAR archive file)

* Download the InterpolationTable documentation (PDF)

/* Time Series Input Manager */

Most simulation models use time-series input for driving variables- for example, ecological models typically use hourly or daily input for weather, river flow, etc. Our Time Series Input Manager class reads an input file of time series data, creates an array of the data needed for the current model run, and provides the correct input to the model for the current time. The Time Series Input Manager can be used with daily, hourly, or other (user-defined) time steps.

* Download the Time Series Input Manager source code (TAR archive file)

* Download the Time Series Input Manager documentation (PDF)

/* Survival Probability Manager */

Ecological IBMs typically model survival (mortality) of individuals using stochastic functions: A random draw is used to determine whether each individual survives each time step, but the survival probability is a function of the individual's state and its habitat. A number of different survival probability functions are usually defined, each representing one potential source of mortality (starvation, predation, extreme weather, etc.). The Survival Probability Manager is a group of classes that (a) allow the programmer to quickly define the survival probabilities and (b) manage the survival simulations. A primary benefit of the Survival Probability Manager is minimizing the code needed to add, delete, or modify mortality models.

The Survival Probability Manager is also potentially useful for other kinds of model in which events are modeled as stochastic functions of one or several inputs.

The Survival Probability Manager allows the programmer to define "survival probabilities", each a model of one mortality source. Each survival probability can be determined by one or more functions of the animal or its habitat. The "limiting function" survival model assumes that a number of habitat and animal characteristics may at any time limit the survival probability. Built-in functions include boolean ("yes-no"), constant, and logistic. Custom functions can be programmed.

Code is provided for updating survival functions efficiently when habitat conditions or the animal changes. The Survival Probability Manager provides, when requested, a list of survival probabilities for the current state of the animal and habitat.

* Download the Survival Manager source code (TAR file)

* Download the Survival Manager documentation (PDF)

/* Poisson Distribution */

Swarm provides a number of random number distributions, but previously did not include a Poisson distribution. This distribution models the (integer) number of times some event occurs, given (a) the rate (over time or space) at which the event occurs on average, and (b) an interval (over time or space). It follows the same format and protocols of other Swarm random distributions and in fact has been included in distributions of Swarm created on or after July 24, 2001.

* Download the Poisson distribution code (TAR archive)

* Download the Poisson distribution documentation (PDF)

/* Binomial Distribution */

This distribution models the (integer) number of times some event occurs, given (a) the probability of occurrance per trial and (b) the number of trials. We use it, for example, to determine how many of a nest of fish eggs die, given (a) an egg mortality probability and (b) the number of eggs currently alive. It follows the same format and protocols of other Swarm random distributions and is included in distributions of Swarm version 2.2 created after July, 2004. (Therefore, we do not provide separate documentation for the binomial distribution- use should be self-evident from its protocol file “binomialDistP.h”.)

* Download the binomial distribution code (TAR archive)

/* Year Shuffler */

Often in long ecological simulations, the modeler is concerned that results can be partly an artifact of the sequence of annual habitat conditions. For example, the habitat input for a model might include some years with unusually good conditions and some years with unusually bad conditions; results of the model might be affected by how many good and bad years are simulated and the order in which they occur. One way to deal with this potential problem is to re-run the simulations with the years in different orders. YearShuffler is designed to support such analyses. It modifies time series input data to randomize the sequence of years, either without replacement (each year is used only once) or with replacement (years may be used more than once or not at all).

* Download the Year Shuffler code (TAR archive)

* Download the Year Shuffler documentation (PDF)

/* Solar Manager */

Solar Manager provides functions related to day length and solar energy modeling. The user provides a site latitude and date, and Solar Manager can calculate such variables as day length (hours of sunlight), sunrise and sunset time, and an estimate of daily mean solar radiation. The class also includes a tool for estimating hourly temperatures from daily minimum and maximum temperatures (often, the only available data).

* Download the Solar Manager code (TAR archive)

* Download the Solar Manager documentation (PDF)

/* Water Temperature Model */

WaterTemperatureModel is a class calculating heat fluxes and temperature changes for waterbodies. It is designed especially for shallow, still waterbodies such as ponds or river backwaters. Heat fluxes due to solar radiation, atmospheric radiation, water back-radiation, evaporative cooling, and convection are modeled simply, using inputs such as air temperature and humidity, wind speed, and surface area.

* Download the Water Temperature Model code (TAR archive)

* Download the Water Temperature Model documentation (PDF)