Crate use_stoichiometry 

use-stoichiometry

Small stoichiometry primitives for RustUse chemistry crates.

use-stoichiometry represents stoichiometric coefficients, formula terms, mole ratios, reaction-side entries, reagent labels, and simple yield values. It stays structural and intentionally avoids equation balancing, product inference, reaction kinetics, thermochemistry, equilibrium calculations, electrochemistry, lab automation, and reaction databases.

What this crate provides

Item	Purpose
StoichiometricCoefficient	Nonzero stoichiometric coefficient
StoichiometricTerm	Coefficient plus formula
StoichiometricRatio	Coefficient ratio
MoleRatio	Mole-ratio wrapper
ReactionSide	Reactant or product side label
ReactionEntry	Formula entry on one reaction side
ReactantEntry	Reactant-side entry wrapper
ProductEntry	Product-side entry wrapper
FormulaQuantity	Formula plus stoichiometric coefficient
LimitingReagent	Validated limiting-reagent label
ExcessReagent	Validated excess-reagent label
TheoreticalYield	Positive finite theoretical yield value
ActualYield	Nonnegative finite actual yield value
PercentYield	Nonnegative finite percent yield value
StoichiometryValidationError	Structured construction and validation error

Installation

[dependencies]
use-stoichiometry = "0.1.0"

Quick Examples

Create a reaction entry

use use_chemical_formula::ChemicalFormula;
use use_stoichiometry::{ReactionEntry, ReactionSide, StoichiometricCoefficient};

let water = ReactionEntry::new(
    StoichiometricCoefficient::new(2)?,
    ChemicalFormula::parse("H2O")?,
    ReactionSide::Product,
)?;

assert_eq!(water.coefficient().value(), 2);
assert_eq!(water.formula().to_string(), "H2O");
assert_eq!(water.side(), ReactionSide::Product);
assert_eq!(water.to_string(), "2H2O");

Create a mole ratio

use use_stoichiometry::{MoleRatio, StoichiometricCoefficient};

let ratio = MoleRatio::new(
    StoichiometricCoefficient::new(2)?,
    StoichiometricCoefficient::new(1)?,
)?;

assert_eq!(ratio.numerator().value(), 2);
assert_eq!(ratio.denominator().value(), 1);
assert_eq!(ratio.to_string(), "2:1");

Calculate percent yield

use use_stoichiometry::PercentYield;

let yield_percent = PercentYield::from_actual_and_theoretical(8.0, 10.0)?;

assert_eq!(yield_percent.value(), 80.0);
assert_eq!(yield_percent.to_string(), "80%");

Scope

• Represents stoichiometric coefficients, formula terms, mole ratios, reaction-side labels, formula quantities, limiting-reagent labels, excess-reagent labels, theoretical yield values, actual yield values, percent yield values, and stable display formatting.
• Uses use-chemical-formula for formula primitives and parsing examples.
• Keeps all chemistry knowledge caller-provided. Callers choose formulas, coefficients, sides, labels, and yield values.
• No chemical equation balancing.
• No product inference from reactants.
• No reaction kinetics.
• No thermochemistry.
• No equilibrium calculations.
• No electrochemistry.
• No unit-heavy mass/mole conversion.
• No hardcoded reaction database.
• No runtime network access or external chemistry data.
• No lab automation toolkit behavior.

Relationship to use-chemistry

use-stoichiometry is a focused child crate for stoichiometry primitives. The use-chemistry umbrella crate reexports it alongside formula, compound, molecule, ion, oxidation-state, bond, element, isotope, periodic-table, atomic-number, atomic-mass, and electron-shell helpers. Stoichiometry primitives.

Structs

ActualYield

A nonnegative finite actual yield value.

ExcessReagent

A validated excess-reagent label.

FormulaQuantity

A formula with a stoichiometric quantity.

LimitingReagent

A validated limiting-reagent label.

MoleRatio

A mole ratio between two stoichiometric coefficients.

PercentYield

A nonnegative finite percent yield value.

ProductEntry

A product-side reaction entry.

ReactantEntry

A reactant-side reaction entry.

ReactionEntry

A stoichiometric entry on one side of a reaction.

StoichiometricCoefficient

A nonzero stoichiometric coefficient.

StoichiometricRatio

A ratio between two stoichiometric coefficients.

StoichiometricTerm

A stoichiometric coefficient paired with a formula.

TheoreticalYield

A positive finite theoretical yield value.

Enums

ReactionSide

A reaction-side label.

StoichiometryValidationError

Errors returned when constructing stoichiometry values.