Repository files navigation

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

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

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

Notable recognition:

• 2019 PLoS Computational Biology Research Prize for Public Impact

make: compiles the current project. If noproject has been defined, it firstpopulates the cancer heterogeneity 2Dsample 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 theMakefile,main.cpp, and everything in./config and./custom_modules/) in./user_projects/name, wherename is your choice for the project. If the project already exists, overwrite it.

make load PROJ=name: load the user projectname from./user_projects/name (including theMakefile,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/ inmake load PROJ=name.)

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

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

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

Homepage:http://PhysiCell.org

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

Downloads:https://PhysiCell.sf.net ANDhttps://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 athttps://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.

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 primarily introduces bugfixes and stability refinements, closer matching to the cell behavior grammar (including the newtransition to X synonym fortransform 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 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 Introduces Cell Behavior Hypothesis Grammar (CBHG) 3.0, enhancing the modeling of cellular behaviors with the addition of a newCell_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 theattack_duration parameter), and a clarifiedattack_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 newCell_Integrity class (withinPhenotype) allows more control over cell damage. Attacking cells (see above) can increase damage, as well as a new generalizeddamage_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 ratedamage_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 theSetup 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 theSetup Guides for details.

• In anticipation with the upcomingPhysiGym 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.

• asymmetric division is now possible through the config file
  • try the sample project with makeasymmetric-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 behaviorasymmetric division to [cell_type]
• create full path to output folder if it does not exist
• writerandom_seed tooutput/random_seed.txt for reproducibility even when usingsystem_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
• transferconserved custom data on phagocytosis from eaten to eater cell

• Introduced changes to Rules:
  • damage rate (a part ofCell_Integrity) is now a generalized term for a rate of damage caused by non-attack means
  • attack damage rate means whatdamage rate used to mean: how fast an attacking cell deals damage to a target cell throughout the duration of the atttack
  • phagocytose dead cell is replaced by death-model-specific rates:
    • phagocytose apoptotic cell
    • phagocytose necrotic cell
    • phagocytose other dead cell
• NewCell_Integrity class in PhysiCell_phenotype.h.damage was moved from Cell_State into Cell_Integrity
  • the cancer-biorobots-samplecustom.cpp was updated to reflect this change.
• contact with dead cell has been supplemented with additional (refined) signalscontact with apoptotic cell,contact with necrotic cell, andcontact with other dead cell
• Seed for random numbers: in the top most tag of a config file (for options that apply to the overall simulation), there is now a <random_seed>. Traditionally, this has been provided in <user_parameters> and if it is still present there, it will override the one in . Users are encouraged to migrate away from its use in <user_parameters> as this will likely be removed from sample projects in a future release.
  • Setting as an integer will have the same behavior as theuser_parameter
    • <random_seed>0</random_seed>
  • Setting as “”, “random”, or “system_clock” will use the system clock to set the random seed
    • <random_seed />
    • <random_seed></random_seed>
    • <random_seed>random</random_seed>
    • <random_seed>system_clock</random_seed>
• New option for a user-defined custom function for cell division. If provided, the custom function will receive pointers to the two daughter cells. A new sample project,custom-division-sample, is provided.
• Initial parameter distributions
  • Users can now start cells with heterogeneity in any behavior or also the total volume
  • For ease of access, in studio navigate to Cell Types > Misc > Parameter Distributions
  • Five distributions supported:
    • Uniform
      • Set min and max; behavior ~ U(min, max)
    • Log uniform
      • Set min and max; z ~ U(log(min), log(max)); behavior ~ exp(z)
      • Note: min and max are on the behavior scale, not the logarithmic scale
    • Normal
      • Set μ and σ; behavior ~ N(μ, σ)
      • Optionally set lb, ub to impose lb <= behavior <= ub
    • Log normal
      • Set μ and σ; z ~ N(μ, σ); behavior ~ exp(z)
      • Optionally set lb, ub to impose lb <= behavior <= ub
      • Note: μ and σ are on the logarithmic scale
      • Note: lb and ub are on the behavior scale
    • Log10 normal
      • Same as log normal, except behavior ~ 10^z
      • Implemented because log10 values are more human-interpretable
  • Can enforce that the base value is within the distribution to help constrain parameter sweeps
  • “Enable” attributes make it easy to toggle on/off individual distributions or for an entire cell type
• MultiCellDS update:
  • PhysiBoSS intracellular data is now part of data export
  • Spring attachments are now part of data export
  • Streamlined MultiCellDS with incorporation of more single-cell parameters/state variables
• Update to PhysiBoSS 2.2.3
  • Added steepness parameter to output mapping, controlling the Hill coefficient used.
  • Added use_for_dead parameter to input and output mapping, to define if this mapping should be used on dead cells.
  • Added three new sample projects:
    • template_BM: adaptation of the template project of PhysiCell, with PhysiBoSS support
    • physiboss-tutorial: three toy models presented in the PhysiBoSS tutorial (10.48550/arXiv.2406.18371).
    • physiboss-tutorial-invasion: update of the cancer invasion model by Ruscone et al., also presented in the PhysiBoSS tutorial.
• Update to PhysiMeSS 1.0.1
  • Most parameters are now defined in custom_data, to make them specific to a cell definition. This introduces the possibility to have multiple types of fibers.
