chematic-perception

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

Features

Ring Detection (SSSR)

Horton minimum cycle basis: deterministic smallest-ring basis
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

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
Horton candidates + GF(2)	SSSR ring detection	graph-dependent; bounded by the implementation
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.

Validation

Run cargo test -p chematic-perception. Model choices, differential results, and known residuals are documented in docs/validation.md and docs/compatibility-scope.md. Release history is maintained in the repository CHANGELOG.md.

License

MIT OR Apache-2.0

chematic-perception 1.0.12