Trial hierarchy

AbstractMonad <: AbstractSampling

Abstract type for Simulation and Monad.

All associated simulations share both input folders and variation IDs.

AbstractSampling <: AbstractTrial

Abstract type for Simulation, Monad, and Sampling.

All associated simulations share the same input folders; only variations differ.

AbstractTrial

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

InputFolder

Hold the information for a single input folder (location + folder name + metadata).

Created automatically by InputFolders constructors.

Fields

• location::Symbol: The location key (e.g. :config, :custom_code).
• id::Int: Database row ID for this folder.
• folder::String: Folder name within data/inputs/<path_from_inputs>/.
• basename::Union{String,Missing}: Primary input file name, or missing.
• required::Bool: Whether this location is required.
• varied::Bool: Whether this folder supports parameter variations.
• path_from_inputs::String: Relative path from data/inputs/ to this folder.

InputFolders

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

Constructors

1. All folders as keyword arguments (omitted ⟹ ""):

InputFolders(; config="default", custom_code="default")

1. Required folders as positional args (alphabetical order), optional as kwargs:

InputFolders("default", "default"; ic_cell="cells_in_disc")

Fields

• input_folders::NamedTuple: Keys are location symbols; values are InputFolders.

MMOutput{T<:AbstractTrial}

Hold the result of a run call.

Fields

• trial::T: The trial that was run.
• n_scheduled::Int: Number of simulations scheduled in this run.
• n_success::Int: Number of simulations that completed successfully.

Monad

A group of identical-up-to-randomness simulations.

Constructors

Monad(inputs, variation_id; n_replicates=0, use_previous=true)
Monad(monad_id; n_replicates=0, use_previous=true)
Monad(simulation)

Fields

• id::Int
• inputs::InputFolders
• variation_id::VariationID

Sampling

A group of monads sharing the same input folders but differing in parameter values.

Fields

• id::Int
• inputs::InputFolders
• monads::Vector{Monad}

Simulation

A single run of the model.

Constructors

Simulation(simulation_id)          # retrieve existing
Simulation(inputs, variation_id)   # create new (inserts into DB)
Simulation(monad)                  # new sim with same params as monad

Fields

• id::Int
• inputs::InputFolders
• variation_id::VariationID

Trial

A group of samplings that may have different input folders.

Fields

• id::Int
• samplings::Vector{Sampling}

VariationID

Record the variation row IDs for each varied input location.

A value of -1 means the location is not in use; 0 means the base (unvaried) file is being used.

constituentIDs(T::AbstractTrial)
constituentIDs(::Type{T}, id::Int)
constituentIDs(output::MMOutput)

Read the constituent IDs for trial T from its CSV file — one level down only, so a Trial reports its samplings and a Sampling its monads. Use simulationIDs or monadIDs to descend the whole hierarchy instead.

A Simulation has no constituents and throws ArgumentError; the MMOutput form forwards to the trial that was run, and so throws for a simulation-wrapping output.

locationPath(input_folder::InputFolder)

Return the full path to the input folder described by input_folder.

locationPath(location::Symbol, S::AbstractSampling)

Return the full path to the input folder for location used by sampling S.

monadIDs()
monadIDs(simulation::Simulation)
monadIDs(monad::Monad)
monadIDs(sampling::Sampling)
monadIDs(trial::Trial)
monadIDs(Ts::AbstractArray{<:AbstractTrial})
monadIDs(output::MMOutput)

Return the IDs of the monads a trial covers: a Monad reports itself, a Sampling its constituent monads, a Trial the monads of all its samplings. With no argument, every monad ID in the database. An MMOutput forwards to the trial that was run. Results are concatenated for the array form, not deduplicated.

For a Simulation the answer is the monad matching that simulation's parameterization — its simulator version, input folders and variation IDs — of which there can be at most one. This is a lookup, never a write, so asking cannot bring a monad into being. Int[] means nothing shares the parameterization, which is why monadsTable(simulation) gives an empty table rather than throwing.

Parameterization is not membership. A simulation inserted directly with Simulation(inputs, variation_id), as Simulation(monad) does, resolves to the monad sharing its parameters without appearing in that monad's replicate list; run is what adds it there. A failed simulation, removed from that list, also still resolves to it.

pathToOutputFolder(simulation_id::Int)
pathToOutputFolder(simulation::Simulation)
pathToOutputFolder(simulation_process::SimulationProcess)

Return the path to the output folder for a simulation. Accepts a raw ID, a Simulation, or the SimulationProcess handed to a post_processor (see run) — so a post-processor can locate its simulation's output without reaching into struct internals.

setNumberOfParallelSims(n::Int)

Set the maximum number of parallel simulations.

simulationIDs()
simulationIDs(simulation::Simulation)
simulationIDs(monad::Monad)
simulationIDs(sampling::Sampling)
simulationIDs(trial::Trial)
simulationIDs(Ts::AbstractArray{<:AbstractTrial})
simulationIDs(output::MMOutput)

Return the IDs of every simulation a trial covers, descending the full hierarchy: a Sampling reports the simulations of all its monads, a Trial those of all its samplings. With no argument, every simulation ID in the database. An MMOutput forwards to the trial that was run, reporting all of its simulations rather than only the ones that run dispatched.

Results are concatenated for the array form, not deduplicated.

simulationsFromIDs(simulation_ids) -> Vector{Simulation}

Construct many Simulations in one database query. Prefer this over Simulation.(ids), which issues one query per simulation.

Missing IDs are skipped rather than throwing, and the result follows the order of simulation_ids.

Example

sims = simulationsFromIDs([1, 2, 3])

trialFolder(T::Type{<:AbstractTrial}, id::Int)
trialFolder(T::AbstractTrial)
trialFolder(output::MMOutput)

Return the output folder path for trial type T with the given ID. The MMOutput form gives the folder of the trial that was run.

trialID(T::AbstractTrial) -> Int
trialID(output::MMOutput) -> Int
trialID(samplings::Vector{Sampling}) -> Union{Int,Missing}

Return the database ID of a trial, or of the trial an MMOutput wraps.

The Vector{Sampling} form instead looks up which Trial groups exactly those samplings, in any order, and gives missing when none does. It never creates one — that is Trial(samplings).

trialType(T::AbstractTrial)
trialType(output::MMOutput)

Return the concrete type of T: Simulation, Monad, Sampling, or Trial. For an MMOutput, the type of the trial that was run.