Crate pauling 

A cheminformatics library in pure Rust for the perception of chemical resonance from molecular graphs.

The theory of chemical resonance was first developed by Linus Pauling in the 1930s.

Overview

pauling perceives resonance by executing a robust, multi-stage pipeline that analyzes a molecular graph’s topology. The primary entry point is the find_resonance_systems function, which performs the full workflow:

1. Ring Perception: Identifies the Smallest Set of Smallest Rings (SSSR).
2. Aromaticity Perception: Determines aromatic systems using Hückel’s rule.
3. Kekulization: Assigns a valid Kekulé structure to aromatic rings.
4. Atom State Perception: Calculates valence, lone pairs, and hybridization.
5. Resonance Identification: Groups all conjugated atoms and bonds into distinct resonance systems.

The library is designed to be flexible. It operates on any data structure that implements the traits::MoleculeGraph trait, allowing seamless integration with existing molecular modeling projects. For convenience, a simple Molecule implementation is provided for testing and examples.

Quick Start

use pauling::{find_resonance_systems, BondOrder, Element, Molecule, PerceptionError};

// 1. Build a benzene molecule (C6H6) with all atoms explicitly defined.
let mut benzene = Molecule::new();

// First, create the 6 carbon atoms for the ring.
let carbons: Vec<_> = (0..6).map(|_| benzene.add_atom(Element::C, 0)).collect();

// Then, create the alternating bonds of the carbon backbone.
let mut ring_bonds = Vec::new();
ring_bonds.push(benzene.add_bond(carbons[0], carbons[1], BondOrder::Double).unwrap());
ring_bonds.push(benzene.add_bond(carbons[1], carbons[2], BondOrder::Single).unwrap());
ring_bonds.push(benzene.add_bond(carbons[2], carbons[3], BondOrder::Double).unwrap());
ring_bonds.push(benzene.add_bond(carbons[3], carbons[4], BondOrder::Single).unwrap());
ring_bonds.push(benzene.add_bond(carbons[4], carbons[5], BondOrder::Double).unwrap());
ring_bonds.push(benzene.add_bond(carbons[5], carbons[0], BondOrder::Single).unwrap());

// Finally, create and attach the 6 hydrogen atoms.
for &carbon_id in &carbons {
    let hydrogen_id = benzene.add_atom(Element::H, 0);
    benzene.add_bond(carbon_id, hydrogen_id, BondOrder::Single).unwrap();
}

// 2. Run the perception pipeline.
let systems = find_resonance_systems(&benzene)?;

// 3. Analyze the results.
// Benzene has one resonance system, which consists of only the carbon ring.
assert_eq!(systems.len(), 1);
let system = &systems[0];

// Verify that the system contains exactly the 6 carbon atoms.
let mut system_atoms = system.atoms.clone();
system_atoms.sort();
assert_eq!(system_atoms, carbons);

// Verify that the system contains exactly the 6 carbon-carbon bonds.
let mut system_bonds = system.bonds.clone();
system_bonds.sort();
ring_bonds.sort();
assert_eq!(system_bonds, ring_bonds);

Modules

traits

The core traits (MoleculeGraph, AtomView, BondView) for graph abstraction. Traits that describe atoms, bonds, and the containing graph. Traits that describe the minimum molecular graph interface required by Pauling.

Structs

Molecule

A simple, in-memory molecular graph implementation for examples and testing. Lightweight adjacency-based molecule that implements MoleculeGraph.

ResonanceSystem

Represents a single, connected network of conjugated atoms and bonds. Canonical representation of a resonance system. Connected conjugated component identified by the resonance detector.

Enums

BondOrder

An enumeration of bond orders (Single, Double, etc.). Classification of a bond’s order as used by the perception pipeline.

Element

An enumeration of chemical elements. Chemical element recognised by the perception pipeline.

MoleculeBuildError

Errors that can occur during the construction of a Molecule. Error emitted when an invalid atom or bond is added to a Molecule.

PerceptionError

The error type for all fallible perception operations. Error returned when a perception stage cannot complete successfully.

Functions

find_resonance_systems

The primary entry point to the pauling perception pipeline. Finds all distinct resonance systems present in a molecular graph.

Type Aliases

AtomId

A stable, user-facing identifier for an atom. Unique identifier for an atom inside a molecular graph.

BondId

A stable, user-facing identifier for a bond. Unique identifier for a bond inside a molecular graph.