PhysiCell: An open source physics-based cell simulator for 3-D multicellular systems

Many multicellular systems problems can only be understood by studying how cells move, grow, divide, interact, and die. Tissue-scale dynamics emerge from systems of many interacting cells as they respond to and influence their microenvironment. The ideal “virtual laboratory” for such multicellular systems simulates both the biochemical microenvironment (the “stage”) and many mechanically and biochemically interacting cells (the “players” upon the stage). PhysiCell—physics-based multicellular simulator—is an open source agent-based simulator that provides both the stage and the players for studying many interacting cells in dynamic tissue microenvironments. It builds upon a multi-substrate biotransport solver to link cell phenotype to multiple diffusing substrates and signaling factors. It includes biologically-driven sub-models for cell cycling, apoptosis, necrosis, solid and fluid volume changes, mechanics, and motility “out of the box.” The C++ code has minimal dependencies, making it simple to maintain and deploy across platforms. PhysiCell has been parallelized with OpenMP, and its performance scales linearly with the number of cells. Simulations up to 105-106 cells are feasible on quad-core desktop workstations; larger simulations are attainable on single HPC compute nodes. We demonstrate PhysiCell by simulating the impact of necrotic core biomechanics, 3-D geometry, and stochasticity on the dynamics of hanging drop tumor spheroids and ductal carcinoma in situ (DCIS) of the breast. We demonstrate stochastic motility, chemical and contact-based interaction of multiple cell types, and the extensibility of PhysiCell with examples in synthetic multicellular systems (a “cellular cargo delivery” system, with application to anti-cancer treatments), cancer heterogeneity, and cancer immunology. PhysiCell is a powerful multicellular systems simulator that will be continually improved with new capabilities and performance improvements. It also represents a significant independent code base for replicating results from other simulation platforms. The PhysiCell source code, examples, documentation, and support are available under the BSD license at http://PhysiCell.MathCancer.org and http://PhysiCell.sf.net.

