Classes

InputFolders

Consolidate the folder information for a simulation/monad/sampling.

Pass the folder names within the inputs/<path_from_inputs> directory to create an InputFolders object. The path_from_inputs is defined in the data/inputs.toml file for each. It is possible to acces the InputFolder values using index notation, e.g. input_folders[:config].

Several constructors exist:

1. All folders passed as keyword arguments. Omitted folders are assumed to be "", i.e. those inputs are unused.

InputFolders(; config="default", custom_codes="default", rulesets_collection="default")

1. Pass in the required inputs as arguments and the optional inputs as keyword arguments. The required folders must be passed in alphabetical order.

Refer to the names defined in data/inputs.toml to see this order. Omitted optional folders are assumed to be "", i.e. those inputs are unused.

config_folder = "default"
custom_code_folder = "default"
ic_cell_folder = "cells_in_disc"
InputFolders(config_folder, custom_code_folder; ic_cell=ic_cell_folder)

Fields

• input_folders::NamedTuple: The input locations defined in data/inputs.toml define the keys. The values are InputFolders.

Simulation

A simulation that represents a single run of the model.

To create a new simulation, best practice is to use createTrial and supply it with the InputFolders and any number of single-valued DiscreteVariations:

inputs = InputFolders(config_folder, custom_code_folder)
simulation = createTrial(inputs) # uses the default config file as-is

ev = DiscreteVariation(configPath("max_time"), 1440)
simulation = createTrial(inputs, ev) # uses the config file with the specified variation

If there is a previously created simulation that you wish to access, you can use its ID to create a Simulation object:

simulation = Simulation(simulation_id)

Finally, a new Simulation object can be created from an existing Monad object. This will not use a simulation already in the database, but will create a new one with the same inputs and variations:

simulation = Simulation(monad)

Fields

• id::Int: integer uniquely identifying this simulation. Matches with the folder in data/outputs/simulations/
• inputs::InputFolders: contains the folder info for this simulation.
• variation_id::VariationID: contains the variation IDs for this simulation.

Monad

A group of simulations that are identical up to randomness.

To create a new monad, best practice is to use createTrial and supply it with the InputFolders and any number of single-valued DiscreteVariations. Set n_replicates=0 to avoid adding new simulations to the database. This is useful for creating references for later use. Otherwise, set n_replicates > 1 to create the simulations to go with this monad. If n_replicates = 1, it will return a Simulation object.

inputs = InputFolders(config_folder, custom_code_folder)
monad = createTrial(inputs; n_replicates=0) # uses the default config file as-is

ev = DiscreteVariation(configPath("max_time"), 1440)
monad = createTrial(inputs, ev; n_replicates=10) # uses the config file with the specified variation

monad = createTrial(inputs, ev; n_replicates=10, use_previous=false) # changes the default behavior and creates 10 new simulations for this monad

If there is a previously created monad that you wish to access, you can use its ID to create a Monad object:

monad = Monad(monad_id)
monad = Monad(monad_id; n_replicates=5) # ensures at least 5 simulations in the monad (using previous sims)

Fields

• id::Int: integer uniquely identifying this monad. Matches with the folder in data/outputs/monads/
• inputs::InputFolders: contains the folder info for this monad.
• variation_id::VariationID: contains the variation IDs for this monad.

Sampling

A group of monads that have the same input folders, but differ in parameter values.

To create a new sampling, best practice is to use createTrial and supply it with the InputFolders and any number of DiscreteVariations. At least one should have multiple values to create a sampling.

inputs = InputFolders(config_folder, custom_code_folder)
ev = DiscreteVariation(configPath("max_time"), [1440, 2880]))
sampling = createTrial(inputs, ev; n_replicates=3, use_previous=true)

If there is a previously created sampling that you wish to access, you can use its ID to create a Sampling object:

sampling = Sampling(sampling_id)
sampling = Sampling(sampling_id; n_replicates=5) # ensures at least 5 simulations in each monad (using previous sims)
sampling = Sampling(sampling_id; n_replicates=5, use_previous=false) # creates 5 new simulations in each monad

If you have a vector of Monad objects that you wish to group into a sampling, you can use the constructor:

sampling = Sampling(monads; n_replicates=0, use_previous=true)

