Rust Cheminformatics: Porting RDKit Source Semantics to Rust
Rust Cheminformatics: Porting RDKit Source Semantics to Rust
Rust 化学信息学：将 RDKit 源码语义移植到 Rust
COSMolKit currently validates its parity-covered Rust cheminformatics surfaces against pinned RDKit 2026.03.1 using three complementary corpus tiers, culminating in the complete ChEMBL 37 structure table. The current extended profile covers 2,897,819 source records, 31 validation phases, and 3,968 shard tasks. Its consolidated accepted evidence records 2,931,581,192 matching checks with zero blocking mismatch, with distance-geometry validation additionally traversing more than 2.75 billion matrix entries.
COSMolKit 目前正针对固定的 RDKit 2026.03.1 版本，通过三个互补的语料库层级来验证其 Rust 化学信息学接口的对等性，最终涵盖了完整的 ChEMBL 37 结构表。当前的扩展配置包含 2,897,819 条源记录、31 个验证阶段和 3,968 个分片任务。其汇总的验证证据记录了 2,931,581,192 次匹配检查，且零阻塞性不匹配；此外，距离几何验证还遍历了超过 27.5 亿个矩阵条目。
These are not simply “molecules that produced the same final string.” Depending on the declared parity boundary, COSMolKit compares exact molecular state, fingerprints, parameter branches, serialization behavior, operation composition, batch and concurrent execution, stochastic outcomes, matrices, coordinates, energies, gradients, and errors. The exact scope is documented separately in VALIDATION.md. The more interesting question for this article is not how large the validation corpus became. It is how the implementation reached that result.
这些不仅仅是“产生相同最终字符串的分子”。根据所声明的对等边界，COSMolKit 会比较精确的分子状态、指纹、参数分支、序列化行为、操作组合、批处理与并发执行、随机结果、矩阵、坐标、能量、梯度和错误。具体的范围在 VALIDATION.md 中有单独记录。对于本文而言，更有趣的问题不是验证语料库变得有多大，而是该实现是如何达到这一结果的。
A straightforward way to build an RDKit-compatible Rust library is to treat RDKit as an executable oracle: implement a feature approximately, run a corpus through both implementations, inspect the mismatches, let an agent patch the failing cases, expand the corpus, and repeat. Modern coding agents make this workflow remarkably fast. COSMolKit deliberately follows a different development model. For compatibility-critical chemistry, the implementation is derived from the pinned upstream source first. Differential corpora are then used to audit that port rather than to iteratively teach a heuristic implementation how to imitate RDKit. That distinction is the subject of this article.
构建 RDKit 兼容的 Rust 库的一种直接方法是将 RDKit 视为一个可执行的“预言机”：近似实现某个功能，在两个实现中运行语料库，检查不匹配项，让 AI 代理修复失败案例，扩展语料库，然后重复此过程。现代编程代理使这种工作流程变得非常快。COSMolKit 特意遵循了一种不同的开发模式。对于兼容性至关重要的化学计算，其实现首先源自固定的上游源码。差异化语料库随后被用于审计该移植版本，而不是通过迭代方式教导启发式实现如何模仿 RDKit。这种区别正是本文的主题。
Two Ways to Build an RDKit-Compatible Implementation
构建 RDKit 兼容实现的两种方式
With an executable reference such as RDKit, the most obvious development strategy is differential output fitting. Start with an implementation of the general algorithm, run the same molecules through RDKit and the new implementation, compare the outputs, and repair whatever differs. In the agent era, this approach is especially attractive. An agent can implement a feature from documentation or a high-level algorithm description, execute thousands of differential examples, cluster failures, infer additional rules, patch the implementation, and repeat the process with very little human intervention.
有了像 RDKit 这样可执行的参考实现，最显而易见的开发策略是“差异化输出拟合”。从通用算法的实现开始，在 RDKit 和新实现中运行相同的分子，比较输出，并修复所有差异。在 AI 代理时代，这种方法特别具有吸引力。代理可以根据文档或高级算法描述实现功能，执行数千个差异化示例，对失败案例进行聚类，推断附加规则，修补实现，并在极少的人工干预下重复该过程。
Conceptually: implement an approximate feature ↓ run reference corpus ↓ observe mismatches ↓ infer missing behavior ↓ patch ↓ expand corpus ↓ repeat. This is a legitimate engineering strategy when approximate compatibility is sufficient. It can also produce very high empirical agreement. The difficulty is that the corpus gradually becomes part of the implementation specification. A feature may reach 99% on a small corpus, only to expose an entirely new class of failures when the corpus grows. Another increase may reveal interactions between aromaticity and stereochemistry; another may expose query behavior, unusual valence state, operation ordering, or some previously unseen combination of options.
概念上：实现近似功能 ↓ 运行参考语料库 ↓ 观察不匹配项 ↓ 推断缺失行为 ↓ 修补 ↓ 扩展语料库 ↓ 重复。当近似兼容性足够时，这是一种合法的工程策略。它也可以产生非常高的经验一致性。困难在于，语料库逐渐成为了实现规范的一部分。一个功能在小型语料库上可能达到 99% 的一致性，但当语料库扩大时，却会暴露出全新的失败类别。语料库的进一步增加可能会揭示芳香性和立体化学之间的相互作用；另一次增加可能会暴露查询行为、异常价态、操作顺序或以前从未见过的选项组合。
The implementation therefore tends to grow together with the corpus: larger corpus ↓ new mismatch family ↓ new heuristic branch ↓ larger implementation ↓ larger corpus ↓ … At that point, development progress becomes difficult to estimate. “99.9% complete” does not tell us whether the remaining 0.1% consists of ten isolated cases or an entire semantic family that the implementation has not yet modeled. More importantly, even a corpus with millions of molecules cannot prove that a real production workflow will not exercise an unobserved combination. COSMolKit tries to invert this relationship.
因此，实现往往会随着语料库的增长而增长：更大的语料库 ↓ 新的不匹配系列 ↓ 新的启发式分支 ↓ 更大的实现 ↓ 更大的语料库 ↓ …… 此时，开发进度变得难以估计。“99.9% 完成”并不能告诉我们剩下的 0.1% 是由十个孤立案例组成的，还是实现尚未建模的整个语义族。更重要的是，即使拥有数百万个分子的语料库也无法证明真实的生产工作流程不会触发某种未观察到的组合。COSMolKit 试图颠倒这种关系。
Corpus Agreement and Semantic Reproduction Are Different Claims
语料库一致性与语义复现是不同的主张
Consider two implementations that both report 100% agreement on the same million-molecule corpus. Implementation A was built through repeated differential correction. When the corpus exposed a mismatch, the implementation was modified until the output matched. Implementation B was constructed by tracing the relevant upstream source behavior, reproducing those state transitions in Rust, and then using the million molecules to test whether the port was correct. The headline result can be identical: 1,000,000 / 1,000,000 matched but the evidentiary meaning is different.
考虑两个在同一百万分子语料库上报告 100% 一致性的实现。实现 A 是通过反复的差异化修正构建的。当语料库暴露出不匹配时，修改实现直到输出匹配为止。实现 B 是通过追踪相关的上游源码行为，在 Rust 中复现这些状态转换，然后使用这百万个分子来测试移植是否正确而构建的。最终结果可能相同：1,000,000 / 1,000,000 匹配，但其证据意义不同。
The distinction is essentially this: 这种区别本质上是：
| Corpus-driven output fitting | Source-backed reproduction |
|---|---|
| 基于语料库的输出拟合 | 基于源码的复现 |
| Reference output reveals missing behavior | Upstream source defines intended behavior |
| 参考输出揭示缺失的行为 | 上游源码定义预期的行为 |
| Failing example motivates implementation change | First source-state divergence motivates implementation change |
| 失败示例驱动实现变更 | 首次源码状态偏差驱动实现变更 |
| Corpus gradually acts as specification | Corpus acts as auditor |
| 语料库逐渐充当规范 | 语料库充当审计员 |
| New corpus scale may require new heuristic branches | New corpus scale tests an already-defined transition |
| 新的语料库规模可能需要新的启发式分支 | 新的语料库规模测试已定义的转换 |
| Passing observed cases supports empirical agreement | Passing cases support a source-derived semantic claim |
| 通过观察到的案例支持经验一致性 | 通过案例支持源自源码的语义主张 |
| Progress can become difficult to estimate as edge cases accumulate | Remaining work can be tracked against source/call-graph closure |
| 随着边缘案例积累，进度难以估计 | 剩余工作可根据源码/调用图闭包进行跟踪 |
The first approach is not inherently illegitimate. It simply supports a different kind of confidence. For COSMolKit’s parity-covered chemistry, we wanted the second.
第一种方法并非本质上不合法。它只是支持一种不同类型的置信度。对于 COSMolKit 的对等化学计算，我们选择了第二种。
The Corpus Should Audit the Implementation, Not Write It
语料库应该审计实现，而不是编写实现
The central development rule is therefore: Validation should verify the port. It should not become the process by which the implementation discovers what the reference probably meant. The intended direction is: pinned upstream source ↓ identify source semantics ↓ reproduce them in Rust ↓ focused source regression ↓ large-scale differential validation not: large reference corpus ↓ observe wrong output ↓ invent a correction ↓ rerun ↓ repeat until the corpus is green.
因此，核心开发规则是：验证应该用于核实移植结果，而不应成为实现去“猜测”参考实现意图的过程。预期的方向是：固定上游源码 ↓ 识别源码语义 ↓ 在 Rust 中复现 ↓ 聚焦源码回归 ↓ 大规模差异化验证；而不是：大型参考语料库 ↓ 观察错误输出 ↓ 发明修正方案 ↓ 重新运行 ↓ 重复直到语料库全部通过。
That change in direction has consequences throughout the project. It changes how source code is written. It changes how a mismatch is debugged. It changes what an agent is allowed to do when a test fails. And it changes what “100% parity” means.
这种方向的改变对整个项目产生了深远影响。它改变了源码的编写方式，改变了不匹配项的调试方式，改变了测试失败时 AI 代理被允许的操作，也改变了“100% 对等”的含义。