20 Acknowledgements 91 Bibliography 91 1 Introduction and citing PhysiCell This user guide will teach you how to download and use PhysiCell [3], as well as document the key classes and functions. Wherever possible, it will demonstrate with specific examples. Please note that this guide will be periodically updated. Users should check PhysiCell.MathCancer.org for the latest version. The PhysiCell method paper is in revision for additional peer review at PLoS Computational Biology [3].
If you use PhysiCell, please cite it as: We built our model using PhysiCell (Version 1.2.2) [1].
[1] A. Ghaffarizadeh We will update this citation information as PhysiCell progresses through peer review.
If you prefer to cite a peer-reviewed journal publication while waiting for our main method paper, you you can also cite an earlier (2-D)  [Return to 2 Getting started: The Quickstart and your First Simulation As of Version 1.2.2, every download of PhysiCell includes a Quickstart.pdf guide in the root directory. If you follow the instructions in that guide (along with instructions to set up your compiler and environment; see Section 4), you should be able to run and visualize your first PhysiCell simulation (heterogeneous tumor growth) in well under an hour.
You should also watch the #PhysiCell hashtag on Twitter for updates on PhysiCell and new tricks, tips, and tutorials. Tutorials and other blog posts can be found at http://MathCancer.org/blog/physicell-tutorials/. See Section 3 for resources for help, including support tickets and the PhysiCell blog.
[Return to

Preparing your development environment
PhysiCell was designed to be cross-platform compatible, without need for a package manager system or any other complex installation. In principle, any C++11 compliant compiler with OpenMP support should work. In practice, we use g++ as our "gold standard." You'll also want to ensure that your build environment supports makefiles. Command-line zip/unzip is also helpful, but not required.
Please note that OSX (and its associated developer tools) ships with "g++" instead of g++: it uses LLVM/Clang and an alias to pretend to be g++. Unfortunately, the version of LLVM/Clang that Apple ships does not fully support OpenMP, and so compiling can fail on those platforms without further setup. For OSX, we recommend following our Homebrew-based tutorial to install real g++.
Full tutorials on installing a 64-bit g++/OpenMP environment (on Windows via mingw-w64 and on OSX using Homebrew) can be found at: http://www.MathCancer.org/blog/physicell-tutorials/ Most linux users should already have a 64-bit g++ environment installed by default.
[Return to

Suggested tutorials and resources
Working in PhysiCell requires some knowledge of C++, Makefiles, and command-line routines in Unix-like systems. If you are not familiar with these skillsets, we recommend the following resources: • URL (Linux): Use your package manager to install mplayer (which includes mencoder).

Overall codebase structure
PhysiCell was created by extending the Basic_Agent class in BioFVM [2] to include a fuller cell phenotype and force-based cell motion. In the overall software philosophy, we structure PhysiCell in several critical subdirectories: 1. BioFVM This includes a working copy of the BioFVM multi-substrate diffusion code [2]. Users should be able to fully replace these files with any later version of BioFVM. Note that BioFVM distributions also include pugixml (an efficient cross-platform XML parser) [6].
2. config While this directory is not currently used, PhysiCell will eventually parse XML files with configuration information in this directory. Any custom configuration files should be placed in this directory.
3. core The core library files for PhysiCell are kept in this directory. Users should not modify functions in the core library.
4. custom modules This directory is the right place to put custom user code. Moreover, users should list their custom code files in custom_modules/PhysiCell_custom.h.

5.
modules This is where we place non-core (but helpful) standard code modules for distribution with PhysiCell. Currently, we include pathology, MultiCellDS [1], and SVG (scalable vector graphic) functions. Future releases may include basic modules for extracellular matrix.
The following subdirectories are also included: 1. archives If you use the make zip or make archive rules, the compressed archives will be placed here.  [2], pugixml [6], PhysiCell, and any other (BSD-compatible) dependencies are kept here. 6. output Some examples will put their outputs here.

documentation
7. povray This includes some basic utilities for visulization by povray (an open source raytracing package) [9].
8. template projects This directory once stored template projects for 2D and 3D. These have been moved to the sample projects as of Version 1.2.2. This directory will be deprecated.
9. sample projects This directory includes sample projects, including 2D and 3D template projects and at least the four sample projects in [3]. A good start to a new project is to use the make template2D or make template3D makefile rules, which will populate the main.cpp, Makefile, and ./custom_modules with appropriate codes to get started. See Section 6 for more information on the template projects, and Section 7 for the full list of sample projects and instructions to build them.
[Return to Table of Contents.]

Using project templates
As of Version 1.1.0, PhysiCell includes templates for 2-D and 3-D projects. These template projects set up all the critical BioFVM (microenvironment) and PhysiCell data structures and give examples on seeding a few cells. When beginning a new project with PhysiCell, we strongly recommend starting with these templates.
To start a new 2-D project (based on the template), go to the command line in the root PhysiCell directory, and run:

make template2D
This will populate a starting project from the files in ./sample_projects/template2D/. In particular, it will overwrite the Makefile, copy template_projects/template2D.cpp to main.cpp in the root directory, and copy the contents of ./sample_projects/template2D/custom_modules/ to ./custom_modules. Note that the Makefile has been modified to include the custom modules: # put your custom objects here (they should be in the custom_modules directory) This is the recommended structure for a project.
Once you're ready, build the project by typing make By default, the executable will be called project2D (project2D.exe on windows). To change the name of the executable, modify the PROJECT_NAME variable in the Makefile.
To start a new 3-D project based on a template, type make template3D and continue as before.
Now, run the code: ./project2D (in Windows, omit the "./".) This will generate (among other things) a series of SVG images that visualize the simulation once per hour.
More examples will be introduced on the PhysiCell blog. See Section 3.
[Return to 1. biorobots-sample is a 2-D example of 3 cell types: cargo cells, worker cells (which seek out cargo cells and haul them to a destination), and director cells (which attract worker cells).
2. cancer-biorobots-sample extends the biorobots example to (1) simulate a 2-D tumor that develops a necrotic core, (2) so that cargo cells are hauled towards hypoxic tumor regions, and (3) so that released cargo cells secrete a chemotherapeutic compounds.
3. heterogeneity-sample simulates a 2-D tumor with heterogeneous "genetics" that drive differential proliferation.
4. cancer-immune-sample extends the heterogeneity example to 3D, and introduces a new immune cell type (modeling T cells) that migrate towards tumor cells, temporarily adhere, test for immunogenicity, and initiate apoptosis.
5. template2D is the template for a 2-D project. See Section 6.
6. template3D is the template for a 3-D project. See Section 6.
[Return to

The BioFVM microenvironment
PhysiCell is built upon BioFVM [2], and so it uses the (bio)chemical microenvironment from BioFVM, including diffusion, decay, cell-based secretions/uptake, and bulk supply/uptake functions. All PhysiCell projects already include bioFVM once you have included PhysiCell: #include "./core/PhysiCell.h" We also suggest using the BioFVM and PhysiCell namespaces: using namespace BioFVM; using namespace PhysiCell;

A brief note on the microenvironment
BioFVM divides the simulation domain into a collection of non-intersecting voxels: volumetric pixels. Each voxel has a unique integer index: this is its unique address, for quickly accessing its information. As particularly notable information, each voxel stores its own position (center) and volume.
BioFVM adds one or more diffusible substrates to this microenvironment. Each substrate has a diffusion coefficient and decay rate. At present, these are homogeneous throughout the microenvironment, although improvements are planned for BioFVM to have spatially variable diffusion coefficients. In BioFVM, each substrate diffuses and decays, and can be secreted or uptaken by individual cells (see Section 11.7) at their individual positions. You can also set bulk uptake and secretion functions, which are applied in each voxel. These are not used in the current template and sample PhysiCell projects. See [2] for more information.
For each voxel, we store a vector of chemical substrates (densities), and a vector of gradients (one gradient vector for each substrate). Moreover, users can use "Dirichlet nodes" to overwrite the substrate values at any voxel within the simulation domain. This is useful for modeling biotransport in irregular domains, setting substrate values along blood vessels, or applying classical Dirichlet conditions along the outer edges of the simulation domain. Note that without specifying Dirichlet conditions, BioFVM applies Neumann (no flux) conditions at the outer simulation boundaries.
[Return to You can set these options either towards the top of your main program source file (e.g., in main.cpp) or in a standalone setup function. See the sample projects for examples. Here is sample use, to set the tissue name to "liver" and set up to 3D with Dirichlet conditions of oxygen = 38 mmHg: BioFVM defaults to a 1 mm 3 domain centered at (0,0,0) with ∆x = ∆y = ∆z = 20 µm, simulating 3D with no Dirichlet conditions and no gradient calculations, and minutes time units and micron space units. If you call initialize_microenvironment() without setting units (see Section 8.2.1), these defaults will be used.
The code also automatically chooses the correct 2D/3D diffusion solver, and sets the single diffusing field to oxygen with diffusion coefficient 10 5 µm 2 /min and decay coefficient 0.1 1/min (for a 1 mm diffusion length scale in the absence of cells).
By the end of these commands, the default Microenvironment is set to microenvironment. You can get this address at any time using the BioFVM command:

Microenvironment* get_default_microenvironment( void )
You'll also need to set up PhysiCell's mechanics data structures (for cell-cell interaction testing) and match them to BioFVM: As of Version 1.2.0, PhysiCell has automated cell secretions/uptake as part of its phenotype updates. There is no need to explicitly call the BioFVM cell-based functions in the main program loop.
Note that the PhysiCell template projects and sample projects already include these critical setup commands. See Section 6.
[Return to

Sampling the microenvironment
To make it easier to write functions involving microenvironment substrates at any cell's location, BioFVM 1.1.5 added the following function: int Microenvironment::find density index( std::string name ) This allows you to find the index of the substrate named name. Note that this function is case sensitive.
The following functions can access the substrates and their gradients in space:  [Return to BioFVM applies these Dirichlet conditions every time it evaluates the diffusion solver.
[Return to

Other BioFVM resources
To learn more about using BioFVM, take a look at the tutorials at:

Cells
Each Cell is an extension of BioFVM's Basic_Agent class. As such, it has access to all the parent class's member data and functions. In PhysiCell, Cells have the following major parts: 1. std::string type name: The name of the type of cell. 6. Phenotype phenotype: A hierarchical organization of the cell's properties. This data element is discussed in great depth in Section 10.
The following inherited member data and functions (from Basic_Agent) are especially helpful: 1. int ID is a unique integer identifier for the cell. No other cell now or in the future will have the same ID.
2. int index is the cell's current index in std::vector<Basic_Agent*> all_basic_agents, the list of all current Basic_Agents in the simulation.
3. int type is a user-specified (default 0) integer code to classify the cell's type. Use these to quickly compare if two cells are of the same or different types, or to perform type-specific operations on them.
4. int get current voxel index( void ) returns the cell's positional index in the BioFVM Microenvironment.
5. std::vector<double>& nearest density vector( void ) allows the user to directly access (i.e., sample or modify) the vector of substrates at the cell's position. This is useful building functions that alter cell phenotype based on the microenvironment.
6. std::vector<double>& nearest gradient( int substrate index ) returns (by reference) the gradient of the substrate with index substrate_index, at the cell's current position. This is useful for things like chemotaxis.
7. std::vector<gradient>& nearest gradient vector( void ) returns a vector of all the substrate gradients at the cell's position. Each gradient is a std::vector<double> of size 3.
Here is how the Cell class is defined in PhysiCell_cell.h:  (c) If s ≤ ∆t/T per or if ∆t < T per (where T per is the cell's mean persistence time), then continue.
Otherwise, leave v mot unchanged and exit.
(d) Choose a random direction ξ in 3-D: (e) Update the motility bias vector b and the bias b by calling functions.update_migration_bias.
(f) Set v mot according to biased random motion: Here 0 ≤ b ≤ 1 is the motility bias (phenotype.motility.migration_bias), b is the migration bias direction (phenotype.motility.migration_bias_direction), and s mot is the migration speed (phenotype.motility.migration_speed). See Section 11.6. See Section 9.4.3 for more information on cell functions, and Section 11.6 for further details on cell motility.
2. void advance bundled phenotype functions( double dt ) automatically runs the following cell functions once every phenotype time step (by default, once per 6 simulated minutes): (a) Evaluate functions.update_phenotype to update the phenotype based upon the current sampling of the microenvironment and any other parameters (e.g., cell-cell interactions). If update_phenotype == NULL, this is skipped. See Section 10 for more information on the cell phenotype class.
(b) Advance the cell volume model by dt_ time by calling functions.volume_update_function. Skip this step if functions.volume_update_function == NULL. See Section 11.3 for more information on cell volume.
(c) Update the cell geometry (radius, nuclear radius, surface area, etc.) by calling phenotype.geometry.update. See Section 11.4 for more information on the cell geometry. (d) Check for death events in the next dt_ time (such as apoptosis and necrosis) by calling phenotype.death.check_for_death. If the function returns true, set the cell's current cycle model to the appropriate death model, evaluate any death entry functions, and set motility to zero. Cell secretions are set to zero, and cell uptake is cut by a factor of 10. (Users can make further changes to secretion and uptake using entry_functions that are called at the start of a death model phase. See Section 11.1.1.) See Section 11.2 for more information on cell death, and see Section 11.1 on the general cycle class.
(e) Advance the current cycle model, whether it is a (live) cell cycle model or a death cycle model, by calling phenotype.cycle.advance_cycle. See Section 11.1 for more details. 8. void flag for removal( void ) adds the cell to the list of cells that should be removed from the simulation at the next opportunity.
9. void start death( int death model index ) immediately kills the cell (with the death model indicated by death_model_index), sets cell.phenotype.death.dead = true, sets motility to zero, sets secretion to zero, cuts all uptake by a factor of ten, and executes any "entry" functions for the associated death model. 10. Cell* divide( void ) performs cell division, and returns the memory address of the newlycreated cell.
11. void die( void ) removes the cell from the simulation.
12. void step(double dt) is neither used nor implemented. It will be deprecated.
13. Cell() is the default constructor. Users should use the create_cell functions rather than this constructor. See Section 9.3.
14. bool assign position(std::vector<double> new position) safely sets the cell's position to new_position. Always use this rather than directly editing position (inherited from Basic_Agent).
15. bool assign position(double, double, double) performs the same function as above, but supplying the x, y, and z coordinates separately.
16. void set total volume(double) safely sets the cell's total volume. It also sets the cell's subvolumes proportionally.
17. double& get total volume(void) returns the cell's current total volume, stored in cell.phenotype.volume.total. It is not the preferred way to access this data, but it is provided to overwrite the base Basic_Agent::get_total_volume function.
18. void update position( double dt ) uses the cell's current and previous velocities to safely update the cell's position, using the second-order Adams-Bashforth algorithm.
19. void assign orientation() sets the cell's state.orientation according to its current model (if any). See Section 9.4.3.
20. void copy function pointers(Cell*) overwrites the functions in functions with those from the supplied Cell.
21. void update voxel in container(void) updates the cell's position within the interaction testing data structure.
22. void copy data(Cell *) copies the member data (including custom_data, parameters, but not phenotype from the Cell at Cell*. 23. void set phenotype( Phenotype& phenotype ) is no longer used and will be deprecated. Users can now safely overwrite the cell's phenotype at any time.
24. void update radius() is neither implemented nor used. It will be deprecated.
25. Cell Container* get container() returns the memory address of the Cell_Container containing the cell.
26. std::vector<Cell*>& cells in my container( void ) returns (by reference) a vector of pointers to the cells in the current mechanics voxel. For performance reasons, we are giving users direct access to the underlying data structures, rather than copies. It is critical that users do not alter the underlying array of Cell*. Future releases of PhysiCell will provide more refined access functions, including better lists of neighbors and lists of nearby mechanics voxels.
27. void convert to cell definition( Cell Definition& cd ) converts the cell to match the name, type, custom data, parameters, function, and phenotype stored in the Cell Definition in cd.
(See Section 9.4.5 for more information on cell definitions.) As of Version 1.2.2, this function does not overwrite the is_movable, is_out_of_domain, and displacement data of the cell.
This function is particularly useful if you want to do thinks like stem cell heirarchies, where you might "convert" a stem cell to a differentiated cell, each of which has been defined separately.
[Return to Table of Contents.]

Other key functions
The following are functions in the PhysiCell namespace (and are not members of the Cell class). Cell* pCell = (*all_cells) [13]; if( pCell->custom_data[ "infected" ] == true ) { delete_cell ( 13 ); } 4. void delete cell( Cell* ) deletes the cell with located at Cell* and removes it from all relevant data structures. This is the safe way to directly remove a cell from a simulation.
Example: Let's check the 13th cell and delete it if a custom variable "infected" (See Section 9.4.1) indicates that it is infected. (See Section 15.4 for more on the vector all_cells that lists the memory addresses of all cells.) Cell* pCell = (*all_cells) [13]; Here are the main data elements and member functions, in greater detail: ccc.add_vector_variable( "home", myvec ); 9. int find variable index( std::string name ) returns the index of the variable with name name, if it exists. Note that this function is case sensitive.
Example: We'll create a custom cell data structure called my_custom_data, add some scalar and vector variables, and display it.

mmHg)
o2_necrosis_max ≤ o2_necrosis_threshold 9. Phenotype* pReference live phenotype is a pointer to a Phenotype (See Section 10) which will serve as reference values when oxygen is equal to o2_reference.
10. double max necrosis rate is the necrosis rate (in units 1/min) when the oxygen value dips below o2_necrosis_max.
11. int necrosis type is used to decide between deterministic and stochastic necrosis.

Cell Parameters() is the default constructor.
[Return to Table of Contents.]

Cell Functions
This data structure attaches user-specified functions for key cell behaviors. Note that in PhysiCell, almost all functions that act on cells take the form void function( Cell* pCell, Phenotype& phenotype, double dt ).
Ordinarily, phenotype = pCell->phenotype, but we allow these to be specified separately for cases where pCell = NULL.
Here is the full class definition: Here are the member data and functions in greater detail: 1. Cycle Model cycle model is the cell cycle model to be used for this cell (or Cell_Definition-see Section 9.4.5). The Cycle\_Model class is discussed in greater detail in Section 11.1.3.
2. void (*volume update function)( Cell* pCell, Phenotype& phenotype, double dt ) is a function pointer to a user-specified model of cell volume regulation, based upon the parameters stored in phenotype.volume. See Section 11.3 for more detail. We recommend the reference model in [3]: standard_volume_update_function.
3. void (*update migration bias)( Cell* pCell, Phenotype& phenotype, double dt ) is a function pointer to a user-specified model to set the migration bias direction, e.g., towards a chemical gradient. See Section 11.6 for more detail. We give an example in Section 17.

Cell State
The Cell_State is a small collection of cell descriptors that do not neatly belong in the cell Phenotype.
Here is the full class definition: And here are further details on the member data and functions: 1. std::vector<Cell*> neighbors is the memory addresses of all cells that are currently neighbors of the cell (as determined by the adhesion interaction potential). This variable is not currently updated in PhysiCell, but it will be in a future release.
2. std::vector<double> orientation is the cell's current basal-to-apical orientation, as a unit vector. Please note that if the cell's phenotype.geometry.polarity = 0, then this state variable has no meaning. Also note that in 2-D simulations, one should set orientation = {0,0,1}.
3. double simple pressure is a simple analog for mechanical pressure, nondimensionalized by a scale. We define the dimensional pressure p i by where N i is the set of the neighbor cells of the cell, F ccr ij is the cell-cell "repulsive" imparted on cell i by its neighbor j, and S i is the cell surface area. In [3,7], we approximated F ccr ij by where To define a scale, suppose the cell is in close packing in 3D by equally-sized cells with total volume V , mean radius R, maximal cross-sectional area A, and equal coefficient c j ccr = c i ccr for each neighbor j. In 3D, the cell has 12 neighbors in a tight sphere packing. By [4], the equilibrium cell-cell distance s in a 3-D confluent cell packing is This defines a pressure scale: Thus, we define a dimensionless analog of pressure by: 4. Cell State() is the default constructor.

Cell Definition
The Cell_Definition class allows users to define a cell type, including its default phenotype, and all its custom functions. Users can then work on defining multiple cell types at the start of a simulation and using these to initialize many cells at the start of a simulation (or during a simulation).
Here is the full class definition: Here are the member data and functions in greater detail: 1. int type is a unique identifier for the cell type. It will be copied to the cell's type.
2. std::string name is the "plain English" name of the cell type. It is copied to the cell's type_name.
3. pMicroenvironment is a pointer to the simulation's BioFVM microenvironment, which is always &microenvironment.
4. parameters is defined in Section 9.4.2. It is copied to the cell's parameters.
5. custom data is defined in Section 9.4.1. It is copied to the cell's custom_data.
6. functions is defined in Section 9.4.3. It is copied to the cell's functions.
7. phenotype is defined in Section 10. It is copied to the cell's phenotype.
8. Cell Definition() is the default constructor.
[Return to Table of Contents.]

Phenotype
The Phenotype is one of the most important components of a cell in PhysiCell, allowing us to specify the current state and properties of a cell. Most functions in PhysiCell are based upon either updating the phenotype or advancing the simulation based upon each cell's current phenotype.
The Phenotype is divided into multiple functional groups: 1. Cycle gives cell cycle information, including the graph structure of the cycle model, associated parameter values (transition rates), and information on the current cycle phase. See Section 11.1. Note that for a dead cell, the "cycle model" is set to a death model.

2.
Death gives current cell death rates for one or more death models. See Section 11.2.
3. Volume gives the cell's current total volume, as well as nuclear, cytoplasmic, fluid, and other subvolumes. See Section 11.3.

4.
Geometry records the cell's radius, nuclear radius, and surface area (using spherical approximations). See Section 11.4.

5.
Mechanics records the cell's adhesion and repulsion strength parameters for interactions with cells and the basement membrane, as well as the maximum adhesive interaction distance (a multiple of the cell's equivalent radius). Future releases of PhysiCell will likely expand this aspect of the cell phenotype. See Section 11.5.
6. Motility records phenotype information on motility, currently including persistence, a direction for biased random walks (e.g., chemotaxis), and a scalar bias parameter that can vary motility between purely Brownian and completely deterministic along the current bias direction. See Section 11.6.
7. Secretion records cell secretion and uptake rates, as well as a saturation density (at which secretion ends). See Section 11.7.
Here is how the Phenotype class is defined in PhysiCell_phenotype.h: In the Section 11, we give further details on the data elements within the Phenotype class.
[Return to Cycle stores the graph structure and parameters of the current cycle model, which can either be a cell cycle model or a death cycle model. It also includes member functions to progress through the cycle, and call appropriate cell division or removal functions. Before introducing Cycle (Section 11.1.5), we will detail the sub-classes necessary to work with a cycle model. All these data structures have been introduced with the goal of separating the graph structure of a cycle model (Cycle_Model: Section 11.1.3) from its parameter values (Cycle_Data: section 11.1.4), while still bundling them in a simple structure (Cycle: Section 11.1.5) for use in a Phenotype.
A Cycle_Model is constructed of one or more Phases (Section 11.1.1) that are connected into a directed graph by Phase_Links (Section 11.1.2).
[Return to Table of Contents.]

Phase
The Phase class defines the phase in a cycle model, including the following data elements: 1. int index is an internal unique index within a cycle model.

int code is a unique global identifier for the phase, using constants defined in
PhysiCell_constants.h using PhysiCell_constants. See Section 15.7.

bool division at phase exit is a Boolean variable that indicates whether the cell should divide
at the end of this phase (e.g., at the end of M phase).

bool removal at phase exit is a Boolean variable that indicates whether the cell should be re-
moved at the end of this phase (e.g., at the end of apoptosis).
6. void (*entry function)(Cell* pCell, Phenotype& phenotype, double dt) is a pointer to a function that is executed at the start of the phase. This would be a good place to write a function to perform mutations (e.g., at the start of G0/G1, randomly choose selected phenotype parameters according to a distribution).
Here is the formal class declaration: 1. Phase() is the default constructor. It sets index = 0, code = 0, name = "unnamed", all flags to false, and the entry function to NULL.
[Return to Table of Contents.]

Phase Link
The Phase_Link class is a link between one Phase and another (e.g., progression from G0/G1 to S phase). It includes the following data elements: 1. int start phase index is the unique index of the starting phase in the phase transition (a link from phase start_phase_index to phase end_phase_index).

int end phase index is the unique index of the ending phase in the phase transition (a link from
phase start_phase_index to phase end_phase_index).
3. bool fixed duration is a Boolean variable that indicates whether the cell spends a fixed amount of time before transitioning from phase start_phase_index to phase end_phase_index. Note that this variable only makes sense if there is a single, unique phase transition starting from start_phase_index.

void (*arrest function)(Cell* pCell, Phenotype& phenotype, double dt) is a function
pointer that allows you to set an arrest condition for the phase transition (e.g., only progress from M to G0/G1 if the cell is of sufficient volume). Its return value is true if the transition is arrested, and false if the transition is allowed to proceed. Set this pointer to NULL to bypass checking for arrest in this phase link. 5. void (*exit function)(Cell* pCell, Phenotype& phenotype, double dt) is a function pointer to a function that is executed at the end of the phase transition. This would be a good place to write a function to perform mutations (e.g., at the transition from M to G0/G1, randomly choose selected phenotype parameters according to a distribution).
Here is the formal class declaration:

Cycle Model
The Cycle_Model connects one or more Phases through Phase_Links, and stores this entire graph structure along with parameter values. (See Cycle_Data in Section 11.1.4.) It also contains member functions to assist with constructing and executing a cycle model, as well as to readily access transition rates. Here are the key data elements: 2. std::string name is the "plain English" name of the cycle model (e.g., Ki67 (Basic)).  Please note that this returns 0 if there is no exact match! Note that this function is case sensitive.

int code is a unique global (integer) identifier for the cycle model, using constants defined in
7. double& transition rate( int start index , int end index ) is a user-friendly interface function to access (by reference) the transition rate from phase start_index to phase end_index.
8. Phase Link& phase link(int start index , int end index) is a user-friendly interface function to access (by reference) the Phase_Link from phase start_index to phase end_index.
9. void advance model( Cell* pCell, Phenotype& phenotype, double dt ) advances the the cycle model by dt time (assumed minutes in current PhysiCell versions). For the current phase in phenotype.cycle.data.current_phase(), it evaluates the probability of advancing to all linked phases within dt time (see [3]) and changes the model (and the state of phenotype.cycle.data) accordingly. It will call cell division and removal functions as needed.
10. std::ostream& display( std::ostream& os ) allows streaming of a basic visual output of the cycle model. I recommend calling display( std::cout ).
[Return to Table of Contents.]

Cycle Data
The Cycle_Data class contains key parameters and state variables for a cell cycle model (see Section 11.1.3), as well as member functions to easily access transition rates and the current cycle phase. It includes the following data elements: 5. int current phase index indicates the current phase in the Cycle_Model.
6. double elapsed time in phase records how long the cell has been in the current phase.
Here is the formal class declaration:
2. Phase& current phase( void ) is a user-friendly interface function to access (by reference) the current Phase in the cycle. Use this to get the name and other structural information.
3. void sync to cycle model( void ) resizes the internal data structures for consistency with the pCycle_Model, if it is non-NULL.

double& transition rate( int start phase index , int end phase index ) is a user-
friendly interface function to access (by reference) the transition rate from phase start_phase_index to phase end_phase_index.

double& exit rate( int phase index ) is a user-friendly interface function to access (by ref-
erence) the rate of exiting the phase_index phase, in the case where there is only one Phase_Link from that phase to another. (e.g., for a cycle model where the S phase only links to the G2 phase.) In this case, the cell spends (in the mean) 1 exit rate(phase index) time in phase phase_index.
[Return to

Cycle
The Cycle bundles a Cycle_Model with Cycle_Data for simpler inclusion in a Phenotype. Its main data elements are: 1. Cycle Model* pCycle Model is a pointer to a Cycle_Model.

2.
Cycle Data data is Cycle_Data associated with the Cycle_Model. Note that this is an independent copy of the pCycle_Model->data, so that a single cell's phenotype can be updated without modifying the defaults for the underlying cycle model.
Here is the formal class declaration: 3. Cycle Model& model(void) returns (by reference) the cycle model pointed to by pCycle_Model.

4.
Phase& current phase(void) returns (by reference) the current phase (as given in data) in the cycle model. 5. int& current phase index(void) returns (by reference) the current phase index (as given in data) in the cycle model. 6. void sync to cycle model(Cycle Model& cm) sets pCycle_Model = &cm and then overwrites data with cm.data.
[Return to

Death models
A death model is a Cycle_Model (Section 11.1.3), where one of the phases is marked to trigger cell removal. We define Death_Parameters (Section 11.2.1) to include key parameters needed in most death models, and bundle these as Death (Section 11.2.2) within the phenotype, similarly to Cycle (Section 11.1.5).
[Return to Table of Contents.]

Death Parameters
Death_Parameters bundles key parameters needed to initialize a cell death model, particularly changes in a cell's volume model. The key data elements include: 1. std::string time units gives the time units (by default minutes throughout PhysiCell).
2. double unlysed fluid change rate is the rate of fluid change (in min −1 ) prior to cell lysis.
3. double lysed fluid change rate is the rate of fluid change (in min −1 ) after cell lysis.
4. double cytoplasmic biomass change rate is the degradation rate for cytoplasmic solids (in min −1 ). 5. double nuclear biomass change rate is the degradation rate for nuclear solids (in min −1 ). 6. double calcification rate is the rate of cell calcification (in min −1 ). 7. double relative rupture volume is the relative amount by which the cell must swell (compared to the volume at the onset of cell death) before it bursts or lyses.
Here is the formal class declaration:  [3].
[Return to Table of Contents.]

Death
In PhysiCell, we allow the cells to evaluate multiple death models (e.g., apoptosis and necrosis). Death stores the cell's death rates, the corresponding death models, and associated parameters. Here are the data elements: 1. std::vector<double> rates is a vector of death rates, one per death model. 2. std::vector<Cycle Model*> models is a vector of pointers to death models, which are of type Cycle_Model.
3. std::vector<Death Parameters> parameters is a vector of Death_Parameterss, one for each Cycle_Model.
4. bool dead is a Boolean variable that is true if the cell is dead.

int current death model index is the index of the current death model, when dead == true.
Here is the formal class declaration:

Volume
Volume stores the cell's total volume, its various sub-volume elements, and critical parameters. (PhysiCell supplies reasonable defaults.) Here are the main elements (all volume units in PhysiCell are currently assumed to be µm 3 .) 1. double total is the cell's total volume.
2. double solid is the solid component of the cell's total volume. It is in dimensional units of volumenot a fraction or ratio. Note that volume.total = volume.solid + volume.fluid.
3. double fluid is the fluid component of the cell's total volume. It is in dimensional units of volumenot a fraction or ratio. Note that volume.total = volume.solid + volume.fluid.
4. double fluid fraction is the fraction of the cell that is fluid, defined as: volume.fluid_fraction = volume.fluid / volume.total.
5. double nuclear is the total nuclear volume. Note that: volume.total = volume.nuclear + volume.cytoplasmic.
6. double nuclear solid is the solid component of the cell's nuclear volume. It is in dimensional units of volume-not a fraction or ratio. Note that: volume.nuclear = volume.nuclear_solid + volume.nuclear_fluid.
7. double nuclear fluid is the fluid component of the cell's nuclear volume. It is in dimensional units of volume-not a fraction or ratio. Note that: volume.nuclear = volume.nuclear_solid + volume.nuclear_fluid.
8. double cytoplasmic is the total cytoplasmic volume. Note that: volume.total = volume.nuclear + volume.cytoplasmic.
9. double cytoplasmic solid is the solid component of the cell's cytoplasmic volume. It is in dimensional units of volume-not a fraction or ratio. Note that: volume.cytoplasmic = volume.cytoplasmic_solid + volume.cytoplasmic_fluid.

double cytoplasmic fluid is the fluid component of the cell's cytoplasmic volume. It is in
dimensional units of volume-not a fraction or ratio. Note that: volume.cytoplasmic = volume.cytoplasmic_solid + volume.cytoplasmic_fluid.
11. double calcified fraction is the fraction of the cell that is calcified. (This is particularly useful to simulations of ductal carcinoma in situ of the breast.) Note that 0 ≤ calcified fraction ≤ 1.
12. double cytoplasmic to nuclear ratio is volume.cytoplasmic / volume.nuclear. Note that 0 ≤ cytoplasmic to nuclear ratio ≤ 1.
13. double rupture volume is the (dimensional) volume at which a cell will burst or lyse.
14. double cytoplasmic biomass change rate is the rate that cytoplasmic solid material can be synthesized to reach the target cytoplasmic solid volume. It is assumed to be written in units of min −1 .
15. double nuclear biomass change rate is the rate that nuclear solid material can be synthesized to reach the target nuclear solid volume. It is assumed to be written in units of min −1 .
16. double fluid change rate is the rate that fluid can enter or leave the cell to reach the target fluid fraction. It is assumed to be written in units of min −1 .
17. double calcification rate is the rate that the cell calcifies. It is assumed to be written in units of min −1 .
18. double target solid cytoplasmic is the cell's target ("desired" or "goal") solid cytoplasmic volume.
19. double target solid nuclear is the cell's target ("desired" or "goal") solid nuclear volume.
21. double relative rupture volume is the relative volume at which a cell, written as a multiple of the cell's total volume at the onset of a swelling process. (For example, at the start of necrosis.) Note that 0 ≤ relative rupture volume ≤ 1.
Here is the class declaration:

Geometry
Geometry stores critical aspects of cell geometry other than volume. In the current implementation, we use spherical approximations for the cell geometry, since PhysiCell tracks cell volume but not cell morphology. The main data elements are: 1. double radius is the cell's equivalent radius, based upon the spherical approximation volume.total = 4 3 π radius 3 .
In the current version of PhysiCell, spatial units are assumed to be µm.
2. double nuclear radius is the nucleus' equivalent radius, based upon the spherical approximation volume.nuclear = 4 3 π nuclear radius 3 .
Its units are assumed µm.
3. double surface area is the cell's equivalent surface area, based upon the spherical approximation surface area = 4π radius 2 .
4. double polarity is a dimensionless number between 0 and 1 to indicate how polarized the cell is along its basal-to-apical axis. If the polarity is zero, the cell has no discernible polarity. Note that polarity should be set to one for 2-D simulations.
Its units are assumed µm 2 .
Here is the class definition in PhysiCell_phenotype.h: 2. void update radius( Cell* pCell, Phenotype& phenotype, double dt) sets radius according to the spherical approximation in Section 11.4, using phenotype.volume.total.
[Return to

Mechanics
Mechanics stores the main mechanics parameters for a cell. The main data elements are: 1. double cell cell adhesion strength is the parameter C cca in the default PhysiCell mechanics model, written as a multiple of the drag coefficient ν; see [3]. It regulates the relative strength of cell-cell adhesive forces. Future releases of PhysiCell will allow this to be defined for interactions with multiple cell types.
2. double cell BM adhesion strength is the parameter C cba in the default PhysiCell mechanics model, written as a multiple of the drag coefficient ν; see [3]. It regulates the relative strength of adhesion of cells to the basement membrane, when present.
3. double cell cell repulsion strength is the parameter C ccr in the default PhysiCell mechanics model, written as a multiple of the drag coefficient ν; see [3]. It regulates the relative strength of cell-cell "repulsive" forces (resistance to deformation and compression).
4. double cell BM repulsion strength is the parameter C cbr in the default PhysiCell mechanics model, written as a multiple of the drag coefficient ν; see [3]. It regulates the relative strength of cell-BM "repulsive" forces (resistance of cells to deformation and compression, and resistance of basement membranes to penetration and deformation by cells).
5. double relative maximum adhesion distance is the maximum distance of cell adhesion to other cells or a basement membrane, given as a (dimensionless) multiple of geometry.radius.
6. double maximum adhesion distance is the absolute maximum distance at which a cell interacts adhesively with other cells or basement membrane. We tend not to use this variable in PhysiCell functions, so it may be deprecated in future releases.
As future releases of PhysiCell may include additional mechanics models, this class may be expanded in the future. In particular, we anticipate models to allow varying strengths of adhesion between different cell types, and improved adhesion models.

Motility
Motility stores motility parameters and the current speed/direction of motility. It was designed to be sufficiently generic to allow recovery of purely Brownian motion, deterministic taxis, and combinations of these. Here are the main data elements: 1. bool is motile is a Boolean variable that can be used to enable/disable cell motility.
2. double persistence time is the mean time cell continues at its current speed and direction before re-evaluating and choosing a new motility vector. It is assumed to have units minutes.
3. double migration speed is the speed of motility, in the absence of other forces (e.g., cell-cell adhesion). It is assumed to have units of µm/min. 4. std::vector<double> migration bias direction is the 3-D vector giving the cell's preferred direction of motility for biased Brownian motion. If the user modifies this vector, they must ensure it is a unit vector : ||migration bias direction|| = 1.
5. double migration bias (with a value in [0,1]) sets the degree to which cell motility is biased along migration_bias_direction. If 0, then motion is completely Brownian. If 1, it is completely deterministc along the bias direction.
6. bool restrict to 2D is a Boolean variable that is set to true is we are restricting cell motility to 2D.
7. std::vector<double> motility vector is the velocity vector for cell motility, based upon the all the variables and parameters defined above. See also Section 11.6.2.
Here is the class definition:

Motility definitions
The direction of (biased random) motility is given by where b (migration_bias) is the level of bias, ξ is a random unit vector (length 1, uniformly random direction), and d bias (migration_bias_direction) is the directional bias for motility. See Section 9.2 for more information on how the Motility class is used when updating a cell's velocity.
[Return to

Secretion
Secretion collects the cell's biotransport parameters for interfacing with BioFVM [2]. Its main data elements include: 1. Microenvironment* pMicroenvironment is a pointer to the correct microenvironment, where substrates have already been declared.
2. std::vector<double> secretion rates is a vector of secretion rates for the substrates in the microenvironment.
3. std::vector<double> uptake rates is a vector of uptake rates for the substrates in the microenvironment.
Here is the full class declaration:

Secretion() is the default constructor. If a default Microenvironment has already been set in
BioFVM, then pMicroenvironment is set to this (otherwise NULL). Thereafter, secretion_rates, uptake_rates, and saturation_densities are resized for consistency with pMicroenvironment, with all values set to 0.0.
2. void sync to current microenvironment(void) resizes secretion_rates, uptake_rates, and saturation_densities consistency with pMicroenvironment and sets all vector entries to 0.0.
3. void sync to microenvironment(Microenvironment* pNew Microenvironment) sets pMicroenvironment = pNew_Microenvironment, resizes secretion_rates, uptake_rates, and saturation_densities for consistency with pMicroenvironment, and sets all vector entries to 0.0. 4. void advance( Basic Agent* pCell, Phenotype& phenotype, double dt) evaluates the BioFVM secretion and uptake functions for this individual cell. Consistency checks with BioFVM (including those from volume changes) are fully automated.
5. void set all secretion to zero( void ) sets all the secretion rates to zero. (Please note that settings pCell->is_active = false is the most efficient way to set all secretion and uptake to zero in a cell.) 6. void set all uptake to zero( void ) sets all the uptake rates to zero. (Please note that settings pCell->is_active = false is the most efficient way to set all secretion and uptake to zero in a cell.) 7. void scale all secretion by factor(double factor) multiplies all the secretion rates by factor.
8. void scale all uptake by factor(double factor) multiplies all the uptake rates by factor.
[Return to

Cell Containers
PhysiCell uses Cell_Containers to help organize and search for cells within the simulation (spatial) domain, and to accelerate cell-cell mechanics. It is overloaded with much of the core functionality of PhysiCell, so we highly recommend that you avoid direct operations on cell containers! For reference, here is the full class definition:

PhysiCell Outputs
PhysiCell supports several methods of output, including SVG files (allowing virtual pathology through a fixed cross-section), MultiCellDS digital snapshots (a single-time save file), and other output methods.
Over the next several releases, we plan further improvements to PhysiCell outputs.

Virtual Pathology
PhysiCell can simulate transmitted light microscopy to create virtual H&E (hematoxylin and eosin) images, as well as false-colored images. These images are saved as SVG (scalable vector graphics) files, which allow lossless rescaling of the image. Moreover, because SVG files are a specialized XML, users can change labels and other image aspects long after image processing, using simple text editors.
We also note that the SVG functions provided in PhysiCell (./modules/PhysiCell_SVG.h) can be compiled independently of PhysiCell.
[Return to std::vector<std::string> (*cell coloring function)(Cell*) ) creates an SVG plot through z = z slice, using the coloring function cell_coloring_function (See Section 13.1.3), with labeling for time time, in the microenvironment M, saved to filename.
This function checks all cells for intersection with the plane through z = z slice, and plots the intersecting part of the cell cytoplasm and nucleus (using circular approximations). In the plot, 1 pixel is 1 µm.
Example: H&E plot through z = 0µm, followed by a false-colored Ki-67 plot through z = 10µm: The SVG plotting options are set by PhysiCell_SVG_options, which is discussed further in Section 15.6.
2. std::string formatted minutes to DDHHMM( double minutes ) creates a nicely formated string (in days, hours, and minutes) based upon minutes. It is used extensively in SVG_plot.
3. std::vector<double> transmission( std::vector<double>& incoming light, std::vector<double>& absorb color, double thickness, double stain ) simulates transmission of light of color incoming_light through a tissue of thickness thickness, stained at relative intensity stain (with range from 0 to 1), which absorbs light of color absorb_color. Its output is the transmitted color, as an RGB vector.
We use a Lambert-Beer [5] light transmission model for each color channel (Red, Green, Blue): Note that we use 24-bit color, so red, green, and blue values should vary from 0 to 255. Outputs to SVG files will be rounded to the nearest integer value. This function is available for use in custom coloring functions, and PhysiCell uses it for virtual H&E stains.
Future releases will include functions to color the background according to data values in the BioFVM microenvironment.
[Return to Table of Contents.]

Cell coloring functions
PhysiCell's virtual pathology functions are built upon choosing a coloring function for the cells. A coloring function takes the form: std::vector<std::string> some_coloring_function( Cell* pCell ) and it returns a vector of four strings: the cytoplasm fill color, cytoplasm outline color, nuclear color, and nuclear outline color.
Colors in SVG can be specified as: 1. RGB colors: Use a string of the form "rgb(R,G,B)", where R, G, and B are the red, green, and blue values, and they are integers between 0 and 255.
The following cell coloring functions are provided in PhysiCell: which approximates the process of staining cytoplasmic solids with eosin, and the water fraction remaining unstained. The result of this simulated transmission is then fed back through the transmission function (as the incoming light color), with an hematoxylin absorb color (49.90,51.00,20.40) [10], a thickness of 20, and a stain intensity given by stain = pCell->phenotype.volume.calcified fraction which approximates the process of staining calcified cytoplasmic solids with hematoxylin.
All outlines match the corresponding fill colors.
[Return to Example: Simulated immunohistochemistry with DAB and a hematoxylin counterstain As in H&E, we assume that hematoxylin stains all nuclear solids, and here we assume that it stains cytoplasmic solids at 10% of the nuclear intensity. We assume that DAB stains a nuclear protein (in custom data). Based on these virtual stains, we use simulated light transmission.

MultiCellDS digital simulation snapshots
PhysiCell saves its data as specialized MultiCellDS digital snapshots [1]. These snapshots save key metadata (See Section 15.5), the microenvironment, and a compact cell readout in an XML file. See [1] and http://multicellds.org/Standards.php for detailed information on the data standard.
To save a MultiCellDS simulation snapshot, use: void save PhysiCell to MultiCellDS xml pugi( std::string filename base, Microenvironment& M , double current simulation time); Here, the filebase determines how all the snapshot sub-files will be named: filebase.xml, filebase_cells.mat, filebase_mesh0.mat, etc. Here is the overall structure of PhysiCell snapshot 1. XML headers in the <XML> tag.
(a) Metadata in a <metadata> tag, including simulation provenance (who ran it, with what software, citation information, etc.), and other notable elements including: i. The current simulation time, saved in a tag like <current_time units="min">0.000000</current_time>.

Key initialization functions
The following initialization functions should be called (in this order): 1. omp set num threads(omp num threads); to set the number of threads in the simulation.
2. SeedRandom(); to initialize the random number generator. (It generates a random seed based on the current system time.) You can also use long SeedRandom( long input ); to specify the random seed, such as to continue a simulation.
4. Cell Container* cell container = create cell container for microenvironment( microenvironment, mechanics voxel size );. Note that microenvironment is the default PhysiCell microenvironment. See Section 12.
5. initialize default cell definition(); sets up the default Cell_Definition and makes sure it is self-consistent. It also automatically runs setup functions to create standard cell cycle and death models. Users creating new cell definitions are encouraged to copy the default cell definition and then modify it.
All these initialization functions are included in the 2-D and 3-D project templates. See Section 6.
[Return to

Default microenvironment
The name of the default microenvironment in PhysiCell is microenvironment, which is declared in ./core/PhysiCell_phenotype.cpp. This strcture is initialized with the function initialize_microenvironment() based upon the settings in default_microenvironment_options (of type Microenvironment_Options).
Here is the definition of that data structure:

Default cell definition
In Section 9.4.5, we documented the data structure for a Cell Definition (similar to a MultiCellDS digital cell line [1]).
PhysiCell creates a default Cell_Definition called cell_defaults. Once the user calls initialize_default_cell_definition() (Section 14), this default definition is set to parameter values for the a generic breast epithelium line (calibrated to MCF-10A). The various member functions are used by BioFVM/PhysiCell when saving a simulation snapshot, and are not needed for users. We define Software_Metadata, Citation_Metadata, and Person_Metadata (currently unused) below. The other metadata elements (spatial_units, etc.) are as expected.
[Return to
[Return to

PhysiCell Constants
The structure PhysiCell_constants (in ./core/PhysiCell_constants.h) defines many standardized constants and integer identifiers. They can be accessed with syntax like this:

Standard models
PhysiCell includes several models for easier out-of-the-box simulation. We document here the underlying mathematics of these models, as also presented in [3].
Live start b (divides) Figure 1: The graph structure of the Live cell cycle model. The default phase is marked "start."

Cell Cycle Models
PhysiCell includes several pre-built cell cycle models. More models will be added in future releases.
In this model, live cells can divide into two live cells, with birth rate b. See Fig. 1. The population-scale model is given by: In PhysiCell, the transition rate from the Live state to the Live state is Further details on the biology of this model (including details the placement of daughter cells and changes in cell volume) and reference parameter values can be found in [3].
In this model, Ki67-cells (those staining negative for the cell proliferation marker Ki67) can enter the cell cycle to become Ki67+ cells, at transition rate r 01 . Ki67+ cells divide into two Ki67-cells at rate r 10 . See Further details on the biology of this model (including details the placement of daughter cells and changes in cell volume) and reference parameter values can be found in [3].
[Return to This Cycle_Mode has the following Phases: 1. Phase 0: Named Ki67-with code PhysiCell_constants::Ki67_negative. This is the default phase of the model.
In this model, Ki67-cells (those staining negative for the cell proliferation marker Ki67) can enter the cell cycle to become premitotic Ki67+ cells, at transition rate r 01 . Ki67+ premitotic cells divide into two Ki67+ postmitotic cells at rate r 12 . Postmitotic Ki67+ cells become Ki67-cells at rate r 20 . See Fig. 3.
The population-scale model is given by:  Figure 3: The graph structure of the Ki67 Advanced cell cycle model. The default phase is marked "start." Further details on the biology of this model (including details the placement of daughter cells and changes in cell volume) and reference parameter values can be found in [3].
[Return to

Death Cycle Models
PhysiCell currently includes two pre-built death cycle models. More models may be added in future releases, such as autophagy.
In this model, apoptotic cells shrink and exit the phase at rate r 01 (with fixed duration 1/r 01 ). Cells are removed from the simulation at the end of the apoptotic phase. (PhysiCell currently uses a dummy "debris" phase to avoid coding a phase transition from the apoptotic phase to the apoptotic phase; this may be removed in future releases.) See Fig. 4. The population-scale model is given by: Further details on the biology of this model (including details on changes in cell volume) and reference parameter values can be found in [3].
[Return to Table of Contents.] Apoptotic start removed r 01 Figure 4: The graph structure of the Apoptosis death cycle model. The default phase is marked "start," and the cell is removed as marked.'

Nec. (swelling) start
Nec. (lysed) removed r 01 , Block r 12 Figure 5: The graph structure of the Necrosis death cycle model. The default phase is marked "start," and the cell is removed as marked. The transition from the unlysed to lysed state is blocked until the cell volume reaches sufficient volume.
In this model, unlysed necrotic cells swell and attempt to transition to the lysed necrotic phase. There is a block on the transition until the cell reaches a sufficient total volume. Lysed cells gradually shrink (and calcify, if enable) and exit the phase at rate r 12 . Cells are removed from the simulation at the end of the lysed necrotic phase. (PhysiCell currently uses a dummy "debris" phase to avoid coding a phase transition from the lysed necrotic phase phase to another necrotic phase; this may be removed in future releases.) See Fig. 5.
Further details on the biology of this model (including details on changes in cell volume) and reference parameter values can be found in [3].
[Return to The standard volume model separately evolves the total fluid volume, cytoplasmic solid volume, and nuclear solid volume, as a system of ODEs (given in [3]). The standard model also updates cell calcification (but the default rate parameter is zero). See Section 11.3 for more information on the Volume class in the Phenotype, and [3] for the biological details of this model.
[Return to In this model, the cell uses the mechanics interaction data structure to find nearby cells, adds the contributions from adhesion and "repulsion,", adds the effects of basement membrane interactions (by calling functions.add_cell_basement_membrane_interactions), then computes the contribution to cell velocity by the motility model (by calling update_motility_vector, which in turn calls functions.update_migration_bias). See Section 11.6 for details on motility, Section 11.5 for key cell mechanics phenotype parameters, and Section 9 for more information on Cells and their member functions.
[Return to

Up orientation model (up orientation)
By default 3-D cells have no preferred orientation, and 2-D cells have an "up" orientation (set to [0,0,1]) to ensure they stay in the z = 0 plane. This supplied function is up_orientation.
16.6 Oxygen-dependent phenotype (update cell and death parameters O2 based) Oxygen-dependent cell proliferation and death rates are so commonly needed in cancer models that we include a model function as standard: update_cell_and_death_parameters_O2_based. Here is the overall model for proliferation:

Example: a custom migration bias
In this example, cells migrate along oxygen gradients. The migration speed is fastest in regions of low oxygen, and the migration is least stochastic (most biased) as the oxygenation increases.

Example: a custom cell rule
In this example, an immune cell tests nearby cells first for contact, and then for expression of an antigen (a custom variable). The immune cell initiates apoptosis in the target cell with probability that scales with the antigen expression.