MathCancer Blog

Introducing cell interactions & transformations

Introduction

PhysiCell 1.10.0 introduces a number of new features designed to simplify modeling of complex interactions and transformations. This blog post will introduce the underlying mathematics and show a complete example. We will teach this and other examples in greater depth at our upcoming Virtual PhysiCell Workshop & Hackathon (July 24-30, 2022). (Apply here!!)

Cell Interactions

In the past, it has been possible to model complex cell-cell interactions (such as those needed for microecology and immunology) by connecting basic cell functions for interaction testing and custom functions. In particular, these functions were used for the COVID19 Coalition’s open source model of SARS-CoV-2 infections and immune responses. We now build upon that work to standardize and simplify these processes, making use of the cell’s state.neighbors (a list of all cells deemed to be within mechanical interaction distance).

All the parameters for cell-cell interactions are stored in cell.phenotype.cell_interactions.

Phagocytosis

A cell can phagocytose (ingest) another cell, with rates that vary with the cell’s live/dead status or the cell type. In particular, we store:

• double dead_phagocytosis_rate  : This is the rate at which a cell can phagocytose a dead cell of any type.
• std::vector<double> live_phagocytosis_rates : This is a vector of phagocytosis rates for live cells of specific types. If there are n cell definitions in the simulation, then there are n rates in this vector. Please note that the index i for any cell type is its index in the list of cell definitions, not necessarily the ID of its cell definition. For safety, use one of the following to determine that index:
  • find_cell_definition_index( int type_ID ) : search for the cell definition’s index by its type ID (cell.type)
  • find_cell_definition_index( std::string type_name ) : search for the cell definition’s index by its human-readable type name (cell.type_name)

We also supply a function to help access these live phagocytosis rates.

• double& live_phagocytosis_rate( std::string type_name )   : Directly access the cell’s rate of phagocytosing the live cell type by its human-readable name. For example,

pCell->phenotype.cell_interactions.live_phagocytosis_rate( "tumor cell" ) = 0.01;

At each mechanics time step (with duration \(\Delta t\), default 0.1 minutes), each cell runs through its list of neighbors. If the neighbor is dead, its probability of phagocytosing it between \(t\) and \(t+\Delta t\) is

\[ \verb+dead_phagocytosis_rate+ \cdot \Delta t\]

If the neighbor cell is alive and its type has index j, then its probability of phagocytosing the cell between \(t\) and \(t+\Delta t\) is

\[ \verb+live_phagocytosis_rates[j]+ \cdot \Delta t\]

PhysiCell’s standardized phagocytosis model does the following:

• The phagocytosing cell will absorb the phagocytosed cell’s total solid volume into the cytoplasmic solid volume
• The phagocytosing cell will absorb the phagocytosed cell’s total fluid volume into the fluid volume
• The phagocytosing cell will absorb all of the phagocytosed cell’s internalized substrates.
• The phagocytosed cell is set to zero volume, flagged for removal, and set to not mechanically interact with remaining cells.
• The phagocytosing cell does not change its target volume. The standard volume model will gradually “digest” the absorbed volume as the cell shrinks towards its target volume.

Cell Attack

A cell can attack (cause damage to) another live cell, with rates that vary with the cell’s type. In particular, we store:

• double damage_rate  : This is the rate at which a cell causes (dimensionless) damage to a target cell. The cell’s total damage is stored in cell.state.damage.  The total integrated attack time is stored in cell.state.total_attack_time.
• std::vector<double> attack_rates : This is a vector of attack rates for live cells of specific types. If there are n cell definitions in the simulation, then there are n rates in this vector. Please note that the index i for any cell type is its index in the list of cell definitions, not necessarily the ID of its cell definition. For safety, use one of the following to determine that index:
  • find_cell_definition_index( int type_ID ) : search for the cell definition’s index by its type ID (cell.type)
  • find_cell_definition_index( std::string type_name ) : search for the cell definition’s index by its human-readable type name (cell.type_name)

We also supply a function to help access these attack rates.

• double& attack_rate( std::string type_name )   : Directly access the cell’s rate of attacking the live cell type by its human-readable name. For example,

pCell->phenotype.cell_interactions.attack_rate( "tumor cell" ) = 0.01;

At each mechanics time step (with duration \(\Delta t\), default 0.1 minutes), each cell runs through its list of neighbors. If the neighbor cell is alive and its type has index j, then its probability of attacking the cell between \(t\) and \(t+\Delta t\) is

\[ \verb+attack_rates[j]+ \cdot \Delta t\]

To attack the cell:

• The attacking cell will increase the target cell’s damage by \( \verb+damage_rate+ \cdot \Delta t\).
• The attacking cell will increase the target cell’s total attack time by \(\Delta t\).

Note that this allows us to have variable rates of damage (e.g., some immune cells may be “worn out”), and it allows us to distinguish between damage and integrated interaction time. (For example, you may want to write a model where damage can be repaired over time.)

As of this time, PhysiCell does not have a standardized model of death in response to damage. It is up to the modeler to vary a death rate with the total attack time or integrated damage, based on their hypotheses. For example:

\[ r_\textrm{apoptosis} = r_\textrm{apoptosis,0} + \left( r_\textrm{apoptosis,max} – r_\textrm{apoptosis,0} \right)  \cdot \frac{ d^h }{ d_\textrm{halfmax}^h + d^h } \]

In a phenotype function, we might write this as:

void damage_response( Cell* pCell, Phenotype& phenotype, double dt )
{ // get the base apoptosis rate from our cell definition
     Cell_Definition* pCD = find_cell_definition( pCell->type_name );
     double apoptosis_0 = pCD->phenotype.death.rates[0];
     double apoptosis_max = 100 * apoptosis_0;
     double half_max = 2.0;
     double damage = pCell->state.damage;
     phenotype.death.rates[0] = apoptosis_0 + 
(apoptosis_max -apoptosis_0) * Hill_response_function(d,half_max,1.0);
     return;
}

Cell Fusion

A cell can fuse with another live cell, with rates that vary with the cell’s type. In particular, we store:

• std::vector<double> fusion_rates : This is a vector of fusion rates for live cells of specific types. If there are n cell definitions in the simulation, then there are n rates in this vector. Please note that the index i for any cell type is its index in the list of cell definitions, not necessarily the ID of its cell definition. For safety, use one of the following to determine that index:
  • find_cell_definition_index( int type_ID ) : search for the cell definition’s index by its type ID (cell.type)
  • find_cell_definition_index( std::string type_name ) : search for the cell definition’s index by its human-readable type name (cell.type_name)

We also supply a function to help access these fusion rates.

• double& fusion_rate( std::string type_name )   : Directly access the cell’s rate of fusing with the live cell type by its human-readable name. For example,

pCell->phenotype.cell_interactions.fusion_rate( "tumor cell" ) = 0.01;

At each mechanics time step (with duration \(\Delta t\), default 0.1 minutes), each cell runs through its list of neighbors. If the neighbor cell is alive and its type has index j, then its probability of fusing with the cell between \(t\) and \(t+\Delta t\) is

\[ \verb+fusion_rates[j]+ \cdot \Delta t\]

PhysiCell’s standardized fusion model does the following:

