Metadata-Version: 2.4
Name: ventisim
Version: 0.1.0
Summary: Gymnasium environments for reinforcement learning in mechanical ventilation
Project-URL: Repository, https://github.com/HassDhia/ventisim
Project-URL: Documentation, https://github.com/HassDhia/ventisim#readme
Author-email: Hass Dhia <partners@smarttechinvest.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.10
Requires-Dist: gymnasium>=0.29
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.11
Provides-Extra: all
Requires-Dist: mypy; extra == 'all'
Requires-Dist: pytest-cov; extra == 'all'
Requires-Dist: pytest>=7.0; extra == 'all'
Requires-Dist: ruff; extra == 'all'
Requires-Dist: stable-baselines3>=2.0; extra == 'all'
Requires-Dist: torch>=2.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: train
Requires-Dist: stable-baselines3>=2.0; extra == 'train'
Requires-Dist: torch>=2.0; extra == 'train'
Description-Content-Type: text/markdown

# ventisim

**Gymnasium Environments for Reinforcement Learning in Mechanical Ventilation**

[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Tests](https://img.shields.io/badge/tests-230%20passed-brightgreen.svg)]()
[![PyPI](https://img.shields.io/pypi/v/ventisim.svg)](https://pypi.org/project/ventisim/)

VentiSim provides standardized [Gymnasium](https://gymnasium.farama.org/) environments for developing and benchmarking reinforcement learning algorithms applied to mechanical ventilation management. The environments model lung mechanics, gas exchange, and PEEP-dependent alveolar recruitment with physiologically grounded parameters derived from the ARDS literature.

## Installation

```bash
pip install ventisim
```

With training dependencies (stable-baselines3, PyTorch):

```bash
pip install ventisim[train]
```

Full development install:

```bash
pip install ventisim[all]
```

## Quick Start

```python
import gymnasium as gym
import ventisim  # registers environments

env = gym.make("ventisim/TidalVolumeControl-v0")
obs, info = env.reset(seed=42)

for step in range(200):
    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 | Obs Dim | Act Dim | Key Challenge |
|---|---|---|---|---|
| `ventisim/TidalVolumeControl-v0` | Pressure control | 7 | 1 | Deliver target VT (6 mL/kg IBW) while keeping plateau < 30 cmH2O |
| `ventisim/PEEPOptimization-v0` | PEEP titration | 8 | 1 | Balance recruitment vs. overdistension for optimal PaO2 |
| `ventisim/FullVentilatorManagement-v0` | Multi-parameter | 10 | 4 | Simultaneously optimize oxygenation, ventilation, and lung protection |

All environments support three difficulty tiers (`easy`, `medium`, `hard`) controlling inter-patient variability, compliance drift, and measurement noise.

## Architecture

```
Models Layer
  SingleCompartmentLung  -- RC-circuit lung mechanics (compliance, resistance)
  GasExchangeModel       -- Alveolar gas equation + shunt + PEEP recruitment
  VirtualPatient         -- ARDS severity profiles (Berlin definition)

Environments Layer (Gymnasium API)
  TidalVolumeControl-v0         -- 1D action: inspiratory pressure
  PEEPOptimization-v0           -- 1D action: PEEP change
  FullVentilatorManagement-v0   -- 4D action: FiO2, PEEP, RR, P_insp

Agents Layer
  Random                 -- Uniform random sampling (lower bound)
  Heuristic              -- Clinical protocol baselines (proportional control)
  PPO                    -- Proximal Policy Optimization via stable-baselines3
```

## Training

Train all agents and generate results:

```bash
python train_all.py
```

Train a single environment:

```bash
ventisim-train --env ventisim/TidalVolumeControl-v0
```

Run benchmarks (random + heuristic):

```bash
ventisim-benchmark
```

## Paper

If you use VentiSim in your research, please cite:

```bibtex
@software{dhia2026ventisim,
  author    = {Dhia, Hass},
  title     = {VentiSim: Gymnasium Environments for Reinforcement Learning
               in Mechanical Ventilation},
  year      = {2026},
  publisher = {Smart Technology Investments Research Institute},
  url       = {https://github.com/HassDhia/ventisim},
}
```

## License

MIT License. See [LICENSE](LICENSE) for details.

## Contact

Hass Dhia -- Smart Technology Investments Research Institute

partners@smarttechinvest.com
