Simulation

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} or a String can be automatically converted to an AnnualDate, allowing this syntax: nestingend::AnnualDate = (August, 15), or nestingend::AnnualDate = "15 August".

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.

camelcase(string)

Return a CamelCaseVersion of the string (each word capitalised and joined to the next).

cycle!(vector, n=1)

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

snakecase(string)

Return a snakecaseversion of the string (all small letters, words joined by underscores).

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.

uncamelcase(string)

Reverse camelcase() (e.g. "WinterWheat" -> "Winter Wheat").

unsnakecase(string)

Reverse snakecase() (e.g. "winter_wheat" -> "winter wheat").

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

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.

HomeRange

Container for home range / territory polygons.

Landscape

A vector-based landscape representation.

LandscapeElement

Container for landscape features (landcover, soil, optional crop state).

The soil type of a LandscapeElement

_closest_point_on_curve(pos, curve)

Return the closest point on a curve to pos and the squared distance. The closing segment is included if the curve is not explicitly closed.

_closest_point_on_geom(pos, geom)

Return the closest point on the polygon boundary of geom to pos and the squared distance between them. Holes are included as candidates.

_closest_point_on_segment(pos, a, b)

Return the closest point on the segment a-b to pos and the squared distance.

_geom_to_geoms(geom)

Convert an ArchGDAL geometry into one or more polygon geometries (splitting multipolygons).

add_homerange!(ls::Landscape, hr::HomeRange)

Adds a HomeRange to a Landscape and update the spatial index.

add_land!(ls::Landscape, le::LandscapeElement)

Adds a LandscapeElement to a Landscape, and assigns le.id a new LandElemID (therefore modifying both arguments).

allelements(model)

Return all elements in the model landscape.

coverage_stats(polys, boundary; precision_eps=0.0)

Compute coverage, gap area, and overlap area for a set of polygon geometries within a boundary polygon.

coverage_stats(ls::Landscape; boundary=nothing, precision_eps=0.0)

Compute coverage statistics for a Landscape. If no boundary is provided, the landscape extent is used as a rectangular boundary.

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, habitatfunction, model, maxradius=1km, stepsize::Length=100m)

Calculate the direction from the given location to the closest landscape element matching the habitat descriptor function. Returns a bearing (0-359°) or nothing if no matching landscape element is found.

distanceto(pos, habitatfunction, model, maxradius=1km, stepsize::Length=100m)

Return the distance to the closest landscape element matching the habitat descriptor function. Is a thin wrapper around findnearest().

distancetoedge(pos, model)

Calculate the distance from the given location to the edge of the local landscape element.

findnearest(pos, habitatfunction, model, maxradius=1km, stepsize::Length=100m)

Find the closest landscape element matching the habitat function, if there is one within the maxradius. Searches in concentric circles determined by stepsize. Returns a tuple of the found landscape element (or nothing) and the distance to it.

gap_polygons(polys, boundary; precision_eps=0.0)

Return a vector of gap polygons (boundary minus union of polys).

gap_polygons(ls::Landscape; boundary=nothing, precision_eps=0.0)

Return gap polygons for a Landscape. If no boundary is provided, the landscape extent is used as a rectangular boundary.

get_homeranges_at_coord(landscape::Landscape, coord::Coord)

Find any HomeRanges containing the given coordinate. Uses the spatial index for fast candidate filtering, then precise geometric test.

Returns a vector of HomeRanges found (empty if none found).

get_homeranges_in_extent(landscape::Landscape, ext::Extent2D)

Find all HomeRanges whose extents intersect with the given extent using the spatial index for efficient O(log n) lookup.

Returns a lazy iterator over HomeRange objects.

get_land_elem_at_coord(landscape::Landscape, coord::Coord)

Find the LandscapeElement containing the given coordinate. Uses the spatial index for fast candidate filtering, then precise geometric test.

Returns the LandscapeElement if found, or nothing otherwise.

get_land_elems_in_extent(landscape::Landscape, ext::Extent2D)

Find all LandscapeElements whose extents intersect with the given extent using the spatial index for efficient O(log n) lookup.

Returns a lazy iterator over LandscapeElement objects.

inextent(pos, model)

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

initlandscape(gpkgpath="landscape.gpkg";
              landcover_field=:landcover,
              soil_field=:soil_type)

Initialise a Landscape from a GeoPackage at gpkgpath. Each feature is converted to a LandscapeElement, keeping only the Persefone landcover value.

Arguments

• landcover_field: Field name containing landcover values (default: :landcover)
• soil_field: Field name containing soil type values (optional; default: :soil_type)

isvalid(ls::Landscape)

Return true if all geometries in the landscape are topologically valid.

landcover(position, model)

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

landelem(position, model)

Return the LandscapeElement at this position (Coord).

landelem(id, model)

Return the LandscapeElement with this ID.

nearby_land_elements(landscape, landscapeelement, buffer=5m)

Expand the given landscape elements extent by the buffer distance, then return an iterator over all landscape elements in this extent.

remove_homerange!(ls::Landscape, hr::HomeRange)

Remove the given homerange from the landscape and update the spatial index.

safebounds(pos, model)

Clamp a position to the landscape extent.

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.