Simulation

AbstractCropState

The abstract supertype of all crop states in the model. Each crop model has to define a type CropState <: AbstractCropState.

AbstractCropType

The abstract supertype of all crop types in the model. Each crop model has to define a type CropType <: AbstractCropType.

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).

The spatial resolution of the currently used input maps.

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.

@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.

@lastyear(annualdate)

Construct a date object referring to the last year in the model from an AnnualDate. Only use in scopes where model is available.

@nextyear(annualdate)

Construct a date object referring to the next year in the model from an AnnualDate. Only use in scopes where model 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.

@thisyear(annualdate)

Construct a date object referring to the current model year from an AnnualDate. Only use in scopes where model 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 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.)

The soil type of a Pixel or FarmPlot

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, region, landcovermap, farmfieldsmap, soiltypesmap)

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

Holds the weather information for the whole simulation period.

check_missing_weatherdata(dataframe)

Check the weather input data for missing values in columns where input values are required.

cloudcover(weather, date)
cloudcover(model, date)
cloudcover(model)

Return the average cloudcover in eigths on date.

daynumber(weather, date)

Returns the number of days, counting weather.firstdate as day 1.

evapotranspiration(weather, date)
evapotranspiration(model, date)
evapotranspiration(model)

Return the potential evapotranspiration (ETo) on date.

findspans(predicate_fn, array) -> Vector{UnitRange{Int}}

Returns spans of indices in a 1-d array where a predicate_fn returns true. The spans are returned as a Vector of UnitRange{Int}, where each range is of the form start_index:end_index.

humidity(weather, date)
humidity(model, date)
humidity(model)

Return today's average vapour pressure in %.

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/regions/auxiliary/extract_weather_data.R.

maxtemp(weather, date)
maxtemp(model, date)
maxtemp(model)

Return the maximum temperature in °C on date.

meantemp(weather, date)
meantemp(model, date)
meantemp(model)

Return the mean temperature in °C on date.

mintemp(weather, date)
mintemp(model, date)
mintemp(model)

Return the minimum temperature in °C on date.

precipitation(weather, date)
precipitation(model, date)
precipitation(model)

Return the total precipitation in mm on date.

sunshine(weather, date)
sunshine(model, date)
sunshine(model)

Return the sunshine duration in hours on date.

windspeed(weather, date)
windspeed(model, date)
windspeed(model)

Return the average windspeed in m/s on date.

@cloudcover(date=model.date)

Return the average cloudcover in eigths today/on the specified date. Can only be used in scopes where model is available.

@evapotranspiration(date=model.date)

Return the potential evapotranspiration (ETo) today/on the specified date. Can only be used in scopes where model is available.

@humidity(date=model.date)

Return the average vapour pressure (in %) today/on the specified date. Can only be used in scopes where model is available.

@maxtemp(date=model.date)

Return the maximum temperature today/on the specified date. Can only be used in scopes where model is available.

@meantemp(date=model.date)

Return the mean temperature today/on the specified date. Can only be used in scopes where model is available.

@mintemp(date=model.date)

Return the minimum temperature today/on the specified date. Can only be used in scopes where model is available.

@precipitation(date=model.date)

Return the total precipitation in mm today/on the specified date. Can only be used in scopes where model is available.

@sunshine(date=model.date)

Return the sunshine duration in hours today/on the specified date. Can only be used in scopes where model is available.

@windspeed(date=model.date)

Return the average windspeed in m/s today/on the specified date. Can only be used in scopes where model is available.