Crate use_molecule 

use-molecule

Small molecular identity primitives for RustUse chemistry crates.

use-molecule represents molecules as discrete chemical entities with a name, formula, optional explicit atoms, optional simple atom connections, formal charge, and lightweight classification labels. It stays structural and avoids simulation, force fields, orbital theory, reaction modeling, file formats, external data fetching, and molecule databases.

What this crate provides

Item	Purpose
Molecule	Named molecular entity with formula and metadata
MoleculeBuilder	Builder for optional atom-level molecule assembly
MoleculeName	Validated molecule name
MolecularFormula	Molecule-facing formula wrapper
MolecularAtom	Explicit atom entry
MolecularAtomId	Optional validated atom identifier
AtomIndex	Zero-based explicit atom index
AtomLabel	Validated atom element-label shape
AtomCount	Explicit atom count wrapper
AtomConnection	Simple index-to-index atom connection
MoleculeCharge	Formal molecule charge
MoleculeKind	Lightweight classification label
MoleculeValidationError	Structured construction and validation errors

Installation

[dependencies]
use-molecule = "0.1.0"

Quick Examples

Create a simple molecule

use use_chemical_formula::ChemicalFormula;
use use_molecule::{Molecule, MoleculeKind};

let water = Molecule::new("water", ChemicalFormula::parse("H2O")?)?
    .with_kind(MoleculeKind::Neutral);

assert_eq!(water.name().as_str(), "water");
assert_eq!(water.formula().to_string(), "H2O");
assert_eq!(water.kinds(), &[MoleculeKind::Neutral]);

Build a molecule with explicit atoms

use use_molecule::{MolecularAtom, Molecule};

let molecule = Molecule::builder("water")
    .formula("H2O".parse()?)
    .atom(MolecularAtom::new("O")?)
    .atom(MolecularAtom::new("H")?)
    .atom(MolecularAtom::new("H")?)
    .build()?;

assert_eq!(molecule.atom_count(), 3);

Scope

• Represents molecule identity, names, formulas, atoms, connections, charge, and kind labels.
• Uses use-chemical-formula for formula primitives and atom label shape validation.
• Validates that molecule names, atom identifiers, atom labels, and connection indices are structurally usable.
• Keeps atom connections as simple index pairs with an optional order.
• No molecular geometry.
• No force fields.
• No orbital theory or quantum chemistry.
• No reactions or stoichiometry.
• No molar mass calculation.
• No SMILES, InChI, MOL, SDF, PDB, or other external chemical file formats.
• No runtime network access or hardcoded molecule database.

Relationship to use-chemistry

use-molecule is a focused child crate for molecular identity primitives. The use-chemistry umbrella crate reexports it alongside compound, formula, element, isotope, periodic-table, atomic-number, atomic-mass, and electron-shell helpers. Molecular identity primitives.

Structs

AtomConnection

A simple connection between explicit atoms.

AtomCount

A count of explicit atoms in a molecule.

AtomIndex

A zero-based atom index into a molecule’s explicit atom list.

AtomLabel

A validated atom label with a basic element-symbol shape.

MolecularAtom

An explicit atom entry in a molecule.

MolecularAtomId

A validated atom identifier.

MolecularFormula

A molecule-facing chemical formula wrapper.

Molecule

A named molecular entity with formula and optional structural primitives.

MoleculeBuilder

Builder for assembling a molecule with optional explicit atom data.

MoleculeCharge

A formal molecule charge.

MoleculeName

A validated molecule name.

Enums

MoleculeKind

A lightweight molecule classification label.

MoleculeValidationError

Errors returned when constructing molecule values.