PhysiCell: an Open Source Physics-Based Cell Simulator for 3-D Multicellular Systems

Versions: 1.14.0 -

Release dates: 15 September 2024 -

• 1.14.0 : 15 September 2024
• 1.14.1 : 13 December 2024
• 1.14.2 : 20 January 2025

Overview:

PhysiCell is a flexible open source framework for building agent-based multicellular models in 3-D tissue environments.

Reference: A Ghaffarizadeh, R Heiland, SH Friedman, SM Mumenthaler, and P Macklin, PhysiCell: an Open Source Physics-Based Cell Simulator for Multicellular Systems, PLoS Comput. Biol. 14(2): e1005991, 2018. DOI: 10.1371/journal.pcbi.1005991

Visit http://MathCancer.org/blog for the latest tutorials and help.

Notable recognition:

• 2019 PLoS Computational Biology Research Prize for Public Impact

Key makefile rules:

make: compiles the current project. If no project has been defined, it first populates the cancer heterogeneity 2D sample project and compiles it

make project-name: populates the indicated sample project. Use "make" to compile it.

• project-name choices:
  • template
  • biorobots-sample
  • cancer-biorobots-sample
  • cancer-immune-sample
  • celltypes3-sample
  • heterogeneity-sample
  • pred-prey-farmer
  • virus-macrophage-sample
  • worm-sample
  • ode-energy-sample
  • physiboss-cell-lines-sample
  • cancer-metabolism-sample
  • interaction-sample
  • mechano-sample
  • rules-sample
  • physimess-sample
  • custom-division-sample
  • asymmetric-division-sample
  • immune-function-sample episode-sample

make list-projects : list all available sample projects

make clean : removes all .o files and the executable, so that the next "make" recompiles the entire project

make data-cleanup : clears out all simulation data

make reset : de-populates the sample project and returns to the original PhysiCell state. Use this when switching to a new PhysiCell sample project.

make save PROJ=name: save the current project (including the Makefile, main.cpp, and everything in ./config and ./custom_modules/) in ./user_projects/name, where name is your choice for the project. If the project already exists, overwrite it.

make load PROJ=name: load the user project name from ./user_projects/name (including the Makefile, main.cpp, and everything in ./config and ./custom_modules/).

make list-user-projects: list all user projects in ./user_projects/. (Use these names without the trailing / in make load PROJ=name.)

make jpeg : uses ImageMagick to convert the SVG files in the output directory to JPG (with appropriate sizing to make movies). Supply OUTPUT=foldername to select a different folder.

make movie : uses ffmpeg to convert the JPG files in the output directory an mp4 movie. Supply OUTPUT=foldername to select a different folder, or FRAMERATE=framerate to override the frame rate.

make upgrade : fetch the latest release of PhysiCell and overwrite the core library and sample projects.

Key Links

Homepage: http://PhysiCell.org

Setup Guide: https://github.com/physicell-training/ws2023/blob/main/agenda.md#set-up-physicell

Downloads: https://PhysiCell.sf.net AND https://github.com/MathCancer/PhysiCell/releases

Support: https://join.slack.com/t/physicellcomm-sf93727/shared_invite/zt-qj1av6yd-yVeer8VkQaNDjDz7fF00jA

User Guide: Look at UserGuide.pdf in the documentation folder.

Setup and Training: See this year's workshop and hackathon at https://github.com/PhysiCell-Training/ws2023

Older Tutorials: http://www.mathcancer.org/blog/physicell-tutorials/

