Struct Material 

pub struct Material {
    pub comp: BTreeMap<NuclideId, f64>,
    /* private fields */
}

A nuclear material: nuclide masses plus optional density and metadata.

The composition stores absolute masses per nuclide, in grams by convention; only relative amounts matter for fraction-based consumers, which normalize on demand. Density is deliberately separate from the composition: it is a property of the physical stream and is not scaled or combined by the arithmetic operators except where noted.

Combining two materials clears density and metadata (a mixture has no single density); scalar scaling preserves them.

Fields

comp: BTreeMap<NuclideId, f64>

Stored masses (grams) keyed by nuclide.

Implementations

impl Material

pub fn from_formula( formula: &str, masses: &impl MassProvider, abundances: &impl AbundanceProvider, density: Option<f64>, ) -> FormulaResult<Self>

Build a material from a chemical formula, expanding each element into its naturally occurring isotopes.

Mirrors Material::from_atom_frac: atom counts come from the parsed formula weighted by natural-abundance fractions, stored masses are n_i * M_i using masses, and density is attached unchanged. Fails with the parse/abundance variants of FormulaError for bad input and with FormulaError::Core wrapping crate::Error::MissingMass when an isotope’s mass is unknown.

pub fn expand_elements( &mut self, masses: &impl MassProvider, abundances: &impl AbundanceProvider, ) -> FormulaResult<()>

Replace natural-element placeholder entries with their isotopic breakdown, preserving each entry’s stored mass.

Placeholders follow the mcnp-io inp convention: a bare elemental zaid (z*1000, AAA == 0) becomes the nucid z * 10_000_000 ([is_elemental]). Each placeholder of element z holding g grams is replaced by isotope masses g * x_i * M_i / M̄, where x_i are the (normalized) natural-abundance fractions and M̄ the abundance-weighted mean atomic mass — i.e. the same number of atoms of each isotope as the elemental entry implied. Explicitly named nuclides are left untouched, so mixed elemental + isotopic compositions are supported.

Fails with FormulaError::NoAbundanceData when the provider has no isotopes for an element, or FormulaError::Core wrapping crate::Error::MissingMass when an isotope mass is unknown.

pub fn collapse_elements(&self) -> Self

Inverse grouping of Material::expand_elements: fold every nuclide into its element’s placeholder row keyed by the natural-element id z * 10_000_000 (zaid z*1000). Placeholder entries already carry that key and simply accumulate alongside collapsed nuclides. Density and metadata are preserved; masses are summed exactly.

impl Material

pub fn new() -> Self

An empty material.

pub fn from_atom_frac( atoms: &[(NuclideId, f64)], masses: &impl MassProvider, density: Option<f64>, ) -> Result<Self>

Build a material from atom counts/fractions, converting to masses via m_i = n_i * M_i with atomic masses from masses.

Entries with zero atom count are skipped. Fails with crate::Error::MissingMass if any nonzero entry lacks a known atomic mass.

pub fn add_nuclide(&mut self, id: NuclideId, mass: f64)

Add mass grams of id, accumulating when already present.

pub fn remove_nuclide(&mut self, id: NuclideId) -> Option<f64>

Remove a nuclide, returning its stored mass if present.

pub fn clear(&mut self)

Drop the entire composition (density and metadata are kept).

pub fn mass(&self) -> f64

Total stored mass in grams.

pub fn density(&self) -> Option<f64>

Mass density previously set on this material, if any.

pub fn set_density(&mut self, density: Option<f64>)

Set (or unset) the mass density.

pub fn metadata(&self) -> Option<&Value>

Free-form metadata attached to this material.

pub fn set_metadata(&mut self, metadata: Option<Value>)

Replace the free-form metadata.

pub fn weight_fractions(&self) -> Result<BTreeMap<NuclideId, f64>>

Normalized weight fractions; they sum to one.

pub fn atom_fractions( &self, masses: &impl MassProvider, ) -> Result<BTreeMap<NuclideId, f64>>

Normalized atom fractions; they sum to one.

Each nuclide contributes moles proportional to mass / M; atomic masses come from masses.

