reacnet-scope

ReacNet Scope 是面向 ReacNetGenerator 输出结果的交互式后处理与分析软件，主要用于解析和管理反应分子动力学模拟中生成的物种与反应事件，并提供物种检索、明确反应序列的证据验证和时间演化分析等功能，从而提升 ReacNetGenerator 结果的可查询性、可解释性和应用效率，并为复杂反应机理分析及实验质谱结果解释提供辅助支持。

当前支持的主要输出包括 .reactionabcd、.species、原生 .timeline.h5、.lammpstrj，以及兼容保留的 .reactionevent.csv、.molecules.csv：

• Web 前端：分子式/SMILES/质量数检索、结构渲染和时间曲线绘图
• Web 前端：直接反应通道的事件频率与一/二阶质量作用表观速率常数（证据满足时）
• Web 前端：RNG 事件检索、参与原子与键展示和索引化局部轨迹提取
• CLI：批量检索、明确路径验证、事件证据包、TOP-N 统计、曲线绘制

它的核心定位是反应 MD 后处理与 ReacNetGenerator 输出解析；质谱实验解释是下游对接场景，而不是把本项目做成峰检测、色谱处理或通用质谱软件。

当前产品范围、领域语义、功能契约和发布验收以 docs/software-design-baseline.md 为准；较早的日期化设计稿和实施计划仅作为历史资料保留。

Description

reacnet-scope is a data-driven analysis toolkit for aligning reactive MD results with experimental interpretation.
It parses ReacNetGenerator outputs and provides integrated query, filtering, and visualization workflows across:

• Species lookup by formula, SMILES, and mass (nominal/exact).
• Exact Reaction Type sequence verification against event evidence.
• Time-series plotting from species files with formula/SMILES aggregation.
• Generic element-distribution evolution from indexed .species files or tidy tables.
• SMILES structure rendering, event evidence inspection, and pathway auditing in a lightweight web UI.

The project includes both CLI and web interfaces so the same core logic can be used for scripted batch analysis and interactive exploration.

目录结构

• reacnet_scope/：领域对象、数据集发现、索引、查询、事件路径验证和导出核心逻辑
• scripts/webapp_dash/：推荐使用的 Dash Web 界面
• scripts/rng_query_cli.py：终端检索入口
• tests/：自动化测试；examples/：最小数据与可复现实例
• docs/：专题说明与设计记录；deploy/：远程部署配置示例

快速开始

1. 安装依赖

uv sync

源码开发环境默认包含完整测试栈，以及 Web 和轨迹适配依赖，因此 uv run pytest -q 在干净环境中即可运行全量测试。仅部署精简运行环境时， 显式排除开发组并选择发布 extras：

uv sync --locked --no-dev --extra web --extra trajectory

2. 启动 Dash Web（推荐）

./start-reacnet-scope.sh

脚本会自动使用项目的 .venv、开放当前用户的主目录与 /media/$USER:/data:/mnt，并启动 http://127.0.0.1:8060。如果虚拟环境尚未 创建，脚本会先根据 uv.lock 完成安装。运行 ./start-reacnet-scope.sh --check 可以只检查配置而不启动服务；额外挂载点可通过 REACNET_SCOPE_EXTRA_ROOTS 追加，多个目录用冒号分隔。

远程部署时，目录浏览器看到的是服务端文件系统，实际数据挂载点必须包含在允许 根目录中。

加载 ReacNetGenerator 数据集

进入侧栏“数据工作区”中的“管理数据”页面，点击“选择数据集”（已有数据时为 “更换数据集”）。服务器浏览器会标记当前目录中的 ReacNetGenerator 数据集； 目录中只有一个数据集时自动选中，存在多个数据集时按文件名前缀列出候选。 选择后点击一次“加载并使用”即可。加载后停留在“管理数据”，以便确认能力与索引 状态；需要进入物种检索时再点击“开始物种检索”。最近成功加载的十个数据集会 保存在当前浏览器本地，并优先显示在选择器顶部；它们不会自动切换当前数据集。

base 是同组 RNG 输出的内部公共前缀，通常无需手动填写。选择器顶部可直接粘贴 数据目录或完整公共前缀；本地使用时可从系统文件管理器复制文件夹路径，远程部署 时则填写服务端路径。浏览器原生目录选择只能访问客户端文件，不能直接授权服务端 目录；所有服务端路径仍受 REACNET_SCOPE_ALLOWED_ROOTS 限制。

Dash 默认进入“物种检索”。分析与数据工作区入口直接显示在左侧栏，不使用下拉菜单； 不同类别以分组关系组织：