• Introducing experimental pre-compiled binaries, available via python beta/download_binary.py.
• Non-monotonic rules: a single signal can now both cause an increaseand a decrease in a behavior for a cell type (bringing the implementation in better compliance with the specification athttps://www.biorxiv.org/content/10.1101/2023.09.17.557982)
• Initialize substrate initial conditions using a .mat or .csv file
  • implemented in PhysiCell Studio; see output there for formatting of the csv
• Substrate heatmaps on SVGs improvements:
  • set colormaps in the config file
  • set the svg substrate color function by default for config-only based implementation

• PR349 (minor improvement):load_PhysiCell_config_file() was split intoload_PhysiCell_config_file() andread_PhysiCell_config_file() functions

• PR349 (minor improvement):BioFVM BioFVM_microenvironment::initialize_microenvironment() was split intoinitialize_microenvironment() andset_microenvironment_initial_condition() functions.

• PR349 (minor improvement): InBioFVM/BioFVM_MultiCellDS.*, a newreset_BioFVM_substrates_initialized_in_dom() function was added.

• PR349 (minor improvement): A newBioFVM::BioFVM_basic_agent::reset_max_basic_agent_ID() function was added.

• Switchedsetup_cell_rules( void ) to output the full list of signals and behaviors with synonyms in./output/dictionaries.txt for fuller reference.

• Added new functions:

  • void display_signal_dictionary_with_synonyms( std::ostream& os )
  • void display_response_dictionary_with_synonyms( std::ostream& os )

• Addedtransition to X andtransition to cell type N as synonyms for the behaviortransform to X (with synonymtransform to cell type X), at the request of the cancer community who regardtransformation as synonymous withcancerous transformation. (Andtransition to X is now the "primary" name for the behavior.)

• PR352 (minor improvement): more robust macro to check for windows machines when creating directories

• PR353 (minor feature): Python script to download latest release of Studio (and create /studio).

  To use it, go to the root directory and run:

  python beta/get_physicell.py

  and then to run studio (with the template project):

    make reset && make template && make  python studio/bin/studio.py &

• PhysiBoSS PDFs removed from repo, links provided in tutorial README.md
• build binaries on releasepublished instead ofcreated
• beta/download_binary.py gets PhysiCell Version 1.14.1
• add reference to PhysiMeSS article
• make immune-function-sample to make sample project showing new (1.14.0) phagocytosis and attack modules
• addrules_sample to tests
• test and build on macos-13 instead of macos-12 as that is being deprecated by GitHub actions

• Scripts in/beta to help with testing, both manually and via GitHub Actions:test_build_samples.sh andtest*.py
• The Makefiles for all sample projects now do a recursive copy (cp -r) for files in the /config directory
• throw error if duplicate substrate or user_parameter name found

• PR350 (minor fix): use standard save event triggers in asymmetric division example
• PR351 (minor fix): re-round template project cycle durations

• store value ofattack_duration when parsing config file
• set rules to Version 3.0 for all projects
• store theconserved boolean when parsingcustom_data in the config
• when a cell dies, make sure it is removed fromneighbors lists for all neighboring cells
• usestd::stoul in place ofstd::stoi to properly read in large ints for random seeds
• usestd::ostringstream to write voxel coordinates to avoid overflowing the buffer
• fixcustom_divisionsample_project so it does not requirerandom_seed as auser_parameter
• actually recordapplies_to_dead boolean for exported rules
• initializetotal_attack_time = 0.0; to avoid random initial values
• update all sample projects to 1.14.x
  • update phagocytosis parameters
  • update attack parameters
• remove extraneous call toSeedRandom() in PhysiBoSS cell lines project
• do not let random detachment occur when one cell is attacking another

• sample_projects_intracellular/ode/ode_energy/main.cpp was updated to usesave_PhysiCell_to_MultiCellDS_v2
• Cell::convert_to_cell_definition now retains the cell volume
• fix bug in storing rules that occasionally resulted in seg faults

• Future releases may further refineCell_Integrity with more specific forms of damage (and accompanying damage and repair rates).

• We intend to deprecate the unused phenotype variablesrelative_maximum_attachment_distance,relative_detachment_distance, andmaximum_attachment_rate fromphenotype.mechanics.

• We intend to mergeCustom_Variable andCustom_Vector_Variable in the future.

• We may change the role ofoperator() andoperator[] inCustom_Variable to more closely mirror the functionality inParameters<T>.

• Additional search functions (e.g., to find a substrate or a custom variable) will start to return -1 if no matches are found, rather than 0.

• We will change the timing of whenentry_functions are executed within cycle models. Right now, they are evaluated immediately after the exit from the preceding phase (and prior to any cell division events), which means that only the parent cell executes it, rather than both daughter cells. Instead, we'll add an internal Boolean for "just exited a phase", and use this to execute the entry function at the next cycle call. This should make daughter cells independently execute the entry function.

• We might maketrigger_death clear out all the cell's functions, or at least add an option to do this.

• We might change the behavior of copied Custom Data when a cell changes type (changes to a new cell definition). Currently, all custom data elements in a cell are overwritten based on those in the new cell definition. This is not the best behavior for custom data elements that represent state variables instead of type-dependent parameters.

• Further XML-based simulation setup.

• Read saved simulation states (as MultiCellDS digital snapshots)

• Create an angiogenesis sample project

• Create a small library of angiogenesis and vascularization codes as an optional standard module in ./modules (but not as a core component)

• Further update sample projects to make use of more efficient interaction testing available

• Major refresh of documentation.