AMMPER (Agent-based Model for Microbial Populations Exposed to Radiation) simulates how ionizing radiation affects a growing population of yeast (Saccharomyces cerevisiae). Every cell is an individual agent on a 3D lattice that moves, divides, takes direct radiation damage and damage from reactive oxygen species (ROS), and repairs DNA. It models the two strains flown on NASA's BioSentinel mission (wild type and the radiation-sensitive rad51Δ mutant) under 150 MeV proton, gamma, NSRL GCRSim, and deep-space radiation, and you can drive it from a command line or a desktop GUI.
Note
AMMPER is research software. It's meant for studying radiation biology and for teaching. Don't use it for clinical or operational radiation-risk decisions.
A rad51Δ colony growing over 15 generations after 10 Gy of 150 MeV protons
Blue circles: healthy cells · orange stars: dead · green: radiation energy deposits.
Important
AMMPER needs Python 3.9, 3.10, or 3.11 (python.org/downloads).
Check with python3 --version (macOS/Linux) or py --version (Windows).
On Windows with several versions installed, use py -3.11 in place of
python3 below, e.g. py -3.11 -m venv venv.
From a clone of this repository:
python3 -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install --upgrade pip setuptools wheel
pip install -e .| Command | What it does |
|---|---|
ammper setup |
Checks that dependencies and data are in place, and warns if your machine lacks the memory for the heavier Complex ROS runs |
ammper quickstart |
Runs a short tutorial simulation (a few seconds), no questions asked |
ammper run |
Runs a full simulation, asking you for radiation type, dose, cell type, and ROS model |
ammper gui |
Opens the desktop GUI |
ammper data status |
Shows which RITRACKS radiation-track folders are on this machine |
ammper data verify |
Re-checks those folders against the dataset manifest |
ammper data pull |
Downloads RITRACKS folders from Zenodo: everything, or just what a run needs (gcrsim, deep-space) |
ammper |
With no arguments, opens a guided menu that picks one of the above |
ammper --help |
Everything above, plus options |
Start with ammper setup, then ammper quickstart. The tutorial saves its
output to results/bulk_aB/quickstart/ and prints the exact path when it
finishes.
Tip
You can launch ammper run and ammper gui from any folder. In a clone, results go to
results/ inside the repository (interactive runs: results/single_runs/); in a normal
install they go to ~/ammper/results/. Set AMMPER_HOME to put them (and downloaded
radiation data) somewhere else.
A normal git clone already contains everything the four radiation types need, so every
preset in the CLI and the GUI works offline, with no flags and no downloads.
The full RITRACKS dataset has 49 proton-energy folders and is published on Zenodo
(doi:10.5281/zenodo.22992521); ammper data pull downloads any missing data.
Main menu
Simulation setup
Simulation running
Results: the colony at generations 1, 5, 9, 12 and 15
ammper quickstart: a tutorial run, no prompts
ammper run: an interactive simulation
The ammper command is all you need for single simulations. For batches of
runs, or to rebuild figures, you can call the scripts directly. They find
their own paths, so they work from any folder.
# One simulation: radType cellType ROSType dose outputFolder
# radType a = 150 MeV Proton b = GCRSim c = Deep Space d = Gamma
# cellType a = wild type b = rad51
# ROSType a = Basic b = Complex (warns if your machine is short of memory)
# dose Proton: 0, 2.5, 5, 10, 20, 30 · others: any placeholder
python3 -m ammper.AMMPERBulk_aB a a a 2.5 WT_Basic_25Output goes to results/bulk_aB/<outputFolder>/. Use the single-letter
codes; spelled-out names like "150 MeV Proton" won't work.
Figures:
python3 analysis/growth_curves/stack_growth_curves.py # main text Figure 1
python3 analysis/aB/ab_final_plots_panel.py # main text Figure 2 (panels)
python3 analysis/aB/stack_ab_figures.py # main text Figure 2 (stack)In your own scripts, resolve paths through
ammper_paths instead of hardcoding them:
import ammper_paths as P
df = pd.read_csv(P.ab_experimental("AlamarblueRawdataWTKGy.csv"))
sim = P.bulk_aB("WT_Basic_0")
out = P.figures("my_panel.png") # creates figures/ if needed(Code inside src/ammper/ uses from ammper import paths as P; see
CONTRIBUTING.md.)
src/ammper/ the simulation (installed as the `ammper` package)
cli.py the `ammper` command
AMMPERCLI.py interactive simulation (`ammper run`)
AMMPERBulk_aB.py non-interactive runner (quickstart, scripts, batches)
cellDefinition.py the Cell agent: movement, division, damage, repair
genTraverse_*.py radiation tracks (ground-test and deep-space)
genROSOld.py ROS model (Basic)
GammaRadGen.py gamma radiation events
cellPlot*.py per-generation 3D plots
paths.py path resolution
gui/ desktop GUI (PyQt5) with its fonts and images (`ammper gui`)
data/ read-only data that ships with the package: fluence tables, apoptosis data,
the Zenodo MANIFEST.json and the 150 MeV RITRACKS folder
data/
radiation_input/ RITRACKS folders you download with `ammper data pull` (in a clone)
experimental/ alamarBlue and BioSentinel measurements (manuscript analysis inputs)
analysis/ alamarBlue fitting, growth curves, ROS and gamma analysis
revisions_2026/ manuscript revision code and figures
results/ simulation output
tests/ test suite (`pytest`)
docs/ documentation assets
If you use AMMPER in your work, please cite:
Singh A., Santa Maria S. R., Gentry D. M., Liddell L. C., Lera M. P., Lee J. A. Agent-based Model for Microbial Populations Exposed to Radiation (AMMPER) simulates yeast growth for deep-space experiments. Gravitational and Space Research 12(1):159–176 (2024). doi:10.2478/gsr-2024-0012
See CONTRIBUTING.md. Run the tests with:
pip install -e ".[dev]"
pytestReleased under the NASA Open Source Agreement 1.3.
- Coded and created by Amrita Singh and Daniel Palacios
- Conceptualized by Amrita Singh
- Graphical user interface design by Madeline Marous
- Logo design by Madeline Marous and Sam Lino
- Additional software support by Danny Mejia
- Repository control, open-source distribution, and oversight by Dr. Jessica A. Lee
Created at NASA Ames Research Center.