• The fusing cell will absorb the fused cell’s total cytoplasmic solid volume into the cytoplasmic solid volume
• The fusing cell will absorb the fused cell’s total nuclear volume into the nuclear solid volume
• The fusing cell will keep track of its number of nuclei in state.number_of_nuclei.  (So, if the fusing cell has 3 nuclei and the fused cell has 2 nuclei, then the new cell will have 5 nuclei.)
• The fusing cell will absorb the fused cell’s total fluid volume into the fluid volume
• The fusing cell will absorb all of the fused cell’s internalized substrates.
• The fused cell is set to zero volume, flagged for removal, and set to not mechanically interact with remaining cells.
• The fused cell will be moved to the (volume weighted) center of mass of the two original cells.
• The fused cell does change its target volume to the sum of the original two cells’ target volumes. The combined cell will grow / shrink towards its new target volume.

Cell Transformations

A live cell can transform to another type (e.g., via differentiation). We store parameters for cell transformations in cell.phenotype.cell_transformations, particularly:

• std::vector<double> transformation_rates : This is a vector of transformation rates from a cell’s current to type to one of the other cell types. If there are n cell definitions in the simulation, then there are n rates in this vector. Please note that the index i for any cell type is its index in the list of cell definitions, not necessarily the ID of its cell definition. For safety, use one of the following to determine that index:
  • find_cell_definition_index( int type_ID ) : search for the cell definition’s index by its type ID (cell.type)
  • find_cell_definition_index( std::string type_name ) : search for the cell definition’s index by its human-readable type name (cell.type_name)

We also supply a function to help access these transformation rates.

• double& transformation_rate( std::string type_name )   : Directly access the cell’s rate of transforming into a specific cell type by searching for its human-readable name. For example,

pCell->phenotype.cell_transformations.transformation_rate( "mutant tumor cell" ) = 0.01;

At each phenotype time step (with duration \(\Delta t\), default 6 minutes), each cell runs through the vector of transformation rates. If a (different) cell type has index j, then the cell’s probability transforming to that type between \(t\) and \(t+\Delta t\) is

\[ \verb+transformation_rates[j]+ \cdot \Delta t\]

PhysiCell uses the built-in Cell::convert_to_cell_definition( Cell_Definition& ) for the transformation.

Other New Features

This release also includes a number of handy new features:

Advanced Chemotaxis

After setting chemotaxis sensitivities in phenotype.motility and enabling the feature, cells can chemotax based on linear combinations of substrate gradients.

• std::vector<double> phenotype.motility.chemotactic_sensitivities is a vector of chemotactic sensitivities, one for each substrate in the environment. By default, these are all zero for backwards compatibility. A positive sensitivity denotes chemotaxis up a corresponding substrate’s gradient (towards higher values), whereas a negative sensitivity gives chemotaxis against a gradient (towards lower values).
• For convenience, you can access (read and write) a substrate’s chemotactic sensitivity via phenotype.motility.chemotactic_sensitivity(name) where name is the human-readable name of a substrate in the simulation.
• If the user sets cell.cell_functions.update_migration_bias = advanced_chemotaxis_function, then these sensitivities are used to set the migration bias direction via: \[\vec{d}_\textrm{mot} = s_0 \nabla \rho_0 + \cdots + s_n \nabla \rho_n. \]
• If the user sets cell.cell_functions.update_migration_bias = advanced_chemotaxis_function_normalized, then these sensitivities are used to set the migration bias direction via: \[\vec{d}_\textrm{mot} = s_0  \frac{\nabla\rho_0}{|\nabla\rho_0|} + \cdots + s_n  \frac{ \nabla \rho_n }{|\nabla\rho_n|}.\]

Cell Adhesion Affinities

Signal and Behavior Dictionaries

We will talk about this in the next blog post. See http://www.mathcancer.org/blog/introducing-cell-signal-and-behavior-dictionaries.

A brief immunology example

We will illustrate the major new functions with a simplified cancer-immune model, where tumor cells attract macrophages, which in turn attract effector T cells to damage and kill tumor cells. A mutation process will transform WT cancer cells into mutant cells that can better evade this immune response.

The problem:

We will build a simplified cancer-immune system to illustrate the new behaviors.

• WT cancer cells: Proliferate and release a signal that will stimulate an immune response. Cancer cells can transform into mutant cancer cells. Dead cells release debris. Damage increases apoptotic cell death.
• Mutant cancer cells: Proliferate but release less of the signal, as a model of immune evasion. Dead cells release debris. Damage increases apoptotic cell death.
• Macrophages: Chemotax towards the tumor signal and debris, and release a pro-inflammatory signal. They phagocytose dead cells.
• CD8+ T cells: Chemotax towards the pro-inflammatory signal and cause damage to tumor cells. As a model of immune evasion, CD8+ T cells can damage WT cancer cells faster than mutant cancer cells.

We will use the following diffusing factors:

• Tumor signal: Released by WT and mutant cells at different rates. We’ll fix a 1 min\(^{-1}\) decay rate and set the diffusion parameter to 10000 \(\mu m^2/\)min to give a 100 micron diffusion length scale.
• Pro-inflammatory signal: Released by macrophages. We’ll fix a 1 min\(^{-1}\) decay rate and set the diffusion parameter to 10000 \(\mu;m^2/\)min to give a 100 micron diffusion length scale.
• Debris: Released by dead cells. We’ll fix a 0.01 min\(^{-1}\) decay rate and choose a diffusion coefficient of 1 \(\mu;m^2/\)min for a 10 micron diffusion length scale.

In particular, we won’t worry about oxygen or resources in this model. We can use Neumann (no flux) boundary conditions.

Getting started with a template project and the graphical model builder

The PhysiCell Model Builder was developed by Randy Heiland and undergraduate researchers at Indiana University to help ease the creation of PhysiCell models, with a focus on generating correct XML configuration files that define the diffusing substrates and cell definitions. Here, we assume that you have cloned (or downloaded) the repository adjacent to your PhysiCell repository. (So that the path to PMB from PhysiCell’s root directory is ../PhysiCell-model-builder/).

Let’s start a new project (starting with the template project) from a command prompt or shell in the PhysiCell directory, and then open the model builder.

make template
make
python ../PhysiCell-model-builder/bin/pmb.py 

Setting up the domain

Let’s use a [-400,400] x [-400,400] 2D domain, with “virtual walls” enabled (so cells stay in the domain). We’ll run for 5760 minutes (4 days), saving SVG outputs every 15 minutes.

Setting up diffusing substrates

Move to the microenvironment tab. Click on substrate and rename it to tumor signal . Set the decay rate to 0.1 and diffusion parameter to 10000. Uncheck the Dirichlet condition box so that it’s a zero-flux (Neumann) boundary condition.

Now, select tumor signal in the lefthand column, click copy, and rename the new substrate (substrate01) to pro-inflammatory signal with the same parameters.

 

Then, copy this substrate one more time, and rename it from name debris. Set its decay rate to 0.01, and its diffusion parameter to 1.

Let’s save our work before continuing. Go to File, Save as, and save it as PhysiCell_settings.xml in your config file. (Go ahead and overwrite.)

If model builder crashes, you can reopen it, then go to File, Open, and select this file to continue editing.

Setting up the WT cancer cells

Move to the cell types tab. Click on the default cell type on the left side, and rename it to WT cancer cell. Leave most of the parameter values at their defaults. Move to the secretion sub-tab (in phenotype). From the drop-down menu, select tumor signal. Let’s set a high secretion rate of 10.

We’ll need to set WT cells as able to mutate, but before that, the model builder needs to “know” about that cell type. So, let’s move on to the next cell type for now.

Setting up mutant tumor cells

Click the WT cancer cell in the left column, and click copy. Rename this cell type (for me, it’s cell_def03) to mutant cancer cell.  Click the secretion sub-tab, and set its secretion rate of tumor signal lower to 0.1.

Set the WT mutation rate

Now that both cell types are in the simulation, we can set up mutation. Let’s suppose the mean time to a mutation is 10000 minutes, or a rate of 0.0001 min\(^{-1}\).

