Commit fcb9104e authored by gsaxena's avatar gsaxena
Browse files

Several changes for the documentation, deleted some useless files,...

Several changes for the documentation, deleted some useless files, incorporated files from PhysiCell_1.9.0, added my files from Overleaf
parent 550561be
This diff is collapsed.
# Quickstart Guide to PhysiCell
* [Download](#download)
* [Build: the basics](#build-the-basics)
* [Windows](#windows)
* [macOS](#macos)
* [Linux](#linux)
* [Python](#python)
* [Test setup: simple projects](#test-setup-simple-projects)
* [Test setup: advanced projects](#test-setup-advanced-projects)
* [Visualizing Output](#visualizing-output)
* [Browser](#browser)
* [MATLAB/Octave](#matlaboctave)
* [Matplotlib](#matplotlib)
* [ImageMagick](#imagemagick)
* [ParaView](#paraview)
* [Support](#support)
* [References](#references)
## Download
We currently provide 2 options for downloading PhysiCell:
We currently provide 2 options for downloading the PhysiCell source code:
1) Downloaded source code as a .zip file from http://physicell.mathcancer.org/
(the link there takes you to the latest release on sourceforge).
<!-- https://sourceforge.net/projects/physicell/files/PhysiCell/PhysiCell%201.2.1 -->
* https://sourceforge.net/projects/physicell/
2) We have recently begun migrating our code to GitHub. So, you can also download from https://github.com/MathCancer/PhysiCell/releases.
* https://github.com/MathCancer/PhysiCell/releases
For more detailed information, see Section 3 of the User Guide (in `/documentation`)
and/or also http://www.mathcancer.org/blog/physicell-tutorials/.
......@@ -18,104 +32,184 @@ and/or also http://www.mathcancer.org/blog/physicell-tutorials/.
## Build: the basics
PhysiCell is written in C++ and should build on any of the three major operating systems.
PhysiCell is written in C++ and should build on any of the three major operating systems: Windows, macOS, and Linux.
The one <b>requirement is that your compiler support OpenMP</b>. If, during your build (make) process, you get
a message like: `error: unsupported option '-fopenmp'`, you'll know your Makefile is trying to use a compiler
that doesn't support OpenMP. You may need to install an OpenMP-supported compiler and/or edit the Makefile to use it.
### Windows
The currently preferred way to use PhysiCell on Windows is to install [MinGW-w64](https://sourceforge.net/projects/mingw-w64/) which will let you use
a version of GCC that supports OpenMP. For more detailed information,
[see our blog post](http://www.mathcancer.org/blog/setting-up-a-64-bit-gcc-environment-on-windows).
The preferred way to use PhysiCell on Windows is to install MinGW64,
a minimal version of GCC that supports OpenMP (on a 64-bit computer).
(Sometime in the near future, we plan to provide an option to use native Windows and a recent
[Microsoft Visual C++](https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads) compiler,
using [CMake](https://cmake.org/download/) to build PhysiCell. If you want to be a beta-tester, contact us).
1) If you have followed the MinGW64 [installation instructions from PhysiCell v1.8.0 or before](http://mathcancer.blogspot.com/2016/01/PrepWindowsForCoding.html), we recommend that you uninstall (delete) everything from it and remove what you added to your system PATH environment variable. However, if you prefer, you can probably leave everything as is and the following steps should override your previous installation.
### OSX
2) From [msys2.org](https://www.msys2.org), follow steps 1-4 (stopping before step 5). Click through the setup dialog, accepting the default suggestions.
Unfortunately, the C++ compiler provided by the latest version of XCode on OSX does not support OpenMP.
3) In the MSYS2 console terminal, copy/paste/execute the following command (a package manager to install MINGW64 and additional libraries):
```
$ pacman -S mingw-w64-x86_64-binutils mingw-w64-x86_64-gcc mingw-w64-x86_64-headers-git mingw-w64-x86_64-gcc-libs mingw-w64-x86_64-libwinpthread-git mingw-w64-x86_64-winpthreads-git mingw-w64-x86_64-lapack mingw-w64-x86_64-openblas mingw-w64-x86_64-libxml2 mingw-w64-x86_64-bzip2 git make
```
3) After the above completes, open the Windows application to let you edit your Environment Variables. You have the option of
editing the “User variables” or “System variables”. If it is just for your use and not intended to be shared by other
users on this computer, then you can just edit “User variables”. Edit the “Path” variable and add three “New”
paths. The first two pertain to the MinGW build environment; the third is for using the libRoadrunner library that's needed
by the intracellular models (ODEs) (and is a relative path from your PhysiCell main folder).
```
C:\msys64\mingw64\bin
C:\msys64\usr\bin
.\addons\libRoadrunner\roadrunner\bin
```
4) Using the same application as above, `Move up` each of the two new paths to be at the very top.
<img src="images/mingw64_env_var_path.png" width="459" height="450">
Then click `OK` on each Edit env variable window to complete the PATH update.
5) Open a *new* Command Prompt window (or Powershell, if you prefer it) and type `g++ --version` to verify it can be found:
```
PS C:\Users\heiland> g++ --version
g++.exe (Rev10, Built by MSYS2 project) 10.2.0
Copyright (C) 2020 Free Software Foundation, Inc.
```
### MacOS
Unfortunately, the C++ compiler provided by the latest version of XCode on macOS does not support OpenMP.
To resolve this, we recommend using the `brew` package manager to install a recent version of `gcc`. Follow the [brew
installation instructions](https://docs.brew.sh/Installation.html).
After installing brew, type `brew install gcc` from a Terminal command line. This
should install a recent version of gcc/g++ (supporting OpenMP) into `/usr/local/bin`. You can verify this with:
should install a recent version of gcc/g++ (supporting OpenMP) into `/usr/local/bin`.
You can verify this with (note the g++ version # will change over time, but in June 2021, it was version 11):
```
$ ls -l /usr/local/bin/g++*
... /usr/local/bin/g++-8@ -> ../Cellar/gcc/8.2.0/bin/g++-8
... /usr/local/bin/g++-11@ -> ../Cellar/gcc/11.1.0_1/bin/g++-11
```
Set the following environment variable in your Terminal's shell, e.g., in the bash shell:
Set the following environment variables in your Terminal's shell, e.g., in the bash or zsh shell:
```
$ export PHYSICELL_CPP=/usr/local/bin/g++-11
$ export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:./addons/libRoadrunner/roadrunner/lib
```
$ export PHYSICELL_CPP=/usr/local/bin/g++-8
You should permanently set these in your environment: for the bash shell:
```
$ echo export PHYSICELL_CPP=g++-11 >> ~/.bash_profile
$ export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:./addons/libRoadrunner/roadrunner/lib >> ~/.bash_profile
```
or the zsh shell:
```
$ echo export PHYSICELL_CPP=g++-11 >> ~/.zshenv
$ export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:./addons/libRoadrunner/roadrunner/lib >> ~/.zshenv
```
and the Makefile will use it. You should permanently set this in your environment via:
`$ echo export PHYSICELL_CPP=g++-8 >> ~/.bash_profile`.
### Linux
If you're a Linux user, you probably already have or know how to install/use a proper g++ environment for
building PhysiCell. If not, contact us!
If you're a Linux user, you should already have an OpenMP-enabled g++.
But you will need to append the libRoadrunner relative path to your `LD_LIBRARY_PATH` (similar to the instructions for macOS) if you plan to use that for intracellular ODE models.
<hr> <!---------------------------------------------->
## Python
PhysiCell uses Python in a few different ways:
1) It is needed to install certain libraries for the intracellular models.
2) It can be used for visualization and data analysis scripts.
3) It is used for Jupyter notebook apps of PhysiCell models.
4) It can be used for parameter explorations of models.
We highly recommend installing the freely available Anaconda Python distribution.
However, if you are already actively using Python from another distribution, you may run into possible problems by installing another one.
In that case, you may want to reach out to the PhysiCell community for help (see Support section below).
Download/install the entire [Individual Edition](https://www.anaconda.com/products/individual). This is ~400-500MB in size because it contains a very large suite of modules. If you do not have enough free disk space, contact us for other options.
During the installation process, select the option to add Anaconda to your PATH, in spite of the "Not recommended" comment:
![anaconda_to_path](images/anaconda_add_to_path_med.png)
<!-- On macOS, you may need to insert `alias python=pythonw` into your `~/.bashrc` file (or `~/.bash_profile`). -->
<hr> <!---------------------------------------------->
## Build: sample projects
## Test setup: simple projects
In the current release of PhysiCell, we provide four sample projects to help you get started. Three
of the projects are 2D models (<i>biorobots, anti-cancer biorobots, and cancer heterogeneity</i>); the fourth project
is a 3D model (<i>cancer immunology</i>). The procedure to build and execute each of the sample projects follows the same
We provide several sample projects to help you get started. Most
of the projects are 2D models, but at least one
is 3D (<i>cancer immunology</i>). The procedure to build and execute each of the sample projects follows the same
pattern. For example, from your Terminal, in the root PhysiCell directory/folder:
```
$ make biorobots-sample # populate the biorobots sample project
$ make # compile the project
$ make biorobots-sample # copy files for biorobots
$ make # compile
```
<!-- Note: the first `make` command silently copies over project-specific files, including the Makefile. The
second `make` command attempts to compile the (new) code. Since the Makefile is being overwritten, any edits you
may have done to the previous Makefile (e.g., changing `CC` to point to `g++-7` on OSX) will be lost. You'll need
to edit it again or find another workaround. -->
Assuming the project builds without errors, you should now have an executable called `biorobots` which you can run, e.g.:
```
$ ./biorobots
$ ./biorobots # .\biorobots.exe on Windows
...
(visualize output)
```
This will begin the simulation, write information to your terminal, and generate output files of types `.svg`, `.xml`, and `.mat`. More about those below. You can `Control-c` to kill the simulation early, if you want.
For the remaining three example projects provided with PhysiCell, you would follow similar steps, but first, you may want to clean out the previous simulation's output and prepare for the new one:
For the remaining example projects provided with PhysiCell, you would follow similar steps, but first, you may want to clean out the previous simulation's output and prepare for the new one:
```
$ make data-cleanup # Delete output data. (Optionally, manually move it to another directory to keep it)
$ make reset # clear out the sample project / clean slate
$ make cancer-biorobots-sample # populate the new project
$ make # compile the project
$ ./cancer_biorobots
$ make reset # clear out sample project
$ make list-projects # show all possible samples
Build another one, e.g.:
$ make cancer-biorobots-sample # copy new proj files
$ make # compile
$ ./cancer_biorobots # execute
...
(visualize output)
```
and
## Test setup: advanced projects
To build and run some of the advanced, e.g., intracellular, models:
```
$ make data-cleanup # Delete previous output data.
$ make reset # clear out previous sample project
$ make list-projects # show all possible samples
$ make ode-energy-sample
$ make
$ ./ode_energy # execute
...
(visualize output)
$ make data-cleanup
$ make reset
$ make heterogeneity-sample
$ make
$ ./heterogeneity
```
and
```
$ make physiboss-cell-lines-sample
$ make
$ ./PhysiBoSS_Cell_Lines # execute
...
(visualize output)
$ make data-cleanup
$ make reset
$ make cancer-immune-sample
$ make cancer-metabolism-sample
$ make
$ ./cancer_immune_3D
$ ./cancer_metabolism # execute
...
(visualize output)
```
<hr> <!---------------------------------------------->
## Visualizing Output
PhysiCell does not currently provide a GUI for visualizing output results. Our approach, at least for now,
PhysiCell does not currently provide a GUI for visualizing output results. Our approach, for now,
is to suggest and offer guidance on using other tools, e.g. your browser, [ImageMagick](https://www.imagemagick.org),
[MATLAB](https://www.mathworks.com/products/matlab.html), [Octave](https://octave.sourceforge.io/),
[ParaView](https://www.paraview.org/), and more.
Python, and [ParaView](https://www.paraview.org/).
### Browser
......@@ -123,12 +217,7 @@ At a bare minimum, you should be able to use your browser to `File -> Open` any
that your simulation generates. PhysiCell simulates transmitted light microscopy to create virtual pathology images for the .svg files. Even for 3D models, 2D cross-section images (.svg files) are generated, by
default, using a slice through the Z=0 plane, as depicted in the following image (from the cancer-immune-sample project).
![alt text](https://github.com/rheiland/PhysiCell/blob/master/documentation/images/cancer_immune_snapshot00000574_small.png "SVG slice from 3D cancer-immune-sample project")
### MATLAB/Octave
If you have access to MATLAB (or Octave), we have a [detailed tutorial](http://www.mathcancer.org/blog/working-with-physicell-snapshots-in-matlab/) on how to visualize the
MultiCellDS digital snapshots (.xml and .mat files).
![slice in 3D](images/cancer_immune_snapshot00000574_small.png "SVG slice from 3D cancer-immune-sample project")
### ImageMagick
......@@ -140,7 +229,7 @@ $ convert -resize 15% tmp.png out.png
```
will generate a tiled horizontal sequence of images:
![alt text](https://github.com/rheiland/PhysiCell/blob/master/documentation/images/cancer_immune_seq4x1_small.png "ImageMagick can tile images")
![alt text](images/cancer_immune_seq4x1_small.png "ImageMagick can tile images")
ImageMagick will also let you generate an animated gif of your results, e.g.:
```
......@@ -152,25 +241,60 @@ $ convert -size 1500x1605 tmp.gif -resize 20% small.gif
$ magick animate small.gif
```
PhysiCell 1.8.0 and later provides helper targets in the Makefile that will perform various functions (assuming you have installed ImageMagick), e.g.:
```
$ make jpeg # convert all output/snapshot*.svg to .jpg
$ make gif # create out.gif from output/snapshot*.svg
$ make movie # assuming you have ffmpeg, create out.mp4 from output/snapshot*.jpg
You can also specify the name of the output directory, e.g.:
$ make jpeg OUTPUT=out1
```
### MATLAB/Octave
If you have access to MATLAB (or Octave), we have a [detailed tutorial](http://www.mathcancer.org/blog/working-with-physicell-snapshots-in-matlab/) on how to visualize the
MultiCellDS digital snapshots (.xml and .mat files).
### Matplotlib
We plan to provide a full-featured GUI that uses matplotlib (Python plotting). For now, we have a simple GUI that plots only the cells (the .svg files):
```
$ python beta/plot_cells.py
```
Showing output results (.svg) from the biorobots sample project:
![](images/plot_cells_gui_biorobots_small.png)
You may also see other Python scripts in /beta that can be copied into your /output directory and run, e.g.:
```
$ python anim_svg.py
```
If you want to experiment with plotting data in the .xml and .mat files in /output, see this
blog post http://www.mathcancer.org/blog/python-loader/.
### ParaView
If you install ParaView, you can visualize and interact with output from 3D models (the `.mat` files). Refer to our [blog post](http://www.mathcancer.org/blog/paraview-for-physicell-part-1/) to get started.
![alt text](https://github.com/rheiland/PhysiCell/blob/master/documentation/images/ParaView_clip_planes.png "ParaView w clipping planes and barchart")
![paraview](images/ParaView_clip_planes.png "ParaView w clipping planes and barchart")
<hr> <!---------------------------------------------->
## Support
Please join the [PhysiCell Users](https://groups.google.com/forum/#!forum/physicell-users) forum and follow us on Twitter (https://twitter.com/MathCancer).
We encourage you to join and actively use the [PhysiCell community Slack channel](https://join.slack.com/t/physicellcomm-sf93727/shared_invite/zt-qj1av6yd-yVeer8VkQaNDjDz7fF00jA). There, you can post questions [(#troubleshooting)](https://physicellcomm-sf93727.slack.com/archives/C026Y12AN7R), answer questions, and (hopefully) share successful modeling stories.
Alternatively, you can submit problem tickets at https://sourceforge.net/p/physicell/tickets/
Finally, please follow us on Twitter [@PhysiCell](https://twitter.com/PhysiCell) and [@MathCancer](https://twitter.com/MathCancer).
<hr> <!---------------------------------------------->
## References
* http://physicell.mathcancer.org/
* http://www.mathcancer.org/blog/setting-up-a-64-bit-gcc-environment-on-windows
* http://www.mathcancer.org/blog/setting-up-gcc-openmp-on-osx-homebrew-edition/
* http://physicell.org/
* http://www.mathcancer.org/blog/setting-up-gcc-openmp-on-osx-homebrew-edition/ (beware the version of gcc discussed there is possibly out of date)
* http://www.mathcancer.org/blog/physicell-tutorials/
* http://www.mathcancer.org/blog/working-with-physicell-snapshots-in-matlab/
* http://www.mathcancer.org/blog/python-loader/
* https://github.com/MathCancer/PhysiCell/blob/master/documentation/User_Guide.pdf
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
......@@ -153,4 +153,14 @@ year=2012,
abstract = {Introduction Solid tumors are less oxygenated than their tissue of origin. Low intra-tumor oxygen levels are associated with worse outcome, increased metastatic potential and immature phenotype in breast cancer. We have reported that tumor hypoxia correlates to low differentiation status in breast cancer. Less is known about effects of hypoxia on non-malignant cells. Here we address whether hypoxia influences the differentiation stage of non-malignant breast epithelial cells and potentially have bearing on early stages of tumorigenesis. Methods Normal human primary breast epithelial cells and immortalized non-malignant mammary epithelial MCF-10A cells were grown in a three-dimensional overlay culture on laminin-rich extracellular matrix for up to 21 days at normoxic or hypoxic conditions. Acinar morphogenesis and expression of markers of epithelial differentiation and cell polarization were analyzed by immunofluorescence, immunohistochemistry, qPCR and immunoblot. Results In large ductal carcinoma in situ patient-specimens, we find that epithelial cells with high HIF-1α levels and multiple cell layers away from the vasculature are immature compared to well-oxygenated cells. We show that hypoxic conditions impaired acinar morphogenesis of primary and immortalized breast epithelial cells grown ex vivo on laminin-rich matrix. Normoxic cultures formed polarized acini-like spheres with the anticipated distribution of marker proteins associated with mammary epithelial polarization e.g. α6-integrin, laminin 5 and Human Milk Fat Globule/MUC1. At hypoxia, cells were not polarized and the sub-cellular distribution pattern of the marker proteins rather resembled that reported in vivo in breast cancer. The hypoxic cells remained in a mitotic state, whereas proliferation ceased with acinar morphogenesis at normoxia. We found induced expression of the differentiation repressor ID1 in the undifferentiated hypoxic MCF-10A cell structures. Acinar morphogenesis was associated with global histone deacetylation whereas the hypoxic breast epithelial cells showed sustained global histone acetylation, which is generally associated with active transcription and an undifferentiated proliferative state.},
number = {9},
doi = {10.1371/journal.pone.0046543}
}
@inproceedings{saxena2021biofvm,
title={{BioFVM-X: An MPI+ OpenMP 3-D Simulator for Biological Systems}},
author={Saxena, Gaurav and Ponce-de-Leon, Miguel and Montagud, Arnau and Vicente Dorca, David and Valencia, Alfonso},
booktitle={International Conference on Computational Methods in Systems Biology},
pages={266--279},
year={2021},
organization={Springer},
URL = {https://link.springer.com/chapter/10.1007/978-3-030-85633-5_18}
}
\ No newline at end of file
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment