oncosim 0.1.0

Gymnasium-compatible RL environments for radiation therapy treatment planning

oncosim

Gymnasium environments for reinforcement learning in radiation therapy treatment planning.

---

OncoSim provides three Gymnasium-compatible reinforcement learning environments for radiation therapy treatment planning research. Each environment models a distinct clinical decision problem with physically grounded dynamics based on the linear-quadratic model of cell kill, Poisson TCP, and Lyman-Kutcher-Burman NTCP.

The package includes analytical dose calculation, radiobiological tissue models, configurable difficulty tiers, baseline agents (random, heuristic, PPO), and a benchmark suite for reproducible evaluation.

Installation

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

Development install:

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

Quick Start

import gymnasium as gym
import oncosim

env = gym.make("oncosim/BeamSelection-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

Environment	Paradigm	Observation	Action	Key Challenge
oncosim/BeamSelection-v0	Beam angle optimization	64x64 dose grid, tumor/OAR masks, selected beams	Discrete(36): angle index at 10-degree steps	Maximize tumor coverage while sparing organs at risk
oncosim/DoseFractionation-v0	Fractionation scheduling	Fraction number, tumor volume, cumulative dose, TCP, NTCP	Box(0.5, 4.0): dose per fraction in Gy	Balance tumor control probability against normal tissue toxicity
oncosim/AdaptiveRT-v0	Adaptive replanning	Treatment progress, plan quality, tumor response, dose deviation	MultiDiscrete([2, 5]): replan decision + dose adjustment	Decide when to replan based on anatomical changes during treatment

All environments support configurable difficulty tiers and deterministic seeding for reproducibility.

Architecture

oncosim/
  physics/          # Dose calculation, tissue models, beam geometry
    dose_calc.py    # Pencil beam analytical model
    tissue_models.py # LQ surviving fraction, TCP, NTCP, BED
    beam_geometry.py # 2D beam profiles, structure masks, DVH
  envs/             # Gymnasium environments
    beam_selection.py
    dose_fractionation.py
    adaptive_rt.py
    wrappers.py     # FlattenObs, NormalizeReward
  agents/           # Baseline agents
    random_agent.py
    heuristic_agent.py
    ppo.py          # Stable-Baselines3 PPO wrapper
  training/         # Training and evaluation pipeline
  benchmarks/       # Configurable benchmark suite (5 difficulty tiers)

Benchmarks

Run the benchmark suite:

oncosim-benchmark                          # All tiers
oncosim-benchmark --tiers trivial easy     # Specific tiers

Training

Train PPO agents on all environments:

pip install oncosim[train]
oncosim-train                              # Default: 100k timesteps each
oncosim-train --timesteps 500000           # Custom timesteps

Paper

The accompanying paper is available at:

• PDF (GitHub)

Citation

If you use oncosim in your research, please cite:

@software{dhia2026oncosim,
  author = {Dhia, Hass},
  title = {OncoSim: Gymnasium Environments for Reinforcement Learning in Radiation Therapy Treatment Planning},
  year = {2026},
  publisher = {Smart Technology Investments Research Institute},
  url = {https://github.com/HassDhia/oncosim}
}

License

MIT License. See LICENSE for details.

Contact

Hass Dhia -- Smart Technology Investments Research Institute

• Email: [e-mail]
• Web: smarttechinvest.com/research