Simulation

ModelAgent

The supertype of all agents in the model (animal species, farmer types, farmplots).

SimulationModel

The supertype of AgricultureModel. This is needed to avoid circular dependencies (most types and functions depend on SimulationModel, but the definition of the model struct depends on these types).

AnnualDate

A type to handle recurring dates (e.g. migration, harvest). Stores a month and a day, and can be compared against normal dates. To save typing, a Tuple{Int64,Int64} is automatically converted to an AnnualDate, allowing this syntax: nestingend::AnnualDate = (August, 15).

randn(vector)

Return a random element from the given vector, following a (mostly) normal distribution based on index values (i.e. elements in the middle of the vector will be returned most frequently).

bounds(x; max=Inf, min=0)

A utility function to make sure that a number is within a given set of bounds. Returns max/min if x is greater/less than this.

cycle!(vector, n=1)

Move the first element of the vector to the end, repeat n times.

thisyear(annualdate, model)
nextyear(annualdate, model)
lastyear(annualdate, model)

Convert an AnnualDate to a Date, using the current/next/previous year of the simulation run.

@areaof(npixels)

Calculate the area of a given number of landscape pixels, knowing the resolution of the world map (requires the model object to be available).

@chance(odds)

Return true if a random number is less than the odds (0.0 <= odds <= 1.0), using the model RNG. This is a utility wrapper that can only be used a context where the model object is available.

@rand(args...)

Return a random number or element from the sample, using the model RNG. This is a utility wrapper that can only be used a context where the model object is available.

@randn(vector)

Return a normally-distributed random number or element from the sample, using the model RNG. This is a utility wrapper that can only be used a context where the model object is available.

@shuffle!(collection)

Shuffle the given collection in place, using the model RNG. This is a utility wrapper that can only be used a context where the model object is available.

AgricultureModel

This is the heart of the model - a struct that holds all data and state for one simulation run. It is created by initialise and passed as input to most model functions.

finalise!(model)

Wrap up the simulation. Finalises and visualises output, then terminates.

initialise(configfile=PARAMFILE, params=Dict())

Initialise the model: read in parameters, create the output data directory, and instantiate the SimulationModel object(s). Optionally allows specifying the configuration file and overriding specific parameters. This returns a single model object, unless the config file contains multiple values for one or more parameters, in which case it creates a full-factorial simulation experiment and returns a vector of model objects.

initmodel(settings)

Initialise a model object using a ready-made settings dict. This is a helper function for initialise().

nagents(model)

Return the total number of agents in a model object.

paramscan(settings)

Create a list of settings dicts, covering all possible parameter combinations given by the input settings (i.e. a full-factorial experiment). This is a helper function for initialise().

simulate!(model)

Carry out a complete simulation run using a pre-initialised model object.

simulate(configfile=PARAMFILE, params=Dict())

Initialise one or more model objects and carry out a full simulation experiment, optionally specifying a configuration file and/or specific parameters.

This is the default way to run a Persefone simulation.

stepagent!(agent, model)

All agent types must define a stepagent!() method that will be called daily.

stepsimulation!(model)

Execute one update of the model.

FarmEvent

A data structure to define a landscape event, giving its type, spatial extent, and duration.

The land cover classes encoded in the Mundialis Sentinel data.

The types of management event that can be simulated

Pixel

A pixel is a simple data structure to combine land use and ownership information in a single object. The model landscape consists of a matrix of pixels. (Note: further landscape information may be added here in future.)

createevent!(model, pixels, name, duration=1)

Add a farm event to the specified pixels (a vector of position tuples) for a given duration.

directionto(pos, model, habitatdescriptor)

Calculate the direction from the given location to the closest location matching the habitat descriptor function. Returns a coordinate tuple (target - position), or nothing if no matching habitat is found. Caution: can be computationally expensive!

directionto(pos, model, habitattype)

Calculate the direction from the given location to the closest habitat of the specified type. Returns a coordinate tuple (target - position), or nothing if no matching habitat is found. Caution: can be computationally expensive!

distanceto(pos, model, habitatdescriptor)

Calculate the distance from the given location to the closest location matching the habitat descriptor function. Caution: can be computationally expensive!

distanceto(pos, model, habitattype)

Calculate the distance from the given location to the closest habitat of the specified type. Caution: can be computationally expensive!

distancetoedge(pos, model)

Calculate the distance from the given location to the closest neighbouring habitat. Caution: can be computationally expensive!

farmplot(position, model)

Return the farm plot at this position, or nothing if there is none (utility wrapper).

inbounds(pos, model)

Is the given position within the bounds of the model landscape?

initlandscape(directory, landcovermap, farmfieldsmap)

Initialise the model landscape based on the map files specified in the configuration. Returns a matrix of pixels.

landcover(position, model)

Return the land cover class at this position (utility wrapper).

randomdirection(model, distance)

Get a random direction coordinate tuple within the specified distance.

randompixel(position, model, range, habitatdescriptor)

Find a random pixel within a given range of the position that matches the habitatdescriptor (create this using @habitat).

safebounds(pos, model)

Make sure that a given position is within the bounds of the model landscape.

updateevents!(model)

Cycle through the list of events, removing those that have expired.

Weather

A single weather datum, combining the observations from one day.

initweather(weatherfile, startdate, enddate)

Load a weather file, extract the values that are relevant to this model run (specified by start and end dates), and return a dictionary of Weather objects mapped to dates.

Note: This requires a weather file in the format produced by data/extract_weather_data.R.

maxtemp(model)

Return today's maximum temperature in °C.

meantemp(model)

Return today's mean temperature in °C.

mintemp(model)

Return today's minimum temperature in °C.

precipitation(model)

Return today's total precipitation in mm.

sunshine(model)

Return today's sunshine duration in hours.

vapourpressure(model)

Return today's average vapour pressure in hPa.

windspeed(model)

Return today's average windspeed in m/s.