Crate dreid_typer 

A high-performance Rust library for DREIDING force field atom typing and molecular topology perception.

DreidTyper

DreidTyper is a foundational software library for the automated assignment of DREIDING atom types from molecular connectivity. It provides a modern, robust solution for translating a simple chemical graph (MolecularGraph) into a complete, simulation-ready MolecularTopology.

The library is engineered in Rust for performance, memory safety, and reliability. It employs a deterministic, three-phase pipeline (Perceive-Type-Build) to ensure accurate and reproducible results.

Quickstart

The primary entry point of the library is the assign_topology function. Here’s how to build a simple ethanol molecule and perceive its topology:

use dreid_typer::{
    assign_topology, MolecularGraph, MolecularTopology,
    Element, GraphBondOrder,
};

// 1. Define the molecule's connectivity using a `MolecularGraph`.
let mut graph = MolecularGraph::new();
let c1 = graph.add_atom(Element::C); // Atom for the CH3 group
let c2 = graph.add_atom(Element::C); // Atom for the CH2 group
let o = graph.add_atom(Element::O);
let h_c1_1 = graph.add_atom(Element::H);
let h_c1_2 = graph.add_atom(Element::H);
let h_c1_3 = graph.add_atom(Element::H);
let h_c2_1 = graph.add_atom(Element::H);
let h_c2_2 = graph.add_atom(Element::H);
let h_o = graph.add_atom(Element::H);

graph.add_bond(c1, c2, GraphBondOrder::Single).unwrap();
graph.add_bond(c2, o, GraphBondOrder::Single).unwrap();
graph.add_bond(c1, h_c1_1, GraphBondOrder::Single).unwrap();
graph.add_bond(c1, h_c1_2, GraphBondOrder::Single).unwrap();
graph.add_bond(c1, h_c1_3, GraphBondOrder::Single).unwrap();
graph.add_bond(c2, h_c2_1, GraphBondOrder::Single).unwrap();
graph.add_bond(c2, h_c2_2, GraphBondOrder::Single).unwrap();
graph.add_bond(o, h_o, GraphBondOrder::Single).unwrap();

// 2. Call the main function to perceive the topology using default rules.
let topology: MolecularTopology = assign_topology(&graph).unwrap();

// 3. Inspect the results.
assert_eq!(topology.atoms.len(), 9);
assert_eq!(topology.bonds.len(), 8);
assert_eq!(topology.angles.len(), 13);
assert_eq!(topology.torsions.len(), 12);

// Check the assigned DREIDING atom types.
assert_eq!(topology.atoms[c1].atom_type, "C_3");    // sp3 Carbon
assert_eq!(topology.atoms[c2].atom_type, "C_3");    // sp3 Carbon
assert_eq!(topology.atoms[o].atom_type, "O_3");     // sp3 Oxygen
assert_eq!(topology.atoms[h_o].atom_type, "H_HB");  // Hydrogen-bonding Hydrogen
assert_eq!(topology.atoms[h_c1_1].atom_type, "H_"); // Standard Hydrogen

Modules

rules

Rule parsing and customization utilities.

Structs

Angle

Angle entry emitted in the final topology.

AssignmentError

Error reported when the typing engine stalls before all atoms receive types.

Atom

Atom entry emitted in the final topology, combining identity and typing.

AtomNode

Stores the identifier and element for a single atom within a MolecularGraph.

Bond

Bond entry emitted in the final topology.

BondEdge

Captures a bond between two atoms inside a MolecularGraph.

Inversion

Inversion entry emitted in the final topology.

MolecularGraph

Mutable graph of atoms and bonds supplied to the perception pipeline.

MolecularTopology

Canonical topology produced after the typer assigns atom types and torsions.

ParseBondOrderError

Error returned when parsing a bond order string that does not match the enum.

ParseElementError

Error returned when parsing an unknown or misspelled element symbol.

ParseHybridizationError

Error returned when parsing an unrecognized hybridization label.

Torsion

Torsion entry emitted in the final topology.

Enums

Element

Enumerates every element the typer understands along with its atomic number.

GraphBondOrder

Describes the discrete bond multiplicities supported in input graphs.

GraphValidationError

Errors that describe structural or logical issues with the input MolecularGraph.

Hybridization

Captures the VSEPR-derived hybridization states recognized by the typer.

PerceptionError

Errors raised while running the staged chemical perception pipeline.

TopologyBondOrder

Describes the discrete bond multiplicities used in output topologies.

TyperError

Root error emitted by every fallible operation in the typing pipeline.

Functions

assign_topology

Assigns a full molecular topology using the default embedded DREIDING ruleset.

assign_topology_with_rules

Assigns a full molecular topology using a custom set of typing rules.