Latest info: follow @PhysiCell on Twitter (http://twitter.com/PhysiCell)

See changes.md for the full change log.

---

Release summary:

Version 1.14 upgrades the Cell Beheavior Hypothesis Grammar (to version 3), including refinements to cell phagocytosis, effector attack, and cell damage/integrity in response to community discussions and peer review. It also introduces numerous refinements to cell division, random seeds, and randomized parameter initialization, as well as upgrades to PhysiBoSS and PhysiMeSS and bug fixes. Other refinements are "under the hood," including new GitHub actions and improved automation of testing, as well as improvements to MultiCellDS output.

Version 1.14.2 (20 Jan 2025):

Version 1.14.2 primarily introduces bugfixes and stability refinements, closer matching to the cell behavior grammar (including the new transition to X synonym for transform to X behavior and better support for asymmetric division), a new script to more easily download PhysiCell Studio, and improvements to allow parallel "episodes" of PhysiCell in machine learning environments, such as the upcoming PhysiGym addon.

We are grateful for contributions by Vincent Noël, Randy Heiland, Daniel Bergman, Heber Rocha, and Elmar Bucher in this release.

Version 1.14.1 (13 Dec 2024):

Version 1.14.1 primarily introduces bug fixes as noted below, but also introduces the first implementation of asymmetric division.

Among the notable changes includes a more consistent handling of internalized substrates and conserved custom data on transformation and phagocytosis: they are now conserved in these processes. Several other features and changes are included (see below) as well as additional bug fixes (major and minor). Finally, the test suite will no test on MacOS 13 instead of the now-deprecated-in-GitHub-Actions MacOS 12.

Please report any bugs or issues in Issues or in the PhysiCell community Slack workspace. Also, feel free to suggest new features in either location as well.

We are grateful for contributions by Vincent Noël, Randy Heiland, Daniel Bergman, Heber Rocha, and Elmar Bucher in this release.

Version 1.14.0 (15 Sep 2024):

Version 1.14.0 Introduces Cell Behavior Hypothesis Grammar (CBHG) 3.0, enhancing the modeling of cellular behaviors with the addition of a new Cell_Integrity class and refined phagocytosis behaviors (now split into separate rates for apoptotic, necrotic, and other dead cells). The built-in "attack" model has been refined to include formation of a persistent synapse (with a spring adhesion) throughout the attack (which is tunable via the attack_duration parameter), and a clarified attack_damage_rate to denote the rate at which an attacker damages its target cell. The attacking cell also tracks how long it has attacked (may be useful for exhaustion modeling), whether it is or is not attacking, and the identity (cell pointer) of the cell it is attacking.

The new Cell_Integrity class (within Phenotype) allows more control over cell damage. Attacking cells (see above) can increase damage, as well as a new generalized damage_rate that can (for example) be used to model damage from other sources such as cytotoxic drugs or toxins. A built-in model for damage repair (with default rate damage_repair_rate = 0) can be used for simple modeling of damage repair (e.g., DNA damage response during a cycle damage checkpoint).

This release also includes an option to set the random number generator seed value, new capabilities to draw initial parameters from a random distribution, and support for user-defined custom functions the evaluated during cell division (which allow users to individually set properties of daughter cells, such as during asymmetric division). Beyond bug fixes, the release includes a systematic testing package, utilizing scripts and GitHub Actions for automated testing.

We are grateful for contributions by Vincent Noël, Randy Heiland, Daniel Bergman, Heber Rocha, and Elmar Bucher in this release.

NOTE 1: MacOS users need to define a PHYSICELL_CPP environment variable to specify their OpenMP-enabled g++. See the Setup Guides for details.

NOTE 2: Windows users need to follow an updated (from v1.8) MinGW64 installation procedure. This will install an updated version of g++, plus libraries that are needed for some of the intracellular models. See the Setup Guides for details.

Major new features and changes in the 1.14.z versions

1.14.2

• In anticipation with the upcoming PhysiGym addon (for machine learning / reinforcement learning), it is now possible to run multiple consecutive episodes from a single PhysiCell model within a runtime. The episode sample project demonstrates this possibility.

1.14.1

• asymmetric division is now possible through the config file
  • try the sample project with make asymmetric-division-sample
  • on division, one (and only one) of the daughter cells can be assigned a new cell type
  • set probabilities for each cell type in the config file
  • control these probabilities with rules using the behavior asymmetric division to [cell_type]
• create full path to output folder if it does not exist
• write random_seed to output/random_seed.txt for reproducibility even when using system_clock for setting the seed
• copy the rules file(s) to the output folder and write the parsed rules (v3) to cell_rules_parsed.csv in the output folder
• preserve internalized substrates and conserved custom data on cell transformation
• default to 100% (instead of 0%) of internalized substrates being transferred on phagocytosis
• transfer conserved custom data on phagocytosis from eaten to eater cell