MR-TADF 二维结构绘图工具

mrtadf_depict 用于把 MR-TADF 分子的 SMILES 转成经过结构化排版的二维图，并可独立生成三维 XYZ 初始结构。

从 PyPI 安装

发布后，用户可以直接运行：

python -m pip install mrtadf-depict
mrtadf-depict --help

也可以在 Python 中使用：

from mrtadf_depict import depict_smiles

result = depict_smiles("Brc1ccccc1")
print(result.final_svg)

直接处理单条 SMILES：

mrtadf-depict smiles \
  'Brc1ccccc1' \
  --id example \
  --output single_output

输出目录包含 example.png、example.svg、example.sdf 和 example.json，不需要先建立 CSV。

当前二维流程重点保证：

• 螺芴及类似环系内部保持刚体，不拉伸芳环；
• 螺环中心两根连接键可独立变化，不强制等长，且优先旋转后拉长；
• 极端多螺环结构使用有界束搜索，不进行无限笛卡尔积；
• BNN 核心最终统一为两个 N 水平、B 位于上方；
• 简单卤素、CD3、叔丁基和小型支化基团使用确定性局部规则；
• 最终用 SVG 几何检查报告键交叉和标签碰撞。

五分钟运行

以下命令都从项目根目录 mr_tadf_perf/ 执行。

第 1 步：创建环境

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 步：运行测试

python -m pytest -q production/tests

当前预期结果：

9 passed, 3 subtests passed

第 3 步：批量生成二维图片

mrtadf-depict depict \
  --input production/examples/compound_smiles.csv \
  --output output_2d \
  --engine coordgen

如果没有使用命令行安装，也可以运行：

PYTHONPATH=production python -m mrtadf_depict.cli depict \
  --input production/examples/compound_smiles.csv \
  --output output_2d \
  --engine coordgen

第 4 步：检查结果

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

mrtadf-depict xyz \
  --input production/examples/compound_smiles.csv \
  --output output_xyz \
  --seed 42

XYZ 使用独立的 ETKDGv3 + UFF 三维流程，不会把二维拉长的绘图键带入三维结构。

输入 CSV

必须包含两列：

compound_id,smiles
sample_001,Brc1ccc2...

其他列会被保留在输入中但不会参与计算。compound_id 用作输出文件名，因此应唯一且不含路径分隔符。

Python API

稳定公共 API 只有三个名字：

from mrtadf_depict import (
    PipelineConfig,
    PipelineResult,
    optimize_mrtadf_layout,
)

完整可运行示例见：

python production/examples/use_python_api.py

开发文档

• docs/DEVELOPER_GUIDE.md：从安装到修改算法的完整中文步骤。
• docs/ARCHITECTURE.md：各阶段职责和硬约束。
• docs/TREE.md：唯一有效的源码目录树。
• docs/TESTING.md：测试范围与 GDG610、GGD1700 基准。
• docs/MIGRATION.md：历史脚本到当前模块的映射。
• docs/PUBLISHING.md：PyPI 构建、上传与发布后验证。

开发原则

1. 不再创建 v14.py、v15.py 之类的版本脚本。
2. 新逻辑放进唯一对应模块，并增加回归测试。
3. 螺芴搜索内层禁止反复渲染 SVG。
4. 多臂搜索禁止直接构造完整笛卡尔积。
5. 找不到可靠布局时返回 manual_review，不要破坏原始结构。
6. 二维绘图与三维 XYZ 始终保持独立。

发布到 PyPI

发布者在 production/ 目录执行：

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。