immunosim

Gymnasium environments for reinforcement learning in cancer immunotherapy optimization

ImmunoSim provides four Gymnasium-compatible reinforcement learning environments for optimizing cancer immunotherapy treatment schedules. Each environment wraps validated mathematical models from the tumor immunology literature, enabling RL agents to discover dosing strategies that outperform standard clinical protocols.

The package implements ODE-based tumor-immune dynamics from Kuznetsov-Taylor (1994), checkpoint inhibitor pharmacodynamics from Nikolopoulou (2018, 2021), CAR-T cell kinetics from Barros CARTmath (2021), and cytokine release syndrome modeling from Santurio (2025).

Installation

pip install immunosim              # Core (numpy, scipy, gymnasium)
pip install immunosim[train]       # + SB3, PyTorch for RL training
pip install immunosim[all]         # Everything

Development install:

git clone https://github.com/HassDhia/immunosim.git
cd immunosim
pip install -e ".[all]"

Quick Start

import gymnasium as gym
import immunosim

env = gym.make("immunosim/CheckpointInhibitor-v0")
obs, info = env.reset(seed=42)
for _ in range(100):
    action = env.action_space.sample()
    obs, reward, terminated, truncated, info = env.step(action)
    if terminated or truncated:
        obs, info = env.reset()
env.close()

Environments

Architecture

immunosim/
  models/
    tumor_immune.py      -- Kuznetsov-Taylor (1994) 2-ODE base model
    checkpoint_inhibitor.py -- Anti-PD-1, Anti-CTLA-4, Dual checkpoint modules
    cart_cell.py         -- CARTmath (Barros 2021) + CRS (Santurio 2025)
    patient.py           -- Domain randomization + pseudo-progression detection
  envs/
    checkpoint_inhibitor.py  -- CheckpointInhibitorEnv-v0
    combination_therapy.py   -- CombinationTherapyEnv-v0
    cart_cell.py             -- CARTCellEnv-v0
    adaptive_dosing.py       -- AdaptiveDosingEnv-v0
  agents/
    random_agent.py      -- Random baseline
    heuristic_agent.py   -- Clinical protocol heuristics
    ppo.py               -- PPO via stable-baselines3
  training/
    configs.py           -- Shared ENV_CONFIGS
    train_all.py         -- Train all environments
  benchmarks/
    runner.py            -- Performance benchmarking

Paper

The accompanying paper is available at:

• PDF (GitHub)

Citation

If you use immunosim in your research, please cite:

@software{dhia2026immunosim,
  author = {Dhia, Hass},
  title = {ImmunoSim: Gymnasium Environments for Reinforcement Learning in Cancer Immunotherapy Optimization},
  year = {2026},
  publisher = {Smart Technology Investments Research Institute},
  url = {https://github.com/HassDhia/immunosim}
}

License

MIT License. See LICENSE for details.

Contact

Hass Dhia -- Smart Technology Investments Research Institute

• Email: partners@smarttechinvest.com
• Web: smarttechinvest.com/research