# oncosim

**Gymnasium environments for reinforcement learning in radiation therapy treatment planning.**

![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
![Tests](https://img.shields.io/badge/tests-100%2B%20passing-brightgreen.svg)
[![PyPI version](https://img.shields.io/pypi/v/oncosim.svg)](https://pypi.org/project/oncosim/)

---

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

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

Development install:

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

## Quick Start

```python
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:

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

## Training

Train PPO agents on all environments:

```bash
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)](https://github.com/HassDhia/oncosim/blob/main/paper/oncosim.pdf)

## Citation

If you use oncosim in your research, please cite:

```bibtex
@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](LICENSE) for details.

## Contact

Hass Dhia -- Smart Technology Investments Research Institute
- Email: partners@smarttechinvest.com
- Web: [smarttechinvest.com/research](https://smarttechinvest.com/research)
