microstateledger 0.1.0

Microstate version-control system for drug discovery workflows

MicrostateLedger

MicrostateLedger 是一个面向药物发现流程的“微观态版本控制系统”。

它把分子在不同阶段的状态变化（质子化、互变异构、手性/EZ、构象、配位）转成可追溯、可比较、可回滚的数据资产，覆盖从 RDKit 到 Docking、MD 的工程链路。

目录

• 1. 项目定位
• 2. 核心能力
• 3. 架构总览
• 4. 仓库结构
• 5. 环境要求
• 6. 安装方式
• 7. 快速开始
• 8. 配置说明
• 9. 命令手册
• 10. 数据模型与ID规则
• 11. 映射与可逆性
• 12. 可复现与审计
• 13. 终极门禁（Ultimate Release Gate）
• 14. GitHub 与 PyPI 发布前清单
• 15. 常见问题
• 16. 许可证

---

1. 项目定位

MicrostateLedger 解决的是“化学正确性 + 工程可追踪性”双重问题：

• 化学侧：同一化合物存在多微观态，不同软件阶段可能引入状态漂移。
• 工程侧：跨软件格式转换导致原子编号重排，团队复现困难。

项目目标：

1. 每个微观态都有稳定 ID。
2. 每一步选择都有 decision 记录。
3. 每个输出工件都有哈希与 run 关联。
4. 异常能自动回指并给出动作建议。
5. 支持 diff / rollback / provenance 导出。

---

2. 核心能力

• 稳定对象标识：CompoundID / MicrostateID / ConformerID / PoseID / ArtifactID
• 微观态枚举：protonation / tautomer / stereo
• 构象生成：RDKit ETKDG + PEAS（按策略自动选择）
• Docking 链路：PDBQT 导出、pose 入账、Top-k 选择
• 电荷链路：gasteiger / PyPE_RESP 输入与输出对齐
• MD 参数化：OpenFF Interchange + OpenMM/GROMACS/AMBER 工件
• 异常闭环：手性翻转、E/Z 漂移、化学式变化检测与建议
• 可复现工程：SQLite ledger、artifact 哈希、commands log、gate report

---

3. 架构总览

三层架构：

1. Ledger Core（msl/）

• 配置解析、ID、DB schema、CLI orchestration。

2. Driver Scripts（scripts/ + msl/resources/scripts/）

• RDKit、PEAS、Meeko、OpenFF、PyPE_RESP 等具体执行脚本。

3. Artifact 层（运行时目录）

• objects/、runs/、reports/ 等工件与报告目录（通常不入库）。

典型流程：

ingest -> perceive -> enumerate -> conformers -> dock-prep/dock-ingest -> charge -> md-param -> md-feedback

---

4. 仓库结构

MicrostateLedger/
  msl/                     # 核心包
  scripts/                 # 可直接运行的驱动脚本
  msl/resources/           # 打包内置资源（fallback）
  schemas/ledger.sql       # SQLite schema
  policies/default.yaml    # 默认策略
  tests/                   # 单元与回归测试
  docs/                    # 说明文档
  pyproject.toml           # 打包与依赖定义
  msl.toml                 # 运行配置样例

说明：