• 检索与趋势：物种检索、反应式检索、时间演化、元素分布演化。
• 事件证据：反应事件、轨迹查看、路径验证。
• 数据工作区：管理数据、批量对比。

各工具保持独立，页面只显示当前工具名称、数据状态和操作区域。需要继续分析时， 已选物种可以查看单步的“直接生成/消耗通道”，再将所选通道送入“反应事件”；选中事件后 再打开独立的“轨迹查看”。需要核查多步链路时，在“路径验证”中按顺序输入 2–8 个完整 Reaction Type；软件只验证该序列，不会自动发现、补全或排名路径。数据集选择、文件状态与 派生索引准备集中在独立的“管理数据”页面；批量对比同属侧栏“数据工作区”。

直接反应通道始终保留 TP、逆向 TP 和净 TP。事件索引、Species Abundance 索引、 已确认的 timestep → ps 可进一步给出事件频率；一阶通道据此给出表观 k。 二阶通道还要求轨迹索引包含同时间点模拟盒体积且长度单位已确认为 Å。所有 k 均明确 标记为化学计量质量作用模型下、当前数据集与观察窗内的表观估计，并随 CSV 导出事件数、 暴露量、单位和 95% 置信区间；数据不足时不会把 TP 或净 TP 冒充速率常数。直接反应通道 页可就地确认并保存换算；也可关联位于其他目录的 .lammpstrj、确认 Å 并在后台建立 轨迹索引，随后自动重新计算，无需切换到其他页面。关联只写入 Dataset Workspace，不移动 或修改原始轨迹。在线计算会一次批量 读取全部相关 Species 的对齐丰度并向量化积分；等待期间按钮、进度提示和通道表加载状态保持可见。

“批量对比”可以直接组合当前数据集与最近加载的数据集，也可以递归扫描包含 多条件/多重复模拟的目录。结果按条件组汇总精确反应的检出率、平均 TP、标准差、 平均净 TP 与 95% 置信区间；选中反应可查看各重复实验，表格可按显示列导出 CSV。 为防止不完整结果，任何已选数据源缺失或解析失败都会终止本次比较并明确报错。

自动候选路径搜索、评分、Top-N 合并网络及其 CLI/API 已移除。多步结论必须来自用户 明确给出的 Reaction Type 序列和事件索引中的时间、分子实例及原子 ID 连续证据。

完整的信息架构、功能归属与后续去重计划见 docs/usage-logic-redesign.md。

ReacNetGenerator 生成的 schema-1/2 .timeline.h5 会被自动识别，其中 Reaction Evidence 是事件检索所需能力，Molecular Evidence 是原子、键与物理 timestep 的增强证据。schema 2 的逐事件 Transition Evidence 会被直接用于索引， 无需重建完整的帧—原子成员矩阵。旧版本仍可生成 CSV：

# 添加到原 ReacNetGenerator 命令
--reaction-event --show-molecule-time

原生 timeline/事件 CSV 和大轨迹都必须先在独立进程中建立索引。Dash 查询只读消费 已发布的索引，不会在查询中顺序扫描 HDF5、完整事件 CSV 或轨迹；“管理数据”页可启动 使用同一准备命令的独立后台任务：

uv run reacnet-scope prepare build all /data/case
uv run reacnet-scope prepare status /data/case

如果只需要准备事件检索：

uv run reacnet-scope prepare build event /data/case

事件索引 schema v4 始终记录反应式、Transition 和反应物/产物侧 SMILES； 原生 Molecular Evidence 或 .molecules.csv 会补充参与原子、键变化和物理 timestep。.timeline.h5 的聚合 count 会展开为独立逻辑事件，范围数据按 molecule 分组、组内排序并合并后以有界内存和磁盘检查点构建。完整有效的原生文件优先；仅当 它不存在时才回退 CSV，存在但 incomplete/损坏/schema 不兼容时会明确失败。 Dash 查询期间只打开 SQLite 索引，不回扫原始证据。已有旧索引升级后需执行 reacnet-scope prepare rebuild event /data/case 一次。

统一命令可准备事件、轨迹以及 .species 的通用元素分布索引：

uv run reacnet-scope prepare build element-distribution /data/case

轨迹索引 schema v4 会在离线扫描时同时记录逐帧模拟盒体积，供二阶表观速率估计使用。 旧版轨迹索引需要执行 reacnet-scope prepare rebuild trajectory /data/case；轨迹 长度单位仍需由用户确认为 Å，软件不会根据数值静默猜测。

