A virion endocytosis tissue simulator

Simulate virus endocytosis (internalization), ACE2 receptor dynamics with PhysiCell

Launch Tool

You must login before you can run this tool.

Version 1.0 - published on 13 Apr 2020

doi:10.21981/NWXR-KE91 cite this

Open source: license | download

View All Supporting Documents



Published on


Virion endocytosis tissue simulator

This model simulates SARS-CoV-2 (coronavirus / COVID19) endocytosis, please see PhysiCell model for COVID19 for whole model information. It is being rapidly prototyped and refined with community support (see below).

In this model, SARS-CoV-2 (coronavirus / COVID19) infects a single cell, or a solution of virions is administered to the extracellular space. In the extracellular space, virions adhere to ACE2 receptors and get internalized through endocytosis. Internalized ACE2 receptors release their virus cargo and are recycled back to the surface.

Please cite this project via the preprint:

M. Getz et al., Rapid community-driven development of a SARS-CoV-2 tissue simulator. bioRxiv 2020.04.02.019075, 2020, (Preprint). doi: 10.1101/2020.04.02.019075.


  • Circles: These are lung epithelial cells. They are colored by their (assembled) virion loads in four colors
    • dark blue----: Cells with 0 assembled virions.
    • pale blue----: Cells with 1-9 assembled virions.
    • grey---------: Cells with 10-99 assembled virions.
    • light yellow-: Cells with 100-999 assembled virions.
    • bright yellow: Cells with 1000+ assembled virions.
    Black cells are apoptotic (dead from viral load).
  • Background: Contour plot of released virus that is diffusing in and above the tissue.

Caveats and disclaimers

This model is under active development using rapid prototyping:

  • It has not been peer reviewed.
  • It is intended to drive basic scientific research and public education at this stage.
  • It cannot be used for public policy decisions.
  • It cannot be used for individual medical decisions.

This model will be continually refined with input from the community, particularly experts in infectious diseases. The validation state will be updated as this progresses.

GUI Overview

  • Config Basics tab:    input parameters common to all models (e.g., domain grid, simulation time, choice/frequency of outputs)
  • Microenvironment tab:   microenvironment parameters that are model-specific
  • User Params tab:      user parameters that are model-specific
  • Out: Plots tab:           output display of cells and substrates
  • Animate tab:              generate an animation of cells

Clicking the 'Run' button will use the specified parameters and start a simulation. When clicked, it creates an "Output" widget that can be clicked/expanded to reveal the progress of the simulation. When the simulation generates output files, they can be visualized in the "Out: Plots" tab. The "# cell frames" will be dynamically updated as those output files are generated by the running simulation. When the "Run" button is clicked, it toggles to a "Cancel" button that will terminate (not pause) the simulation.

Model details

This model is being rapidly prototyped. Biological and mathematical detail can be found at:

We request community help in estimating parameters and improving model assumptions at the link above.

This model and cloud-hosted demo are part of the education and outreach for the IU Engineered nanoBIO Node and the NCI-funded cancer systems biology grant U01CA232137. The models are built using PhysiCell: a C++ framework for multicellular systems biology.

Basic instructions

Modify parameters in the "Config Basics", "Microenvironment", or "User Params" tabs. Click the "Run" button once you are ready.

To view the output results, click the "Out: Plots" tab, and move the slider bar to advance through simulation frames. Note that as the simulation runs, the "# cell frames" field will increase, so you can view more simulation frames.

If there are multiple substrates defined in the Microenvironment, you can select a different one from the drop-down widget in the Plots tab. You can also fix the colormap range of values.

Note that you can download full simulation data for further exploration in your tools of choice. And you can also generate an animation of the cells to play in the browser and, optionally, download as a video.

About the software:

This model and cloud-hosted demo are part of the education and outreach for the IU Engineered nanoBIO Node and the NCI-funded cancer systems biology grant U01CA232137. The models are built using PhysiCell: a C++ framework for multicellular systems biology [1] for the core simulation engine and xml2jupyter [2] to create the graphical user interface (GUI).

  1. A. Ghaffarizadeh, R. Heiland, S.H. Friedman, S.M. Mumenthaler, and P. Macklin. PhysiCell: an open source physics-based cell simulator for 3-D multicellular systems. PLoS Comput. Biol. 14(2):e1005991, 2018. DOI: 10.1371/journal.pcbi.1005991.
  2. R. Heiland, D. Mishler, T. Zhang, E. Bower, and P. Macklin. xml2jupyter: Mapping parameters between XML and Jupyter widgets. Journal of Open Source Software 4(39):1408, 2019. DOI: 10.21105/joss.01408.

Powered by

This software is powered by PhysiCell [1-2], a powerful simulation tool that combines multi-substrate diffusive transport and off-lattice cell models. PhysiCell is BSD-licensed, and available at:

It is a C++, cross-platform code with minimal software dependencies. It has been tested and deployed in Linux, BSD, OSX, Windows, and other environments, using the standard g++ compiler. 

See http://PhysiCell.MathCancer.org.

The Jupyter-based GUI was auto-generated by xml2jupyter [3], a technique to create graphical user interfaces for command-line scientific applications.


[1] Ghaffarizadeh A, Heiland R, Friedman SH, Mumenthaler SM, Macklin P (2018) PhysiCell: An open source physics-based cell simulator for 3-D multicellular systems. PLoS Comput Biol 14(2): e1005991. https://dx.doi.org/10.1371/journal.pcbi.1005991

[2] Ghaffarizadeh A, Friedman SH, Macklin P (2016) BioFVM: an efficient, parallelized diffusive transport solver for 3-D biological simulations. Bioinformatics 32(8):1256-8. https://dx.doi.org/10.1093/bioinformatics/btv730

[3] Heiland R, Mishler D, Zhang T, Bower E, Macklin P (2019) Xml2jupyter: Mapping parameters between XML and Jupyter widgets. J Open Source Software 4(39):1408. https://dx.doi.org/10.21105/joss.01408  

[4] M. Getz et al. (2020) Rapid community-driven development of a SARS-CoV-2 tissue simulator. bioRxiv preprint 2020.04.02.019075. https://doi.org/10.1101/2020.04.02.019075

[5] Heiland R et al. (2020) PhysiCell model for COVID19. nanoHUB apphttps://nanohub.org/tools/pc4covid19


Cite this work

Researchers should cite this work as follows:

  • Yafei Wang, Randy Heiland, Paul Macklin (2020), "A virion endocytosis tissue simulator," https://nanohub.org/resources/virion2receptor. (DOI: 10.21981/NWXR-KE91).

    BibTex | EndNote