Commit 496f42fd authored by gsaxena's avatar gsaxena
Browse files

README.md modified, shortened.

parent 2a837120
# Parallelizing PhysiCell Version 1.6.1
# PhysiCell-X: A Distributed-Shared Parallel Version of PhysiCell
Aim: Parallelize heterogeneity-sample example in 3-D.
**Version:** 0.1
Important
=========
`$make heterogeneity-sample`
copies multiple files in generic directories like **./config, ./custom_modules.**
When parallelizing, we are not changing the files inside the **sample_projects** directory.
So when doing `$make heterogeneity-sample` again, several files in the current directory
will be replaced by the original files (which will not be parallel).
Need to be **CAREFUL** before executing `$make heterogeneity-sample` again.
But only `$make` can be done without any problems - for example if we change the main.cpp file and we `$make` then no files are replaced.
Thus we can do `$make clean` - this removes all `.o` files and the executable i.e. `heterogeneity.exe` are deleted.
```
bsc99102@login1:~/GS_PhysiCell_X> make clean
rm -f *.o
rm -f heterogeneity.exe*
```
Then:
```
bsc99102@login1:~/GS_PhysiCell_X> make
mpic++ -march=native -O3 -fomit-frame-pointer -mfpmath=both -fopenmp -m64 -std=c++11 -g -c ./BioFVM/BioFVM_vector.cpp
mpic++ -march=native -O3 -fomit-frame-pointer -mfpmath=both -fopenmp -m64 -std=c++11 -g -c ./BioFVM/BioFVM_mesh.cpp
mpic++ -march=native -O3 -fomit-frame-pointer -mfpmath=both -fopenmp -m64 -std=c++11 -g -c ./BioFVM/BioFVM_microenvironment.cpp
mpic++ -march=native -O3 -fomit-frame-pointer -mfpmath=both -fopenmp -m64 -std=c++11 -g -c ./BioFVM/BioFVM_solvers.cpp
mpic++ -march=native -O3 -fomit-frame-pointer -mfpmath=both -fopenmp -m64 -std=c++11 -g -c ./BioFVM/BioFVM_matlab.cpp
mpic++ -march=native -O3 -fomit-frame-pointer -mfpmath=both -fopenmp -m64 -std=c++11 -g -c ./BioFVM/BioFVM_utilities.cpp
mpic++ -march=native -O3 -fomit-frame-pointer -mfpmath=both -fopenmp -m64 -std=c++11 -g -c ./BioFVM/BioFVM_basic_agent.cpp
mpic++ -march=native -O3 -fomit-frame-pointer -mfpmath=both -fopenmp -m64 -std=c++11 -g -c ./BioFVM/BioFVM_MultiCellDS.cpp
mpic++ -march=native -O3 -fomit-frame-pointer -mfpmath=both -fopenmp -m64 -std=c++11 -g -c ./BioFVM/BioFVM_agent_container.cpp
mpic++ -march=native -O3 -fomit-frame-pointer -mfpmath=both -fopenmp -m64 -std=c++11 -g -c ./BioFVM/pugixml.cpp
mpic++ -march=native -O3 -fomit-frame-pointer -mfpmath=both -fopenmp -m64 -std=c++11 -g -c ./core/PhysiCell_phenotype.cpp
mpic++ -march=native -O3 -fomit-frame-pointer -mfpmath=both -fopenmp -m64 -std=c++11 -g -c ./core/PhysiCell_cell_container.cpp
mpic++ -march=native -O3 -fomit-frame-pointer -mfpmath=both -fopenmp -m64 -std=c++11 -g -c ./core/PhysiCell_standard_models.cpp
mpic++ -march=native -O3 -fomit-frame-pointer -mfpmath=both -fopenmp -m64 -std=c++11 -g -c ./core/PhysiCell_cell.cpp
mpic++ -march=native -O3 -fomit-frame-pointer -mfpmath=both -fopenmp -m64 -std=c++11 -g -c ./core/PhysiCell_custom.cpp
mpic++ -march=native -O3 -fomit-frame-pointer -mfpmath=both -fopenmp -m64 -std=c++11 -g -c ./core/PhysiCell_utilities.cpp
mpic++ -march=native -O3 -fomit-frame-pointer -mfpmath=both -fopenmp -m64 -std=c++11 -g -c ./core/PhysiCell_constants.cpp
mpic++ -march=native -O3 -fomit-frame-pointer -mfpmath=both -fopenmp -m64 -std=c++11 -g -c ./modules/PhysiCell_SVG.cpp
mpic++ -march=native -O3 -fomit-frame-pointer -mfpmath=both -fopenmp -m64 -std=c++11 -g -c ./modules/PhysiCell_pathology.cpp
mpic++ -march=native -O3 -fomit-frame-pointer -mfpmath=both -fopenmp -m64 -std=c++11 -g -c ./modules/PhysiCell_MultiCellDS.cpp
mpic++ -march=native -O3 -fomit-frame-pointer -mfpmath=both -fopenmp -m64 -std=c++11 -g -c ./modules/PhysiCell_various_outputs.cpp
mpic++ -march=native -O3 -fomit-frame-pointer -mfpmath=both -fopenmp -m64 -std=c++11 -g -c ./modules/PhysiCell_pugixml.cpp
mpic++ -march=native -O3 -fomit-frame-pointer -mfpmath=both -fopenmp -m64 -std=c++11 -g -c ./modules/PhysiCell_settings.cpp
mpic++ -march=native -O3 -fomit-frame-pointer -mfpmath=both -fopenmp -m64 -std=c++11 -g -c ./DistPhy/DistPhy_Environment.cpp
mpic++ -march=native -O3 -fomit-frame-pointer -mfpmath=both -fopenmp -m64 -std=c++11 -g -c ./DistPhy/DistPhy_Cartesian.cpp
mpic++ -march=native -O3 -fomit-frame-pointer -mfpmath=both -fopenmp -m64 -std=c++11 -g -c ./DistPhy/DistPhy_Utils.cpp
mpic++ -march=native -O3 -fomit-frame-pointer -mfpmath=both -fopenmp -m64 -std=c++11 -g -c ./custom_modules/heterogeneity.cpp
mpic++ -march=native -O3 -fomit-frame-pointer -mfpmath=both -fopenmp -m64 -std=c++11 -g -o heterogeneity.exe BioFVM_vector.o BioFVM_mesh.o BioFVM_microenvironment.o BioFVM_solvers.o BioFVM_matlab.o BioFVM_utilities.o BioFVM_basic_agent.o BioFVM_MultiCellDS.o BioFVM_agent_container.o pugixml.o PhysiCell_phenotype.o PhysiCell_cell_container.o PhysiCell_standard_models.o PhysiCell_cell.o PhysiCell_custom.o PhysiCell_utilities.o PhysiCell_constants.o PhysiCell_SVG.o PhysiCell_pathology.o PhysiCell_MultiCellDS.o PhysiCell_various_outputs.o PhysiCell_pugixml.o PhysiCell_settings.o DistPhy_Environment.o DistPhy_Cartesian.o DistPhy_Utils.o heterogeneity.o main.cpp
bsc99102@login1:~/GS_PhysiCell_X>
```
Preparation of example to be parallelized
=========================================
(1) Extract version 1.1.6, then rename to GS_PhysiCell_X (Gaurav Saxena PhysiCell X decomposition)
(2) Adjust **./sample_projects/heterogeneity/config/PhysiCell_settings.xml**
(a) Domain: from -240 to +240 in all dimensions,
(b) 3-D,
(c) Time=720 minutes,
(d) Full save=120 minutes,
(e) Tumor radius=150
(f) Voxels already 20^3.
(3) **./sample_projects/custom_modules/heterogeneity.cpp** change
`if(2D == false) then 2D = True;`
to
`if(2D == true) then 2D = false;`
to change this example to force 3-D domain.
(4) Change **./sample_projects/Makefile**
(a) Program name: **heterogeneity.exe** (so that we can list .exe in .gitignore)
(b) List **DistPhy_OBJECTS**
(c) Include **DistPhy_OBJECTS** in **PhysiCell_OBJECTS**
(d) Change **g++** to **mpic++**
(e) Write rules for DistPhy target .o files.
# PhysiCell: an Open Source Physics-Based Cell Simulator for 3-D Multicellular Systems.
**Release date:** 15 March 2022
**Version:** 1.6.1
**Reference:**
**Release date:** 26 January 2020
(a) The PhysiCell-X repository
(b) Saxena, Gaurav, Miguel Ponce-de-Leon, Arnau Montagud, David Vicente Dorca, and Alfonso Valencia.
"BioFVM-X: An MPI+ OpenMP 3-D Simulator for Biological Systems."
In International Conference on Computational Methods in Systems Biology, pp. 266-279. Springer, Cham, 2021.
## Overview:
PhysiCell is a flexible open source framework for building agent-based multicellular models in 3-D tissue environments.
**User Guide:** PhysiCell-X_UserGuide.pdf in the documentation folder (use in conjunction with the PhysiCell documentation).
**Reference:** A Ghaffarizadeh, R Heiland, SH Friedman, SM Mumenthaler, and P Macklin, PhysiCell: an Open Source Physics-Based Cell Simulator for Multicellular Systems, PLoS Comput. Biol. 14(2): e1005991, 2018. DOI: [10.1371/journal.pcbi.1005991](https://dx.doi.org/10.1371/journal.pcbi.1005991)
Visit http://MathCancer.org/blog for the latest tutorials and help.
PhysiCell-X is the distributed-shared parallel version of PhysiCell (http://physicell.org). PhysiCell is a open-source,
multi-physics, multi-scale, agent-based simulator for biological systems. It provides both the stage
(micro-environment) and actors (cells or agents) for simulation. Though PhysiCell is light-weight, flexible and
shared-memory parallelized using OpenMP (Open Multiprocessing), it cannot run on distributed systems i.e.
it cannot be executed on multiple nodes of an HPC (High Performance Computing) cluster. Thus, the problem size that
PhysiCell can handle is limited by the maximum memory of a single node. This is a limitation that needs to be
removed and this is where PhysiCell-X comes in. PhysiCell-X enables the distributed parallelization of PhysiCell by
making use of MPI (Message-Passing Interface). In simple words, you can now use multiple nodes of an HPC system to
solve a single, coherent problem. Thus, the aim of PhysiCell-X is to remove the memory limitation, reduce the time
to solution by distributing the computation onto multiple compute nodes and solve very large sized (real-world
scale) problem.
**Notable recognition:**
+ [2019 PLoS Computational Biology Research Prize for Public Impact](https://blogs.plos.org/biologue/2019/05/31/announcing-the-winners-of-the-2019-plos-computational-biology-research-prize/)
Introduction
============
### Key makefile rules:
PhysiCell-X is based on PhysiCell v1.9.0 which also added support for intracellular modelling. The current version of
PhysiCell-X is v0.1 and it is actively being developed. PhysiCell-X as of now supports only 3-D problems.
**make** : compiles the current project. If no
project has been defined, it first
populates the cancer heterogeneity 2D
sample project and compiles it
**make \[project-name\]**: populates the indicated sample project.
Use "make" to compile it.
Pre-requisites
==============
There are two pre-requisites to running/modelling projects with PhysiCell-X:
(a) A C++ compiler for e.g. GNU compiler (preferred), Intel compiler etc. that supports OpenMP
(b) An MPI implementation such as OpenMPI (preferred), Intel MPI, MPICH.
\[project-name\] choices:
template2D
template3D
biorobots-sample
cancer-biorobots-sample
heterogeneity-sample
cancer-immune-sample
virus-macrophage-sample
Sample Projects
===============
There are multiple MPI parallelized sample projects that can be found in the directories **sample_projects**
and **sample_projects_intracelluar** . To see a list of available projects, do
**make list-projects** : list all available sample projects
`$ make list-projects`
**make clean** : removes all .o files and the executable, so that the next "make" recompiles the entire project
The projects which are MPI parallelized (PhysiCell-X) have *-mpi* as the suffix. To check out a certain project (like
heterogeneity-sample-mpi), do
**make data-cleanup** : clears out all simulation data
`$ make heterogeneity-sample-mpi`
**make reset** : de-populates the sample project and returns to the original PhysiCell state. Use this when switching to a new PhysiCell sample project.
copies multiple files in generic directories under the top-level directory like **./config, ./custom_modules.**
To compile this checked out project, do
`$ make`
**Homepage:** http://PhysiCell.MathCancer.org
After the executable is produced, it can be submitted for execution using one of the provided submission script files (specifically
for SLURM) or executed simply using `mpiexec` or `mpirun`.
**Downloads:** http://PhysiCell.sf.net
The working directories can be cleaned using
**Support:** https://sourceforge.net/p/physicell/tickets/
`$ make clean`
**Quick Start:** Look at QuickStart.pdf in the documentation folder.
and reset to the original state by executing
**User Guide:** Look at UserGuide.pdf in the documentation folder.
**Tutorials:** http://www.mathcancer.org/blog/physicell-tutorials/
`$ make reset`
**Latest info:** follow [@MathCancer](https://twitter.com/MathCancer) on Twitter (http://twitter.com/MathCancer)
There are other Make rules which can be seen in the top level `Makefile`.
See changes.md for the full change log.
PhysiCell (http://physicell.org)
================================
Pure OpenMP programs inside PhysiCell-X can also be executed as PhysiCell-X v0.1 is based on PhysiCell-v1.9.0 but
one needs to compile the pure OpenMP examples through `mpic++` i.e. the MPI compiler wrapper.
* * *
## Release summary:
This release fixes minor bugs and improves the documentation. It also adds some minor new capabilities, such as setting time step sizes in the XML configuration file.
**NOTE:** OSX users must now define PHYSICELL_CPP system variable. See the documentation.
### Major new features and changes:
+ List here.
### Minor new features and changes:
+ "make list-projects" now displayed to standard output a list of all the sample projects.
+ dt_diffusion, dt_mechanics, and dt_phenotype can now be set via the XML configuration file in the options section.
+ Added documentation on the time step sizes to the User Guide.
+ Preliminary work to support Travis CI testing.
+ Updated documentation to note that Cell::start_death is the preferred method to trigger cell death, and NOT Death::trigger_death.
+ Updated Microenvironment::compute_all_gradient_vectors to now compute one-sized gradients on edge voxels. (Previously, no gradient was computed here.)
+ Updated Microenvironment::compute_all_gradient_vectors to check if there is no z-direction (i.e., 2D) and exit early if so.
+ Updated Microenvironment::compute_all_gradient_vectors to check if there is no y-direction (i.e., 1D) and exit early if so.
+ Made PhysiCell_constants.cpp (and added this to the core of all project makefiles) so that dt and other variables can be non-static (i.e., set by XML options).
+ Added "make checkpoint" rule to makefiles. This zips up the user-custom stuff (./config, ./, ./custom_modules) into a timestamped zip file. Use this before upgrading PhysiCell to make sure you keep your own Makefile, etc.
### Beta features (not fully supported):
+ List here.
### Bugfixes:
+ BioFVM's diffusion_decay_solver__constant_coefficients_LOD_3D, diffusion_decay_solver__constant_coefficients_LOD_2D check for regular meshes instead of uniform meshes.
+ Biorobots sample project fixed bugs on searching for substrates vs. searching for cell types.
+ In BioFVM_vectors, the normalize functions now return a zero vector if the vector's norm is less than 1e-16. This is for John Metzcar.
+ In PhysiCell_Cell.cpp, made fixes to Cell::divide() and Cell::assign_position() to fix a bug where cells dividing on the edge of the domain woudl place a daughter cell at (0,0,0). Thanks, Andrew Eckel!
+ Code cleanup in PhysiCell_cell_container in Cell_Container::update_all_cells() as suggested by Andrew Eckel. Thanks!
### Notices for intended changes that may affect backwards compatibility:
+ We intend to merge Custom_Variable and Custom_Vector_Variable in the very near future.
+ We may change the role of operator() and operator[] in Custom_Variable to more closely mirror the functionality in Parameters<T>.
+ We will introduce improvements to placement of daughter cells after division.
+ Some search functions (e.g., to find a substrate or a custom variable) will start to return -1 if no matches are found, rather than 0.
+ We will change the timing of when entry_functions are executed within cycle models. Right now, they are evaluated immediately after the exit from the preceding phase (and prior to any cell division events), which means that only the parent cell executes it, rather htan both daughter cells. Instead, we'll add an internal Boolean for "just exited a phase", and use this to exucte the entry function at the next cycle call. This should make daughter cells independently execute the entry function.
+ We might make "trigger_death" clear out all the cell's functions, or at least add an option to do this.
### Planned future improvements:
+ Further XML-based simulation setup.
+ read saved simulation states (as MultiCellDS digital snapshots)
+ "mainline" prototype cell attach/detach mechanics as standard models (currently in the biorobots and immune examples)
+ integrate SBML-encoded systems of ODEs as custom data and functions for molecular-scale modeling
+ integrate Boolean network support from PhysiBoSS into the mainline code (See http://dx.doi.org/10.1093/bioinformatics/bty766. )
+ Develop contact-based cell-cell interactions.
Important
=========
Please see the detailed user documentation titled **PhysiCell-X_UserGuide.pdf** inside the documentation directory.
+ Add cell differentiation functionality to Phenotype, to be executed during cell division events.
+ Add a new standard phenotype function that uses mechanobiology, where high pressure can arrest cycle progression. (See https://twitter.com/MathCancer/status/1022555441518338048.)
+ Add module for standardized pharmacodynamics, as prototyped in the nanobio project. (See https://nanohub.org/resources/pc4nanobio.)
+ create an angiogenesis sample project
+ create a small library of angiogenesis and vascularization codes as an optional standard module in ./modules (but not as a core component)
+ improved plotting options in SVG
* * *
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