jxx123/simglucose

simglucose – 用於強化學習研究的1型糖尿病模擬器

是什麼 – simglucose 是一個 Python 套件，重現了 FDA 批准的 UVa/Padova T1-D 糖尿病模擬器（2008 年版）。它提供一個虛擬病患環境，可由任何控制演算法（傳統 PID、模型預測控制或學習代理）驅動，並打包為與 OpenAI Gym（及 Gymnasium）API 相容的環境，使其「具備強化學習就緒」。

為何重要 – 訓練或評估用於血糖控制的 RL 代理通常成本高昂且風險高。simglucose 提供 30 名預先定義的虛擬病患（10 名青少年、10 名成人、10 名兒童），具有現實的生理參數，讓研究人員能快速、可重複地測試胰島素投遞策略。

---

主要功能（如 README 所述）

• Gym 相容環境 – 實作標準的 observation, reward, done, info 步驟簽名。支援 gym 與更新的 gymnasium 套件。
• 可自訂獎勵 – 預設獎勵為臨床風險指數的降低；使用者可提供基於過去一小時血糖值的任意函數。
• 平行模擬 – 可透過 pathos 多處理庫同時模擬多個病患（可選，可停用）。
• 情境產生 – 內建隨機情境產生器與 CustomScenario 類別，供使用者自訂進食時間/大小序列。
• 控制器架構 – 提供最小的基礎-追加控制器與簡單基底類別（Controller），使用者可擴充以插入自己的演算法（PID、MPC、RL 等）。
• 可視化 – 執行後可自動繪製葡萄糖軌跡、CVGA（控制變異性格網分析）、區域統計與風險指數摘要。
• 命令列 UI – 互動式 CLI（simulate()）可引導使用者無需撰寫程式碼即可完成情境設定。
• 支援 rllab – 可選整合 rllab 強化學習套件，用於 DDPG 等進階演算法。

---

安裝

# 推薦 – 從 PyPI 安裝
pip install simglucose

# 取得最新程式碼或本地開發
git clone https://github.com/jxx123/simglucose.git
cd simglucose
pip install -e .   # 可編輯安裝

需要 Python ≥ 3.9（3.7/3.8 已不再支援）

---

快速入門範例（Gym）

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

# 定義一個簡單的進食情境
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()   # 隨機基礎胰島素
    obs, reward, done, info = env.step(action)
    if done:
        break

相同環境可與任何期望 Gym 接口的 RL 套件一起使用。

---

使用自訂控制器

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):
        # 非常簡單的策略 – 不注射胰島素
        return Action(basal=0, bolus=0)
    def reset(self):
        self.state = 0

simulate(controller=MyController(0))

將 MyController 替換為學習策略、PID 等，模擬器將提供觀測並收集獎勵。

---

高階批次模擬

README 中說明如何建立 SimObj 物件，個別使用 sim() 執行，或使用 batch_sim(parallel=True) 並行執行多個。這對於超參數掃描或在全病患群體中比較多個控制器非常有用。

---

文件與資源

• 病患參數表 – definitions_of_vpatient_parameters.md 列出每位虛擬病患的生理常數。
• 風險指數 – 預設獎勵使用《糖尿病技術與治療》（2008）中的臨床風險指標。
• 範例 – 倉儲包含 examples/ 目錄下的可執行腳本，涵蓋 Gym、Gymnasium、PID 控制與離線分析。
• 引用 – 若發表成果，請引用：Jinyu Xie. Simglucose v0.2.1 (2018). https://github.com/jxx123/simglucose。

---

適用對象

• 強化學習研究者：建構胰島素投遞代理。
• 生物醫學工程師：在臨床試驗前原型化控制演算法。
• 教育工作者：在課堂上示範閉迴路血糖控制。

---

提及的限制

• 由於 Matplotlib 線程安全性問題，macOS 上無法同時啟用 animate 與 parallel。
• Windows 支援尚未測試。
• 本套件僅供研究使用；非醫療設備。

---

社群

歡迎透過 GitHub 問題追蹤器提交問題與拉取請求。貢獻指南遵循 scikit-learn 模式（分叉 → 分支 → PR）。

---

結論 – simglucose 提供一個真實、開源的 T1-D 模擬環境，可直接接入標準 RL 工具鏈，支援快速開發與基準測試血糖控制演算法。