elements_rs 0.1.4

A comprehensive library for chemical elements and their isotopes with rich metadata
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

# Elements

[![CI](https://github.com/earth-metabolome-initiative/elements-rs/actions/workflows/rust.yml/badge.svg)](https://github.com/earth-metabolome-initiative/elements-rs/actions/workflows/rust.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Codecov](https://codecov.io/gh/earth-metabolome-initiative/elements-rs/branch/main/graph/badge.svg)](https://codecov.io/gh/earth-metabolome-initiative/elements-rs)
[![Crates.io](https://img.shields.io/crates/v/elements_rs.svg)](https://crates.io/crates/elements_rs)
[![Docs.rs](https://docs.rs/elements_rs/badge.svg)](https://docs.rs/elements_rs)

A comprehensive Rust crate providing type-safe enumerations and rich metadata for all [chemical elements](https://en.wikipedia.org/wiki/Chemical_element) of the [periodic table](https://en.wikipedia.org/wiki/Periodic_table) and their [isotopes](https://en.wikipedia.org/wiki/Isotope). The crate includes all 118 elements from Hydrogen to Oganesson with detailed information for each [isotope](https://en.wikipedia.org/wiki/Isotope) including [mass numbers](https://en.wikipedia.org/wiki/Mass_number), [relative atomic masses](https://en.wikipedia.org/wiki/Relative_atomic_mass), [isotopic composition](https://en.wikipedia.org/wiki/Natural_abundance), and identification of the most abundant isotope. Chemical properties are fully supported: [standard atomic weights](https://en.wikipedia.org/wiki/Standard_atomic_weight), [oxidation states](https://en.wikipedia.org/wiki/Oxidation_state) with validation, [valence electrons](https://en.wikipedia.org/wiki/Valence_electron), bond numbers, [electron configurations](https://en.wikipedia.org/wiki/Electron_configuration) with [atomic orbitals](https://en.wikipedia.org/wiki/Atomic_orbital), and [principal quantum numbers](https://en.wikipedia.org/wiki/Principal_quantum_number).

Would you like to see more information or features? Please open an issue or a pull request!

The crate is [`no_std`](https://docs.rust-embedded.org/book/intro/no-std.html), and optionally supports [`serde`](https://serde.rs/) for serialization/deserialization and [`arbitrary`](https://crates.io/crates/arbitrary) for fuzzing.

## Usage

Add this to your `Cargo.toml`:

```toml
[dependencies]
elements_rs = "0.1"
```

### Basic Example

```rust
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

```rust
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

```rust
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`](https://crates.io/crates/serde) (default): Enables [`Serialize`](https://docs.serde.rs/serde/trait.Serialize.html) and [`Deserialize`](https://docs.serde.rs/serde/trait.Deserialize.html) implementations for `Element` and `Isotope` types
- [`arbitrary`](https://crates.io/crates/arbitrary): Enables [`Arbitrary`](https://docs.rs/arbitrary/latest/arbitrary/trait.Arbitrary.html) implementations for `Element` and `Isotope` types, useful for fuzzing

## License

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