# 低能隙分子条件生成研究

**Repository Path**: QDISUPC2026/low-gap-molecule-generation

## Basic Information

- **Project Name**: 低能隙分子条件生成研究
- **Description**: 面向电子结构性质长尾分布的低能隙分子条件生成研究
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-06-12
- **Last Updated**: 2026-06-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 面向电子结构性质长尾分布的低能隙分子条件生成研究

本项目基于 **DiGress** 与 **FreeGress** 的图扩散模型框架，研究面向 QM9 电子结构性质（HOMO、LUMO、gap）长尾分布的低能隙分子条件生成方法。

## 背景

有机光电材料的性能与其电子结构性质（尤其是 HOMO-LUMO 能隙）密切相关。低能隙分子在有机光伏、近红外发光等领域具有重要应用价值，但这类分子在已知化学空间中呈现典型的长尾分布——低能隙样本极为稀缺。

传统的分子图扩散生成模型（如 DiGress）在无条件生成任务中表现优异，FreeGress 进一步引入了无分类器引导（Classifier-Free Guidance, CFG）和基于分类器引导（Classifier-Based Guidance）实现性质条件生成。然而，在极端低能隙区域（如 QM9 数据集的 0.1%、0.2% 分位数），这些方法的生成覆盖率和多样性仍然不足。

本研究旨在解决这一长尾分布下的低能隙分子条件生成难题。

## 项目结构

```
.
├── freegress/                          # 原始 FreeGress 代码库
│   ├── configs/                        # 配置文件（数据集/实验/模型/训练）
│   ├── src/
│   │   ├── analysis/                   # 分子分析工具（RDKit, ORCA 图计数）
│   │   ├── datasets/                   # 数据集加载（QM9, ZINC250k, MOSES 等）
│   │   ├── diffusion/                  # 扩散模型核心组件
│   │   ├── guidance/                   # 引导采样（CFG / Classifier-Based）
│   │   ├── metrics/                    # 分子评估指标
│   │   └── models/                     # 图 Transformer 模型
│   └── requirements.txt
│
├── freegress1_modified_safe/           # ★ 主要实验代码：长尾感知安全版本
│   ├── configs/                        # 扩展配置（含 guidance/guidance.yaml）
│   ├── src/                            # 核心源码（与 freegress 结构一致）
│   ├── own1/                           # 实验脚本与后处理
│   │   ├── train_freegress1_gap_original_objective_from_scratch_5090.py
│   │   └── run_freegress1_safe_tail_aware_quick_generation_5090.py
│   ├── qm9_long_tail_analysis.py       # QM9 长尾分布分析脚本
│   └── MODIFICATION_SUMMARY.md         # 修改摘要
│
└── psi/                                # Psi4 集成的实验代码分支
    ├── configs/
    ├── src/
    │   ├── analysis/psi4_gap_worker.py # Psi4 量子化学计算接口
    │   └── ...
    └── ...
```

## 方法概述

### 1. 基础生成框架

- **DiGress**：离散图扩散模型，通过逐步去噪生成分子图
- **FreeGress**：在 DiGress 基础上加入性质条件生成能力，支持：
  - 无分类器引导（Classifier-Free Guidance, CFG）：以 `p_uncond`（ρ）控制无条件训练比例，推理时用 `s` 调节引导强度
  - 基于分类器引导（Classifier-Based Guidance）：训练性质回归器，推理时用 `λ` 控制梯度引导强度

### 2. 长尾低能隙策略（freegress1_modified_safe）

本版本的核心改进：

- **安全三层策略**：保持原始 FreeGress 训练目标不变（禁用 TailRW 加权损失分支），将长尾感知从训练阶段转移到推理阶段
- **尾部分位数采样**：支持在 0.1%、0.2%、0.5%、1%、1.5%、2% 等多个尾部分位数阈值下进行条件生成
- **CFG 强度扫描**：对每个尾部阈值，扫描 `s = 0, 1, 3, 5, 7` 寻找最优引导强度
- **有效性与多样性后处理**：
  - 过滤空 SMILES / RDKit 无效分子
  - 连通性过滤
  - 典型唯一化（canonical uniqueness）
  - Psi4 量子化学验证（可选）
  - 统计 unique low-gap 候选分子数量

