Simulation
The core and world directories hold source files that are important for all submodels, including scheduling, landscape, weather, and input/output functions.
Persefone.jl
This file defines the module, including all exported symbols and two high-level types.
Persefone.ModelAgent — TypeModelAgentThe supertype of all agents in the model (animal species, farmer types, farmplots).
Persefone.SimulationModel — TypeSimulationModelThe 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).
simulation.jl
This file includes the basal functions for initialising and running simulations.
Persefone.AgricultureModel — TypeAgricultureModelThis 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.
Persefone.finalise! — Methodfinalise!(model)Wrap up the simulation. Finalises and visualises output, then terminates.
Persefone.initialise — Functioninitialise(config=PARAMFILE, seed=nothing)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 the seed parameter. 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.
Persefone.initmodel — Methodinitmodel(settings)Initialise a model object using a ready-made settings dict. This is a helper function for initialise().
Persefone.nagents — Methodnagents(model)Return the total number of agents in a model object.
Persefone.paramscan — Methodparamscan(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().
Persefone.simulate — Functionsimulate(config=PARAMFILE, seed=nothing)Initialise one or more model objects and carry out a full simulation experiment, optionally specifying a configuration file and a seed for the RNG.
This is the default way to run a Persefone simulation.
Persefone.simulate! — Methodsimulate!(model)Carry out a complete simulation run using a pre-initialised model object.
Persefone.stepagent! — Methodstepagent!(agent, model)All agent types must define a stepagent!() method that will be called daily.
Persefone.stepsimulation! — Methodstepsimulation!(model)Execute one update of the model.
landscape.jl
This file manages the landscape maps that underlie the model.
Persefone.FarmEvent — TypeFarmEventA data structure to define a landscape event, giving its type, spatial extent, and duration.
Persefone.LandCover — TypeThe land cover classes encoded in the Mundialis Sentinel data.
Persefone.Management — TypeThe types of management event that can be simulated
Persefone.Pixel — TypePixelA 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.)
Persefone.bounds — Methodbounds(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.
Persefone.createevent! — Functioncreateevent!(model, pixels, name, duration=1)Add a farm event to the specified pixels (a vector of position tuples) for a given duration.
Persefone.directionto — Methoddirectionto(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!
Persefone.directionto — Methoddirectionto(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!
Persefone.distanceto — Methoddistanceto(pos, model, habitatdescriptor)Calculate the distance from the given location to the closest location matching the habitat descriptor function. Caution: can be computationally expensive!
Persefone.distanceto — Methoddistanceto(pos, model, habitattype)Calculate the distance from the given location to the closest habitat of the specified type. Caution: can be computationally expensive!
Persefone.distancetoedge — Methoddistancetoedge(pos, model)Calculate the distance from the given location to the closest neighbouring habitat. Caution: can be computationally expensive!
Persefone.farmplot — Methodfarmplot(position, model)Return the farm plot at this position, or nothing if there is none (utility wrapper).
Persefone.inbounds — Methodinbounds(pos, model)Is the given position within the bounds of the model landscape?
Persefone.initlandscape — Methodinitlandscape(directory, landcovermap, farmfieldsmap)Initialise the model landscape based on the map files specified in the configuration. Returns a matrix of pixels.
Persefone.landcover — Methodlandcover(position, model)Return the land cover class at this position (utility wrapper).
Persefone.randomdirection — Methodrandomdirection(model, distance)Get a random direction coordinate tuple within the specified distance.
Persefone.randompixel — Functionrandompixel(position, model, range, habitatdescriptor)Find a random pixel within a given range of the position that matches the habitatdescriptor (create this using @habitat).
Persefone.safebounds — Methodsafebounds(pos, model)Make sure that a given position is within the bounds of the model landscape.
Persefone.updateevents! — Methodupdateevents!(model)Cycle through the list of events, removing those that have expired.
weather.jl
This file reads in weather data and makes it available to the model.
Persefone.Weather — TypeWeatherA single weather datum, combining the observations from one day.
Persefone.initweather — Methodinitweather(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.
Persefone.maxtemp — Methodmaxtemp(model)Return today's maximum temperature in °C.
Persefone.meantemp — Methodmeantemp(model)Return today's mean temperature in °C.
Persefone.mintemp — Methodmintemp(model)Return today's minimum temperature in °C.
Persefone.precipitation — Methodprecipitation(model)Return today's total precipitation in mm.
Persefone.sunshine — Methodsunshine(model)Return today's sunshine duration in hours.
Persefone.vapourpressure — Methodvapourpressure(model)Return today's average vapour pressure in hPa.
Persefone.windspeed — Methodwindspeed(model)Return today's average windspeed in m/s.