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.AbstractCropState
— TypeAbstractCropState
The abstract supertype of all crop states in the model. Each crop model has to define a type CropState <: AbstractCropState
.
Persefone.AbstractCropType
— TypeAbstractCropType
The abstract supertype of all crop types in the model. Each crop model has to define a type CropType <: AbstractCropType
.
Persefone.ModelAgent
— TypeModelAgent
The supertype of all agents in the model (animal species, farmer types, farmplots).
Persefone.SimulationModel
— TypeSimulationModel
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).
Persefone.MAPRESOLUTION
— ConstantThe spatial resolution of the currently used input maps.
Persefone.AnnualDate
— TypeAnnualDate
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)
.
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.@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.@lastyear
— Macro@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.
Persefone.@nextyear
— Macro@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.
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.
Persefone.@thisyear
— Macro@thisyear(annualdate)
Construct a date object referring to the current model year from an AnnualDate. Only use in scopes where model
is available.
simulation.jl
This file includes the basal functions for initialising and running simulations.
Persefone.AgricultureModel
— TypeAgricultureModel
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.
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
— TypeFarmEvent
A data structure to define a landscape event, giving its type, spatial extent, and duration.
Persefone.Management
— TypeThe types of management event that can be simulated
Persefone.Pixel
— TypePixel
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.)
Persefone.SoilType
— TypeThe soil type of a Pixel or FarmPlot
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, region, landcovermap, farmfieldsmap, soiltypesmap)
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
— TypeWeather
Holds the weather information for the whole simulation period.
Persefone.check_missing_weatherdata
— Methodcheck_missing_weatherdata(dataframe)
Check the weather input data for missing values in columns where input values are required.
Persefone.cloudcover
— Methodcloudcover(weather, date)
cloudcover(model, date)
cloudcover(model)
Return the average cloudcover in eigths on date
.
Persefone.daynumber
— Methoddaynumber(weather, date)
Returns the number of days, counting weather.firstdate
as day 1
.
Persefone.evapotranspiration
— Methodevapotranspiration(weather, date)
evapotranspiration(model, date)
evapotranspiration(model)
Return the potential evapotranspiration (ETo) on date
.
Persefone.findspans
— Methodfindspans(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
.
Persefone.humidity
— Methodhumidity(weather, date)
humidity(model, date)
humidity(model)
Return today's average vapour pressure in %.
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/regions/auxiliary/extract_weather_data.R
.
Persefone.maxtemp
— Methodmaxtemp(weather, date)
maxtemp(model, date)
maxtemp(model)
Return the maximum temperature in °C on date
.
Persefone.meantemp
— Methodmeantemp(weather, date)
meantemp(model, date)
meantemp(model)
Return the mean temperature in °C on date
.
Persefone.mintemp
— Methodmintemp(weather, date)
mintemp(model, date)
mintemp(model)
Return the minimum temperature in °C on date
.
Persefone.precipitation
— Methodprecipitation(weather, date)
precipitation(model, date)
precipitation(model)
Return the total precipitation in mm on date
.
Persefone.sunshine
— Methodsunshine(weather, date)
sunshine(model, date)
sunshine(model)
Return the sunshine duration in hours on date
.
Persefone.windspeed
— Methodwindspeed(weather, date)
windspeed(model, date)
windspeed(model)
Return the average windspeed in m/s on date
.
Persefone.@cloudcover
— Macro@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.
Persefone.@evapotranspiration
— Macro@evapotranspiration(date=model.date)
Return the potential evapotranspiration (ETo) today/on the specified date. Can only be used in scopes where model
is available.
Persefone.@humidity
— Macro@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.
Persefone.@maxtemp
— Macro@maxtemp(date=model.date)
Return the maximum temperature today/on the specified date. Can only be used in scopes where model
is available.
Persefone.@meantemp
— Macro@meantemp(date=model.date)
Return the mean temperature today/on the specified date. Can only be used in scopes where model
is available.
Persefone.@mintemp
— Macro@mintemp(date=model.date)
Return the minimum temperature today/on the specified date. Can only be used in scopes where model
is available.
Persefone.@precipitation
— Macro@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.
Persefone.@sunshine
— Macro@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.
Persefone.@windspeed
— Macro@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.