• msl/resources/* 与仓库同名资源是双轨设计。
• 当仓库脚本不可用时，CLI 会自动 fallback 到 ~/.microstateledger/resources/<version>/。

---

5. 环境要求

推荐：

• OS：Linux
• Python：>=3.10
• 包管理：pip（核心）+ conda（多工具环境隔离）

核心 Python 依赖（自动安装）：

• typer>=0.9
• pyyaml>=6
• tomli（仅 Python < 3.11）

可选能力依赖（按需）：

• cheminformatics：RDKit / Dimorphite
• docking：Meeko / Vina
• md：OpenFF toolkit / Interchange / OpenMM
• repro：DVC / DataLad

---

6. 安装方式

6.1 开发/源码安装（推荐）

git clone <your-repo-url>
cd MicrostateLedger
python -m pip install -e .

如果网络代理或离线限制导致 build isolation 拉依赖失败，可用：

python -m pip install -e . --no-build-isolation --no-deps

6.2 从构建产物安装（wheel）

python -m pip install dist/microstateledger-0.1.0-py3-none-any.whl

6.3 PyPI 现状

当前版本 0.1.0 尚未公开发布到 PyPI，因此直接执行：

pip install MicrostateLedger

会返回 No matching distribution found。发布后再改用该命令。

6.4 server 专用 wrapper 脚本说明

bin/msl、bin/rdkit_python 等脚本是服务器路径硬编码包装器（包含固定 ROOT 和 CONDA 路径）。

在新机器上：

• 要么修改这些脚本里的路径；
• 要么直接使用可移植命令：python -m msl.cli ...。

---

7. 快速开始

7.1 初始化

python -m msl.cli init --config msl.toml
python -m msl.cli migrate --config msl.toml

7.2 从 SMILES 到微观态

CID=$(python -m msl.cli ingest "CCO" --config msl.toml)
python -m msl.cli perceive "$CID" --config msl.toml
python -m msl.cli enumerate "$CID" --config msl.toml

7.3 构象与 docking 准备

MID=<your_microstate_id>
python -m msl.cli conformers "$MID" --method rdkit --n 20 --topk 5 --seed 20260206 --config msl.toml
python -m msl.cli dock-prep "$MID" <conformer_id> --config msl.toml

7.4 电荷与 MD 参数化

python -m msl.cli charge "$MID" --method gasteiger --config msl.toml
python -m msl.cli md-param "$MID" --config msl.toml

7.5 MD 反馈

python -m msl.cli md-feedback "$MID" <probe_snapshot.sdf> --config msl.toml

7.6 一键 demo

python -m msl.cli demo CCO --out-dir ./demo_runs --config msl.toml

---

8. 配置说明

8.1 msl.toml

[project]
name = "MicrostateLedger"
root = "/path/to/MicrostateLedger"
objects_dir = "objects"
runs_dir = "runs"
reports_dir = "reports"
policy = "policies/default.yaml"
ledger_db = "ledger.sqlite"

[envs]
conda = "/path/to/conda"
base_dir = "envs"

[logging]
level = "INFO"
log_dir = "logs"

关键点：

• root 决定相对目录的解析基准。
• envs.base_dir 对应多工具环境根目录。
• policy 是所有阶段决策的上游输入。

8.2 policies/default.yaml

主键说明：

• project.ph：感知与枚举 pH 范围
• project.max_microstates：全局微观态上限
• stages.pre_docking_enum.*：枚举与 Top-k 策略
• stages.conformer_generation.*：构象方法与筛选
• stages.docking.*：pose 选择策略
• stages.pre_md.*：电荷、参数化、最终态选择
• stages.md_feedback.*：异常检查开关

---

9. 命令手册

CLI 总览：

msl --help

主要命令组：

9.1 初始化与数据库

• init：初始化 ledger
• migrate：schema 迁移

9.2 化学流程主链

• ingest：标准化并注册 compound
• perceive：风险感知
• enumerate：枚举微观态
• conformers：生成构象
• dock-prep / dock-ingest / dock-select
• charge：电荷生成或导入
• md-param：MD 系统参数化
• md-feedback / md-transition

9.3 差分与审计

• diff-microstate
• diff-conformer
• diff-charge
• diff-pipeline
• prov-export

9.4 运维与恢复

• batch：支持 state 文件续跑
• clean-invalid-microstates
• policy-snapshot / checkout
• inject：人工注入微观态

9.5 数据与外部系统

• dvc-init / dvc-track
• datalad-init / datalad-save
• lwreg-init / lwreg-register
• receptor-add

说明：所有命令支持 --help，例如：

msl conformers --help

---

10. 数据模型与ID规则

核心表：

• runs：执行记录（stage/tool/params/status）
• compounds
• microstates
• conformers
• poses
• systems
• artifacts
• edges
• decisions
• anomalies
• atom_maps

ID 规则（摘要）：

• CompoundID = C-<reg_hash_prefix>
• MicrostateID = M-sha256(fixedH_inchi|formal_charge|stereo|coordination)
• ConformerID = X-<sha256(file)>
• PoseID = P-<sha256(file)>

---

11. 映射与可逆性

MicrostateLedger 通过 canonical atom id + sidecar JSON 保证跨软件映射可追踪：

• Docking：ligand.map.json
• MD：atommap.json（以及 gromacs/amber map）

可逆判定基线：

1. canonical_atom_id 在 docking map 中可查。
2. 同一 canonical_atom_id 在 MD map 中可查。
3. 可选：元素/连接关系一致性校验。

---

12. 可复现与审计

项目提供以下可复现保障：

• 每个工件入库时记录 sha256
• 每个阶段生成 run_id
• 每个关键选择写入 decisions
• 异常写入 anomalies 并挂接 target_id
• prov-export 导出 PROV-JSON

建议实践：

• 每次大实验前保存 policy snapshot
• 每次发布前执行 ultimate_release_gate.py
• 把 commands.log 与 artifact_manifest.json 作为审计附件保留

---

13. 终极门禁（Ultimate Release Gate）

执行：

python scripts/ultimate_release_gate.py \
  --outdir ultimate_test_runs/ultimate_release_gate_$(date +%F) \
  --report-dir reports/ultimate_release_gate_$(date +%F) \
  --commands-log reports/ultimate_release_gate_$(date +%F)/commands.log \
  --seed 20260206 \
  --n-repeats 3

产物：

• ULTIMATE_REPORT.md
• artifact_manifest.json
• commands.log
• gate_3_1 ... gate_3_7 JSON

详细说明见：docs/ultimate_release_gate.md

---

14. GitHub 与 PyPI 发布前清单

14.1 GitHub 发布前

1. 工作区干净：git status
2. 测试通过：python -m pytest -q
3. 包可构建：python -m build
4. README 渲染检查：python -m twine check dist/*
5. CI workflow 存在：.github/workflows/ci.yml
6. 版本号已确认：pyproject.toml 的 project.version
7. 打 tag：git tag v0.1.0
8. 推送分支与 tag。

14.2 PyPI 发布前

1. 先在 TestPyPI 验证上传
2. 确保 twine check 无报错
3. 检查 wheel/sdist 含必要文件（schema/policy/resources）
4. 执行上传：

python -m twine upload dist/*

说明：若当前未发布到 PyPI，pip install MicrostateLedger 会失败，这是预期状态。

---

15. 常见问题

Q1: pip install -e . 报 SOCKS/proxy 错误

原因：代理依赖缺失（如 SOCKS）。

处理：

unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY all_proxy ALL_PROXY
python -m pip install -e .

离线/受限环境可用：

python -m pip install -e . --no-build-isolation --no-deps

Q2: 提示 No space left on device

原因：/tmp 或根分区空间不足。

处理：把临时目录和 pip cache 挪到大盘：

export TMPDIR=/data/your_tmp
export PIP_CACHE_DIR=/data/your_pip_cache

Q3: msl 命令找不到或 wrapper 不可用

处理：

• 直接使用 python -m msl.cli ...
• 或修正 bin/* 中硬编码路径（ROOT/CONDA）

Q4: 为什么某些阶段会记录 missing_env 决策

这是降级机制，表示对应可选环境不可用，系统将跳过该阶段并保留审计记录。

---

16. 许可证

见 LICENSE。

如果你用于受监管研发流程，建议把以下三类文件作为交付件归档：

• policy snapshot
• artifact manifest
• commands log