Setting up the PhysiCell microenvironment with XML

As of release 1.6.0, users can define all the chemical substrates in the microenvironment with an XML configuration file. (These are stored by default in ./config/. The default parameter file is ./config/PhysiCell_settings.xml.) This should make it much easier to set up the microenvironment (previously required a lot of manual C++), as well as make it easier to change parameters and initial conditions.

In release 1.7.0, users gained finer grained control on Dirichlet conditions: individual Dirichlet conditions can be enabled or disabled for each individual diffusing substrate on each individual boundary. See details below.

This tutorial will show you the key techniques to use these features. (See the User_Guide for full documentation.) First, let’s create a barebones 2D project by populating the 2D template project. In a terminal shell in your root PhysiCell directory, do this:

make template2D

We will use this 2D project template for the remainder of the tutorial. We assume you already have a working copy of PhysiCell installed, version 1.6.0 or later. (If not, visit the PhysiCell tutorials to find installation instructions for your operating system.) You will need version 1.7.0 or later to control Dirichlet conditions on individual boundaries.

You can download the latest version of PhysiCell at:

Microenvironment setup in the XML configuration file

Next, let’s look at the parameter file. In your text editor of choice, open up ./config/PhysiCell_settings.xml, and browse down to <microenvironment_setup>:

<microenvironment_setup>
	<variable name="oxygen" units="mmHg" ID="0">
		<physical_parameter_set>
			<diffusion_coefficient units="micron^2/min">100000.0</diffusion_coefficient>
			<decay_rate units="1/min">0.1</decay_rate>  
		</physical_parameter_set>
		<initial_condition units="mmHg">38.0</initial_condition>
		<Dirichlet_boundary_condition units="mmHg" enabled="true">38.0</Dirichlet_boundary_condition>
	</variable>
	
	<options>
		<calculate_gradients>false</calculate_gradients>
		<track_internalized_substrates_in_each_agent>false</track_internalized_substrates_in_each_agent>
		<!-- not yet supported --> 
		<initial_condition type="matlab" enabled="false">
			<filename>./config/initial.mat</filename>
		</initial_condition>
		<!-- not yet supported --> 
		<dirichlet_nodes type="matlab" enabled="false">
			<filename>./config/dirichlet.mat</filename>
		</dirichlet_nodes>
	</options>
</microenvironment_setup>

Notice a few trends:

  • The <variable> XML element (tag) is used to define a chemical substrate in the microenvironment. The attributes say that it is named oxygen, and the units of measurement are mmHg. Notice also that the ID is 0: this unique integer identifier helps for finding and accessing the substrate within your PhysiCell project. Make sure your first substrate ID is 0, since C++ starts indexing at 0.
  • Within the <variable> block, we set the properties of this substrate:
    • <diffusion_coefficient> sets the (uniform) diffusion constant for the substrate.
    • <decay_rate> is the substrate’s background decay rate.
    • <initial_condition> is the value the substrate will be (uniformly) initialized to throughout the domain.
    • <Dirichlet_boundary_condition> is the value the substrate will be set to along the outer computational boundary throughout the simulation, if you set enabled=true. If enabled=false, then PhysiCell (via BioFVM) will use Neumann (zero flux) conditions for that substrate.
  • The <options> element helps configure other simulation behaviors:
    • Use <calculate_gradients> to control whether PhysiCell computes all chemical gradients at each time step. Set this to true to enable accurate gradients (e.g., for chemotaxis).
    • Use <track_internalized_substrates_in_each_agent> to enable or disable the PhysiCell feature of actively tracking the total amount of internalized substrates in each individual agent. Set this to true to enable the feature.
    • <initial_condition> is reserved for a future release where we can specify non-uniform initial conditions as an external file (e.g., a CSV or Matlab file). This is not yet supported.
    • <dirichlet_nodes> is reserved for a future release where we can specify Dirchlet nodes at any location in the simulation domain with an external file. This will be useful for irregular domains, but it is not yet implemented.

Note that PhysiCell does not convert units. The units attributes are helpful for clarity between users and developers, to ensure that you have worked in consistent length and time units. By default, PhysiCell uses minutes for all time units, and microns for all spatial units.

Changing an existing substrate

Let’s modify the oxygen variable to do the following:

  • Change the diffusion coefficient to 120000 \(\mu\mathrm{m}^2 / \mathrm{min}\)
  • Change the initial condition to 40 mmHg
  • Change the oxygen Dirichlet boundary condition to 42.7 mmHg
  • Enable gradient calculations

If you modify the appropriate fields in the <microenvironment_setup> block, it should look like this:

<microenvironment_setup>
	<variable name="oxygen" units="mmHg" ID="0">
		<physical_parameter_set>
			<diffusion_coefficient units="micron^2/min">120000.0</diffusion_coefficient>
			<decay_rate units="1/min">0.1</decay_rate>  
		</physical_parameter_set>
		<initial_condition units="mmHg">40.0</initial_condition>
		<Dirichlet_boundary_condition units="mmHg" enabled="true">42.7</Dirichlet_boundary_condition>
	</variable>
	
	<options>
		<calculate_gradients>true</calculate_gradients>
		<track_internalized_substrates_in_each_agent>false</track_internalized_substrates_in_each_agent>
		<!-- not yet supported --> 
		<initial_condition type="matlab" enabled="false">
			<filename>./config/initial.mat</filename>
		</initial_condition>
		<!-- not yet supported --> 
		<dirichlet_nodes type="matlab" enabled="false">
			<filename>./config/dirichlet.mat</filename>
		</dirichlet_nodes>
	</options>
