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:

cargo add utomid-rs

Or manually in Cargo.toml:

[dependencies]
utomid-rs = "0.1"

🚀 Usage

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:

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 for details.