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).
Persefone.AnnualDate — TypeAnnualDateA 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).
Base.randn — Functionrandn(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).
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.cycle! — Functioncycle!(vector, n=1)Move the first element of the vector to the end, repeat n times.
Persefone.thisyear — Methodthisyear(annualdate, model)
nextyear(annualdate, model)
lastyear(annualdate, model)Convert an AnnualDate to a Date, using the current/next/previous year of the simulation run.
Persefone.@areaof — Macro@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).
Persefone.@chance — Macro@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.
Persefone.@rand — Macro@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.
Persefone.@randn — Macro@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.
Persefone.@shuffle! — Macro@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.
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 — Methodinitialise(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.
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! — Methodsimulate!(model)Carry out a complete simulation run using a pre-initialised model object.
Persefone.simulate — Methodsimulate(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.
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.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.