事件轨迹查看与 OVITO 复核

“反应事件”页只负责检索和选择 RNG 事件；点击“打开轨迹查看”后进入独立页面。 “轨迹查看”只读取轨迹索引返回的帧字节范围，并由 ASE 处理晶胞、周期边界和最小 镜像重定位。页面中的 3Dmol.js 查看器默认只显示参与原子，也可在“完整上下文 / 参与原子 / 仅反应核”之间切换。成键和断键信息始终来自 RNG 事件证据，不根据 坐标重新猜键。

局部轨迹打开后可从该 Reaction Occurrence 的任一具体反应物或产物启动“分子实例 谱系”。默认以全部非氢原子为锚点，向前/向后各追踪 3 次持久结构变化，并把 5 个 Analyzed Frames 内返回完全相同结构的快速回穿折叠为一段；原始事件始终保留在事件表和 JSON/CSV 导出中。缺少可靠元素映射时不会猜测氢原子对应的 Atom ID，需先确认 Type → Element，或显式选择全部原子/指定 Atom IDs。详细边界见 docs/molecule-lineage-analysis.md。

事件索引先按相邻 Molecular Evidence 帧中的原子连通组追踪参与原子，再约去反应 两侧计量相同的净不变物种，与 RNG 的净反应事件匹配。升级前建立的事件索引需 执行 reacnet-scope prepare rebuild event /data/case 后才能使用该关联规则。

原始 dump 只有数值 type 时，页面会从当前局部轨迹检测 Type，并为 每个 Type 提供可搜索的元素下拉框。点击“应用设置并重新提取”即确认该映射， 设置会保存到当前数据集的 Dataset Workspace；轨迹自带 element 列时始终优先使用 原始元素。

点击“下载事件包 ZIP”可得到一个确定性、可复核的最小证据包：

• event.json：事件内容、来源签名、原子分组/映射和轨迹提取参数；
• frames.csv：逐帧 source timestep、可选 ps、原始/显示坐标、晶胞/PBC 和确认单位；
• changed_bond_distances.csv：RNG 证据中发生键变化的原子对在每帧的几何距离；
• trajectory.lammpstrj：当前原子范围的局部轨迹；
• trajectory.extxyz：元素映射完整时提供，保留晶胞/PBC 和原子 ID；
• bonds.csv：来自 RNG 事件证据的成键、断键与未变键；
• README.txt：来源、坐标处理、限制和 ASE/OVITO 打开命令。

轨迹页还可单独下载帧 CSV 和键变距离 CSV。只有数据集已经确认 timestep → ps 换算时才写入 time_ps；只有坐标长度单位已经确认为 Å 时，距离 单位才写为 angstrom，否则相应单位字段保持空白。距离只针对 RNG 证据中发生 形成、断裂或键级变化的原子对计算，不据此推断中间帧键级。

元素映射不完整时仍可下载 ZIP 和 LAMMPS 轨迹，仅省略 trajectory.extxyz。也可从终端导出同一格式：

export REACNET_SCOPE_CACHE_DIR="$PWD/.cache/reacnet-scope"
uv run reacnet-scope export-event \
  --case /data/case \
  --event-id EVENT_ID \
  --scope participants \
  --type-map '1=C,2=H,3=O' \
  --out EVENT_evidence.zip

DFT 初始几何导出

对具有精确 Molecular Evidence 的 matched Reaction Occurrence，轨迹页面会显示 独立的“DFT 初始几何”区域。反应物固定来自事件的 before_timestep，产物固定 来自 after_timestep。可按两侧的具体 Molecule Instance 自选，并合并为反应物/ 产物复合物、逐分子导出或同时生成两种文件。

导出器按侧别键图通过 PBC 重建完整分子，保留多分子反应接触的相对位置，再把 非周期分子簇整体居中。它不旋转、优化或修键，也不会把中间轨迹帧声明为过渡态。 元素映射必须完整，并需要一次性确认源轨迹坐标单位为 Å。电荷和自旋多重度可选， 留空时明确记录为 unspecified，软件不会自动猜测。

页面提供 XYZ 预检、质量警告、预览和复制。正式 ZIP 包含所选 XYZ、 manifest.json、atom_map.csv 和 README.txt；这是从事件证据派生的 DFT 初始几何，不会改变现有事件证据包。终端可导出同一格式：