</microenvironment_setup>

Adding a new diffusing substrate

Let’s add a new dimensionless substrate glucose with the following:

  • Diffusion coefficient is 18000 \(\mu\mathrm{m}^2 / \mathrm{min}\)
  • No decay rate
  • The initial condition is 1 (dimensionless)
  • Neumann (no flux) boundary conditions

To add the new variable, I suggest copying an existing variable (in this case, oxygen) and modifying to:

  • change the name and units throughout
  • increase the ID by one
  • write in the appropriate initial and boundary conditions

If you modify the appropriate fields in the <microenvironment_setup> block, it should look like this:

<microenvironment_setup>
	<variable name="oxygen" units="mmHg" ID="0">
		<physical_parameter_set>
			<diffusion_coefficient units="micron^2/min">120000.0</diffusion_coefficient>
			<decay_rate units="1/min">0.1</decay_rate>  
		</physical_parameter_set>
		<initial_condition units="mmHg">40.0</initial_condition>
		<Dirichlet_boundary_condition units="mmHg" enabled="true">42.7</Dirichlet_boundary_condition>
	</variable>
	
	<variable name="glucose" units="dimensionless" ID="1">
		<physical_parameter_set>
			<diffusion_coefficient units="micron^2/min">18000.0</diffusion_coefficient>
			<decay_rate units="1/min">0.0</decay_rate>  
		</physical_parameter_set>
		<initial_condition units="dimensionless">1</initial_condition>
		<Dirichlet_boundary_condition units="dimensionless" enabled="false">0</Dirichlet_boundary_condition>
	</variable>

	<options>
		<calculate_gradients>true</calculate_gradients>
		<track_internalized_substrates_in_each_agent>false</track_internalized_substrates_in_each_agent>
		<!-- not yet supported --> 
		<initial_condition type="matlab" enabled="false">
			<filename>./config/initial.mat</filename>
		</initial_condition>
		<!-- not yet supported --> 
		<dirichlet_nodes type="matlab" enabled="false">
			<filename>./config/dirichlet.mat</filename>
		</dirichlet_nodes>
	</options>
</microenvironment_setup>

Controlling Dirichlet conditions on individual boundaries

In Version 1.7.0, we introduced the ability to control the Dirichlet conditions for each individual boundary for each substrate. The examples above apply (enable) or disable the same condition on each boundary with the same boundary value.

Suppose that we want to set glucose so that the Dirichlet condition is enabled on the bottom z boundary (with value 1) and the left and right x boundaries (with value 0.5) and disabled on all other boundaries. We modify the variable block by adding the optional Dirichlet_options block:

<variable name="glucose" units="dimensionless" ID="1">
	<physical_parameter_set>
		<diffusion_coefficient units="micron^2/min">18000.0</diffusion_coefficient>
		<decay_rate units="1/min">0.0</decay_rate>  
	</physical_parameter_set>
	<initial_condition units="dimensionless">1</initial_condition>
	<Dirichlet_boundary_condition units="dimensionless" enabled="true">0</Dirichlet_boundary_condition>
	<Dirichlet_options>
		<boundary_value ID="xmin" enabled="true">0.5</boundary_value>
		<boundary_value ID="xmax" enabled="true">0.5</boundary_value>
		<boundary_value ID="ymin" enabled="false">0.5</boundary_value>
		<boundary_value ID="ymin" enabled="false">0.5</boundary_value>
		<boundary_value ID="zmin" enabled="true">1.0</boundary_value>
		<boundary_value ID="zmax" enabled="false">0.5</boundary_value>
	</Dirichlet_options>
</variable>

Notice a few things:

  1. The Dirichlet_boundary_condition element has its enabled attribute set to true
  2. The Dirichlet condition is set under any individual boundary with a boundary_value element.
    • The ID attribute indicates which boundary is being specified.
    • The enabled attribute allows the individual boundary to be enabled (with value given by the element’s value) or disabled (applying a Neumann or no-flux condition for this substrate at this boundary).
    • Any individual boundary indicated by a boundary_value element supersedes the value given by Dirichlet_boundary_condition for this boundary.

Closing thoughts and future work

In the future, we plan to develop more of the options to allow users to set set the initial conditions externally and import them (via an external file), and to allow them to set up more complex domains by importing Dirichlet nodes.

More broadly, we are working to push more model specification from raw C++ to imported XML. It is our hope that this will vastly simplify model development, facilitate creation of graphical model editing tools, and ultimately broaden the class of developers who can use and contribute to PhysiCell. Thanks for giving it a try!

Share this:
Tags : , , ,

Return to News • Return to MathCancer