Input, Output, and Settings
These functions are responsible for reading in all model configurations (passed by config file or commandline), administrating them during a run, and printing any output.
parameters.toml
This is the default configuration file for Persephone, containing all model parameters. The syntax is described here: https://toml.io/en/
DO NOT MODIFY THIS FILE FOR SIMULATION EXPERIMENTS! Instead, copy it to another directory, modify the copy, and then pass it to the model using the --config
parameter.
input.jl
Persephone.PARAMFILE
— ConstantThe file that stores all default parameters: src/parameters.toml
Persephone.flattenTOML
— MethodflattenTOML(dict)
An internal utility function to convert the two-dimensional dict returned by TOML.parsefile()
into a one-dimensional dict, so that instead of writing settings["domain"]["param"]
one can use settings["domain.param"]
. Can be reversed with prepareTOML
.
Persephone.getsettings
— Functiongetsettings(configfile, seed=nothing)
Combines all configuration options to produce a single settings dict. Precedence: commandline parameters - user config file - default values
Persephone.parsecommandline
— Methodparsecommandline()
Certain software parameters can be set via the commandline.
Persephone.preprocessparameters
— Methodpreprocessparameters(settings)
Take the raw input parameters and process them (convert types, perform checks, etc.). This is a helper function for getsettings
.
Persephone.@param
— Macro@param(domainparam)
Return a configuration parameter from the global settings. The argument should be in the form <domain>.<parameter>
, for example @param(core.outdir)
. Possible values for <domain>
are core
, nature
, farm
, or crop
. For a full list of parameters, see src/parameters.toml
.
Note: this macro only works in a context where the model
object is available!
Persephone.@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.
Persephone.@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.
output.jl
Persephone.DataOutput
— TypeDataOutput
A struct for organising model output. This is designed for text-based data output that is updated more or less regularly (e.g. population data in csv files). Submodels can register their own output functions using newdataoutput!
.
Struct fields: - filename: the name of the file to be created in the user-specified output directory - header: a string to be written to the start of the file as it is initialised - outputfunction: a function that takes a model object and returns a string to write to file - frequency: how often to call the output function (daily/monthly/yearly/end/never)
Persephone.createdatadir
— Methodcreatedatadir(outdir, overwrite)
Creates the output directory, dealing with possible conflicts.
Persephone.modellogger
— Methodmodellogger(loglevel, outdir)
Create a logger object that writes output both to screen and to a logfile. This object is stored as model.logger
and can then be used with with_logger()
. Note: requires createdatadir
to be run first.
Persephone.newdataoutput!
— Methodnewdataoutput!(model, filename, header, outputfunction, frequency)
Create and register a new data output. This function must be called by all submodels that want to have their output functions called regularly.
Persephone.outputdata
— Methodoutputdata(model)
Cycle through all registered data outputs and activate them according to their configured frequency.
Persephone.prepareTOML
— MethodprepareTOML(dict)
An internal utility function to re-convert the one-dimensional dict created by flattenTOML
into the two-dimensional dict needed by TOML.print
, and convert any data types into TOML-compatible types where necessary.
Persephone.saveinputfiles
— Methodsaveinputfiles(model)
Copy all input files into the output directory, including the actual parameter settings used. This allows replicating a run in future.
Persephone.withtestlogger
— Methodwithtestlogger(model)
Replace the model logger with the currently active logger. This is intended to be used in the testsuite to circumvent a Julia issue, where @test_logs
doesn't work with local loggers.