chematic-perception 0.1.94

SSSR ring perception and Hückel aromaticity for chematic — pure-Rust RDKit alternative
Documentation

chematic-perception

Pure Rust molecular structure perception — ring detection, aromaticity, stereochemistry, charges.

Features

Ring Detection (SSSR)

  • Balducci-Pearlman Algorithm: Efficiently finds smallest set of smallest rings
  • Gaussian Elimination (GF(2)): Linear algebra over finite fields
  • Usage: find_sssr(&mol) -> RingSet

Aromaticity Model

  • Hückel 4n+2 π-Electron Rule: Aromatic vs non-aromatic detection
  • Antiaromaticity (4n) (NEW in v0.1.32): Identifies unstable systems
    • Cyclobutadiene, Cyclooctatetraene, etc.
  • API:
    • assign_aromaticity(&mol) -> AromaticityModel
    • ring_classifications(&mol) -> Vec<RingAromaticity>
    • antiaromatic_rings(&mol) -> Vec<Vec<AtomIdx>>
    • has_antiaromaticity(&mol) -> bool

Stereochemistry

  • CIP Priority Rules: Determine R/S configuration
  • 2D → 3D Stereo: Assign stereoisomers from 2D wedge/dash
  • E/Z Geometry: Double-bond stereochemistry
  • Chiral Enumeration: Generate all stereoisomers

Molecular Properties

  • Implicit Hydrogens: OpenSMILES valence rules
  • Formal Charges: Automatic charge assignment
  • Heteroatoms: N, O, S, P, halogens with correct aromaticity

Version History

v0.1.93 (2026-06-12):

  • NEW: Full multi-sphere CIP priority module (cip_priority module)
  • Hierarchical sphere-by-sphere comparison with phantom atoms for double bonds
  • Atomic mass tiebreaker (Rule 4), isotope handling (Rule 2)
  • Correct R/S assignment for chiral centers with more complex stereochemistry

v0.1.92 (2026-06-12):

  • InChI /t (tetrahedral) and /b (E/Z) stereo layer parsing
  • CIP code assignment from InChI round-trip

v0.1.91 (2026-06-12):

  • Enhanced ECFP radii and Ertl functional group detection
  • True structural fragment signatures

v0.1.32 (2026-06-07):

  • Antiaromaticity detection (4n systems like cyclobutadiene)
  • Improved ring classification APIs

Quick Start

Detect rings

use chematic_perception::find_sssr;

let rings = find_sssr(&mol);
println!("Rings: {}", rings.ring_count());

for ring in rings.rings() {
    println!("Ring atoms: {:?}", ring.atoms);
}

Classify aromaticity

use chematic_perception::assign_aromaticity;

let model = assign_aromaticity(&mol);
let classifications = model.ring_classifications(&mol);

for (i, ring_class) in classifications.iter().enumerate() {
    println!("Ring {}: {:?}", i, ring_class);
}

Check for antiaromaticity (NEW)

if model.has_antiaromaticity(&mol) {
    let antiarom = model.antiaromatic_rings(&mol);
    println!("Antiaromatic rings (unstable): {}", antiarom.len());
}

Assign stereochemistry

use chematic_perception::assign_stereo_from_2d;

let mol_with_stereo = assign_stereo_from_2d(&mol)?;
// mol_with_stereo: 2D wedge/dash bonds converted to R/S

Algorithms

Algorithm Purpose Complexity
Balducci-Pearlman + GF(2) SSSR ring detection O(n³)
Hückel 4n+2 Rule Aromaticity classification O(n)
CIP Priority Rules R/S stereochemistry O(n log n)
E/Z Geometry Detection Double-bond stereochemistry O(n)

Crate Dependencies

  • chematic-core — Atom, Bond, Molecule types
  • chematic-smiles — SMILES parsing

Zero FFI: Pure Rust, WASM-compatible.

Testing

cargo test --lib
# 34 tests: SSSR edge cases, aromaticity, stereochemistry

Version History

v0.1.32 (2026-06-07):

  • NEW: Antiaromaticity detection (4n Hückel rule)
  • NEW: ring_classifications(), antiaromatic_rings(), has_antiaromaticity() methods
  • 16 new aromaticity tests (including antiaromatic systems)

License

MIT OR Apache-2.0