### 3. 核心评价指标

| 指标 | 说明 |
|------|------|
| validity | RDKit 有效分子比例 |
| uniqueness | 去重后的唯一分子数 |
| low-gap hit ratio | 生成分子中满足低能隙阈值的比例 |
| **n_unique_low_gap** | ★ 主要论文化指标：低能隙唯一候选分子数 |
| low-gap bin coverage | 低能隙区域分布覆盖度 |

> 由于原始 FreeGress 基线在 low-gap hit ratio 上已较强，本工作以 **n_unique_low_gap**（尤其在 0.1%、0.2%、0.5% 极端低能隙阈值下的唯一候选分子数量）作为最核心的对比指标。

## 环境安装

基于 PyTorch 2.0.1, CUDA 11.8, PyTorch Geometric 2.3.1。

```bash
# 创建 conda 环境
conda create -c conda-forge -n digress rdkit=2023.03.2 python=3.9
conda activate digress

# 验证 RDKit
python3 -c 'from rdkit import Chem'

# 安装 graph-tool
conda install -c conda-forge graph-tool=2.45

# 安装 CUDA 工具链
conda install -c "nvidia/label/cuda-11.8.0" cuda

# 安装 PyTorch
pip3 install torch==2.0.1 --index-url https://download.pytorch.org/whl/cu118

# 安装其他依赖
pip install -r requirements.txt
pip install -e .

# 编译 ORCA 图计数工具
cd src/analysis/orca
g++ -O2 -std=c++11 -o orca orca.cpp
```

## 快速开始

### 1. QM9 数据长尾分析

```bash
python qm9_long_tail_analysis.py \
  --project-root /path/to/project \
  --output-dir /path/to/output \
  --low-gap-quantile 0.10
```

### 2. 训练 gap 条件生成模型（FreeGress1）

```bash
python own1/train_freegress1_gap_original_objective_from_scratch_5090.py
```

### 3. 推理：长尾感知快速生成

```bash
python own1/run_freegress1_safe_tail_aware_quick_generation_5090.py
```

该脚本自动执行：
- 在多个尾部阈值和 CFG 强度组合下生成分子
- 导出 `generated_smiles_for_psi.csv`
- 写入运行清单和阈值表

### 4. 后处理与评估

```bash
python own1/postprocess_tail_generation_results_5090.py
```

### 5. 通用 CFG 训练与测试

```bash
# 训练（CFG 模式，目标 HOMO，p_uncond=0.1）
python3 main.py +experiment=guidance_parameters.yaml \
  general.name='homo_cf_p01_noextra' \
  guidance.guidance_target=["homo"] \
  model.extra_features=null \
  guidance.p_uncond=0.1 \
  general.gpus=[0]

# 测试（CFG 模式，s=5）
python3 main.py +experiment=guidance_parameters.yaml \
  general.name='homo_cf_p01_noextra_s5' \
  guidance.guidance_target=["homo"] \
  model.extra_features=null \
  guidance.s=5 \
  general.test_only="PATH_TO_CHECKPOINT" \
  general.gpus=[0]
```

## 数据集

- **QM9**：~130k 有机小分子，含 HOMO/LUMO/gap 等 19 个量子化学性质（B3LYP/6-31G(2df,p) 级别）
- **ZINC-250k**：250k 类药物分子，用于大规模无条件/条件生成

## 致谢

本项目代码基于以下开源工作：

- [DiGress](https://github.com/cvignac/DiGress) — 离散去噪图扩散模型
- FreeGress — 无分类器图扩散分子性质条件生成
- [PyTorch Geometric](https://github.com/pyg-team/pytorch_geometric) — 图神经网络框架
- [RDKit](https://www.rdkit.org/) — 化学信息学工具包
- [Psi4](https://psicode.org/) — 开源量子化学计算

## 许可

本项目基于原始 FreeGress 代码修改，遵循原始项目的许可协议。详见各子目录下的 LICENSE 文件。
## 许可证
> ⚠️ 额外约束：**严禁将本项目（含修改后的衍生作品）用于各类学科竞赛、科创比赛、项目申报、评优评奖等参赛场景**。
> 本项目仅允许个人非商业学习、研究与参考。