which will create a new Sampling object with the provided monads, ensuring each has at least n_replicates simulations per monad, using previous simulations if requested and available.

Fields

• id::Int: integer uniquely identifying this sampling. Matches with the folder in data/outputs/samplings/
• inputs::InputFolders: contains the folder info for this sampling.
• monads::Vector{Monad}: array of monads belonging to this sampling.

Trial

A group of samplings that can have different input folders.

To create a new trial, best practice currently is to create a vector of Sampling objects and passing them to Trial.

inputs_1 = InputFolders(config_folder_1, custom_code_folder_1)
inputs_2 = InputFolders(config_folder_2, custom_code_folder_2)
ev = DiscreteVariation(configPath("max_time"), [1440, 2880]))
sampling_1 = createTrial(inputs_1, ev; n_replicates=3, use_previous=true)
sampling_2 = createTrial(inputs_2, ev; n_replicates=3, use_previous=true)
trial = Trial([sampling_1, sampling_2])

If there is a previous trial that you wish to access, you can use its ID to create a Trial object:

trial = Trial(trial_id)
trial = Trial(trial_id; n_replicates=5) # ensures at least 5 simulations in each monad (using previous sims)
trial = Trial(trial_id; n_replicates=5, use_previous=false) # creates 5 new simulations in each monad

Fields

• id::Int: integer uniquely identifying this trial. Matches with the folder in data/outputs/trials/
• inputs::Vector{InputFolders}: contains the folder info for each sampling in this trial.
• variation_ids::Vector{Vector{VariationID}}: contains the variation IDs for each monad in each sampling in this trial.

AbstractMonad <: AbstractSampling

Abstract type for the Simulation and Monad types.

All the inputs and variations must be the same for all associated simulations.

AbstractSampling <: AbstractTrial

Abstract type for the Simulation, Monad, and Sampling types.

All the inputs must be the same for all associated simulations. Variations can differ.

AbstractTrial

Abstract type for the Simulation, Monad, Sampling, and Trial types.

There are no restrictions on inputs or variations for this type.

InputFolder

Hold the information for a single input folder.

Users should use the InputFolders to create and access individual InputFolder objects.

Fields

• location::Symbol: The location of the input folder, e.g. :config, :custom_code, etc. Options are defined in data/inputs.toml.
• id::Int: The ID of the input folder in the database.
• folder::String: The name of the input folder. It will be in data/inputs/<path_from_inputs>.
• basename::Union{String,Missing}: The basename of the input file. This can be used to determine if the input file is varied.
• required::Bool: Whether the input folder is required. This is defined in data/inputs.toml.
• varied::Bool: Whether the input folder is varied. This is determined by the presence of a varied basename in the input folder.
• path_from_inputs::String: The path from the data/inputs directory to the input folder. This is defined in data/inputs.toml.

VariationID

The variation IDs for any of the possibly varying inputs.

For each input type that can be varied, a record of the current variation ID for that input type. By convention, a values of -1 indicates that the input is not being used (hence this is disallowed for a required input type). A value of 0 indicates that the base file is being used, unvaried. Hence, if the input type is sometimes varied (such as ic_cell with a cells.csv file), this value must be 0 in such conditions.

addSimulationID(monad::Monad, simulation_id::Int)

Adds a simulation ID to the monad's list of simulation IDs.

createSimpleInputFolders()

Creates a simple method for creating InputFolders objects at module initialization based on data/inputs.toml.

The required inputs are sorted alphabetically and used as the positional arguments. The optional inputs are used as keyword arguments with a default value of "", indicating they are unused.

printInputFolders(io::IO, input_folders::InputFolders, n_indent::Int=1)

Prints the folder information for each input folder in the InputFolders object.

printVariationID(io::IO, variation_id::VariationID, n_indent::Int=1)

Prints the variation ID information for each varied input in the VariationID object.

trialID(samplings::Vector{Sampling})

Get the trial ID for a vector of samplings or create a new trial if one does not exist.

trialID(T::AbstractTrial)

Returns the ID of the AbstractTrial object, which is the ID of the simulation, monad, sampling, or trial.

trialType(T::AbstractTrial)

Returns the type of the trial, which can be Simulation, Monad, Sampling, or Trial.