jxx123/simglucose

simglucose – A Type‑1 Diabetes Simulator for Reinforcement‑Learning Research

What it is – simglucose is a Python package that reproduces the FDA‑approved UVa/Padova T1‑D diabetes simulator (2008 version). It provides a virtual patient environment that can be driven by any control algorithm – classic PID, model‑predictive control, or a learning agent – and is packaged to work with the OpenAI Gym (and Gymnasium) API, making it “reinforcement‑learning‑ready”.

Why it matters – Training or evaluating RL agents for glucose‑control is otherwise expensive and risky. simglucose offers 30 pre‑defined virtual patients (10 adolescents, 10 adults, 10 children) with realistic physiological parameters, so researchers can run fast, reproducible experiments on insulin‑delivery policies.

---

Key Features (as described in the README)

• Gym‑compatible environment – Implements the standard observation, reward, done, info step signature. Works with both gym and the newer gymnasium libraries.
• Customizable reward – Default reward is the reduction in a clinical risk index; users can supply any function of the last‑hour blood‑glucose values.
• Parallel simulation – Multiple patients can be simulated concurrently via the pathos multiprocessing library (optional, can be disabled).
• Scenario generation – Built‑in random scenario generator and a CustomScenario class for user‑defined meal‑time/size sequences.
• Controller scaffolding – Provides a minimal basal‑bolus controller and a simple base class (Controller) that users extend to plug in their own algorithms (PID, MPC, RL, etc.).
• Visualization – After a run the package can automatically plot glucose traces, CVGA (Control Variability Grid Analysis), zone statistics, and risk‑index summaries.
• Command‑line UI – An interactive CLI (simulate()) walks users through scenario setup without writing code.
• Support for rllab – Optional integration with the rllab reinforcement‑learning library for advanced algorithms like DDPG.

---

Installation

# Recommended – install from PyPI
pip install simglucose

# For the latest code or to develop locally
git clone https://github.com/jxx123/simglucose.git
cd simglucose
pip install -e .   # editable install

Python ≥ 3.9 is required (3.7/3.8 are no longer supported).

---

Quick‑Start Example (Gym)

import gym
from gym.envs.registration import register
from simglucose.simulation.scenario import CustomScenario
from datetime import datetime

# Define a simple meal scenario
scenario = CustomScenario(start_time=datetime(2018,1,1), scenario=[(1,20)])

register(
    id='simglucose-adolescent2-v0',
    entry_point='simglucose.envs:T1DSimEnv',
    kwargs={'patient_name': 'adolescent#002', 'custom_scenario': scenario}
)

env = gym.make('simglucose-adolescent2-v0')
obs = env.reset()
for t in range(100):
    env.render(mode='human')
    action = env.action_space.sample()   # random basal insulin
    obs, reward, done, info = env.step(action)
    if done:
        break

The same environment can be used with any RL library that expects a Gym interface.

---

Using a Custom Controller

from simglucose.simulation.user_interface import simulate
from simglucose.controller.base import Controller, Action

class MyController(Controller):
    def __init__(self, init_state):
        self.state = init_state
    def policy(self, observation, reward, done, **info):
        # Very simple policy – no insulin
        return Action(basal=0, bolus=0)
    def reset(self):
        self.state = 0

simulate(controller=MyController(0))

Replace MyController with a learned policy, PID, etc., and the simulator will feed it observations and collect rewards.

---

Advanced Batch Simulation

The README shows how to build SimObj objects, run them individually with sim(), or run many in parallel with batch_sim(parallel=True). This is useful for hyper‑parameter sweeps or comparing multiple controllers across the full patient cohort.

---

Documentation & Resources

• Patient parameter sheet – definitions_of_vpatient_parameters.md lists the physiological constants for each virtual patient.
• Risk index – The default reward uses the clinical risk metric from Diabetes Technology & Therapeutics (2008).
• Examples – The repository includes ready‑to‑run scripts under examples/ for Gym, Gymnasium, PID control, and offline analysis.
• Citation – If you publish results, cite: Jinyu Xie. Simglucose v0.2.1 (2018). https://github.com/jxx123/simglucose.

---

Who Might Use This

• Reinforcement‑learning researchers building insulin‑delivery agents.
• Biomedical engineers prototyping control algorithms before clinical trials.
• Educators demonstrating closed‑loop glucose control in a classroom setting.

---

Limitations Mentioned

• animate and parallel cannot both be True on macOS due to Matplotlib thread‑safety.
• Windows support is untested.
• The package is for research only; it is not a medical device.

---

Community

Issues and pull‑requests are welcomed via the GitHub issue tracker. Contribution guidelines follow the scikit‑learn model (fork → branch → PR).

---

Bottom line – simglucose provides a realistic, open‑source T1‑D simulation environment that plugs directly into standard RL toolchains, enabling rapid development and benchmarking of glucose‑control algorithms.