Click the WT cancer cell in the left column to select it. Go to the interactions tab. Go down to transformation rate, and choose mutant cancer cell from the drop-down menu. Set its rate to 0.0001.

 

Create macrophages

Now click on the WT cancer cell type in the left column, and click copy to create a new cell type. Click on the new type (for me cell_def04) and rename it to macrophage.

Click on cycle and change to a live cells and change from a duration representation to a transition rate representation. Keep its cycling rate at 0.

Go to death and change from duration to transition rate for both apoptosis and necrosis, and keep the death rates at 0.0

Now, go to the motility tab. Set the speed to 1 \(\mu m/\)min, persistence time to 5 min, and migration bias to 0.5. Be sure to enable motility. Then, enable advanced motility. Choose tumor signal from the drop-down and set its sensitivity to 1.0. Then choose debris from the drop-down and set its sensitivity to 0.1

Now, let’s make sure it secretes pro-inflammatory signal. Go to the secretion tab. Choose tumor signal from the drop-down, and make sure its secretion rate is 0. Then choose pro-inflammatory signal from the drop-down, set its secretion rate to 100, and its target value to 1.

Lastly, let’s set macrophages up to phagocytose dead cells. Go to the interactions tab. Set the dead phagocytosis rate to 0.05 (so that the mean contact time to wait to eat a dead cell is 1/0.05 = 20 minutes). This would be a good time to save your work.

Macrophages probably shouldn’t be adhesive. So go to the mechanics sub-tab, and set the cell-cell adhesion strength to 0.0.

Create CD8+ T cells

Select macrophage on the left column, and choose copy. Rename the new cell type to CD8+ T cell.  Go to the secretion sub-tab and make sure to set the secretion rate of pro-inflammatory signal to 0.0.

Now, let’s use simpler chemotaxis for these towards pro-inflammatory signal. Go to the motility tab. Uncheck advanced chemotaxis and check chemotaxis. Choose pro-inflammatory signal from the drop-down, with the towards option.

Lastly, let’s set these cells to attack WT and tumor cells. Go to the interactions tab. Set the dead phagocytosis rate to 0.

Now, let’s work on attack. Set the damage rate to 1.0. Near attack rate, choose WT tumor cell from the drop-down, and set its attack rate to 10 (so it attacks during any 0.1 minute interval). Then choose mutant tumor cell from the drop-down, and set its attack rate to 1 (as a model of immune evasion, where they are less likely to attack a non-WT tumor cell).

Set the initial cell conditions

Go to the user params tab. On number of cells, choose 50. It will randomly place 50 of each cell type at the start of the simulation.

That’s all! Go to File and save (or save as), and overwrite config/PhysiCell_settings.xml. Then close the model builder.

Testing the model

Go into the PhysiCell directory. Since you already compiled, just run your model (which will use PhysiCell_settings.xml that you just saved to the config directory). For Linux or MacOS (or similar Unix-like systems):

./project

Windows users would type project without the ./ at the front.

Take a look at your SVG outputs in the output directory. You might consider making an animated gif (make gif) or a movie:

make jpeg && make movie

Here’s what we have.

Promising! But we still need to write a little C++ so that damage kills tumor cells, and so that dead tumor cells release debris. (And we could stand to “anchor” tumor cells to ECM so they don’t get pushed around by the immune cells, but that’s a post for another day!)

Customizing the WT and mutant tumor cells with phenotype functions

First, open custom.h in the custom_modules directory, and declare a function for tumor phenotype:

void tumor_phenotype_function( Cell* pCell, Phenotype& phenotype, double dt );

Now, let’s open custom.cpp to write this function at the bottom. Here’s what we’ll do:

• If dead, set rate of debris release to 1.0 and return.
• Otherwise, we’ll set damage-based apoptosis.
  • Get the base apoptosis rate
  • Get the current damage
  • Use a Hill response function with a half-max of 36, max apoptosis rate of 0.05 min\(^{-1}\), and a hill power of 2.0

Here’s the code:

void tumor_phenotype_function( Cell* pCell, Phenotype& phenotype, double dt )
{
   // find my cell definition 
   static Cell_Definition* pCD = find_cell_definition( pCell->type_name ); 
   
   // find the index of debris in the environment 
   static int nDebris = microenvironment.find_density_index( "debris" ); 
   static int nTS = microenvironment.find_density_index( "tumor signal" ); 

   // if dead: release debris. stop releasing tumor signal
   if( phenotype.death.dead == true )
   {
      phenotype.secretion.secretion_rates[nDebris] = 1; 
      phenotype.secretion.saturation_densities[nDebris] = 1; 

      phenotype.secretion.secretion_rates[nTS] = 0; 
		
      // last time I'll execute this function (special optional trick) 
      pCell->functions.update_phenotype = NULL; 
      return; 
   }

   // damage increases death 

   // find death model 
   static int nApoptosis = 
      phenotype.death.find_death_model_index( PhysiCell_constants::apoptosis_death_model );

   double signal = pCell->state.damage; // current damage 
   double base_val = pCD->phenotype.death.rates[nApoptosis]; // base death rate (from cell def)
   double max_val = 0.05; // max death rate (at large damage)

   static double damage_halfmax = 36.0; 
   double hill_power = 2.0; 

   // evaluate Hill response function 
   double hill = Hill_response_function( signal , damage_halfmax , hill_power ); 
   // set "dose-dependent" death rate
   phenotype.death.rates[nApoptosis] = base_val + (max_val-base_val)*hill; 	

   return; 
}

Now, we need to make sure we apply these functions to tumor cell. Go to `create_cell_types` and look just before we display the cell definitions. We need to:

• Search for the WT tumor cell definition
• Set the update_phenotype function for that type to the tumor_phenotype_function we just wrote
• Repeat for the mutant tumor cell type.

Here’s the code:

...
   /* 
      Put any modifications to individual cell definitions here. 
      
      This is a good place to set custom functions. 
   */ 
	
   cell_defaults.functions.update_phenotype = phenotype_function; 
   cell_defaults.functions.custom_cell_rule = custom_function; 
   cell_defaults.functions.contact_function = contact_function; 
   
   Cell_Definition* pCD = find_cell_definition( "WT cancer cell"); 
   pCD->functions.update_phenotype = tumor_phenotype_function; 

   pCD = find_cell_definition( "mutant cancer cell"); 
   pCD->functions.update_phenotype = tumor_phenotype_function; 
	
   /*
      This builds the map of cell definitions and summarizes the setup. 
   */
		
   display_cell_definitions( std::cout ); 
   return; 
}

That’s it! Let’s recompile and run!

make && ./project 

And here’s the final movie.

Much better! Now the

Coming up next!

We will use the signal and behavior dictionaries to help us easily write C++ functions to modulate the tumor and immune cell behaviors.

Once ready, this will be posted at http://www.mathcancer.org/blog/introducing-cell-signal-and-behavior-dictionaries/.

from pyMCDS import pyMCDS

__init__(xml_file, [output_path = '.'])
    '''
    xml_file : string
        String containing the name of the output xml file
    output_path : 
        String containing the path (relative or absolute) to the directory
        where PhysiCell output files are stored
    '''

mcds = pyMCDS('output00000087.xml', '~/path/to/PhysiCell/output')
# Now our data lives in:
mcds.data

mcds.data['metadata']
mcds.data['continuum_variables']['my_chemical']

>>> mcds.data['metadata']['time_units']
'min'
>>> mcds.get_time()
5220.0