uv run reacnet-scope export-dft-geometry \
  --case /data/case \
  --event-id EVENT_ID \
  --reactants all \
  --products all \
  --layout both \
  --type-map '1=C,2=H,3=O' \
  --source-unit angstrom \
  --state reactants=0,1 \
  --state products=0,1 \
  --out EVENT_dft_geometry.zip

--reactants 和 --products 也接受 none 或从 1 开始的分子序号（例如 1,3）。使用 --save-unit-confirmation 可把 Å 确认保存到当前 Dataset Workspace；以后可省略 --source-unit。命令默认不覆盖已有文件，覆盖需要 显式传入 --force。--state 的键必须与实际输出 XYZ 文件名（去掉 .xyz） 完全一致；例如逐分子文件 reactant-01-atoms-1-12.xyz 使用 --state reactant-01-atoms-1-12=0,2，未知或重复键会被拒绝。

确定性以相同来源签名、路径、版本和导出参数为范围。manifest 保留绝对来源路径 用于审计；在线导出不会为了跨目录副本生成内容哈希而扫描整条大型轨迹。

命令默认不覆盖已有文件；需要替换时显式传入 --force。页面仍保留独立的 “子轨迹”和“OVITO 脚本”下载；将两者放在同一目录后可运行：

ovitos EVENT_view_ovito.py EVENT_subset.lammpstrj

本地模式还提供用户主动点击的“在 OVITO 中打开”。程序会检测 macOS App、Windows 常见安装位置和 Linux PATH；也可通过 REACNET_SCOPE_OVITO_EXECUTABLE=/path/to/ovito 显式指定。远程部署设置 REACNET_SCOPE_DEPLOYMENT_MODE=remote，界面只保留下载，不会启动服务器 GUI。

网页查看器固定使用 vendored 3Dmol.js 2.5.5，不依赖浏览器访问 CDN。3Dmol.js 及其所含组件的许可证保存在 scripts/webapp_dash/assets/3Dmol-min.js.LICENSE.txt。

当前范围与未来候选

当前版本以“反应式检索 → RNG 事件 → 局部轨迹/事件包”为主要分析链路，并提供 “明确 Reaction Type 序列 → 路径验证”作为独立证据工作流。机理网络和自动路径发现 不属于当前版本、发布验收或近期路线图。

“机理网络”仅保留为未来候选功能名称，不预设数据模型、界面或导出格式。若以后 重新启动，应基于届时确认的用户需求重新立项和设计，不恢复旧实现。

元素分布索引以流式方式读取大型 .species 文件，把每个 timestep 压缩为 元素计数字典 → 数量，同时保存每个物种的全程峰值和原始行字节偏移；Dash 绘图不再回扫 .species。用户指定参考物种时，系统按其精确 SMILES 从索引 按需读取时间序列；点击下钻时只读取一个时间点并查询峰值摘要，避免将数千万 条物种记录展开为内存 DataFrame。 reacnet-scope prepare 提供 status、build、rebuild、cancel 和 clear；能力为 event、trajectory、element-distribution 或 all。 取消会保留最近的构建检查点。Route 准备模式和独立旧入口已删除。

在 Dash 的“管理数据”页面中，“索引构建与状态”默认展开；基础检索无需等待。 需要物种时间演化、事件、轨迹帧或元素分布能力时，可建立、续建或重建对应索引， 并查看 Dataset Workspace 位置、占用空间和等价 CLI 命令。运行或失败的后台任务 直接显示，已完成任务收进历史记录。默认 Workspace 位于数据集 sidecar；只读、 共享或远程来源回退到平台用户工作区，也可显式设置 REACNET_SCOPE_CACHE_DIR。清理不会修改 RNG 原始输出。

3. 查看 CLI 帮助

uv run reacnet-scope --help

4. 指定 reactionabcd 文件查询

uv run reacnet-scope species --reac /path/to/xxx.reactionabcd --formula C6H4

默认输入文件规则

默认会按以下顺序寻找 reactionabcd：

1. 环境变量 RNG_REACTION_FILE
2. ../datas/1ER_2500K/rng_data/2CP_O2_1ER.lammpstrj.reactionabcd（相对本工具目录上一级）
3. <tool_root>/datas/1ER_2500K/rng_data/2CP_O2_1ER.lammpstrj.reactionabcd
4. <cwd>/datas/1ER_2500K/rng_data/2CP_O2_1ER.lammpstrj.reactionabcd

建议在跨项目使用时显式传 --reac 或设置 RNG_REACTION_FILE。

时间有序、原子连续的路径验证

