Skip to main content

Crate chematic_cip

Crate chematic_cip 

Source
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 a Chirality annotation 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.