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/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/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/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.

CopyOrMove

An enum to indicate whether a source file or folder should be copied or moved during the import process. Possible values are _copy_ and _move_.

ImportDestFolder

A struct to hold the information about a destination folder to be created in the PhysiCellModelManager.jl structure.

Used internally in the importProject function to manage the creation of folders in the PhysiCellModelManager.jl structure.

Fields

• path_from_inputs::AbstractString: The path to the destination folder relative to the inputs folder.
• created::Bool: Indicates if the folder was created during the import process.
• description::AbstractString: A description of the folder.

ImportDestFolders

A struct to hold the information about the destination folders to be created in the PhysiCellModelManager.jl structure.

Used internally in the importProject function to manage the creation of folders in the PhysiCellModelManager.jl structure.

Fields

• import_dest_folders::NamedTuple: A named tuple containing the destination folders. The keys are the project locations and the values are ImportDestFolder instances.

ImportSource

A struct to hold the information about a source file or folder to be imported into the PhysiCellModelManager.jl structure.

Used internally in the importProject function to manage the import of files and folders from a user project into the PhysiCellModelManager.jl structure.

Fields

• src_key::Symbol: The key in the source dictionary.
• input_folder_key::Symbol: The key in the destination dictionary.
• path_from_project::AbstractString: The path to the source file or folder relative to the project.
• pcmm_name::AbstractString: The name of the file or folder in the PhysiCellModelManager.jl structure.
• type::AbstractString: The type of the source (e.g., file or folder).
• required::Bool: Indicates if the source is required for the project.
• found::Bool: Indicates if the source was found during import.
• copy_or_move::CopyOrMove: Indicates if the source should be copied or moved to the destination folder. See CopyOrMove.

ImportSources

A struct to hold the information about the sources to be imported into the PhysiCellModelManager.jl structure.

Used internally in the importProject function to manage the import of files and folders from a user project into the PhysiCellModelManager.jl structure.

Fields

• config::ImportSource: The config file to be imported.
• main::ImportSource: The main.cpp file to be imported.
• makefile::ImportSource: The Makefile to be imported.
• custom_modules::ImportSource: The custom modules folder to be imported.
• rulesets_collection::ImportSource: The rulesets collection to be imported.
• intracellular::ImportSource: The intracellular components to be imported.
• ic_cell::ImportSource: The cell definitions to be imported.
• ic_substrate::ImportSource: The substrate definitions to be imported.
• ic_ecm::ImportSource: The extracellular matrix definitions to be imported.
• ic_dc::ImportSource: The DC definitions to be imported.

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/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/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/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.

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

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

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

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

trialID(T::AbstractTrial)

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

trialID(samplings::Vector{Sampling})

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

trialType(T::AbstractTrial)

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