Elements

A comprehensive Rust crate providing type-safe enumerations and rich metadata for all chemical elements of the periodic table and their isotopes. The crate includes all 118 elements from Hydrogen to Oganesson with detailed information for each isotope including mass numbers, relative atomic masses, isotopic composition, and identification of the most abundant isotope. Chemical properties are fully supported: standard atomic weights, oxidation states with validation, valence electrons, bond numbers, electron configurations with atomic orbitals, and principal quantum numbers. Optional features provide database integration through Diesel (PostgreSQL and SQLite), PostgreSQL extension support via PGRX, and serialization through serde.

Usage

Add this to your Cargo.toml:

[dependencies]
elements = "0.1"

Basic Example

use elements_rs::{Element, BondsNumber, ValenceElectrons};

// Get an element
let carbon = Element::C;

// Access properties
println!("Name: {}", carbon.name());
println!("Atomic weight: {}", carbon.standard_atomic_weight());
println!("Valence electrons: {}", carbon.valence_electrons());

// Check oxidation states
assert!(carbon.is_valid_oxidation_state(4));
assert!(carbon.is_valid_oxidation_state(-4));

// Get bond information
let (min_bonds, max_bonds) = carbon.number_of_bonds();
assert_eq!((min_bonds, max_bonds), (4, 4));

Working with Isotopes

use elements_rs::isotopes::{CarbonIsotope, Isotope, MassNumber, RelativeAtomicMass};

// Get a specific isotope
let carbon_12 = CarbonIsotope::C12;
println!("Mass number: {}", carbon_12.mass_number());
println!("Relative atomic mass: {}", carbon_12.relative_atomic_mass());

// Work with the generic Isotope enum
let isotope = Isotope::C(carbon_12);

Parsing from Strings

use elements_rs::Element;
use std::str::FromStr;

// Parse element symbols
let oxygen = Element::from_str("O").unwrap();
let nitrogen = Element::from_str("N").unwrap();

Feature Flags

serde (default): Enables Serialize and Deserialize implementations for Element and Isotope types
diesel: Adds Diesel ORM trait implementations for database queries
sqlite: Enables SQLite-specific type mappings (requires diesel)
postgres: Enables PostgreSQL-specific type mappings (requires diesel)
diesel_pgrx: Integrates Diesel with PGRX for PostgreSQL extension development (requires diesel)
pgrx: Enables PostgreSQL extension API through PGRX
pg13, pg14, pg15, pg16, pg17: Select specific PostgreSQL version (requires pgrx, mutually exclusive)

Compiling the PGRX Extension

After cloning the repository, you can compile the PGRX extension in the ./extension directory by running:

USER_ID=$(id -u) GROUP_ID=$(id -g) docker compose up

Note: The USER_ID and GROUP_ID environment variables ensure proper file permissions when mounting volumes, avoiding root-owned files on the host system.

License

This project is licensed under the same terms as the parent EMI monorepo.

elements_rs 0.1.0