pub fn mix_by_mass(parts: &[(&Material, f64)]) -> Result<Self>

Mix streams weighted by relative mass amounts.

Fractions need not sum to one; they are relative weights of each stream’s full mass.

pub fn mix_by_volume(parts: &[(&Material, f64)]) -> Result<Self>

Mix streams weighted by relative volumes, converting each stream’s contribution through its own density (m = v * rho). Every input must have a positive density set.

impl Material

pub fn activity( &self, analytics: &Analytics<'_>, ) -> Result<BTreeMap<NuclideId, f64>, AnalyticsError>

Activity A = λ·N per nuclide, in becquerels.

Atom counts follow from stored masses through masses (N = m / (M · u) with u = 1.66053906892e-24 g) and decay constants through decays. Fails with AnalyticsError::MissingDecay for nuclides without decay data and AnalyticsError::Core wrapping crate::Error::MissingMass when an atomic mass is unknown.

pub fn specific_activity( &self, analytics: &Analytics<'_>, ) -> Result<f64, AnalyticsError>

Specific activity of the whole material, in Bq/g: total activity divided by total stored mass. Fails with AnalyticsError::Core for empty or non-positive materials; otherwise identical error behavior to Material::activity.

pub fn decay_heat( &self, analytics: &Analytics<'_>, energies: &impl DecayEnergyProvider, ) -> Result<BTreeMap<NuclideId, f64>, AnalyticsError>

Decay heat per nuclide, in watts: P_i = A_i · E_i.

Activities come from Material::activity (masses via analytics, decay constants via analytics.decays); mean recoverable energies per decay come from energies in MeV, converted with MEV_TO_JOULES. Energies are screening-level placeholders (see DecayEnergies), so heat numbers are order-of-magnitude checks, not calorimetry.

Fails with AnalyticsError::MissingEnergy for nuclides without a decay-energy row; otherwise identical error behavior to Material::activity.

pub fn total_decay_heat( &self, analytics: &Analytics<'_>, energies: &impl DecayEnergyProvider, ) -> Result<f64, AnalyticsError>

Total decay heat of the whole material, in watts: the sum of Material::decay_heat. Same error behavior.

impl Material

pub fn to_xml(&self, name: &str, density: f64, units: &str) -> Result<String>

Serialize this material as a <material> XML fragment.

Components are written as weight fractions (wo attributes). The density and its units are taken from the arguments rather than from Material::density, matching the free-standing export style.

Trait Implementations

impl Add for Material

fn add(self, rhs: Material) -> Material

Combine two mass streams: per-nuclide masses add. Density and metadata are cleared on the mixture. Nuclides whose combined mass is exactly zero are dropped.

type Output = Material

The resulting type after applying the + operator.

impl Add<f64> for Material

fn add(self, rhs: f64) -> Material

Raise the total mass by rhs grams while preserving relative composition. Density is unchanged.

Panics

If the current mass is non-positive or the new total would be.

type Output = Material

The resulting type after applying the + operator.

impl Clone for Material

fn clone(&self) -> Material

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Material

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Material

fn default() -> Material

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Material

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Div<f64> for Material

fn div(self, rhs: f64) -> Material

Divide every stored mass by rhs (density unchanged).

Panics

If rhs is zero.

type Output = Material

The resulting type after applying the / operator.

impl Mul<f64> for Material

fn mul(self, rhs: f64) -> Material

Scale every stored mass by rhs (density unchanged).

type Output = Material

The resulting type after applying the * operator.

impl PartialEq for Material

fn eq(&self, other: &Material) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for Material

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Material

impl Sub for Material

fn sub(self, rhs: Material) -> Material

Remove a mass stream: per-nuclide masses subtract. Density and metadata are cleared. Nuclides whose combined mass is exactly zero are dropped.

type Output = Material

The resulting type after applying the - operator.

impl Sub<f64> for Material

fn sub(self, rhs: f64) -> Material

Lower the total mass by rhs grams while preserving relative composition.

Panics

If the current mass is non-positive or the remainder would be.

type Output = Material

The resulting type after applying the - operator.