# utomid-rs
**utomid-rs** is a compact Rust library for representing chemical elements and compounds.
It’s designed for simulation and material modeling, with a focus on **compact encoding**
and **fast operations** rather than full-blown chemistry accuracy.
---
## ✨ Features
- Lookup of all 118 chemical elements (`Element` struct)
- Encode atomic numbers into a compact `u8` representation
- Decode element IDs back into names, symbols, valence, and atomic mass
- Build compounds either as expanded lists (`[1, 1, 8]` for H₂O) or compact pairs (`[(1,2), (8,1)]`)
- Calculate compound **molecular mass**
- Render compounds into human-readable **formulas** (e.g. `"H2O"`, `"C6H12O6"`)
- Benchmark-ready for performance tuning
---
## 📦 Installation
Add this crate to your project:
```bash
cargo add utomid-rs
```
Or manually in `Cargo.toml`:
```toml
[dependencies]
utomid-rs = "0.1"
```
---
## 🚀 Usage
```rust
use utomid_rs::{CompactCompound, compound_formula, compound_mass};
// Expanded representation (array of atomic numbers)
let water = vec![1,1,8]; // H2O
println!("Formula: {}", compound_formula(&water));
println!("Mass: {}", compound_mass(&water));
// Compact representation
let water_compact = CompactCompound::new(vec![(1,2), (8,1)]);
println!("Formula: {}", water_compact.formula());
println!("Mass: {}", water_compact.mass());
```
Output:
```
Formula: H2O
Mass: 18.015
```
---
## 🧪 Benchmarks
Run with:
```bash
cargo bench
```
Sample results (on a mid-tier CPU):
```
mass H2O (compact) time: ~18 ns
formula H2O (compact) time: ~92 ns
mass glucose (compact) time: ~27 ns
formula glucose (compact) ~165 ns
```
---
## 📖 Roadmap
- Add bond/interaction utilities
- Expand into materials-level abstractions (`air`, `water`, `steel`, etc.)
- Optional probabilistic reaction rules
---
## 📜 License
Licensed under MIT.
See [LICENSE](LICENSE) for details.