Header:

• Language: C++11 and Python >= 3.9
• Software dependencies: PhysiCell >= v1.14.2
• Python library dependencies: gymnasium, lxml, matplotlib, numpy, pandas, (ipython, PyQt6)
• Operating system dependencies: compiles on Linux, Windows Subsystem for Linux, and Mac OS X.
• Author: Alexandre Bertin, Elmar Bucher
• Date: 2024-spring
• Doi:
• License: BSD-3-Clause
• User manual: this README.md file
• Source code: https://github.com/Dante-Berth/PhysiGym

Abstract:

PhysiCell is a physics-based cell simulator for 3D multicellular systems. More precisely, PhysiCell is an agent-based model and diffusion transport solver that is off-lattice, center-based, multiscale in space and time, and written in C++.

Gymnasium is the API standard for reinforcement learning, written in Python.

The Python-based physigym module presented here was written on top of the python_with_physicell extending module from the physicellembedding project, which makes it possible to extend the python interpreter to interact with PhysiCell models in the Python language.

Both, physigym and extending, are PhysiCell custom_modules.

Walking through the tutorial, you will gain the understanding needed to tackle more complex PhysiCell-based reinforcement learning projects. First, you will set up a very basic template model that can figure as a starting point for your own project. Then you will learn on a somewhat more complex tumor_immune_base model how to deep reinforcement learn a policy using the sac (soft actor critic) algorithm.

Limitations: Because of the way how PhysiCell is implemented and run, it is not possible to generate more than one PhysiCell Gymnasium environment per runtime. A runtime warning will be thrown if you try to do so.

May the force be with you!

🧩 HowTo Guide:

• install PhysiCell
• install and troubleshoot the physigym user_project
• uninstall the physigym user_project

🧩 Tutorial:

• physigym modelling tutorial
• physigym reinforcement learning tutorial

🧩 Reference Manual:

• reference manual
• class ModelPhysiCellEnv gymnasium environment structure

Discussion:

To be developed.

About Documentation:

Within the PhysiGym library, we tried to stick to the documentation policy laid out by Daniele Procida in his "what nobody tells you about documentation" talk at PyCon 2017 in Portland, Oregon.

Contributions:

• Concept and implementation: Alexandre Bertin, Elmar Bucher
• Involved: Emmanuel Rachelson, Heber Lima da Rocha, Marcelo Hurtado, Owen Griere, Paul Macklin, Randy Heiland, Vera Pancaldi, Vincent François

If you like to contribute to the software with models or rl algorithms, please make a pull request to the development branch.

Funding:

This material is based upon research supported by the Chateaubriand Fellowship from the Office for Science & Technology from the Embassy of France in the United States, the Occitanie Region Toulouse, France, and Inserm, France.

Cite:

To be BibTeX.

Road Map:

• Add more models and rl algorithm.

Release Notes:

• 1.0.0 (2025-07-14): public beta release.
• 0.4.1 (2025-06-21): bue ok release.
• 0.4.0 (2025-02-28): models, rl, os portability, unit tests, and documentation complete.
• 0.3.1 (2025-02-05): custom_modules/embedding to custom_module/extending change.
• 0.3.0 (2025-01-16): complete physigym PhysiCell >= v1.14.2 compatibility.
• 0.2.1 (2024-11-29): physicell gymnasium environment limitation handling.
• 0.2.0 (2024-10-27): physigym PhysiCell v1.13.1 to v1.14.n adaption.
• 0.1.0 (2024-06-20): the basic physigym implementation works.
• 0.0.0 (2024-04-15): physigym rises from the ashes.