Running the PhysiCell sample projects
Introduction
In PhysiCell 1.2.1 and later, we include four sample projects on cancer heterogeneity, bioengineered multicellular systems, and cancer immunology. This post will walk you through the steps to build and run the examples.
If you are new to PhysiCell, you should first make sure you’re ready to run it. (Please note that this applies in particular for OSX users, as Xcode’s g++ is not compatible out-of-the-box.) Here are tutorials on getting ready to Run PhysiCell:
- Setting up a 64-bit gcc environment in Windows.
- Setting up gcc / OpenMP on OSX (MacPorts edition)
- Setting up gcc / OpenMP on OSX (Homebrew edition)
Note: This is the preferred method for Mac OSX. - Getting started with a PhysiCell Virtual Appliance (for virtual machines like VirtualBox)
Note: The “native” setups above are preferred, but the Virtual Appliance is a great “plan B” if you run into trouble
Please note that we expect to expand this tutorial.
Building, running, and viewing the sample projects
All of these projects will create data of the following forms:
- Scalable vector graphics (SVG) cross-section plots through z = 0.0 μm at each output time. Filenames will look like snapshot00000000.svg.
- Matlab (Level 4) .mat files to store raw BioFVM data. Filenames will look like output00000000_microenvironment0.mat (for the chemical substrates) and output00000000_cells.mat (for basic agent data).
- Matlab .mat files to store additional PhysiCell agent data. Filenames will look like output00000000_cells_physicell.mat.
- MultiCellDS .xml files that give further metadata and structure for the .mat files. Filenames will look like output00000000.xml.
You can read the combined data in the XML and MAT files with the read_MultiCellDS_xml function, stored in the matlab directory of every PhysiCell download. (Copy the read_MultiCellDS_xml.m and set_MultiCelLDS_constants.m files to the same directory as your data for the greatest simplicity.)
(If you are using Mac OSX and PhysiCell version > 1.2.1, remember to set the PHYSICELL_CPP environment variable to be an OpenMP-capable compiler – rf. Homebrew setup.)
Biorobots (2D)
Type the following from a terminal window in your root PhysiCell directory:
make biorobots-sample make ./biorobots make reset # optional -- gets a clean slate to try other samples
Because this is a 2-D example, the SVG snapshot files will provide the simplest method of visualizing these outputs. You can use utilities like ImageMagick to convert them into other formats for publications, such as PNG or EPS.
Anti-cancer biorobots (2D)
make cancer-biorobots-sample make ./cancer_biorobots make reset # optional -- gets a clean slate to try other samples
Cancer heterogeneity (2D)
make heterogeneity-sample make project ./heterogeneity make reset # optional -- gets a clean slate to try other samples
Cancer immunology (3D)
make cancer-immune-sample make ./cancer_immune_3D make reset # optional -- gets a clean slate to try other samples