# We can extract one of the meshgrid arrays as a numpy array
>>> y_coords = mcds.data['mesh']['y_coordinates']
>>> y_coords.shape
(75, 75, 75)
>>> y_coords[0, 0, :4]
array([-740., -740., -740., -740.])

# We can also extract the array of voxel centers
>>> centers = mcds.data['mesh']['voxels']['centers']
>>> centers.shape
(3, 421875)
>>> centers[:, :4]
array([[-740., -720., -700., -680.],
       [-740., -740., -740., -740.],
       [-740., -740., -740., -740.]])

# We have a handy function to quickly extract the components of the full meshgrid
>>> xx, yy, zz = mcds.get_mesh()
>>> yy.shape
(75, 75, 75)
>>> yy[0, 0, :4]
array([-740., -740., -740., -740.])

# We can also use this to return the meshgrid describing an x, y plane
>>> xx, yy = mcds.get_2D_mesh()
>>> yy.shape
(75, 75)

# we need to know the names of the substrates to work with
# this data. We have a function to help us find them.
>>> mcds.get_substrate_names()
['oxygen', 'my_chemical']

# The diffusable chemical dictionaries are messy
# if we need to do a lot with them it might be easier
# to put them into their own instance
>>> oxy_dict = mcds.data['continuum_variables']['oxygen']
>>> oxy_dict['decay_rate']
{'value': 0.1, 'units': '1/min'}

# What we care about most is probably the numpy 
# array of concentrations
>>> oxy_conc = oxy_dict['data']
>>> oxy_conc.shape
(75, 75, 75)

# Alternatively, we can get the same array with a function
>>> oxy_conc2 = mcds.get_concentrations('oxygen')
>>> oxy_conc2.shape
(75, 75, 75)

# We can also get the concentrations on a plane using the
# same function and supplying a z value to "slice through"
# note that right now the z_value must be an exact match
# for a plane of voxel centers, in the future we may add
# interpolation.
>>> oxy_plane = mcds.get_concentrations('oxygen', z_value=100.0)
>>> oxy_plane.shape
(75, 75)

# we can also find the concentration in a single voxel using the
# position of a point within that voxel. This will give us an
# array of all concentrations at that point.
>>> mcds.get_concentrations_at(x=0., y=550., z=0.)
array([17.94514446,  0.99113448])

# Extracting single variables is just like before
>>> cell_ids = mcds.data['discrete_cells']['ID']
>>> cell_ids.shape
(18595,)
>>> cell_ids[:4]
array([0., 1., 2., 3.])

# If we're clever we can extract 2D arrays
>>> cell_vec = np.zeros((cell_ids.shape[0], 3))
>>> vec_list = ['position_x', 'position_y', 'position_z']
>>> for i, lab in enumerate(vec_list):
...     cell_vec[:, i] = mcds.data['discrete_cells'][lab]
...
array([[ -69.72657128,  -39.02046405, -233.63178904],
       [ -69.84507464,  -22.71693265, -233.59277388],
       [ -69.84891462,   -6.04070516, -233.61816711],
       [ -69.845265  ,   10.80035554, -233.61667313]])

# We can get the list of all of the variables stored in this dictionary
>>> mcds.get_cell_variables()
['ID',
 'position_x',
 'position_y',
 'position_z',
 'total_volume',
 'cell_type',
 'cycle_model',
 'current_phase',
 'elapsed_time_in_phase',
 'nuclear_volume',
 'cytoplasmic_volume',
 'fluid_fraction',
 'calcified_fraction',
 'orientation_x',
 'orientation_y',
 'orientation_z',
 'polarity',
 'migration_speed',
 'motility_vector_x',
 'motility_vector_y',
 'motility_vector_z',
 'migration_bias',
 'motility_bias_direction_x',
 'motility_bias_direction_y',
 'motility_bias_direction_z',
 'persistence_time',
 'motility_reserved',
 'oncoprotein',
 'elastic_coefficient',
 'kill_rate',
 'attachment_lifetime',
 'attachment_rate']
# We can also get all of the cell data as a pandas DataFrame 
>>> cell_df = mcds.get_cell_df() 
>>> cell_df.head() 
ID     position_x   position_y    position_z total_volume cell_type cycle_model ... 
0.0   - 69.726571  - 39.020464  - 233.631789       2494.0       0.0         5.0 ... 
1.0   - 69.845075  - 22.716933  - 233.592774       2494.0       0.0         5.0 ... 
2.0   - 69.848915  - 6.040705   - 233.618167       2494.0       0.0         5.0 ... 
3.0   - 69.845265    10.800356  - 233.616673       2494.0       0.0         5.0 ... 
4.0   - 69.828161    27.324530  - 233.631579       2494.0       0.0         5.0 ... 

# if we want to we can also get just the subset of cells that
# are in a specific voxel
>>> vox_df = mcds.get_cell_df_at(x=0.0, y=550.0, z=0.0)
>>> vox_df.iloc[:, :5]
             ID  position_x  position_y  position_z  total_volume
26718  228761.0    6.623617  536.709341   -1.282934   2454.814507
52736  270274.0   -7.990034  538.184921    9.648955   1523.386488

from pyMCDS import pyMCDS
import numpy as np
import matplotlib.pyplot as plt

# load data
mcds = pyMCDS('output00003696.xml', '../output')

# Set our z plane and get our substrate values along it
z_val = 0.00
plane_oxy = mcds.get_concentrations('oxygen', z_slice=z_val)

# Get the 2D mesh for contour plotting
xx, yy = mcds.get_mesh()

# We want to be able to control the number of contour levels so we
# need to do a little set up
num_levels = 21
min_conc = plane_oxy.min()
max_conc = plane_oxy.max()
my_levels = np.linspace(min_conc, max_conc, num_levels)

# set up the figure area and add data layers
fig, ax = plt.subplot()
cs = ax.contourf(xx, yy, plane_oxy, levels=my_levels)
ax.contour(xx, yy, plane_oxy, color='black', levels = my_levels,
           linewidths=0.5)

# Now we need to add our color bar
cbar1 = fig.colorbar(cs, shrink=0.75)
cbar1.set_label('mmHg')

