use-stoichiometry 0.1.0

Stoichiometry primitives for RustUse
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118

# 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

```toml
[dependencies]
use-stoichiometry = "0.1.0"
```

## Quick Examples

### Create a reaction entry

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

# fn main() -> Result<(), Box<dyn std::error::Error>> {
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");
# Ok(())
# }
```

### Create a mole ratio

```rust
use use_stoichiometry::{MoleRatio, StoichiometricCoefficient};

# fn main() -> Result<(), Box<dyn std::error::Error>> {
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");
# Ok(())
# }
```

### Calculate percent yield

```rust
use use_stoichiometry::PercentYield;

# fn main() -> Result<(), Box<dyn std::error::Error>> {
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%");
# Ok(())
# }
```

## 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.