PhysiCellModelManager.jl

Check out Getting started for a quick guide to using PhysiCellModelManager.jl. Make sure you are familiar with the Best practices section before using PhysiCellModelManager.jl.

Quick start

See Getting started for more details.

1. Install Julia.
2. Ensure the general registry is added:

pkg> registry add General

3. Add the BergmanLabRegistry:

pkg> registry add https://github.com/drbergman-lab/BergmanLabRegistry

4. Install PhysiCellModelManager.jl:

pkg> add PhysiCellModelManager

5. Create a new PCMM project:

julia> using PhysiCellModelManager
julia> createProject() # uses the current directory as the PCMM project folder

Note: A PCMM project is distinct from PhysiCell's sample_projects and user_projects.

6. Import a sample project or a user project from PhysiCell:

julia> importProject("path/to/PhysiCell/user_projects/my_project") # replace with the path to your project folder

7. Check the output of Step 6 and record your input folders:

julia> config_folder = "my_project" # replace these with the name from the output of Step 6
julia> custom_code_folder = "my_project"
julia> rules_folder = "my_project" 
julia> inputs = InputFolders(config_folder, custom_code_folder; rulesets_collection = rules_folder) # also add ic_cell and ic_substrate if used

8. Run the model:

julia> out = run(inputs; n_replicates = 1)

9. Check the output:

julia> using Plots # make sure to install Plots first
julia> plot(out)
julia> plotbycelltype(out)

10. Vary parameters:

julia> xml_path = configPath("some_cell_type", "apoptosis", "death_rate") # replace with a cell type in your model
julia> new_apoptosis_rates = [1e-5, 1e-4, 1e-3]
julia> dv = DiscreteVariation(xml_path, new_apoptosis_rates)
julia> out = run(inputs, dv; n_replicates = 3) # 3 replicates per apoptosis rate => 9 simulations total

---

Implementation Status

For Claude Code sessions: this section is the authoritative record of what has been built. Update it as features are completed. See PRD.md for behavioral specifications and progress.md for decision rationale.

Completed

• Project initialization (createProject, initializeModelManager)
• Model import from PhysiCell project folders (importProject, InputFolders)
  • Wizard for guiding users through the import process and recording their input folders
• Parameter variation — discrete, grid, distributed, latent, co-variation
• Space-filling designs — LHS, Sobol, RBD
• Simulation execution — local multi-process runner
• HPC job script generation and submission
• Analysis — population counts and time series (finalPopulationCount, populationTimeSeries, meanPopulationTimeSeries)
• Sensitivity analysis — MOAT, Sobol, and RBD
• Calibration — PhysiCell-specific summary statistics (endpointPopulationCounts, endpointPopulationFractions, meanPopulationTimeSeries) for use with ModelManager's CalibrationProblem; ABC-SMC algorithm, posterior visualization, and resumeABC live in ModelManager
  • GP-accelerated ABC (surrogate model to reduce expensive PhysiCell evaluations)
  • Bayesian optimization
  • Additional methods (MCMC, Nelder-Mead, etc.) as subtypes of AbstractCalibrationMethod
• Database management — SQLite schema, versioned migrations (up.jl), diagnostics
• Export and pruning of simulation outputs
• Intracellular model support (custom data, rules)
• IC cell and IC ECM file management

Remaining

• Support showing snapshots from a monad/sampling/trial in a single figure. Support CairoMakie (as extension) to make a movie from the snapshots.
• GP-accelerated ABC and additional calibration methods (see Calibration bullet above)