## Common problems and solutions

Here, we document common problems and solutions in compiling and running PhysiCell projects.

### Compiling Errors

I get the error “clang: error: unsupported option ‘-fopenmp’” when I compile a PhysiCell Project

When compiling a PhysiCell project in OSX, you may see an error like this:

This shows that clang is being used as the compiler, instead of g++. To fix this error, edit your Makefile, and fix the CC line.

CC := g++-7 # use this if you installed g++ 7 by Homebrew

or
CC := g++-mp-7 # use this if you installed g++ 7 by MacPorts


If you have not installed g++ by MacPorts or Homebrew, please see the following tutorials:

When I compile, I get tons of weird “no such instruction” errors like
no such instruction: vmovsd (%rdx,%rax), #xmm0′” or
no such instruction: vfnmadd132sd (%rsi,%rax,8), $xmm5,%xmm0′ When you compile, you may see a huge list of arcane symbols, like this: The “no such instruction” means that the compiler is trying to send CPU instructions (like these vmovsd lines) that your system doesn’t understand. (It’s like trying SSE4 instructions on a Pentium 4.) The first solution to try is to use a safer architecture, using the ARCH definition. Open your Makefile, and search for the ARCH line. If it isn’t set to native, then try that. If it is already set to native, try a safer, older architecture like core2 by commenting out native (add a # symbol to any Makefile line to comment it out), and uncommenting the core2 line: # ARCH := native ARCH := core2  “I don’t understand the ‘m’ flag!” When you compile a project, you may see an error that looks like this: This seems to be due to incompatibilities between MacPort’s gcc chain and Homebrew (especially if you installed gcc5 in MacPorts). As we showed in this tutorial, you can open a terminal window and run a single command to fix it: echo export PATH=/usr/bin:$PATH >> ~/.profile


Note that you’ll need to restart your terminal to fully apply the fix.

### Errors Running PhysiCell

My project compiles fine, but when I run it, I get errors like “illegal instruction: 4“.

This means that PhysiCell has been compiled for the wrong architecture, and it is sending unsupported instructions to your CPU. See the “no such instruction” error above for a fix.

I fixed my Makefile, and things compiled fine, but I can’t compile a different project or the sample projects.

The Makefile rules for the sample projects (e.g., make biorobots-sample) overwrite the Makefile in the PhysiCell root directory, so you’ll need to re-modify the Makefile with the correct CC (and potentially ARCH) lines any time you run a template project or sample project make rule. This will be improved in future editions of PhysiCell. Sorry!!

It compiled fine, but the project crashes with “Segmentation fault: 11″, or the program just crashes with “killed.”

Everything compiles just fine and your program starts, but you may get a segmentation fault either early on, or later in your simulation. Like this:

[Screenshot soon! This error is rare.]

Or on Linux systems it might just crash with a simple “killed” message:

This error occurs if there is not enough (contiguous) memory to run a project. If you are running in a Virtual Machine, you can solve this by increasing the amount of memory. If you are running “natively” you may need to install more RAM or decrease the problem size (the size of the simulation domain or the number of cells). To date, we have only encountered this error on virtual machines with little memory. We recommend using 8192 MB (8 GB):

## A small computational thought experiment

In Macklin (2017), I briefly touched on a simple computational thought experiment that shows that for a group of homogeneous cells, you can observe substantial heterogeneity in cell behavior. This “thought experiment” is part of a broader preview and discussion of a fantastic paper by Linus Schumacher, Ruth Baker, and Philip Maini published in Cell Systems, where they showed that a migrating collective homogeneous cells can show heterogeneous behavior when quantitated with new migration metrics. I highly encourage you to check out their work!

In this blog post, we work through my simple thought experiment in a little more detail.

Note: If you want to reference this blog post, please cite the Cell Systems preview article:

P. Macklin, When seeing isn’t believing: How math can guide our interpretation of measurements and experiments. Cell Sys., 2017 (in press). DOI: 10.1016/j.cells.2017.08.005

### The thought experiment

Consider a simple (and widespread) model of a population of cycling cells: each virtual cell (with index i) has a single “oncogene” $$r_i$$ that sets the rate of progression through the cycle. Between now (t) and a small time from now ( $$t+\Delta t$$), the virtual cell has a probability $$r_i \Delta t$$ of dividing into two daughter cells. At the population scale, the overall population growth model that emerges from this simple single-cell model is:
$\frac{dN}{dt} = \langle r\rangle N,$
where $$\langle r \rangle$$ the mean division rate over the cell population, and is the number of cells. See the discussion in the supplementary information for Macklin et al. (2012).

Now, suppose (as our thought experiment) that we could track individual cells in the population and track how long it takes them to divide. (We’ll call this the division time.) What would the distribution of cell division times look like, and how would it vary with the distribution of the single-cell rates $$r_i$$?

### Mathematical method

In the Matlab script below, we implement this cell cycle model as just about every discrete model does. Here’s the pseudocode:

t = 0;
while( t < t_max )
for i=1:Cells.size()
u = random_number();
if( u < Cells[i].birth_rate * dt )
Cells[i].division_time = Cells[i].age;
Cells[i].divide();
end
end
t = t+dt;
end


That is, until we’ve reached the final simulation time, loop through all the cells and decide if they should divide: For each cell, choose a random number between 0 and 1, and if it’s smaller than the cell’s division probability ($$r_i \Delta t$$), then divide the cell and write down the division time.

As an important note, we have to track the same cells until they all divide, rather than merely record which cells have divided up to the end of the simulation. Otherwise, we end up with an observational bias that throws off our recording. See more below.

### The sample code

http://MathCancer.org/files/matlab/thought_experiment_matlab(Macklin_Cell_Systems_2017).zip

Extract all the files, and run “thought_experiment” in Matlab (or Octave, if you don’t have a Matlab license or prefer an open source platform) for the main result.

All these Matlab files are available as open source, under the GPL license (version 3 or later).

### Results and discussion

First, let’s see what happens if all the cells are identical, with $$r = 0.05 \textrm{ hr}^{-1}$$. We run the script, and track the time for each of 10,000 cells to divide. As expected by theory (Macklin et al., 2012) (but perhaps still a surprise if you haven’t looked), we get an exponential distribution of division times, with mean time $$1/\langle r \rangle$$:

So even in this simple model, a homogeneous population of cells can show heterogeneity in their behavior. Here’s the interesting thing: let’s now give each cell its own division parameter $$r_i$$ from a normal distribution with mean $$0.05 \textrm{ hr}^{-1}$$ and a relative standard deviation of 25%:

If we repeat the experiment, we get the same distribution of cell division times!

So in this case, based solely on observations of the phenotypic heterogeneity (the division times), it is impossible to distinguish a “genetically” homogeneous cell population (one with identical parameters) from a truly heterogeneous population. We would require other metrics, like tracking changes in the mean division time as cells with a higher $$r_i$$ out-compete the cells with lower $$r_i$$.

Lastly, I want to point out that caution is required when designing these metrics and single-cell tracking. If instead we had tracked all cells throughout the simulated experiment, including new daughter cells, and then recorded the first 10,000 cell division events, we would get a very different distribution of cell division times:

By only recording the division times for the cells that have divided, and not those that haven’t, we bias our observations towards cells with shorter division times. Indeed, the mean division time for this simulated experiment is far lower than we would expect by theory. You can try this one by running “bad_thought_experiment”.

This post is an expansion of our recent preview in Cell Systems in Macklin (2017):

P. Macklin, When seeing isn’t believing: How math can guide our interpretation of measurements and experiments. Cell Sys., 2017 (in press). DOI: 10.1016/j.cells.2017.08.005

And the original work on apparent heterogeneity in collective cell migration is by Schumacher et al. (2017):

L. Schumacher et al., Semblance of Heterogeneity in Collective Cell MigrationCell Sys., 2017 (in press). DOI: 10.1016/j.cels.2017.06.006

You can read some more on relating exponential distributions and Poisson processes to common discrete mathematical models of cell populations in Macklin et al. (2012):

P. Macklin, et al., Patient-calibrated agent-based modelling of ductal carcinoma in situ (DCIS): From microscopic measurements to macroscopic predictions of clinical progressionJ. Theor. Biol. 301:122-40, 2012. DOI: 10.1016/j.jtbi.2012.02.002.

Lastly, I’d be delighted if you took a look at the open source software we have been developing for 3-D simulations of multicellular systems biology:

http://OpenSource.MathCancer.org

And you can always keep up-to-date by following us on Twitter: @MathCancer.

## Getting started with a PhysiCell Virtual Appliance

Note: This is part of a series of “how-to” blog posts to help new users and developers of BioFVM and PhysiCell. This guide is for for users in OSX, Linux, or Windows using the VirtualBox virtualization software to run a PhysiCell virtual appliance.

These instructions should get you up and running without needed to install a compiler, makefile capabilities, or any other software (beyond the virtual machine and the PhysiCell virtual appliance). We note that using the PhysiCell source with your own compiler is still the preferred / ideal way to get started, but the virtual appliance option is a fast way to start even if you’re having troubles setting up your development environment.

### What’s a Virtual Machine? What’s a Virtual Appliance?

A virtual machine is a full simulated computer (with its own disk space, operating system, etc.) running on another. They are designed to let a user test on a completely different environment, without affecting the host (main) environment. They also allow a very robust way of taking and reproducing the state of a full working environment.

A virtual appliance is just this: a full image of an installed system (and often its saved state) on a virtual machine, which can easily be installed on a new virtual machine. In this tutorial, you will download our PhysiCell virtual appliance and use its pre-configured compiler and other tools.

### What you’ll need:

• VirtualBox: This is a free, cross-platform program to run virtual machines on OSX, Linux, Windows, and other platforms. It is a safe and easy way to install one full operating (a client system) on your main operating system (the host system). For us, this means that we can distribute a fully working Linux environment with a working copy of all the tools you need to compile and run PhysiCell. As of August 1, 2017, this will download Version 5.1.26.
• PhysiCell Virtual Appliance: This is a single-file distribution of a virtual machine running Alpine Linux, including all key tools needed to compile and run PhysiCell. As of July 31, 2017, this will download PhysiCell 1.2.0 with g++ 6.3.0.
• A computer with hardware support for virtualization: Your CPU needs to have hardware support for virtualization (almost all of them do now), and it has to be enabled in your BIOS. Consult your computer maker on how to turn this on if you get error messages later.

### Main steps:

#### 2) Import the PhysiCell Virtual Appliance

Go the “File” menu and choose “Import Virtual Appliance”. Browse to find the .ova file you just downloaded.

Click on “Next,” and import with all the default options. That’s it!

#### 3) [Optional] Change settings

You most likely won’t need this step, but you can increase/decrease the amount of RAM used for the virtual machine if you select the PhysiCell VM, click the Settings button (orange gear), and choose “System”:We set the Virtual Machine to have 4 GB of RAM. If you have a machine with lots of RAM (16 GB or more), you may want to set this to 8 GB.

Also, you can choose how many virtual CPUs to give to your VM:

We selected 4 when we set up the Virtual Appliance, but you should match the number of physical processor cores on your machine. In my case, I have a quad core processor with hyperthreading. This means 4 real cores, 8 virtual cores, so I select 4 here.

Select the PhysiCell machine, and click the green “start” button. After the virtual machine boots (with the good old LILO boot manager that I’ve missed), you should see this:

Click the "More ..." button, and log in with username: physicell, password: physicell

#### 5) Test the compiler and run your first simulation

Notice that PhysiCell is already there on the desktop in the PhysiCell folder. Right-click, and choose “open terminal here.” You’ll already be in the main PhysiCell root directory.

Now, let’s compile your first project! Type “make template2D && make” And run your project! Type “./project” and let it go!Go ahead and run either the first few days of the simulation (until about 7200 minutes), then hit <control>-C to cancel out. Or run the whole simulation–that’s fine, too.

#### 6) Look at the results

We bundled a few tools to easily look at results. First, ristretto is a very fast image viewer. Let’s view the SVG files: As a nice tip, you can press the left and right arrows to advance through the SVG images, or hold the right arrow down to advance through quickly.

Now, let’s use ImageMagick to convert the SVG files into JPG file: call “magick mogrify -format jpg snap*.svg”

Next, let’s turn those images into a movie. I generally create moves that are 24 frames pers se, so that 1 second of the movie is 1 hour of simulations time. We’ll use mencoder, with options below given to help get a good quality vs. size tradeoff:

When you’re done, view the movie with mplayer. The options below scale the window to fit within the virtual monitor:

If you want to loop the movie, add “-loop 999” to your command.

#### 7) Get familiar with other tools

Use nano (useage: nano <filename>) to quickly change files at the command line. Hit <control>-O to save your results. Hit <control>-X to exit.  <control>-W will search within the file.

Use nedit (useage: nedit <filename> &) to open up one more text files in a graphical editor. This is a good way to edit multiple files at once.

Sometimes, you need to run commands at elevated (admin or root) privileges. Use sudo. Here’s an example, searching the Alpine Linux package manager apk for clang:

physicell:~$sudo apk search gcc [sudo] password for physicell: physicell:~$ sudo apk search clang
clang-analyzer-4.0.0-r0
clang-libs-4.0.0-r0
clang-dev-4.0.0-r0
clang-static-4.0.0-r0
emscripten-fastcomp-1.37.10-r0
clang-doc-4.0.0-r0
clang-4.0.0-r0
physicell:~/Desktop/PhysiCell$ If you want to install clang/llvm (as an alternative compiler): physicell:~$ sudo apk add gcc
physicell:~$sudo apk search clang clang-analyzer-4.0.0-r0 clang-libs-4.0.0-r0 clang-dev-4.0.0-r0 clang-static-4.0.0-r0 emscripten-fastcomp-1.37.10-r0 clang-doc-4.0.0-r0 clang-4.0.0-r0 physicell:~/Desktop/PhysiCell$


Coming soon.

### Why both with zipped source, then?

Given that we can get a whole development environment by just downloading and importing a virtual appliance, why
bother with all the setup of a native development environment, like this tutorial (Windows) or this tutorial (Mac)?

One word: performance. In my testing, I still have not found the performance running inside a
virtual machine to match compiling and running directly on your system. So, the Virtual Appliance is a great
option to get up and running quickly while trying things out, but I still recommend setting up natively with
one of the tutorials I linked in the preceding paragraphs.

### What’s next?

In the coming weeks, we’ll post further tutorials on using PhysiCell. In the meantime, have a look at the
PhysiCell project website, and these links as well:

1. BioFVM on MathCancer.org: http://BioFVM.MathCancer.org
2. BioFVM on SourceForge: http://BioFVM.sf.net
3. BioFVM Method Paper in BioInformatics: http://dx.doi.org/10.1093/bioinformatics/btv730
4. PhysiCell on MathCancer.org: http://PhysiCell.MathCancer.org
5. PhysiCell on Sourceforge: http://PhysiCell.sf.net
6. PhysiCell Method Paper (preprint): https://doi.org/10.1101/088773

## Moving the blog to MathCancer.org

Hi, everyone!

Blogspot has been a great platform for me, but in the end, editing posts with source code and mathematics has been too much of a headache in the neglected blogspot and google UIs.

Elsewhere in the universe, WordPress has developed and encouraged a great ecosystem of plugins that let you do LaTeX and code syntax highlighting directly in your posts with ease. I can’t spend hours and hours on fixing mangled posts. It’s time to move on.

So as of today, I am moving to a self-hosted blog at http://MathCancer.org/blog/

I will leave old posts at http://MathCancer.blogspot.com and gradually migrate them here to MathCancer.org/blog. Thanks for following me over the last few years.

## Banner and Logo Contest : MultiCellDS Project

As the MultiCellDS (multicellular data standards) project continues to ramp up, we could use some artistic skill.

Right now, we don’t have a banner (aside from a fairly barebones placeholder using a lovely LCARS font) or a logo. While I could whip up a fancier banner and logo, I have a feeling that there is much better talent out there. So, let’s have a contest!

Here are the guidelines and suggestions:

1. The banner should use the text MultiCellDS Project. It’s up to artist (and the use) whether the “multicellular data standards” part gets written out more fully (e.g., below the main part of the banner).
2. The logo should be shorter and easy to use on other websites. I’d suggest MCDS, stylized similarly to the main banner.
3. Think of MultiCell as a prefix: MultiCellDS, MultiCellXML, MultiCellHDF, MultiCellDB. So, the “banner” version should be extensible to new directions on the project.
4. The banner and logo should be submitted in a vector graphics format, with all source.
5. It goes without saying that you can’t use clip art that you don’t have rights to. (i.e., use your own artwork or photos, or properly-attributed creative commons-licensed art.)
6. The banner and logo need to belong to the MultiCellDS project once done.
7. We may do some final tweaks and finalization on the winning design for space or other constraints. But this will be done in full consultation with the winner.

So, what are the perks for winning?

1. Permanent link to your personal research / profession page crediting you as the winner.
2. A blog/post detailing how awesome you and your banner and logo are.
3. Beer / coffee is on me next time I see you. SMB 2015 in Atlanta might be a good time to do it!
4. If we ever make t-shirts, I’ll buy yours for you. 🙂
5. You get to feel good for being awesome and helping out the project!

So, please post here, on the @MultiCellDS twitter feed, or contact me if you’re interested.  Once I get a sense of interest, I’ll set a deadline for submissions and “voting” procedures.

Thanks!!

## 2015 Speaking Schedule

Here is my current speaking schedule for 2015. Please join me if you can!

Feb. 13, 2015: Seminar at the Institute for Scientific Computing Research, Lawrence Livermore National Laboratory (LLNL)
Title: Scalable 3-D Agent-Based Simulations of Cells and Tissues in Biology and Cancer [abstract]

## 2014 Speaking Schedule

Here is my current speaking schedule for 2014. Please join me if you can!

Feb. 16, 2014: American Association for the Advancement of Science (AAAS) Annual Meeting, Chicago
Title: Integrating Next-Generation Computational Models of Cancer Progression and Outcome [abstract]
invited by the National Cancer Institute

May 9, 2014: European Society for Medical Oncology (ESMO) 2014 IMPAKT Breast Cancer Conference, Brussels, Belgium
Title: Calibrating breast cancer simulations with patient pathology: Progress and future steps [programme]
Plenary talk

May 13, 2014: Wolfson Centre for Mathematical Biology at the University of Oxford, Oxford, UK
Title: Advances in parallelized 3-D agent-based cancer modeling and digital cell lines [abstract]

June 19, 2014: Biostatistics Seminar, University of Southern California, Los Angeles
Title: Simulating 3-D systems of 500k cells with an agent-based model, and digital cell lines [link]

Aug. 18, 2014: COMBINE (Computational Modeling in Biology Network) 2014 Symposium, University of Southern California, Los Angeles
Title: Digital cell lines and MultiCellDS: Standardizing cell phenotype data for data-driven cancer simulations[Program]

2013 public speaking schedule

I’m in the process of rolling out some updates to my website. The first thing you’ll see is a new talk / tutorial on computational modeling of biological processes, based upon my recent talk at the USC PS-OC Short Course in October 2013. I’ll make another post here when it’s ready. It will include MATLAB source code to run through the models.

In the medium term, I hope to update my list of projects to better reflect current efforts by my lab, particularly in (1) integrative modeling of cancer metastases using high-throughput in vitro experiments and sophisticated bioengineered tissues for calibration and validation, and (2) development of standardizations for cell- and tissue-scale models and experiments.

In the longer term, I hope to switch my website layout a bit to be more like the USC PSOC website. I wrote that site about a year ago, and I like the CSS and structure a lot better. 🙂

## Interview at the 2013 NCI PS-OC Annual Meeting

I recently had the opportunity to be interviewed by Pauline Davies at the 2013 Physical Sciences-Oncology Annual Meeting. (I gave one of the addresses–“Exploring Possibilities for Next-Generation Computational Cancer Models that Work Together”–at the meeting; agenda available here.) The interview (largely in layman’s terms) discusses mathematical and computational modeling of cancer, the potential role for computational modeling in understanding cancer and making predictions that could help patients and their doctors make treatment choices, and the need for model and data standardizations to enable better predictions in the future. The interview draws parallels to hurricane predictions, where multiple models can read/write standardized data and be combined to improve their accuracy.

My interview can be found here, as can the entire set of selected 2013 interviews. You can find more information on my lab and work at MathCancer.org.

I really want to thank Pauline Davies, Jonathan Franca-Koh and the NCI Office of Physical Sciences in Oncology for the opportunity for this discussion!