# Let's put the time in to make these look nice
ax.set_aspect('equal')
ax.set_xlabel('x (micron)')
ax.set_ylabel('y (micron)')
ax.set_title('oxygen (mmHg) at t = {:.1f} {:s}, z = {:.2f} {:s}'.format(
                                        mcds.get_time(),
                                        mcds.data['metadata']['time_units'],
                                        z_val,
                                        mcds.data['metadata']['spatial_units'])

plt.show()

from pyMCDS import pyMCDS
import numpy as np
import matplotlib.pyplot as plt

# load data
mcds = pyMCDS('output00003696.xml', '../output')

# Set our z plane and get our substrate values along it
z_val = 0.00
plane_oxy = mcds.get_concentrations('oxygen', z_slice=z_val)

# Get the 2D mesh for contour plotting
xx, yy = mcds.get_mesh()

# We want to be able to control the number of contour levels so we
# need to do a little set up
num_levels = 21
min_conc = plane_oxy.min()
max_conc = plane_oxy.max()
my_levels = np.linspace(min_conc, max_conc, num_levels)

# get our cells data and figure out which cells are in the plane
cell_df = mcds.get_cell_df()
ds = mcds.get_mesh_spacing()
inside_plane = (cell_df['position_z'] < z_val + ds) \ & (cell_df['position_z'] > z_val - ds)
plane_cells = cell_df[inside_plane]

# We're going to plot two types of cells and we want it to look nice
colors = ['black', 'grey']
sizes = [20, 8]
labels = ['Alive', 'Dead']

# set up the figure area and add microenvironment layer
fig, ax = plt.subplot()
cs = ax.contourf(xx, yy, plane_oxy, levels=my_levels)

# get our cells of interest
# alive_cells = plane_cells[plane_cells['cycle_model'] < 6]
# dead_cells = plane_cells[plane_cells['cycle_model'] > 6]
# -- for newer versions of PhysiCell
alive_cells = plane_cells[plane_cells['cycle_model'] < 100]
dead_cells = plane_cells[plane_cells['cycle_model'] >= 100]

# plot the cell layer
for i, plot_cells in enumerate((alive_cells, dead_cells)):
    ax.scatter(plot_cells['position_x'].values, 
            plot_cells['position_y'].values, 
            facecolor='none', 
            edgecolors=colors[i],
            alpha=0.6,
            s=sizes[i],
            label=labels[i])

# Now we need to add our color bar
cbar1 = fig.colorbar(cs, shrink=0.75)
cbar1.set_label('mmHg')

# Let's put the time in to make these look nice
ax.set_aspect('equal')
ax.set_xlabel('x (micron)')
ax.set_ylabel('y (micron)')
ax.set_title('oxygen (mmHg) at t = {:.1f} {:s}, z = {:.2f} {:s}'.format(
                                        mcds.get_time(),
                                        mcds.data['metadata']['time_units'],
                                        z_val,
                                        mcds.data['metadata']['spatial_units'])
ax.legend(loc='upper right')

plt.show()

make

<camera>
	<distance_from_origin units="micron">1500</distance_from_origin>
	<xy_angle>3.92699081699</xy_angle> <!-- 5*pi/4 -->
	<yz_angle>1.0471975512</yz_angle> <!-- pi/3 -->
</camera>

<options>
	<use_standard_colors>true</use_standard_colors>
	<nuclear_offset units="micron">0.1</nuclear_offset>
	<cell_bound units="micron">750</cell_bound>
	<threads>8</threads>
</options>

<save> <!-- done -->
	<folder>output</folder> <!-- use . for root -->
	<filebase>output</filebase>
	<time_index>3696</time_index>
</save>

<clipping_planes> <!-- done --> 
	<clipping_plane>0,-1,0,0</clipping_plane>
	<clipping_plane>-1,0,0,0</clipping_plane>
	<clipping_plane>0,0,1,0</clipping_plane>
</clipping_planes>

<cell_colors type="0">
	<live>
		<cytoplasm>.25,1,.25</cytoplasm> <!-- red,green,blue --> 
		<nuclear>0.03,0.125</nuclear>
		<finish>0.05,1,0.1</finish> <!-- ambient,diffuse,specular -->
	</live>
	<apoptotic>
		<cytoplasm>1,0,0</cytoplasm> <!-- red,green,blue --> 
		<nuclear>0.125,0,0</nuclear>
		<finish>0.05,1,0.1</finish> <!-- ambient,diffuse,specular -->
	</apoptotic>
	<necrotic>
		<cytoplasm>1,0.5412,0.1490</cytoplasm> <!-- red,green,blue --> 
		<nuclear>0.125,0.06765,0.018625</nuclear>
		<finish>0.01,0.5,0.1</finish> <!-- ambient,diffuse,specular -->
	</necrotic>
</cell_colors>

physicell$ ./povwriter

physicell$ ./povwriter

povwriter version 1.0.0
================================================================================

Copyright (c) Paul Macklin 2019, on behalf of the PhysiCell project
OSI License: BSD-3-Clause (see LICENSE.txt)

Usage:
================================================================================
povwriter : run povwriter with config file ./config/settings.xml

povwriter FILENAME.xml : run povwriter with config file FILENAME.xml

povwriter x:y:z : run povwriter on data in FOLDER with indices from x
to y in incremenets of z

Example: ./povwriter 0:2:10 processes files:
./FOLDER/FILEBASE00000000_physicell_cells.mat
./FOLDER/FILEBASE00000002_physicell_cells.mat
...
./FOLDER/FILEBASE00000010_physicell_cells.mat
(See the config file to set FOLDER and FILEBASE)

povwriter x1,...,xn : run povwriter on data in FOLDER with indices x1,...,xn

Example: ./povwriter 1,3,17 processes files:
./FOLDER/FILEBASE00000001_physicell_cells.mat
./FOLDER/FILEBASE00000003_physicell_cells.mat
./FOLDER/FILEBASE00000017_physicell_cells.mat
(Note that there are no spaces.)
(See the config file to set FOLDER and FILEBASE)

Code updates at https://github.com/PhysiCell-Tools/PhysiCell-povwriter

Tutorial & documentation at http://MathCancer.org/blog/povwriter
================================================================================

Using config file ./config/povwriter-settings.xml ...
Using standard coloring function ...
Found 3 clipping planes ...
Found 2 cell color definitions ...
Processing file ./output/output00003696_cells_physicell.mat...
Matrix size: 32 x 66978
Creating file pov00003696.pov for output ...
Writing 66978 cells ...
done!

Done processing all 1 files!

physicell$ cd output
physicell$ unzip more_samples.zip
Archive: more_samples.zip
inflating: output00000000_cells_physicell.mat
inflating: output00000001_cells_physicell.mat
inflating: output00000250_cells_physicell.mat
inflating: output00000300_cells_physicell.mat
inflating: output00000500_cells_physicell.mat
inflating: output00000750_cells_physicell.mat
inflating: output00001000_cells_physicell.mat
inflating: output00001250_cells_physicell.mat
inflating: output00001500_cells_physicell.mat
inflating: output00001750_cells_physicell.mat
inflating: output00002000_cells_physicell.mat
inflating: output00002250_cells_physicell.mat
inflating: output00002500_cells_physicell.mat
inflating: output00002750_cells_physicell.mat
inflating: output00003000_cells_physicell.mat
inflating: output00003250_cells_physicell.mat
inflating: output00003500_cells_physicell.mat
inflating: output00003696_cells_physicell.mat

physicell$ ls

citation and license.txt
more_samples.zip
output00000000_cells_physicell.mat
output00000001_cells_physicell.mat
output00000250_cells_physicell.mat
output00000300_cells_physicell.mat
output00000500_cells_physicell.mat
output00000750_cells_physicell.mat
output00001000_cells_physicell.mat
output00001250_cells_physicell.mat
output00001500_cells_physicell.mat
output00001750_cells_physicell.mat
output00002000_cells_physicell.mat
output00002250_cells_physicell.mat
output00002500_cells_physicell.mat
output00002750_cells_physicell.mat
output00003000_cells_physicell.mat
output00003250_cells_physicell.mat
output00003500_cells_physicell.mat
output00003696.xml
output00003696_cells_physicell.mat

physicell$ ./povwriter 0:250:3500

povwriter version 1.0.0
================================================================================

Copyright (c) Paul Macklin 2019, on behalf of the PhysiCell project
OSI License: BSD-3-Clause (see LICENSE.txt)

Usage:
================================================================================
povwriter : run povwriter with config file ./config/settings.xml

povwriter FILENAME.xml : run povwriter with config file FILENAME.xml

povwriter x:y:z : run povwriter on data in FOLDER with indices from x
to y in incremenets of z

Example: ./povwriter 0:2:10 processes files:
./FOLDER/FILEBASE00000000_physicell_cells.mat
./FOLDER/FILEBASE00000002_physicell_cells.mat
...
./FOLDER/FILEBASE00000010_physicell_cells.mat
(See the config file to set FOLDER and FILEBASE)

povwriter x1,...,xn : run povwriter on data in FOLDER with indices x1,...,xn

Example: ./povwriter 1,3,17 processes files:
./FOLDER/FILEBASE00000001_physicell_cells.mat
./FOLDER/FILEBASE00000003_physicell_cells.mat
./FOLDER/FILEBASE00000017_physicell_cells.mat
(Note that there are no spaces.)
(See the config file to set FOLDER and FILEBASE)

Code updates at https://github.com/PhysiCell-Tools/PhysiCell-povwriter

Tutorial & documentation at http://MathCancer.org/blog/povwriter
================================================================================

Using config file ./config/povwriter-settings.xml ...
Using standard coloring function ...
Found 3 clipping planes ...
Found 2 cell color definitions ...
Matrix size: 32 x 18317
Processing file ./output/output00000000_cells_physicell.mat...
Creating file pov00000000.pov for output ...
Writing 18317 cells ...
Processing file ./output/output00002000_cells_physicell.mat...
Matrix size: 32 x 33551
Creating file pov00002000.pov for output ...
Writing 33551 cells ...
Processing file ./output/output00002500_cells_physicell.mat...
Matrix size: 32 x 43440
Creating file pov00002500.pov for output ...
Writing 43440 cells ...
Processing file ./output/output00001500_cells_physicell.mat...
Matrix size: 32 x 40267
Creating file pov00001500.pov for output ...
Writing 40267 cells ...
Processing file ./output/output00003000_cells_physicell.mat...
Matrix size: 32 x 56659
Creating file pov00003000.pov for output ...
Writing 56659 cells ...
Processing file ./output/output00001000_cells_physicell.mat...
Matrix size: 32 x 74057
Creating file pov00001000.pov for output ...
Writing 74057 cells ...
Processing file ./output/output00003500_cells_physicell.mat...
Matrix size: 32 x 66791
Creating file pov00003500.pov for output ...
Writing 66791 cells ...
Processing file ./output/output00000500_cells_physicell.mat...
Matrix size: 32 x 114316
Creating file pov00000500.pov for output ...
Writing 114316 cells ...
done!

Processing file ./output/output00000250_cells_physicell.mat...
Matrix size: 32 x 75352
Creating file pov00000250.pov for output ...
Writing 75352 cells ...
done!

Processing file ./output/output00002250_cells_physicell.mat...
Matrix size: 32 x 37959
Creating file pov00002250.pov for output ...
Writing 37959 cells ...
done!

Processing file ./output/output00001750_cells_physicell.mat...
Matrix size: 32 x 32358
Creating file pov00001750.pov for output ...
Writing 32358 cells ...
done!

Processing file ./output/output00002750_cells_physicell.mat...
Matrix size: 32 x 49658
Creating file pov00002750.pov for output ...
Writing 49658 cells ...
done!

Processing file ./output/output00003250_cells_physicell.mat...
Matrix size: 32 x 63546
Creating file pov00003250.pov for output ...
Writing 63546 cells ...
done!

done!

done!

done!

Processing file ./output/output00001250_cells_physicell.mat...
Matrix size: 32 x 54771
Creating file pov00001250.pov for output ...
Writing 54771 cells ...
done!

done!

done!

done!

Processing file ./output/output00000750_cells_physicell.mat...
Matrix size: 32 x 97642
Creating file pov00000750.pov for output ...
Writing 97642 cells ...
done!

done!

Done processing all 15 files!

physicell$ ./povwriter 250,1000,2250

povwriter version 1.0.0
================================================================================

Copyright (c) Paul Macklin 2019, on behalf of the PhysiCell project
OSI License: BSD-3-Clause (see LICENSE.txt)

Usage:
================================================================================
povwriter : run povwriter with config file ./config/settings.xml

povwriter FILENAME.xml : run povwriter with config file FILENAME.xml

povwriter x:y:z : run povwriter on data in FOLDER with indices from x
to y in incremenets of z

Example: ./povwriter 0:2:10 processes files:
./FOLDER/FILEBASE00000000_physicell_cells.mat
./FOLDER/FILEBASE00000002_physicell_cells.mat
...
./FOLDER/FILEBASE00000010_physicell_cells.mat
(See the config file to set FOLDER and FILEBASE)

povwriter x1,...,xn : run povwriter on data in FOLDER with indices x1,...,xn

Example: ./povwriter 1,3,17 processes files:
./FOLDER/FILEBASE00000001_physicell_cells.mat
./FOLDER/FILEBASE00000003_physicell_cells.mat
./FOLDER/FILEBASE00000017_physicell_cells.mat
(Note that there are no spaces.)
(See the config file to set FOLDER and FILEBASE)

Code updates at https://github.com/PhysiCell-Tools/PhysiCell-povwriter

Tutorial & documentation at http://MathCancer.org/blog/povwriter
================================================================================

Using config file ./config/povwriter-settings.xml ...
Using standard coloring function ...
Found 3 clipping planes ...
Found 2 cell color definitions ...
Processing file ./output/output00002250_cells_physicell.mat...
Matrix size: 32 x 37959
Creating file pov00002250.pov for output ...
Writing 37959 cells ...
Processing file ./output/output00001000_cells_physicell.mat...
Matrix size: 32 x 74057
Creating file pov00001000.pov for output ...
Processing file ./output/output00000250_cells_physicell.mat...
Matrix size: 32 x 75352
Writing 74057 cells ...
Creating file pov00000250.pov for output ...
Writing 75352 cells ...
done!

done!

done!

Done processing all 3 files!

physicell$ magick mogrify -format jpg -resize 60% pov*.png

physicell$ magick convert -delay 20 *.jpg out.gif

make template2D

	<user_parameters>
		<random_seed type="int" units="dimensionless">0</random_seed> 
		<!-- example parameters from the template --> 
		
		<!-- motile cell type parameters --> 
		<motile_cell_persistence_time type="double" units="min">15</motile_cell_persistence_time>
		<motile_cell_migration_speed type="double" units="micron/min">0.5</motile_cell_migration_speed>
		<motile_cell_relative_adhesion type="double" units="dimensionless">0.05</motile_cell_relative_adhesion>
		<motile_cell_apoptosis_rate type="double" units="1/min">0.0</motile_cell_apoptosis_rate> 
		<motile_cell_relative_cycle_entry_rate type="double" units="dimensionless">0.1</motile_cell_relative_cycle_entry_rate>
	</user_parameters>

	<user_parameters>
		<random_seed type="int" units="dimensionless">0</random_seed> 
		<!-- example parameters from the template --> 
		
		<!-- motile cell type parameters --> 
		<motile_cell_persistence_time type="double" units="min">15</motile_cell_persistence_time>
		<motile_cell_migration_speed type="double" units="micron/min">0.5</motile_cell_migration_speed>
		<motile_cell_relative_adhesion type="double" units="dimensionless">0.05</motile_cell_relative_adhesion>
		<motile_cell_apoptosis_rate type="double" units="1/min">0.0</motile_cell_apoptosis_rate> 
		<motile_cell_relative_cycle_entry_rate type="double" units="dimensionless">0.1</motile_cell_relative_cycle_entry_rate>
		
		<!-- for the tutorial --> 
		<motile_color type="string" units="dimensionless">darkorange</motile_color>
		
		<base_cycle_entry_rate type="double" units="1/min">0.01</base_cycle_entry_rate> 
		<base_apoptosis_rate type="double" units="1/min">1e-7</base_apoptosis_rate>
		<base_cell_adhesion_distance type="double" units="dimensionless">2.5</base_cell_adhesion_distance> 
		
		<include_motile_cell type="bool" units="dimensionless">true</include_motile_cell>
	</user_parameters>

make 
./project2D

shell$  ./project2D
Using config file ./config/PhysiCell_settings.xml ...
User parameters in XML config file:
Bool parameters::
include_motile_cell: 1 [dimensionless]

Int parameters::
random_seed: 0 [dimensionless]

Double parameters::
motile_cell_persistence_time: 15 [min]
motile_cell_migration_speed: 0.5 [micron/min]
motile_cell_relative_adhesion: 0.05 [dimensionless]
motile_cell_apoptosis_rate: 0 [1/min]
motile_cell_relative_cycle_entry_rate: 0.1 [dimensionless]
base_cycle_entry_rate: 0.01 [1/min]
base_apoptosis_rate: 1e-007 [1/min]
base_cell_adhesion_distance: 2.5 [dimensionless]

String parameters::
motile_color: darkorange [dimensionless]

/* this directly accesses the value of the parameter */ 
double temp = parameters.doubles( "base_cell_adhesion_distance" ); 
std::cout << temp << std::endl; 

/* this streams a formatted output including the parameter name and units */ 
std::cout << parameters.doubles[ "base_cell_adhesion_distance" ] << std::endl; 

std::cout << parameters.doubles["base_cell_adhesion_distance"].name << " " 
     << parameters.doubles["base_cell_adhesion_distance"].value << " " 
     << parameters.doubles["base_cell_adhesion_distance"].units << std::endl; 

/* this directly accesses the value of the parameter */ 
int my_index = parameters.doubles.find_index( "base_cell_adhesion_distance" ); 
double temp = parameters.doubles( my_index ); 
std::cout << temp << std::endl; 

/* this streams a formatted output including the parameter name and units */ 
std::cout << parameters.doubles[ my_index ] << std::endl; 

std::cout << parameters.doubles[ my_index ].name << " " 
     << parameters.doubles[ my_index ].value << " " 
     << parameters.doubles[ my_index ].units << std::endl; 

if( parameters.bools("include_motile_cell") == true )
{ std::cout << "I shall include a motile cell." << std::endl; }

int rand_ind = parameters.ints.find_index( "random_seed" ); 
std::cout << parameters.ints[rand_ind].name << " is at index " << rand_ind << std::endl; 

std::cout << "We'll use this nice color: " << parameters.strings( "motile_color" ); 

	// add custom data here, if any 
	
	/* for the tutorial */ 
	cell_defaults.phenotype.cycle.data.transition_rate(G0G1_index,S_index) = 
		parameters.doubles("base_cycle_entry_rate"); 
	cell_defaults.phenotype.death.rates[apoptosis_model_index] = 
		parameters.doubles("base_apoptosis_rate"); 
		
	cell_defaults.phenotype.mechanics.set_relative_maximum_adhesion_distance( 
		parameters.doubles("base_cell_adhesion_distance") ); 

     // now create a motile cell 
     /*  remove this conditional for the normal project */ 
     if( parameters.bools("include_motile_cell") == true )
     {
           pC = create_cell( motile_cell ); 
           pC->assign_position( 15.0, -18.0, 0.0 );
     }

	// if the cell is motile and not dead, paint it black 
	
	static std::string motile_color = parameters.strings( "motile_color" );  // tutorial 
		
	if( pCell->phenotype.death.dead == false && pCell->type == 1 )
	{
		 output[0] = motile_color; 
		 output[2] = motile_color; 
	}

make 
./project2D

./project2D

!unzip 3D_PhysiCell_matlab_sample.zip

MCDS = read_MultiCellDS_xml( 'output00003696.xml'); 

k = find( MCDS.mesh.Z_coordinates == 0 ); 

contourf( MCDS.mesh.X(:,:,k), MCDS.mesh.Y(:,:,k), ...
     MCDS.continuum_variables(1).data(:,:,k) , 20 ) ;

axis image
colorbar 
xlabel( sprintf( 'x (%s)' , MCDS.metadata.spatial_units) ); 
ylabel( sprintf( 'y (%s)' , MCDS.metadata.spatial_units) ); 

title( sprintf('%s (%s) at t = %3.2f %s, z = %3.2f %s', MCDS.continuum_variables(1).name , ...
     MCDS.continuum_variables(1).units , ...
     MCDS.metadata.current_time , ...
     MCDS.metadata.time_units, ... 
     MCDS.mesh.Z_coordinates(k), ...
     MCDS.metadata.spatial_units ) ); 

print( '-dpng' , 'output_o2.png' );

plot3( MCDS.discrete_cells.state.position(:,1) , MCDS.discrete_cells.state.position(:,2), ...
	MCDS.discrete_cells.state.position(:,3) , 'bo' ); 

axis( 1000*[-1 1 -1 1 -1 1] )
axis square 

% make it easier to work with the cell positions; 
P = MCDS.discrete_cells.state.position;

% find type 1 cells
ind1 = find( MCDS.discrete_cells.metadata.type == 1 ); 
% better still, eliminate those out of the simulation domain 
ind1 = find( MCDS.discrete_cells.metadata.type == 1 & ...
    abs(P(:,1))' < 1000 & abs(P(:,2))' < 1000 & abs(P(:,3))' < 1000 );

% find type 0 cells
ind0 = find( MCDS.discrete_cells.metadata.type == 0 & ...
    abs(P(:,1))' < 1000 & abs(P(:,2))' < 1000 & abs(P(:,3))' < 1000 ); 

%now plot them
P = MCDS.discrete_cells.state.position;
plot3( P(ind0,1), P(ind0,2), P(ind0,3), 'bo' )
hold on
plot3( P(ind1,1), P(ind1,2), P(ind1,3), 'ro' )
hold off
axis( 1000*[-1 1 -1 1 -1 1] )
axis square

clf
simple_plot( MCDS,  MCDS, MCDS.discrete_cells.dead_cells , 'r' )

clf
simple_cutaway_plot( MCDS, MCDS, MCDS.discrete_cells.dead_cells , 'r' )

clf
composite_cutaway_plot( MCDS )

constants = set_MCDS_constants

% find the type 0 necrotic cells
ind0_necrotic = find( MCDS.discrete_cells.metadata.type == 0 & ...
    (MCDS.discrete_cells.phenotype.cycle.current_phase == constants.necrotic_swelling | ...
    MCDS.discrete_cells.phenotype.cycle.current_phase == constants.necrotic_lysed | ...
    MCDS.discrete_cells.phenotype.cycle.current_phase == constants.necrotic) ); 

% find the live type 0 cells
ind0_live = find( MCDS.discrete_cells.metadata.type == 0 & ...
    (MCDS.discrete_cells.phenotype.cycle.current_phase ~= constants.necrotic_swelling & ...
    MCDS.discrete_cells.phenotype.cycle.current_phase ~= constants.necrotic_lysed & ...
    MCDS.discrete_cells.phenotype.cycle.current_phase ~= constants.necrotic & ...
    MCDS.discrete_cells.phenotype.cycle.current_phase ~= constants.apoptotic) ); 

clf
% plot live tumor cells red, in cutaway view
simple_cutaway_plot( MCDS, ind0_live , 'r' ); 
hold on 
% plot dead tumor cells black, in cutaway view 
simple_cutaway_plot( MCDS, ind0_necrotic , 'k' ) 
% plot all immune cells, but without cutaway (to show how they infiltrate)
simple_plot( MCDS, ind1, 'g' ) 
hold off

parameters.dt = 0.1; % 6 min = 0.1 hours 
parameters.time_units = 'hour'; 
parameters.t_max = 3*24; % 3 days 

parameters.K1.duration =  13;
parameters.K1.death_rate = 1.05e-3; 
parameters.K1.initial = 0;  

parameters.K2.duration = 2.5; 
parameters.K2.death_rate = 1.05e-3; 
parameters.K2.initial = 0;  

parameters.Q.duration = 74.35 ; 
parameters.Q.death_rate = 1.05e-3; 
parameters.Q.initial = 1000; 

parameters.A.duration = 8.6; 
parameters.A.initial = 0; 

function solution = Ki67_exact( parameters )

% allocate memory for the main outputs

solution.T = 0:parameters.dt:parameters.t_max; 
solution.K1 = zeros( 1 , length(solution.T)); 
solution.K2 = zeros( 1 , length(solution.T)); 
solution.K = zeros( 1 , length(solution.T)); 
solution.Q = zeros( 1 , length(solution.T)); 
solution.A = zeros( 1 , length(solution.T)); 
solution.Live = zeros( 1 , length(solution.T)); 
solution.Total = zeros( 1 , length(solution.T)); 

% allocate memory for cell fractions

solution.AI = zeros(1,length(solution.T)); 
solution.KI1 = zeros(1,length(solution.T)); 
solution.KI2 = zeros(1,length(solution.T)); 
solution.KI = zeros(1,length(solution.T)); 

% get the main parameters 

T1 = parameters.K1.duration; 
r1A = parameters.K1.death_rate; 

T2 = parameters.K2.duration; 
r2A = parameters.K2.death_rate; 

TQ = parameters.Q.duration; 
rQA = parameters.Q.death_rate; 

TA = parameters.A.duration; 

% write out the mathematical model: 
% d[Populations]/dt = Operator*[Populations]

Operator = [ -(1/T1 +r1A) , 0 , 1/TQ , 0; ...
    2/T1 , -(1/T2 + r2A) ,0 , 0; ...
    0 , 1/T2 , -(1/TQ + rQA) , 0; ... 
    r1A , r2A, rQA , -1/TA ]; 

% eigenvectors and eigenvalues

[V,D] = eig(Operator);
eigenvalues = diag(D); 

% save the eigenvectors and eigenvalues in case you want them. 

solution.V = V; 
solution.D = D; 
solution.eigenvalues = eigenvalues; 

% initial condition 

VecNow = [ parameters.K1.initial ; parameters.K2.initial ; ... 
    parameters.Q.initial ; parameters.A.initial ] ; 
solution.K1(1) = VecNow(1); 
solution.K2(1) = VecNow(2); 
solution.Q(1) = VecNow(3); 
solution.A(1) = VecNow(4); 
solution.K(1) = solution.K1(1) + solution.K2(1); 
solution.Live(1) = sum( VecNow(1:3) ); 
solution.Total(1) = sum( VecNow(1:4) ); 

solution.AI(1) = solution.A(1) / solution.Total(1); 
solution.KI1(1) = solution.K1(1) / solution.Total(1); 
solution.KI2(1) = solution.K2(1) / solution.Total(1); 
solution.KI(1) = solution.KI1(1) + solution.KI2(1); 

% now, get the coefficients to write the analytic solution
% [Populations] = c1*V(:,1)*exp( d(1,1)*t) + c2*V(:,2)*exp( d(2,2)*t ) +
%                 c3*V(:,3)*exp( d(3,3)*t) + c4*V(:,4)*exp( d(4,4)*t ); 

coeff = linsolve( V , VecNow ); 

% find the (hopefully one) positive eigenvalue. 
% eigensolutions with negative eigenvalues decay, 
% leaving this as the long-time behavior. 

eigenvalues = diag(D); 
n = find( real( eigenvalues ) > 0 ) 
solution.long_time.KI1 = V(1,n) / sum( V(:,n) ); 
solution.long_time.KI2 = V(2,n) / sum( V(:,n) ); 
solution.long_time.QI = V(3,n) / sum( V(:,n) ); 
solution.long_time.AI = V(4,n) / sum( V(:,n) ) ;
solution.long_time.KI = solution.long_time.KI1 + solution.long_time.KI2; 

% now, write out the solution at all the times 
for i=2:length( solution.T )
    % compact way to write the solution 
    VecExact = real( V*( coeff .* exp( eigenvalues*solution.T(i) ) ) ); 

    solution.K1(i) = VecExact(1); 
    solution.K2(i) = VecExact(2); 
    solution.Q(i) = VecExact(3); 
    solution.A(i) = VecExact(4); 
    solution.K(i) = solution.K1(i) + solution.K2(i); 
    solution.Live(i) = sum( VecExact(1:3) ); 
    solution.Total(i) = sum( VecExact(1:4) ); 
   
    solution.AI(i) = solution.A(i) / solution.Total(i); 
    solution.KI1(i) = solution.K1(i) / solution.Total(i); 
    solution.KI2(i) = solution.K2(i) / solution.Total(i); 
    solution.KI(i) = solution.KI1(i) + solution.KI2(i);    
end

return; 

make 
2Dtumor

Starting program … 
 
Microenvironment summary: Tumor microenvironment: 
 
Mesh information: 
type: uniform Cartesian
Domain: [0,20] mm x [0,20] mm x [-0.025,0.025] mm
	resolution: dx = 0.05 mm
	voxels: 160000
	voxel faces: 0
	volume: 20 cubic mm
Densities: (3 total)
	live cells:
		units: cells
		diffusion coefficient: 0.00570386 mm^2 / hr
		decay rate: 0 hr^-1
		diffusion length scale: 75523.9 mm

	blood vessels:
		units: vessels/mm^2
		diffusion coefficient: 0 mm^2 / hr
		decay rate: 0 hr^-1
		diffusion length scale: 0 mm

	oxygen:
		units: cells
		diffusion coefficient: 6 mm^2 / hr
		decay rate: 2.2038 hr^-1
		diffusion length scale: 1.65002 mm
 
simulation time: 0 hr (240 hr max)
 
Using method diffusion_decay_solver__constant_coefficients_LOD_2D (2D LOD with Thomas Algorithm) … 
 
simulation time: 12 hr (240 hr max)
simulation time: 24 hr (240 hr max)
simulation time: 36 hr (240 hr max)
simulation time: 48 hr (240 hr max)
simulation time: 60 hr (240 hr max)
simulation time: 72 hr (240 hr max)
simulation time: 84 hr (240 hr max)
simulation time: 96 hr (240 hr max)
simulation time: 108 hr (240 hr max)
simulation time: 120 hr (240 hr max)
simulation time: 132 hr (240 hr max)
simulation time: 144 hr (240 hr max)
simulation time: 156 hr (240 hr max)
simulation time: 168 hr (240 hr max)
simulation time: 180 hr (240 hr max)
simulation time: 192 hr (240 hr max)
simulation time: 204 hr (240 hr max)
simulation time: 216 hr (240 hr max)
simulation time: 228 hr (240 hr max)
simulation time: 240 hr (240 hr max)
Done!

matlab

!ls *.mat
M = read_microenvironment( 'output_240.000000.mat' );
plot_microenvironment( M );

labels{1} = 'tumor cells'; 
labels{2} = 'blood vessel density'; 
labels{3} = 'growth substrate'; 
plot_microenvironment( M ,labels ); 

labels{1} = 'tumor cells'; 
labels{2} = 'blood vessel density'; 
labels{3} = 'growth substrate'; 
for i=0:20
	t = i*12;
	input_file = sprintf( 'output_%3.6f.mat', t ); 
	output_file = sprintf( 'output_%3.6f.png', t ); 
	M = read_microenvironment( input_file ); 
	plot_microenvironment( M , labels ); 
	print( gcf , '-dpng' , output_file );
end