Globals

ModelManager.centralDBFileName(::PhysiCellSimulator)

Return the database filename for a PhysiCell project. Checks for the legacy vct.db name first (pre-PCMM projects), then falls back to pcmm.db.

mm_globals_ref

Module-level Ref holding the active ModelManagerGlobals instance.

Set by the concrete simulator package in its __init__, e.g.:

function __init__()
    ModelManager.mm_globals_ref[] = ModelManagerGlobals(simulator = MySimulator(), ...)
end

ModelManagerGlobals

Mutable struct holding all global state for a ModelManager project.

The active instance is accessed via mm_globals. Concrete simulator packages (e.g. PhysiCellModelManager) create an instance of this struct and register it via mm_globals_ref in their __init__.

Fields

• initialized::Bool: true after initializeModelManager succeeds.
• data_dir::String: Absolute path to the project data/ directory.
• simulator::AbstractSimulator: The active simulator backend.
• inputs_dict::Dict{Symbol,Any}: Parsed contents of inputs.toml.
• project_locations::ProjectLocations: Derived from inputs_dict.
• db::SQLite.DB: Connection to the central project database.
• run_on_hpc::Bool: true to submit simulations as SLURM jobs and to route file removal through the staging path of rm_hpc_safe. initializeModelManager sets it from isRunningOnHPC on every call; override afterwards with useHPC.
• sbatch_options::Dict{String,Any}: Options forwarded to sbatch.
• hpc_completion::HPCCompletionOptions: How the runner detects that a submitted SLURM job has finished. See setHPCCompletionOptions.
• max_number_of_parallel_simulations::Int: Concurrency limit.
• diagnostics_task::Union{Nothing,Task}: The background Task running databaseDiagnostics, set by initializeModelManager. nothing before initialization or if diagnostics have not been launched. Use waitForDiagnostics to block until it completes.
• provenance_id::Union{Nothing,Int}: Row in provenances describing the current creation context (session, launching script, git state). Re-resolved on entry to createTrial and run, and stamped onto the objects they create.
• session_id::String: Random per-session identifier recorded as mm:session. Assigned lazily on first use.
• tag_hints::Bool: Whether to show the one-time tagging hints. See setTagHints!.
• tag_hint_shown::Bool, tag_recovery_hint_shown::Bool: Once-per-session latches for those hints.
• trash_staged_warning_shown::Bool: Once-per-project latch for the warning rm_hpc_safe issues when a shared filesystem forces it to stage a path in data/.trash/ instead of removing it. Its :unremoved case — where it can do neither — is deliberately not latched, since each occurrence names a different leaked path.
• last_trash_sweep::String: yymmdd stamp of the day data/.trash/ was last swept, so a session that outlives a single day re-sweeps instead of relying on the one at startup.

assertInitialized()

Assert that the model manager has been initialized, throwing an informative error if not.

centralDB()

Return the central SQLite.DB connection for the current project.

currentSimulatorVersionID()

Return the current simulator version row ID from the database. Delegates to currentSimulatorVersionID(sim) on the active simulator.

dataDir()

Return the path to the current project's data/ directory.

initializeModelManager(simulator::AbstractSimulator, data_dir::AbstractString; auto_upgrade::Bool=false)

Initialize ModelManager for a project rooted at data_dir using simulator as the concrete backend.

This is the generic entry point that simulator packages (e.g. PhysiCellModelManager) call from their own path-level overloads after setting any simulator-specific fields. It performs all framework-agnostic initialization steps in order:

1. Register simulator and data_dir on the active ModelManagerGlobals.
2. Open the central SQLite database (filename determined by centralDBFileName).
3. Resolve the package version, creating or upgrading the DB schema if needed.
4. Parse inputs.toml.
5. Initialize the database schema (tables, folder registration).
6. Detect whether SLURM is available via isRunningOnHPC and store the result in run_on_hpc. Override it afterwards with useHPC.
7. Call postInitDisplay to print startup information.
8. Launch a background @async task that retries the removal of anything rm_hpc_safe had to stage in data/.trash/, then runs databaseDiagnostics.

Returns true on success, false on any initialization failure — including errors that would otherwise throw (e.g. an unwritable data_dir). All mutated globals are reset to a clean state before any false return, so isInitialized reports false and a subsequent retry starts fresh.

Simulator packages typically provide their own path-level overloads (e.g. accepting path_to_physicell and path_to_data) that validate paths, set simulator-specific state, then delegate here.

inputsDict()

Return the parsed inputs.toml dictionary for the current project.

isInitialized()

Return true if the model manager has been successfully initialized.

mm_globals()::ModelManagerGlobals

Return the active ModelManagerGlobals instance.

Throws an assertion error if no simulator package has registered its globals yet.

projectLocations()

Return the ProjectLocations for the current project.

simulator()

Return the active AbstractSimulator backend.

simulatorVersionIDName()

Return the SQL column name used for the simulator version FK. Delegates to simulatorVersionIDName(sim) on the active simulator.

waitForDiagnostics()

Block until the background databaseDiagnostics task launched during initializeModelManager completes. Returns immediately if diagnostics have already finished or were never started.

initializeModelManager runs five read-only consistency checks (DB↔filesystem sync, orphaned entries, constituent ID integrity, simulation status) in a background task so initialization returns promptly. In interactive sessions the diagnostics typically finish during the first idle moment. In scripts and HPC jobs the task runs opportunistically during I/O-heavy work (e.g. simulation runs); call waitForDiagnostics() explicitly if you need the output before a particular step.

Example

initializeModelManager(sim, data_dir)

# Optional: block until database consistency checks have printed their results.
# Useful in scripts that exit quickly or test suites that inspect diagnostic output.
# waitForDiagnostics()

# ... rest of your workflow ...

ProjectLocations

A struct that contains information about the locations of input files in the project.

Created by reading the inputs.toml file in the data directory via parseProjectInputsConfigurationFile.

Fields

• all::NTuple{L,Symbol}: All registered location names (alphabetically sorted).
• required::NTuple{M,Symbol}: Locations whose input folder is mandatory.
• varied::NTuple{N,Symbol}: Locations that support parameter variations.

folderIsVaried(location::Symbol, folder::String)

Return true if folder in location can have parameter variations applied.

locationFolder(location::Union{String,Symbol})

Return the name of the folder for location within data/inputs/. Defaults to locationTableName.

locationIDName(location)

Return the ID column name for location (e.g. "config_id").

locationIDNames()

Return an iterator over the ID column names for all locations.

locationPath(location::Symbol[, folder])

Return the path to location's input directory. If folder is given, join it.

locationTableName(location)

Return the database table name for location (e.g. "configs").

locationVariationIDName(location)

Return the variation ID column name for location (e.g. "config_variation_id").

locationVariationIDNames()

Return an iterator over the variation ID column names for all varied locations.

locationVariationsDBName(location::Union{String,Symbol})

Return the filename of the per-folder variations SQLite database for location.

locationVariationsFolder(location)

Return the name of the variations folder for location.

locationVariationsTableName(location)

Return the name of the variations table for location (e.g. "config_variations").

parseProjectInputsConfigurationFile()

Parse inputs.toml and update mm_globals with the resulting ProjectLocations and inputs_dict.

Returns true on success, false if the file is missing or malformed.

pathToInputsConfig()

Return the path to inputs.toml.