reacnet-scope verify-path 在已准备的事件索引上把每个具体 RNG 事件作为节点， 只连接“严格更晚、同一精确分子实例、第一次后续消费”的事件；三事件路径还要求 至少一个原子 ID 贯穿两条边。它会统计独立 (重复实验, 原子 ID) 谱系支持、 事件时间间隔和跨重复复现率。它只检查用户明确给出的反应序列，不搜索其他路径。

uv run reacnet-scope verify-path \
  --source rep1=/data/case/rep1/run.lammpstrj \
  --source rep2=/data/case/rep2/run.lammpstrj \
  --reaction 'A + B -> C' \
  --reaction 'C -> D' \
  --out-json path-verification.json

其中 /data/case/... 是路径占位符；请替换为真实公共前缀。例如仓库自带数据可用 --source rp3="$PWD/ref_data/rng-test-rp3-0523/rp3.lammpstrj"。

该分析必须使用含 Molecular Evidence 的原生 .timeline.h5 索引，或同时含 .reactionevent.csv 与 .molecules.csv 的兼容索引；只有事件时间而没有原子/分子 实例映射时不会降级为物种名称拼接。完整语义、统计字段和 边界说明见 时间有序、原子连续的事件路径。

Dash 中可在“事件证据 → 路径验证”通过四步向导运行同一引擎：确认数据、逐行输入 Reaction Type、确认并运行、查看证据。结果明确显示“有证据 / 未观察到 / 证据不足”， 并可逐次审计具体事件—分子实例—原子 ID 图，下载 JSON 或 CSV。

依赖

• Python 3.10+
• 基础依赖：pandas、openpyxl、rdkit
• 可选绘图增强：matplotlib、scipy（CLI species-evolution --out-png 时需要）
• 可选轨迹适配：ase（安装 extra：trajectory）

使用 uv 安装

仅安装基础依赖：

uv sync

安装基础依赖 + 绘图增强依赖：

uv sync --extra plot

Element Distribution Evolution

Dash 的“元素分布演化”从数据集发现可用元素。用户选择分组元素和最大原子数， 再以任意元素表达存在、不存在或原子数范围筛选。数据含碳时页面可默认选择 C， 但 schema、查询和控件都不写死 C/O/Cl。

可选参考物种只由用户输入的精确 SMILES 决定；软件不会从丰度推断“母体”。指定 后会同时显示参考物种及相同分组元素数量的其他物种。点击曲线可下钻到分子式、 SMILES、当前数量、峰值数量和峰值时间。

CLI 查询同一个预建索引：

uv run reacnet-scope element-distribution /data/case \
  --group-element N \
  --max-group-count 8 \
  --filter S=present \
  --filter O=range:1:3

Web 输入规范（统一）

• 顶部 Reaction(.reactionabcd，可选)：仅用于网络检索类模块（分子式/质量/路径/公式反应）。
• Species 时间演化和 Element Distribution 查询使用当前数据集的 .species 来源，不依赖 reactionabcd。
• 单文件输入（Species 文件）支持两种后缀：
  • .species：直接读取
  • .reactionabcd：自动转为同名 .species
• 多文件输入（多文件对比）每行格式统一为：
  • system@replicate::/abs/path/file.species
  • system@replicate::/abs/path/file.reactionabcd（自动转 .species）
• 示例清单见 examples/multi_species_sources.example.txt。

在“Species 时间演化”页重绘多温度物种消耗曲线：

1. 展开“数据源”，将不同温度/重复实验的文件逐行粘贴到“多文件列表”；
2. 点击“读取物种目录”，应用会从已准备的 Species Abundance Index 合并分子式目录；
3. 在可搜索的多选框中选择一个或多个分子式，再点击“绘制”；
4. 每个来源文件会保留独立曲线，图例使用清单中的 system@replicate 标签。

物种目录和曲线查询只读取预建索引，不在交互请求中扫描完整 .species 文件。 如果页面提示索引未就绪，先在数据管理页为相应文件构建 Species Abundance Index。

通用元素分布也可读取 tidy CSV/Excel；至少包含 time、species、count， 可选 dataset 或 system 列用于多数据集对比。分组元素、元素过滤、原子数分箱、 命名区间和平滑参数由同一核心模型处理。

发布到 GitHub/PyPI

• GitHub：提交源码、测试、文档、示例以及 pyproject.toml / uv.lock；构建产物、运行日志、缓存和本地环境均由 .gitignore 排除。
• PyPI：pyproject.toml 已配置 CLI、Dash、索引准备与 Dataset Workspace 管理命令入口。

开发与验证

uv sync --locked
uv run --locked pytest -q
uv build