Expand description
chematic-cip — low-level, hierarchical-digraph CIP (Cahn-Ingold-Prelog)
stereochemistry engine for chematic.
Most applications should use [chematic_chem::assign_cip_with_mode] rather
than depending on this crate directly. That’s the stable, supported entry point
(opt-in CipMode::Accurate: this engine’s R/S and E/Z, legacy allenes; see
docs/rfcs/cip_accurate_rfc.md’s Milestone 5A). This crate is the low-level engine
behind it, published separately so chematic-chem can depend on it normally.
The accurate engine remains experimental and may receive breaking API revisions
in a future 0.x minor release.
Full milestone history in docs/rfcs/cip_accurate_rfc.md at the workspace root: this
crate now builds a provenance-carrying digraph, ranks substituents (Rules 1a/1b/2/4b/5),
and assigns R/S — the current residual-corpus report estimates 99.64%
stable-oracle agreement (4171/4186) against modern RDKit rdCIPLabeler on
the project’s full validation corpus,
with phosphorus on an unsaturated ring labelled as RDKit labels it (a label
that changes with the Kekulé spelling, see label_depends_on_kekule_spelling).
It does not replace chematic_chem::assign_cip()’s default (legacy) path, which is unaffected.
The motivation is a real, proven limitation in chematic-chem’s existing engine:
cip_branch_spheres/compare_branches pool every atom at a given BFS depth into
one sorted multiset and compare shell-by-shell. That’s an approximation of CIP, not
the real algorithm (which recursively compares branch-by-branch, following the
highest-priority sub-branch first) – and the approximation is unsafe to patch
piecemeal: extending a correct double-bond duplication rule to triple bonds went net
negative (16 newly-wrong stereocenters vs. 1 newly-fixed) because the pooled
representation had already discarded the branch/provenance information a correct
comparison needs. This crate’s digraph::CipDigraph keeps that information as
explicit, provenance-carrying nodes instead.
Re-exports§
pub use assign::AccurateCipAssignment;pub use assign::SkipReason;pub use assign::assign_cip_accurate_experimental;pub use assign::assign_cip_accurate_experimental_without_mancude;pub use assign::label_depends_on_kekule_spelling;pub use assign::label_follows_rdkit_smiles_reading;pub use budget::CipBudget;pub use compare::BranchComparison;pub use compare::CipCompareError;pub use compare::CompareContext;pub use compare::compare_ligands;pub use compare::rank_children;pub use digraph::CipDigraph;pub use digraph::DigraphExpander;pub use edge::CipEdge;pub use edge::EdgeId;pub use mancude::MancudeBudget;pub use mancude::MancudeComponentId;pub use mancude::MancudeContext;pub use mancude::MancudeError;pub use mancude::effective_atomic_number;pub use mancude::enumerate_kekule_matchings;pub use mancude::prepare_kekule_form;pub use node::CipNode;pub use node::CipNodeKind;pub use node::NodeId;pub use rational::AtomicNumberKey;pub use rational::RationalAtomicNumber;pub use substituent_rank::SubstituentRanker;pub use trace::ComparisonTrace;pub use trace::DecisionStep;
Modules§
- assign
- A minimal, tetrahedral-only R/S assignment, built on the new comparator, for the
sole purpose of producing labels the Milestone 2 corpus report can diff against
RDKit’s oracle. Not wired into
chematic_chem::assign_cip()or any public surface beyond this crate – explicitly experimental. No E/Z, no allene; this module only touches atoms with aChiralityannotation and exactly 4 resolvable substituent positions. - budget
- Expansion budget: an explicit backstop against pathological node-count blow-up.
- compare
- Recursive, branch-by-branch CIP comparison – Rules 1a (atomic number), 1b (duplicate-node handling), and 2 (isotope). Deliberately not Rules 3+ (stereo-dependent): this module has no notion of R/S, E/Z, or pseudoasymmetry.
- debug
- Human-readable and JSON dumps of a
CipDigraph. - digraph
- The hierarchical digraph itself.
- digraph_
diff - Structural diff between two
CipDigraphs built for “the same” conceptual stereocenter under different, chemically-equivalent input representations (aromatic notation vs. a Kekulé respelling, an atom-renumbering, a SMILES respelling) – Milestone 3B-0’s evidence artifact for why the current (pre-M3B) digraph is representation-dependent on mancude ring systems, collected before any comparator change is made. - edge
- Digraph edge types.
- mancude
- MANCUDE (maximum non-cumulated double bonds) ring treatment: production representation plus a reference oracle.
- node
- Digraph node types.
- rational
- Exact rational representation of a “mean atomic number”.
- substituent_
rank - Pairwise substituent ranking at an arbitrary centre (double-bond ends).
- trace
- Human-readable per-comparison decision traces.
Enums§
- CipError
- Errors from digraph construction/expansion.