mrtadf-depict 0.2.0__tar.gz

mrtadf_depict-0.2.0/MANIFEST.in

@@ -0,0 +1,8 @@
+include README.md
+include pyproject.toml
+recursive-include docs *.md
+recursive-include examples *.py *.csv
+recursive-include tests *.py *.sdf
+global-exclude .DS_Store
+global-exclude *.py[cod]
+global-exclude __pycache__

mrtadf_depict-0.2.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: mrtadf-depict
+Version: 0.2.0
+Summary: 用于 MR-TADF 分子的分层刚性二维结构绘图工具
+Keywords: chemistry,cheminformatics,MR-TADF,RDKit,molecular-depiction
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Natural Language :: Chinese (Simplified)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numpy
+Requires-Dist: rdkit
+Requires-Dist: shapely
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+
+# MR-TADF 二维结构绘图工具
+
+`mrtadf_depict` 用于把 MR-TADF 分子的 SMILES 转成经过结构化排版的二维图，并可独立生成三维 XYZ 初始结构。
+
+## 从 PyPI 安装
+
+发布后，用户可以直接运行：
+
+```bash
+python -m pip install mrtadf-depict
+mrtadf-depict --help
+```
+
+也可以在 Python 中使用：
+
+```python
+from rdkit import Chem
+from mrtadf_depict import optimize_mrtadf_layout
+
+mol = Chem.MolFromSmiles("Brc1ccccc1")
+result = optimize_mrtadf_layout(mol)
+print(result.final_svg)
+```
+
+当前二维流程重点保证：
+
+- 螺芴及类似环系内部保持刚体，不拉伸芳环；
+- 螺环中心两根连接键可独立变化，不强制等长，且优先旋转后拉长；
+- 极端多螺环结构使用有界束搜索，不进行无限笛卡尔积；
+- BNN 核心最终统一为两个 N 水平、B 位于上方；
+- 简单卤素、CD3、叔丁基和小型支化基团使用确定性局部规则；
+- 最终用 SVG 几何检查报告键交叉和标签碰撞。
+
+## 五分钟运行
+
+以下命令都从项目根目录 `mr_tadf_perf/` 执行。
+
+### 第 1 步：创建环境
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e "production[dev]"
+```
+
+要求 Python 3.10 或更高版本。
+
+### 第 2 步：运行测试
+
+```bash
+python -m pytest -q production/tests
+```
+
+当前预期结果：
+
+```text
+9 passed, 3 subtests passed
+```
+
+### 第 3 步：批量生成二维图片
+
+```bash
+mrtadf-depict depict \
+  --input production/examples/compound_smiles.csv \
+  --output output_2d \
+  --engine coordgen
+```
+
+如果没有使用命令行安装，也可以运行：
+
+```bash
+PYTHONPATH=production python -m mrtadf_depict.cli depict \
+  --input production/examples/compound_smiles.csv \
+  --output output_2d \
+  --engine coordgen
+```
+
+### 第 4 步：检查结果
+
+```text
+output_2d/
+├── png/          # 预览图片
+├── svg/          # 最终矢量图，也是碰撞验收依据
+├── sdf/          # 带二维坐标的结构
+└── report.csv    # 状态、碰撞结果、警告和算法元数据
+```
+
+重点检查 `report.csv`：
+
+1. `status` 应为 `ok`；
+2. `final_svg` 理想值为 `(0, 0, 0)`；
+3. `warnings` 应为空；
+4. `metadata` 中若出现 `"adaptive_status": "manual_review"`，必须人工复核。
+
+### 第 5 步：生成 XYZ
+
+```bash
+mrtadf-depict xyz \
+  --input production/examples/compound_smiles.csv \
+  --output output_xyz \
+  --seed 42
+```
+
+XYZ 使用独立的 `ETKDGv3 + UFF` 三维流程，不会把二维拉长的绘图键带入三维结构。
+
+## 输入 CSV
+
+必须包含两列：
+
+```csv
+compound_id,smiles
+sample_001,Brc1ccc2...
+```
+
+其他列会被保留在输入中但不会参与计算。`compound_id` 用作输出文件名，因此应唯一且不含路径分隔符。
+
+## Python API
+
+稳定公共 API 只有三个名字：
+
+```python
+from mrtadf_depict import (
+    PipelineConfig,
+    PipelineResult,
+    optimize_mrtadf_layout,
+)
+```
+
+完整可运行示例见：
+
+```bash
+python production/examples/use_python_api.py
+```
+
+## 开发文档
+
+- [`docs/DEVELOPER_GUIDE.md`](docs/DEVELOPER_GUIDE.md)：从安装到修改算法的完整中文步骤。
+- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)：各阶段职责和硬约束。
+- [`docs/TREE.md`](docs/TREE.md)：唯一有效的源码目录树。
+- [`docs/TESTING.md`](docs/TESTING.md)：测试范围与 GDG610、GGD1700 基准。
+- [`docs/MIGRATION.md`](docs/MIGRATION.md)：历史脚本到当前模块的映射。
+- [`docs/PUBLISHING.md`](docs/PUBLISHING.md)：PyPI 构建、上传与发布后验证。
+
+## 开发原则
+
+1. 不再创建 `v14.py`、`v15.py` 之类的版本脚本。
+2. 新逻辑放进唯一对应模块，并增加回归测试。
+3. 螺芴搜索内层禁止反复渲染 SVG。
+4. 多臂搜索禁止直接构造完整笛卡尔积。
+5. 找不到可靠布局时返回 `manual_review`，不要破坏原始结构。
+6. 二维绘图与三维 XYZ 始终保持独立。
+
+## 发布到 PyPI
+
+发布者在 `production/` 目录执行：
+
+```bash
+python -m pip install --upgrade build twine
+python -m build
+python -m twine check dist/*
+python -m twine upload dist/*
+```
+
+PyPI API token 不要写进代码、配置文件或命令历史。完整安全步骤见
+[`docs/PUBLISHING.md`](docs/PUBLISHING.md)。

mrtadf_depict-0.2.0/README.md

@@ -0,0 +1,166 @@
+# MR-TADF 二维结构绘图工具
+
+`mrtadf_depict` 用于把 MR-TADF 分子的 SMILES 转成经过结构化排版的二维图，并可独立生成三维 XYZ 初始结构。
+
+## 从 PyPI 安装
+
+发布后，用户可以直接运行：
+
+```bash
+python -m pip install mrtadf-depict
+mrtadf-depict --help
+```
+
+也可以在 Python 中使用：
+
+```python
+from rdkit import Chem
+from mrtadf_depict import optimize_mrtadf_layout
+
+mol = Chem.MolFromSmiles("Brc1ccccc1")
+result = optimize_mrtadf_layout(mol)
+print(result.final_svg)
+```
+
+当前二维流程重点保证：
+
+- 螺芴及类似环系内部保持刚体，不拉伸芳环；
+- 螺环中心两根连接键可独立变化，不强制等长，且优先旋转后拉长；
+- 极端多螺环结构使用有界束搜索，不进行无限笛卡尔积；
+- BNN 核心最终统一为两个 N 水平、B 位于上方；
+- 简单卤素、CD3、叔丁基和小型支化基团使用确定性局部规则；
+- 最终用 SVG 几何检查报告键交叉和标签碰撞。
+
+## 五分钟运行
+
+以下命令都从项目根目录 `mr_tadf_perf/` 执行。
+
+### 第 1 步：创建环境
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e "production[dev]"
+```
+
+要求 Python 3.10 或更高版本。
+
+### 第 2 步：运行测试
+
+```bash
+python -m pytest -q production/tests
+```
+
+当前预期结果：
+
+```text
+9 passed, 3 subtests passed
+```
+
+### 第 3 步：批量生成二维图片
+
+```bash
+mrtadf-depict depict \
+  --input production/examples/compound_smiles.csv \
+  --output output_2d \
+  --engine coordgen
+```
+
+如果没有使用命令行安装，也可以运行：
+
+```bash
+PYTHONPATH=production python -m mrtadf_depict.cli depict \
+  --input production/examples/compound_smiles.csv \
+  --output output_2d \
+  --engine coordgen
+```
+
+### 第 4 步：检查结果
+
+```text
+output_2d/
+├── png/          # 预览图片
+├── svg/          # 最终矢量图，也是碰撞验收依据
+├── sdf/          # 带二维坐标的结构
+└── report.csv    # 状态、碰撞结果、警告和算法元数据
+```
+
+重点检查 `report.csv`：
+
+1. `status` 应为 `ok`；
+2. `final_svg` 理想值为 `(0, 0, 0)`；
+3. `warnings` 应为空；
+4. `metadata` 中若出现 `"adaptive_status": "manual_review"`，必须人工复核。
+
+### 第 5 步：生成 XYZ
+
+```bash
+mrtadf-depict xyz \
+  --input production/examples/compound_smiles.csv \
+  --output output_xyz \
+  --seed 42
+```
+
+XYZ 使用独立的 `ETKDGv3 + UFF` 三维流程，不会把二维拉长的绘图键带入三维结构。
+
+## 输入 CSV
+
+必须包含两列：
+
+```csv
+compound_id,smiles
+sample_001,Brc1ccc2...
+```
+
+其他列会被保留在输入中但不会参与计算。`compound_id` 用作输出文件名，因此应唯一且不含路径分隔符。
+
+## Python API
+
+稳定公共 API 只有三个名字：
+
+```python
+from mrtadf_depict import (
+    PipelineConfig,
+    PipelineResult,
+    optimize_mrtadf_layout,
+)
+```
+
+完整可运行示例见：
+
+```bash
+python production/examples/use_python_api.py
+```
+
+## 开发文档
+
+- [`docs/DEVELOPER_GUIDE.md`](docs/DEVELOPER_GUIDE.md)：从安装到修改算法的完整中文步骤。
+- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)：各阶段职责和硬约束。
+- [`docs/TREE.md`](docs/TREE.md)：唯一有效的源码目录树。
+- [`docs/TESTING.md`](docs/TESTING.md)：测试范围与 GDG610、GGD1700 基准。
+- [`docs/MIGRATION.md`](docs/MIGRATION.md)：历史脚本到当前模块的映射。
+- [`docs/PUBLISHING.md`](docs/PUBLISHING.md)：PyPI 构建、上传与发布后验证。
+
+## 开发原则
+
+1. 不再创建 `v14.py`、`v15.py` 之类的版本脚本。
+2. 新逻辑放进唯一对应模块，并增加回归测试。
+3. 螺芴搜索内层禁止反复渲染 SVG。
+4. 多臂搜索禁止直接构造完整笛卡尔积。
+5. 找不到可靠布局时返回 `manual_review`，不要破坏原始结构。
+6. 二维绘图与三维 XYZ 始终保持独立。
+
+## 发布到 PyPI
+
+发布者在 `production/` 目录执行：
+
+```bash
+python -m pip install --upgrade build twine
+python -m build
+python -m twine check dist/*
+python -m twine upload dist/*
+```
+
+PyPI API token 不要写进代码、配置文件或命令历史。完整安全步骤见
+[`docs/PUBLISHING.md`](docs/PUBLISHING.md)。

mrtadf_depict-0.2.0/docs/ARCHITECTURE.md

@@ -0,0 +1,81 @@
+# MR-TADF 二维布局算法结构
+
+## 总入口
+
+`pipeline.optimize_mrtadf_layout()` 负责阶段编排，不实现具体搜索算法。
+
+```text
+初始二维坐标
+→ 螺芴刚体搜索
+→ 非螺芴桥臂
+→ 小型支化基团
+→ 简单终端原子
+→ BNN 严格朝向
+→ SVG 验收
+```
+
+## 螺芴模块
+
+### 拓扑与几何
+
+- `algorithms/spiro/topology.py`：识别 sp3 螺环中心、移动侧和固定侧。
+- `algorithms/spiro/geometry.py`：生成严格刚体姿态，两根连接键可独立变化。
+- `algorithms/spiro/common.py`：共享候选类型、评分键、长度层和结果元数据。
+
+### 搜索策略
+
+- `algorithms/spiro/fast.py`：1–2 臂生产路径。
+  1. 当前键长层生成粗角度候选。
+  2. 对最佳粗角度做局部细化。
+  3. 每臂保留 Top-K。
+  4. 双臂组合先按局部碰撞和净空剪枝。
+  5. 少量候选执行完整评分和 SVG 验收。
+- `algorithms/spiro/extreme.py`：极端路径。
+  - 1–2 臂快速路径失败时扩大角度与束宽。
+  - 3–6 个独立臂使用逐臂束搜索，不构造完整笛卡尔积。
+  - 超时、刚体重叠或臂数超限时返回 `manual_review`。
+  - 若螺芴键线已经无交叉、仅剩后续局部规则可修复的标签碰撞，返回
+    `geometry_clean_pending_local_fixes`，不再重复搜索全部键长层。
+- `algorithms/spiro/__init__.py`：稳定公共入口，不放算法细节。
+
+旧版穷举基线已移到 `benchmarks/legacy_spiro_search.py`，不会进入生产包。
+
+## 不可破坏的约束
+
+1. 螺芴内部原子间距离保持不变。
+2. 两根 C(sp3)–C 绘图键不要求等长，但都不能短于普通绘图键长。
+3. 优先旋转；当前长度无解时才增加连接键长度。
+4. 每根连接键最多拉长到配置上限，默认 5×。
+5. SVG 检测只负责验收，不直接修改坐标。
+6. 无可靠解时保留安全结构并标记人工复核。
+
+## 桥臂模块
+
+- `algorithms/bridges/single.py`：桥臂识别、刚体姿态和单臂搜索。
+- `algorithms/bridges/multi.py`：多个一级桥臂的束搜索。
+- `algorithms/bridges/hierarchy.py`：一级桥臂内部继续识别二级和三级桥臂。
+
+桥臂模块只移动被识别为刚体的外围连通分量，不参与螺芴体系；是否跳过由 `PipelineConfig.skip_bridges_for_spiro` 控制。
+
+## 取代基模块
+
+- `algorithms/substituents/tert_butyl.py`：叔丁基扇形排布。
+- `algorithms/substituents/small_alkyl.py`：塌缩小型 sp3 支化基团修复。
+- `algorithms/substituents/terminals.py`：卤素标准外向键和 CD3 显式氘排布。
+
+这些模块只做局部确定性修复，不承担全分子碰撞搜索。
+
+## 基础设施
+
+- `core/geometry.py`：唯一的通用坐标工具来源。
+- `core/validation.py`：唯一的快速碰撞评分和 SVG 验收来源。
+- `pipeline.py`：只决定阶段顺序、开关、错误隔离和元数据汇总。
+
+## 维护规则
+
+- 新拓扑识别放在 `algorithms/spiro/topology.py`，不要写进搜索循环。
+- 新刚体变换放在 `algorithms/spiro/geometry.py`。
+- 新评分项放在 `algorithms/spiro/common.py` 或 `core/validation.py`。
+- 普通路径优化放在 `algorithms/spiro/fast.py`。
+- 只对罕见复杂结构启用的策略放在 `algorithms/spiro/extreme.py`。
+- 不要把实验版本复制成新的 `v14/v15` 脚本；通过测试和基准维护同一实现。