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)。
