nucleide_bindings/

lib.rs

//! Python bindings (`nucleide._internal`).
//!
//! Thin facade only: all logic lives in workspace crates so the Rust API
//! stays usable without Python. Type stubs live in `python/nucleide/_internal.pyi`.

use std::collections::BTreeMap;
use std::str::FromStr;

use pyo3::exceptions::{PyTypeError, PyValueError};
use pyo3::prelude::*;

use numpy::{IntoPyArray, PyArray1, PyArray2, PyArrayMethods};

use nucleide_nuclei::NuclideId;

/// Package version, re-exported to Python.
#[pyfunction]
fn version() -> &'static str {
    env!("CARGO_PKG_VERSION")
}

fn wrap_nucid_err(e: nucleide_nuclei::Error) -> PyErr {
    PyValueError::new_err(e.to_string())
}

// ---------------------------------------------------------------------------
// Nuclide naming
// ---------------------------------------------------------------------------

/// A nuclide identifier (canonical nucid integer + naming conversions).
#[pyclass(name = "Nuclide")]
struct PyNuclide {
    inner: NuclideId,
}

#[pymethods]
impl PyNuclide {
    /// Create from a name such as "U235" or "Am242_m1".
    #[new]
    fn new(name: &str) -> PyResult<Self> {
        NuclideId::from_name(name)
            .map(|inner| Self { inner })
            .map_err(wrap_nucid_err)
    }

    /// GNDS-style name ("U235", "Am242_m1").
    #[getter]
    fn name(&self) -> String {
        self.inner.to_name()
    }

    /// Raw nucid integer.
    #[getter]
    fn nucid(&self) -> u32 {
        self.inner.nucid()
    }

    /// ZZAAAM form (922350 for U-235).
    #[getter]
    fn zzaaam(&self) -> u32 {
        self.inner.zzaaam()
    }

    /// Atomic number.
    #[getter]
    fn z(&self) -> u32 {
        self.inner.z()
    }

    /// Mass number.
    #[getter]
    fn a(&self) -> u32 {
        self.inner.a()
    }

    /// Metastable state index (0 = ground).
    #[getter]
    fn state(&self) -> u32 {
        self.inner.state()
    }

    /// MCNP ZAID integer.
    #[getter]
    fn zaid(&self) -> u32 {
        nucleide_nuclei::dialects::to_zaid(self.inner)
    }

    /// zzllaaam form ("U-235").
    #[getter]
    fn zzllaaam(&self) -> String {
        nucleide_nuclei::dialects::zzllaaam(self.inner)
    }

    /// Serpent-style name ("U-235").
    #[getter]
    fn serpent(&self) -> String {
        nucleide_nuclei::dialects::serpent(self.inner)
    }

    /// NIST-style name.
    #[getter]
    fn nist(&self) -> String {
        nucleide_nuclei::dialects::nist(self.inner)
    }

    /// Cinder integer id.
    #[getter]
    fn cinder(&self) -> u32 {
        nucleide_nuclei::dialects::to_cinder(self.inner)
    }

    /// ALARA name ("u:235").
    #[getter]
    fn alara(&self) -> String {
        nucleide_nuclei::dialects::alara(self.inner)
    }

    /// SZA integer.
    #[getter]
    fn sza(&self) -> u32 {
        nucleide_nuclei::dialects::to_sza(self.inner)
    }

    /// FLUKA element-isotope name; raises ValueError if unavailable.
    fn fluka(&self) -> PyResult<&'static str> {
        nucleide_nuclei::dialects::id_to_fluka(self.inner)
            .map_err(|e| PyValueError::new_err(e.to_string()))
    }

    /// Atomic mass in u (AME2020), or None if unknown.
    #[getter]
    fn mass(&self) -> Option<f64> {
        nucleide_nuclei::data::atomic_mass(self.inner.nucid())
    }

    /// Natural abundance fraction, or None.
    #[getter]
    fn abundance(&self) -> Option<f64> {
        nucleide_nuclei::data::natural_abundance(self.inner.nucid())
    }

    fn __repr__(&self) -> String {
        format!("Nuclide({})", self.inner.to_name())
    }
}

/// Parse a MCNP ZAID integer into a Nuclide.
#[pyfunction]
fn from_zaid(zaid: u32) -> PyResult<PyNuclide> {
    nucleide_nuclei::dialects::from_zaid(zaid)
        .map(|inner| PyNuclide { inner })
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

fn lookup(key: &Bound<'_, PyAny>, f: impl Fn(u32) -> Option<f64>) -> PyResult<Option<f64>> {
    if let Ok(nucid) = key.extract::<u32>() {
        return Ok(f(nucid));
    }
    if let Ok(name) = key.extract::<&str>() {
        let id = NuclideId::from_name(name).map_err(wrap_nucid_err)?;
        return Ok(f(id.nucid()));
    }
    Err(PyTypeError::new_err("expected int nucid or str name"))
}

/// Atomic mass in u for a nucid integer or name string.
#[pyfunction]
fn atomic_mass(key: &Bound<'_, PyAny>) -> PyResult<Option<f64>> {
    lookup(key, nucleide_nuclei::data::atomic_mass)
}

/// Natural abundance fraction for a nucid integer or name string.
#[pyfunction]
fn natural_abundance(key: &Bound<'_, PyAny>) -> PyResult<Option<f64>> {
    lookup(key, nucleide_nuclei::data::natural_abundance)
}

/// A particle species with cross-code name translations.
#[pyclass(name = "Particle")]
struct PyParticle {
    inner: nucleide_nuclei::particles::ParticleId,
}

#[pymethods]
impl PyParticle {
    /// Create from any alias ("n", "neutron", "gamma", PDC int, ...).
    #[new]
    fn new(spec: &Bound<'_, PyAny>) -> PyResult<Self> {
        let inner = if let Ok(pdc) = spec.extract::<i32>() {
            nucleide_nuclei::particles::ParticleId::from_pdc(pdc)
                .ok_or_else(|| PyValueError::new_err(format!("unknown PDC code {pdc}")))?
        } else if let Ok(s) = spec.extract::<&str>() {
            s.parse::<nucleide_nuclei::particles::ParticleId>()
                .map_err(|e| PyValueError::new_err(e.to_string()))?
        } else {
            return Err(PyTypeError::new_err("expected str alias or int PDC"));
        };
        Ok(Self { inner })
    }

    #[getter]
    fn name(&self) -> &'static str {
        self.inner.name()
    }

    #[getter]
    fn describe(&self) -> &'static str {
        self.inner.describe()
    }

    fn mcnp(&self) -> Option<&'static str> {
        self.inner.mcnp()
    }
    fn mcnp6(&self) -> Option<&'static str> {
        self.inner.mcnp6()
    }
    fn fluka(&self) -> Option<&'static str> {
        self.inner.fluka()
    }
    fn geant4(&self) -> Option<&'static str> {
        self.inner.geant4()
    }

    fn __repr__(&self) -> String {
        format!("Particle('{}')", self.inner.name())
    }
}

/// Resolve a reaction name/MT/id string to its numeric id.
#[pyfunction]
fn rxname_id(name: &str) -> PyResult<u32> {
    nucleide_nuclei::rxname::name_to_id(name).map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Canonical short name for a reaction id.
#[pyfunction]
fn rxname_name(id: u32) -> Option<&'static str> {
    nucleide_nuclei::rxname::id_to_name(id)
}

/// ENDF MT number for a reaction id (0 if none registered).
#[pyfunction]
fn rxname_mt(id: u32) -> i32 {
    nucleide_nuclei::rxname::id_to_mt(id)
}

// ---------------------------------------------------------------------------
// MCNP file I/O
// ---------------------------------------------------------------------------

fn io_err(e: nucleide_mcnp_io::xsdir::Error) -> PyErr {
    PyValueError::new_err(e.to_string())
}
fn m_err<T>(r: Result<T, impl std::fmt::Display>) -> PyResult<T> {
    r.map_err(|e| PyValueError::new_err(e.to_string()))
}

/// One xsdir directory entry.
#[pyclass(name = "XsdirTable")]
struct PyXsdirTable {
    inner: nucleide_mcnp_io::xsdir::XsdirTable,
}

#[pymethods]
impl PyXsdirTable {
    #[getter]
    fn name(&self) -> &str {
        &self.inner.name
    }
    #[getter]
    fn awr(&self) -> f64 {
        self.inner.awr
    }
    #[getter]
    fn filename(&self) -> &str {
        &self.inner.filename
    }
    #[getter]
    fn filetype(&self) -> i64 {
        self.inner.filetype
    }
    #[getter]
    fn address(&self) -> i64 {
        self.inner.address
    }
    #[getter]
    fn tablelength(&self) -> i64 {
        self.inner.tablelength
    }
    #[getter]
    fn temperature(&self) -> Option<f64> {
        self.inner.temperature
    }
    #[getter]
    fn ptable(&self) -> bool {
        self.inner.ptable
    }
    /// ZAID text before the '.'.
    fn zaid(&self) -> &str {
        self.inner.zaid()
    }
    /// Serpent directory-entry line.
    fn to_serpent(&self, directory: &str) -> PyResult<String> {
        m_err(self.inner.to_serpent(directory))
    }
    fn __repr__(&self) -> String {
        format!("<XsdirTable: {}>", self.inner.name)
    }
}

/// Parsed xsdir index file.
#[pyclass(name = "Xsdir")]
struct PyXsdir {
    inner: nucleide_mcnp_io::xsdir::Xsdir,
}

#[pymethods]
impl PyXsdir {
    #[getter]
    fn datapath(&self) -> Option<&str> {
        self.inner.datapath.as_deref()
    }
    /// Atomic weight ratios keyed by zaid integer.
    #[getter]
    fn awr(&self) -> BTreeMap<u32, f64> {
        self.inner.awr.clone()
    }
    /// Directory entries in file order.
    #[getter]
    fn tables(&self) -> Vec<PyXsdirTable> {
        self.inner
            .tables
            .iter()
            .map(|t| PyXsdirTable { inner: t.clone() })
            .collect()
    }
    /// Tables whose name contains `name`.
    fn find_table(&self, name: &str) -> Vec<PyXsdirTable> {
        self.inner
            .find_table(name)
            .into_iter()
            .map(|t| PyXsdirTable { inner: t.clone() })
            .collect()
    }
    /// Distinct nuclides referenced by the entries.
    fn nucs(&self) -> Vec<u32> {
        self.inner.nucs().iter().map(|n| n.nucid()).collect()
    }
}

/// Parse an MCNP xsdir file.
#[pyfunction]
fn read_xsdir(path: &str) -> PyResult<PyXsdir> {
    nucleide_mcnp_io::xsdir::Xsdir::from_file(path)
        .map(|inner| PyXsdir { inner })
        .map_err(io_err)
}

/// One fmesh4 tally from a meshtal file.
#[pyclass(name = "MeshTally")]
struct PyMeshTally {
    inner: nucleide_mcnp_io::meshtal::MeshTallyData,
}

#[pymethods]
impl PyMeshTally {
    #[getter]
    fn tally_number(&self) -> u32 {
        self.inner.tally_number
    }
    /// 'n', 'p', ...
    #[getter]
    fn particle(&self) -> char {
        self.inner.particle.letter()
    }
    #[getter]
    fn dose_response(&self) -> bool {
        self.inner.dose_response
    }
    #[getter]
    fn x_bounds(&self) -> Vec<f64> {
        self.inner.x_bounds.clone()
    }
    #[getter]
    fn y_bounds(&self) -> Vec<f64> {
        self.inner.y_bounds.clone()
    }
    #[getter]
    fn z_bounds(&self) -> Vec<f64> {
        self.inner.z_bounds.clone()
    }
    #[getter]
    fn e_bounds(&self) -> Vec<f64> {
        self.inner.e_bounds.clone()
    }
    /// [nx, ny, nz] cell counts.
    fn dims(&self) -> [usize; 3] {
        self.inner.dims()
    }
    fn num_ves(&self) -> usize {
        self.inner.num_ves()
    }
    fn num_e_groups(&self) -> usize {
        self.inner.num_e_groups()
    }
    /// All-group results for cell (i,j,k): [result_per_group, error_per_group].
    fn cell(&self, i: usize, j: usize, k: usize) -> (Vec<f64>, Vec<f64>) {
        let (r, e) = self.inner.cell(i, j, k);
        (r.to_vec(), e.to_vec())
    }
    /// Energy-integrated totals for cell (i,j,k).
    fn cell_total(&self, i: usize, j: usize, k: usize) -> (f64, f64) {
        self.inner.cell_total(i, j, k)
    }
    /// Full results array `[ve][group]`.
    #[getter]
    fn result(&self) -> Vec<Vec<f64>> {
        self.inner.result.clone()
    }
    /// Full relative-error array `[ve][group]`.
    #[getter]
    fn rel_error(&self) -> Vec<Vec<f64>> {
        self.inner.rel_error.clone()
    }
    /// Per-cell energy-integrated totals.
    #[getter]
    fn total_result(&self) -> Vec<f64> {
        self.inner.total_result.clone()
    }
    /// Per-cell energy-integrated total relative errors.
    #[getter]
    fn total_rel_error(&self) -> Vec<f64> {
        self.inner.total_rel_error.clone()
    }
    /// Full results + relative errors as nested lists (plain copy).
    ///
    /// See `result_array` for the zero-copy NumPy bridge over the same data;
    /// use this when NumPy is unavailable.
    fn to_list(&self) -> (Vec<Vec<f64>>, Vec<Vec<f64>>) {
        (self.inner.result.clone(), self.inner.rel_error.clone())
    }
    /// Per-cell energy-integrated totals + errors as flat lists (plain copy).
    fn totals_list(&self) -> (Vec<f64>, Vec<f64>) {
        (
            self.inner.total_result.clone(),
            self.inner.total_rel_error.clone(),
        )
    }
    /// Full results + relative errors as 2-D float64 NumPy arrays.
    ///
    /// Shape is `(ve, group)` with `ve = (i * ny + j) * nz + k` (x slowest,
    /// z fastest, matching `cell(i, j, k)` and MCNP write order), C-order
    /// (row-major) float64. Each array is owned, writable, and decoupled
    /// from the tally: resizing fails (NumPy base semantics) and later
    /// tally mutation is not reflected. Requires NumPy installed at runtime
    /// (rust-numpy resolves the C-API at import; the wheel itself stays
    /// dependency-free).
    #[allow(clippy::type_complexity)]
    fn result_array<'py>(
        &self,
        py: Python<'py>,
    ) -> PyResult<(Bound<'py, PyArray2<f64>>, Bound<'py, PyArray2<f64>>)> {
        let n_ve = self.inner.num_ves();
        let n_g = self.inner.num_e_groups();
        let flatten = |rows: &[Vec<f64>], name: &str| -> PyResult<Vec<f64>> {
            if rows.len() != n_ve {
                return Err(PyValueError::new_err(format!(
                    "tally {name}: expected {n_ve} rows, found {}",
                    rows.len()
                )));
            }
            let mut flat = Vec::with_capacity(n_ve * n_g);
            for (ve, row) in rows.iter().enumerate() {
                if row.len() != n_g {
                    return Err(PyValueError::new_err(format!(
                        "tally {name}: row {ve} has {} groups, expected {n_g}",
                        row.len()
                    )));
                }
                flat.extend_from_slice(row);
            }
            Ok(flat)
        };
        let flat_r = flatten(&self.inner.result, "result")?;
        let flat_e = flatten(&self.inner.rel_error, "rel_error")?;
        let arr_r = m_err(
            flat_r
                .into_pyarray(py)
                .reshape((n_ve, n_g))
                .map_err(|e| e.to_string()),
        )?;
        let arr_e = m_err(
            flat_e
                .into_pyarray(py)
                .reshape((n_ve, n_g))
                .map_err(|e| e.to_string()),
        )?;
        Ok((arr_r, arr_e))
    }
    /// Per-cell energy-integrated totals + errors as 1-D float64 NumPy arrays.
    ///
    /// Shape is `(num_ves,)` in the same `ve = (i * ny + j) * nz + k` order
    /// as `result_array`. Each array is owned, writable, and decoupled from
    /// the tally. Requires NumPy installed at runtime.
    #[allow(clippy::type_complexity)]
    fn totals_array<'py>(
        &self,
        py: Python<'py>,
    ) -> PyResult<(Bound<'py, PyArray1<f64>>, Bound<'py, PyArray1<f64>>)> {
        Ok((
            self.inner.total_result.clone().into_pyarray(py),
            self.inner.total_rel_error.clone().into_pyarray(py),
        ))
    }
}

/// Parsed meshtal file.
#[pyclass(name = "Meshtal")]
struct PyMeshtal {
    inner: nucleide_mcnp_io::meshtal::Meshtal,
}

#[pymethods]
impl PyMeshtal {
    #[getter]
    fn version(&self) -> &str {
        &self.inner.version
    }
    #[getter]
    fn ld(&self) -> &str {
        &self.inner.ld
    }
    #[getter]
    fn title(&self) -> &str {
        &self.inner.title
    }
    #[getter]
    fn histories(&self) -> u64 {
        self.inner.histories
    }
    /// Tallies keyed by fmesh4 number.
    #[getter]
    fn tallies(&self) -> BTreeMap<u32, PyMeshTally> {
        self.inner
            .tallies
            .iter()
            .map(|(k, v)| (*k, PyMeshTally { inner: v.clone() }))
            .collect()
    }
}

/// Parse an MCNP meshtal file.
#[pyfunction]
fn read_meshtal(path: &str) -> PyResult<PyMeshtal> {
    m_err(nucleide_mcnp_io::meshtal::Meshtal::from_file(path).map(|inner| PyMeshtal { inner }))
}

/// Parsed WWINP weight-window file.
#[pyclass(name = "Wwinp")]
struct PyWwinp {
    inner: nucleide_mcnp_io::wwinp::Wwinp,
}

#[pymethods]
impl PyWwinp {
    #[getter]
    fn ni(&self) -> u32 {
        self.inner.ni
    }
    #[getter]
    fn nr(&self) -> u32 {
        self.inner.nr
    }
    #[getter]
    fn ne(&self) -> Vec<u32> {
        self.inner.ne.clone()
    }
    #[getter]
    fn nf(&self) -> [u32; 3] {
        self.inner.nf
    }
    #[getter]
    fn origin(&self) -> [f64; 3] {
        self.inner.origin
    }
    #[getter]
    fn nc(&self) -> [u32; 3] {
        self.inner.nc
    }
    /// Coarse boundaries per dimension.
    #[getter]
    fn cm(&self) -> Vec<Vec<f64>> {
        self.inner.cm.clone()
    }
    /// Expanded spatial bounds per dimension.
    #[getter]
    fn bounds(&self) -> Vec<Vec<f64>> {
        self.inner.bounds.clone()
    }
    /// Energy upper bounds per particle present.
    #[getter]
    fn e(&self) -> Vec<Vec<f64>> {
        self.inner.e.clone()
    }
    /// Lower bounds for one group: ww_row(particle, group) -> list[nve].
    fn ww_row(&self, particle: usize, group: usize) -> Vec<f64> {
        self.inner.ww[particle][group].clone()
    }
    /// Lower-bound vector for one volume element across groups.
    fn ww_column(&self, particle: usize, ve: usize) -> Vec<f64> {
        self.inner.ww_column(particle, ve)
    }
    /// Lower bounds for one group as a 1-D float64 NumPy array.
    ///
    /// Shape is `(nft,)` with `nft = nf[0] * nf[1] * nf[2]` in file order
    /// (z slowest → x fastest), C-order float64. The array is owned,
    /// writable, and decoupled from the file data. Requires NumPy installed
    /// at runtime. Raises `ValueError` on out-of-range particle/group.
    /// See `ww_row` for the plain-copy list over the same data; use that
    /// when NumPy is unavailable.
    fn ww_row_array<'py>(
        &self,
        py: Python<'py>,
        particle: usize,
        group: usize,
    ) -> PyResult<Bound<'py, PyArray1<f64>>> {
        let row = self
            .inner
            .ww
            .get(particle)
            .and_then(|groups| groups.get(group))
            .ok_or_else(|| {
                PyValueError::new_err(format!(
                    "ww_row_array: particle {particle} group {group} out of range"
                ))
            })?;
        Ok(row.clone().into_pyarray(py))
    }
    /// Lower-bound vector for one volume element as a 1-D float64 NumPy array.
    ///
    /// Shape is `(n_groups,)` for the selected particle (one entry per
    /// energy group at volume element `ve`). Owned, writable, decoupled;
    /// requires NumPy at runtime. Raises `ValueError` on out-of-range
    /// particle/ve. See `ww_column` for the plain-copy list.
    fn ww_column_array<'py>(
        &self,
        py: Python<'py>,
        particle: usize,
        ve: usize,
    ) -> PyResult<Bound<'py, PyArray1<f64>>> {
        let groups = self.inner.ww.get(particle).ok_or_else(|| {
            PyValueError::new_err(format!("ww_column_array: particle {particle} out of range"))
        })?;
        if groups.is_empty() {
            return Err(PyValueError::new_err(format!(
                "ww_column_array: particle {particle} has no groups"
            )));
        }
        let nft = groups[0].len();
        if ve >= nft {
            return Err(PyValueError::new_err(format!(
                "ww_column_array: ve {ve} out of range for {nft} volume elements"
            )));
        }
        for (g, row) in groups.iter().enumerate() {
            if row.len() != nft {
                return Err(PyValueError::new_err(format!(
                    "ww particle {particle}: group {g} has {} values, expected {nft}",
                    row.len()
                )));
            }
        }
        let col: Vec<f64> = groups.iter().map(|row| row[ve]).collect();
        Ok(col.into_pyarray(py))
    }
    /// All lower bounds for one particle as a 2-D float64 NumPy array.
    ///
    /// Shape is `(n_groups, nft)` with `nft = nf[0] * nf[1] * nf[2]`; row `g`
    /// is the `ww_row(particle, g)` vector in file order (z slowest → x
    /// fastest), C-order (row-major) float64. The array is owned, writable,
    /// and decoupled from the file data. Requires NumPy installed at
    /// runtime. Raises `ValueError` on out-of-range particle or on ragged
    /// group rows (the parser guarantees rectangular data; this is
    /// defensive). Particles have independent group counts, so each
    /// particle gets its own array rather than one ragged 3-D stack.
    fn ww_particle_array<'py>(
        &self,
        py: Python<'py>,
        particle: usize,
    ) -> PyResult<Bound<'py, PyArray2<f64>>> {
        let groups = self.inner.ww.get(particle).ok_or_else(|| {
            PyValueError::new_err(format!(
                "ww_particle_array: particle {particle} out of range"
            ))
        })?;
        if groups.is_empty() {
            return Err(PyValueError::new_err(format!(
                "ww_particle_array: particle {particle} has no groups"
            )));
        }
        let nft = groups[0].len();
        let mut flat = Vec::with_capacity(groups.len() * nft);
        for (g, row) in groups.iter().enumerate() {
            if row.len() != nft {
                return Err(PyValueError::new_err(format!(
                    "ww particle {particle}: group {g} has {} values, expected {nft}",
                    row.len()
                )));
            }
            flat.extend_from_slice(row);
        }
        let n_g = groups.len();
        m_err(
            flat.into_pyarray(py)
                .reshape((n_g, nft))
                .map_err(|e| e.to_string()),
        )
    }
}

/// Parse an MCNP WWINP weight-window file.
#[pyfunction]
fn read_wwinp(path: &str) -> PyResult<PyWwinp> {
    m_err(nucleide_mcnp_io::wwinp::Wwinp::from_file(path).map(|inner| PyWwinp { inner }))
}

/// Parsed MCTAL kcode data.
/// One MCTAL bin card as a plain dict (`count`, `values`, plus the
/// verbatim `variant`/`flag` spellings, each `None` when absent).
fn mctal_card_dict<'py>(
    py: Python<'py>,
    card: &nucleide_mcnp_io::mctal::BinCard,
) -> PyResult<pyo3::Bound<'py, pyo3::types::PyDict>> {
    let c = pyo3::types::PyDict::new(py);
    c.set_item("count", card.count)?;
    c.set_item("values", card.values.clone())?;
    c.set_item("variant", card.variant.map(|v| v.to_string()))?;
    c.set_item("flag", card.flag)?;
    Ok(c)
}

#[pyclass(name = "Mctal")]
struct PyMctal {
    inner: nucleide_mcnp_io::mctal::Mctal,
}

#[pymethods]
impl PyMctal {
    #[getter]
    fn code_name(&self) -> &str {
        &self.inner.code_name
    }
    #[getter]
    fn comment(&self) -> &str {
        &self.inner.comment
    }
    #[getter]
    fn n_histories(&self) -> u64 {
        self.inner.n_histories
    }
    #[getter]
    fn n_cycles(&self) -> usize {
        self.inner.n_cycles
    }
    #[getter]
    fn n_inactive(&self) -> usize {
        self.inner.n_inactive
    }
    #[getter]
    fn vars_per_cycle(&self) -> usize {
        self.inner.vars_per_cycle
    }
    #[getter]
    fn k_col(&self) -> Vec<f64> {
        self.inner.k_col.clone()
    }
    #[getter]
    fn k_abs(&self) -> Vec<f64> {
        self.inner.k_abs.clone()
    }
    #[getter]
    fn k_path(&self) -> Vec<f64> {
        self.inner.k_path.clone()
    }
    #[getter]
    fn prompt_life_col(&self) -> Vec<f64> {
        self.inner.prompt_life_col.clone()
    }
    #[getter]
    fn prompt_life_path(&self) -> Vec<f64> {
        self.inner.prompt_life_path.clone()
    }
    /// Running averages (empty unless vars_per_cycle == 19); each entry is a
    /// dict of the averaged pairs plus cycle_histories/fom.
    #[getter]
    fn averages(&self) -> Vec<BTreeMap<String, f64>> {
        self.inner
            .averages
            .iter()
            .map(|a| {
                let mut m = BTreeMap::new();
                m.insert("avg_k_col".into(), a.avg_k_col.0);
                m.insert("avg_k_col_stdev".into(), a.avg_k_col.1);
                m.insert("avg_k_abs".into(), a.avg_k_abs.0);
                m.insert("avg_k_abs_stdev".into(), a.avg_k_abs.1);
                m.insert("avg_k_path".into(), a.avg_k_path.0);
                m.insert("avg_k_path_stdev".into(), a.avg_k_path.1);
                m.insert("avg_k_combined".into(), a.avg_k_combined.0);
                m.insert("avg_k_combined_stdev".into(), a.avg_k_combined.1);
                m.insert("avg_k_combined_active".into(), a.avg_k_combined_active.0);
                m.insert(
                    "avg_k_combined_active_stdev".into(),
                    a.avg_k_combined_active.1,
                );
                m.insert("prompt_life_combined".into(), a.prompt_life_combined.0);
                m.insert(
                    "prompt_life_combined_stdev".into(),
                    a.prompt_life_combined.1,
                );
                m.insert("cycle_histories".into(), a.cycle_histories);
                m.insert("fom".into(), a.fom);
                m
            })
            .collect()
    }
    /// Per-cycle kcode series as 1-D float64 NumPy arrays.
    ///
    /// Returns `(k_col, k_abs, k_path, prompt_life_col, prompt_life_path)`,
    /// each of shape `(n_cycles,)` in cycle order, C-order float64. Each
    /// array is owned, writable, and decoupled from the file data (the
    /// `Vec` is cloned then moved into the array; later mutation is not
    /// reflected). Requires NumPy installed at runtime. See the `k_col`,
    /// `k_abs`, `k_path`, `prompt_life_col`, `prompt_life_path` getters for
    /// the plain-copy lists over the same data; use those when NumPy is
    /// unavailable.
    #[allow(clippy::type_complexity)]
    fn k_arrays<'py>(
        &self,
        py: Python<'py>,
    ) -> PyResult<(
        Bound<'py, PyArray1<f64>>,
        Bound<'py, PyArray1<f64>>,
        Bound<'py, PyArray1<f64>>,
        Bound<'py, PyArray1<f64>>,
        Bound<'py, PyArray1<f64>>,
    )> {
        Ok((
            self.inner.k_col.clone().into_pyarray(py),
            self.inner.k_abs.clone().into_pyarray(py),
            self.inner.k_path.clone().into_pyarray(py),
            self.inner.prompt_life_col.clone().into_pyarray(py),
            self.inner.prompt_life_path.clone().into_pyarray(py),
        ))
    }
    /// Running averages as a 2-D float64 NumPy array.
    ///
    /// Shape is `(n_cycles, 14)` (empty `averages` yields `(0, 14)`) with
    /// one row per cycle in cycle order, C-order float64. Columns are
    /// `avg_k_col`, `avg_k_col_stdev`, `avg_k_abs`, `avg_k_abs_stdev`,
    /// `avg_k_path`, `avg_k_path_stdev`, `avg_k_combined`,
    /// `avg_k_combined_stdev`, `avg_k_combined_active`,
    /// `avg_k_combined_active_stdev`, `prompt_life_combined`,
    /// `prompt_life_combined_stdev`, `cycle_histories`, `fom` — the same
    /// values as the `averages` dicts, in a fixed column order. The array
    /// is owned, writable, and decoupled. Requires NumPy at runtime.
    fn averages_array<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyArray2<f64>>> {
        let n = self.inner.averages.len();
        let mut flat = Vec::with_capacity(n * 14);
        for a in &self.inner.averages {
            flat.extend_from_slice(&[
                a.avg_k_col.0,
                a.avg_k_col.1,
                a.avg_k_abs.0,
                a.avg_k_abs.1,
                a.avg_k_path.0,
                a.avg_k_path.1,
                a.avg_k_combined.0,
                a.avg_k_combined.1,
                a.avg_k_combined_active.0,
                a.avg_k_combined_active.1,
                a.prompt_life_combined.0,
                a.prompt_life_combined.1,
                a.cycle_histories,
                a.fom,
            ]);
        }
        m_err(
            flat.into_pyarray(py)
                .reshape((n, 14))
                .map_err(|e| e.to_string()),
        )
    }
    /// Optional third token of the `tally` line (perturbation count when
    /// present; stored verbatim — perturbation bodies are named-open).
    #[getter]
    fn npert(&self) -> Option<String> {
        self.inner.npert.clone()
    }
    /// Declared tally numbers from the header.
    #[getter]
    fn tally_nums(&self) -> Vec<u32> {
        self.inner.tally_nums.clone()
    }
    /// Parsed standard-tally bodies in file order (empty for legacy
    /// kcode-only files). Each entry is a dict with `number`,
    /// `particle_type`, `detector_type` (or None), `particle_list`,
    /// `comment` (FC lines), one `{count, values, variant, flag}` dict per
    /// bin card (`f`, `d`, `u`, `s`, `m`, `c`, `e`, `t`; `variant`/`flag`
    /// are the stored-verbatim total/cumulative spelling and third-token
    /// flag, each `None` when absent), `vals` (list of `(value, rel_error)`
    /// pairs in file order), `tfc` (the tally-fluctuation-chart
    /// `{jtf, rows}` dict, or `None`), and `total` (sum of values).
    #[getter]
    fn tallies(&self, py: Python<'_>) -> PyResult<Vec<Py<PyAny>>> {
        use pyo3::types::PyDict;
        let mut out = Vec::with_capacity(self.inner.tallies.len());
        for t in &self.inner.tallies {
            let d = PyDict::new(py);
            d.set_item("number", t.number)?;
            d.set_item("particle_type", t.particle_type)?;
            d.set_item("detector_type", t.detector_type)?;
            d.set_item("particle_list", t.particle_list.clone())?;
            d.set_item("comment", t.comment.clone())?;
            for (key, card) in [
                ("f", &t.f),
                ("d", &t.d),
                ("u", &t.u),
                ("s", &t.s),
                ("m", &t.m),
                ("c", &t.c),
                ("e", &t.e),
                ("t", &t.t),
            ] {
                d.set_item(key, mctal_card_dict(py, card)?)?;
            }
            let vals: Vec<(f64, f64)> = t.vals.clone();
            d.set_item("vals", vals)?;
            let tfc_obj = if let Some(tfc) = &t.tfc {
                let td = PyDict::new(py);
                td.set_item("jtf", tfc.jtf.clone())?;
                let mut rows = Vec::with_capacity(tfc.rows.len());
                for r in &tfc.rows {
                    let rd = PyDict::new(py);
                    rd.set_item("nps", r.nps)?;
                    rd.set_item("value", r.value)?;
                    rd.set_item("rel_err", r.rel_err)?;
                    rd.set_item("fom", r.fom)?;
                    rows.push(rd.into_any().unbind());
                }
                td.set_item("rows", rows)?;
                td.into_any().unbind()
            } else {
                py.None()
            };
            d.set_item("tfc", tfc_obj)?;
            d.set_item("total", t.total_val())?;
            out.push(d.into_any().unbind());
        }
        Ok(out)
    }
    /// Parsed mesh-tally bodies (`detector_type <= -1`) in file order.
    /// Each entry mirrors a `tallies` dict plus `mesh_unknown`, the
    /// `ni`/`nj`/`nk` mesh counts, `dims`, `num_cells`, and the
    /// `cora`/`corb`/`corc` bound vectors (`ni+1`/`nj+1`/`nk+1` values).
    /// Mesh tallies carry no `tfc` block.
    #[getter]
    fn mesh_tallies(&self, py: Python<'_>) -> PyResult<Vec<Py<PyAny>>> {
        use pyo3::types::PyDict;
        let mut out = Vec::with_capacity(self.inner.mesh_tallies.len());
        for t in &self.inner.mesh_tallies {
            let d = PyDict::new(py);
            d.set_item("number", t.number)?;
            d.set_item("particle_type", t.particle_type)?;
            d.set_item("detector_type", t.detector_type)?;
            d.set_item("particle_list", t.particle_list.clone())?;
            d.set_item("comment", t.comment.clone())?;
            d.set_item("mesh_unknown", t.mesh_unknown)?;
            d.set_item("ni", t.ni)?;
            d.set_item("nj", t.nj)?;
            d.set_item("nk", t.nk)?;
            d.set_item("dims", t.dims().to_vec())?;
            d.set_item("num_cells", t.num_cells())?;
            d.set_item("cora", t.cora.clone())?;
            d.set_item("corb", t.corb.clone())?;
            d.set_item("corc", t.corc.clone())?;
            for (key, card) in [
                ("d", &t.d),
                ("u", &t.u),
                ("s", &t.s),
                ("m", &t.m),
                ("c", &t.c),
                ("e", &t.e),
                ("t", &t.t),
            ] {
                d.set_item(key, mctal_card_dict(py, card)?)?;
            }
            let vals: Vec<(f64, f64)> = t.vals.clone();
            d.set_item("vals", vals)?;
            d.set_item("total", t.total_val())?;
            out.push(d.into_any().unbind());
        }
        Ok(out)
    }
    /// Tally `vals` as a 2-D float64 NumPy array.
    ///
    /// Shape is `(n_pairs, 2)` with one `(value, rel_error)` row per pair
    /// in file order, C-order float64. Tallies without bodies yield
    /// `(0, 2)`. The array is owned, writable, and decoupled. Requires
    /// NumPy at runtime. See the `tallies` dicts for the plain-copy lists
    /// over the same data; use those when NumPy is unavailable.
    fn tally_vals_array<'py>(
        &self,
        py: Python<'py>,
        number: u32,
    ) -> PyResult<Bound<'py, PyArray2<f64>>> {
        let tally = self
            .inner
            .tallies
            .iter()
            .find(|t| t.number == number)
            .ok_or_else(|| {
                PyValueError::new_err(format!("mctal has no parsed body for tally {number}"))
            })?;
        let mut flat = Vec::with_capacity(tally.vals.len() * 2);
        for (v, e) in &tally.vals {
            flat.push(*v);
            flat.push(*e);
        }
        let n = tally.vals.len();
        m_err(
            flat.into_pyarray(py)
                .reshape((n, 2))
                .map_err(|e| e.to_string()),
        )
    }
    /// Mesh tally `vals` as a 2-D float64 NumPy array.
    ///
    /// Same `(n_pairs, 2)` `(value, rel_error)` layout as
    /// `tally_vals_array`, over the `mesh_tallies` bodies in mesh-cell
    /// order (`i` fastest). Unknown tally numbers raise `ValueError`.
    fn mesh_tally_vals_array<'py>(
        &self,
        py: Python<'py>,
        number: u32,
    ) -> PyResult<Bound<'py, PyArray2<f64>>> {
        let tally = self
            .inner
            .mesh_tallies
            .iter()
            .find(|t| t.number == number)
            .ok_or_else(|| {
                PyValueError::new_err(format!("mctal has no parsed mesh body for tally {number}"))
            })?;
        let mut flat = Vec::with_capacity(tally.vals.len() * 2);
        for (v, e) in &tally.vals {
            flat.push(*v);
            flat.push(*e);
        }
        let n = tally.vals.len();
        m_err(
            flat.into_pyarray(py)
                .reshape((n, 2))
                .map_err(|e| e.to_string()),
        )
    }
}

/// Parse an MCNP MCTAL file (headers, standard + mesh tally bodies with
/// optional `tfc` blocks, and kcode).
#[pyfunction]
fn read_mctal(path: &str) -> PyResult<PyMctal> {
    m_err(nucleide_mcnp_io::mctal::Mctal::from_file(path).map(|inner| PyMctal { inner }))
}

/// Parsed SSW surface-source file.
#[pyclass(name = "SurfSrc")]
struct PySurfSrc {
    inner: nucleide_mcnp_io::surfsrc::SurfSrc,
}

#[pymethods]
impl PySurfSrc {
    #[getter]
    fn kod(&self) -> String {
        self.inner.header.kod.trim_end().to_string()
    }
    #[getter]
    fn ver(&self) -> String {
        self.inner.header.ver.trim_end().to_string()
    }
    #[getter]
    fn np1(&self) -> i64 {
        self.inner.header.np1
    }
    /// Signed stored `np1` (negative ⇒ the file carries table 2).
    #[getter]
    fn orignp1(&self) -> i64 {
        self.inner.header.orignp1
    }
    #[getter]
    fn nrss(&self) -> i64 {
        self.inner.header.nrss
    }
    #[getter]
    fn ncrd(&self) -> i32 {
        self.inner.header.ncrd
    }
    #[getter]
    fn njsw(&self) -> i32 {
        self.inner.header.njsw
    }
    #[getter]
    fn niss(&self) -> i64 {
        self.inner.header.niss
    }
    /// Formatted header block.
    fn print_header(&self) -> String {
        self.inner.header.print_header()
    }
    /// Track records as dicts of named fields.
    fn tracks(&self) -> PyResult<Vec<BTreeMap<String, f64>>> {
        let tracks = self
            .inner
            .read_tracklist()
            .map_err(|e| PyValueError::new_err(e.to_string()))?;
        Ok(tracks
            .iter()
            .map(|t| {
                let mut d = BTreeMap::new();
                d.insert("nps".into(), t.nps);
                d.insert("bitarray".into(), t.bitarray);
                d.insert("wgt".into(), t.wgt);
                d.insert("erg".into(), t.erg);
                d.insert("tme".into(), t.tme);
                d.insert("x".into(), t.x);
                d.insert("y".into(), t.y);
                d.insert("z".into(), t.z);
                d.insert("u".into(), t.u);
                d.insert("v".into(), t.v);
                d.insert("cs".into(), t.cs);
                d.insert("w".into(), t.w);
                d
            })
            .collect())
    }
}

/// Read an MCNP SSW surface-source file (header eagerly; tracks on demand).
#[pyfunction]
fn read_ssw(path: &str) -> PyResult<PySurfSrc> {
    nucleide_mcnp_io::surfsrc::SurfSrc::open(path)
        .map(|inner| PySurfSrc { inner })
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Detected PTRAC layout: 0 = i4 little-endian, 1 = i8 little-endian.
#[pyclass(name = "PtracFile")]
struct PyPtracFile {
    inner: nucleide_mcnp_io::ptrac::PtracFile,
}

#[pymethods]
impl PyPtracFile {
    #[getter]
    fn problem_title(&self) -> &str {
        &self.inner.problem_title
    }
    /// 0 for i4, 1 for i8.
    #[getter]
    fn width_code(&self) -> u8 {
        match self.inner.format {
            nucleide_mcnp_io::ptrac::Format::I4LittleEndian => 0,
            nucleide_mcnp_io::ptrac::Format::I8LittleEndian => 1,
        }
    }
    /// Variable counts per event type as {nps,src,bnk,sur,col,ter}.
    #[getter]
    fn variable_nums(&self) -> BTreeMap<String, usize> {
        let v = &self.inner.variable_nums;
        let mut m = BTreeMap::new();
        m.insert("nps".into(), v.nps);
        m.insert("src".into(), v.src);
        m.insert("bnk".into(), v.bnk);
        m.insert("sur".into(), v.sur);
        m.insert("col".into(), v.col);
        m.insert("ter".into(), v.ter);
        m
    }
    /// All events as dicts: {'event_type': int, '<var>': float, ...}.
    fn events(&self) -> PyResult<Vec<BTreeMap<String, f64>>> {
        let events = self
            .inner
            .events()
            .map_err(|e| PyValueError::new_err(e.to_string()))?;
        Ok(events
            .iter()
            .map(|ev| {
                let mut d = BTreeMap::new();
                d.insert("event_type".to_string(), ev.event_type as f64);
                for (n, v) in ev.iter() {
                    d.insert(n.to_string(), v);
                }
                d
            })
            .collect())
    }
    /// All events as a 2-D float64 NumPy array.
    ///
    /// Shape is `(n_events, 19)` in file order, C-order float64. Columns
    /// follow `nucleide.mcnp.ptrac_event_columns()` (`event_type` plus the
    /// 18 `PtracEvent`-order data columns `node` … `tme`); variables absent
    /// from the file's variable list read as 0.0, matching
    /// `ptrac_event_rows`. The array is owned, writable, and decoupled from
    /// the file data. Requires NumPy installed at runtime. See `events`
    /// for the plain-copy dicts over the same data; use those when NumPy
    /// is unavailable.
    fn events_array<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyArray2<f64>>> {
        let events = self
            .inner
            .events()
            .map_err(|e| PyValueError::new_err(e.to_string()))?;
        let n = events.len();
        let mut flat = Vec::with_capacity(n * PTRAC_EVENT_COLUMNS.len());
        for ev in &events {
            flat.push(ev.event_type as f64);
            for col in &PTRAC_EVENT_COLUMNS[1..] {
                flat.push(ev.get(col).unwrap_or(0.0));
            }
        }
        m_err(
            flat.into_pyarray(py)
                .reshape((n, PTRAC_EVENT_COLUMNS.len()))
                .map_err(|e| e.to_string()),
        )
    }
    /// One event-table column as a 1-D float64 NumPy array.
    ///
    /// `field` is one of `ptrac_event_columns()` (`event_type` or any of
    /// the 18 data columns). Shape is `(n_events,)` in file order; absent
    /// variables read as 0.0, matching `ptrac_event_rows`. Owned, writable,
    /// decoupled; requires NumPy at runtime. Raises `ValueError` for an
    /// unknown field name.
    fn event_field_array<'py>(
        &self,
        py: Python<'py>,
        field: &str,
    ) -> PyResult<Bound<'py, PyArray1<f64>>> {
        if !PTRAC_EVENT_COLUMNS.contains(&field) {
            return Err(PyValueError::new_err(format!(
                "unknown PTRAC field `{field}` (expected one of {})",
                PTRAC_EVENT_COLUMNS.join(", ")
            )));
        }
        let events = self
            .inner
            .events()
            .map_err(|e| PyValueError::new_err(e.to_string()))?;
        let col: Vec<f64> = events
            .iter()
            .map(|ev| {
                if field == "event_type" {
                    ev.event_type as f64
                } else {
                    ev.get(field).unwrap_or(0.0)
                }
            })
            .collect();
        Ok(col.into_pyarray(py))
    }
}

/// PTRAC event-table columns in `pyne.mcnp.PtracEvent` order: `event_type`
/// plus the 18 mapped data columns (`node` … `tme`).
///
/// Mirrors `nucleide.mcnp.ptrac_event_columns()`; `events_array` columns
/// follow this order.
const PTRAC_EVENT_COLUMNS: [&str; 19] = [
    "event_type",
    "node",
    "nsr",
    "nsf",
    "nxs",
    "ntyn",
    "ipt",
    "ncl",
    "mat",
    "ncp",
    "xxx",
    "yyy",
    "zzz",
    "uuu",
    "vvv",
    "www",
    "erg",
    "wgt",
    "tme",
];

/// Read an MCNP PTRAC event file.
#[pyfunction]
fn read_ptrac(path: &str) -> PyResult<PyPtracFile> {
    nucleide_mcnp_io::ptrac::PtracFile::open(path)
        .map(|inner| PyPtracFile { inner })
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// One MCPL particle record (kinetic energy in MeV, position in cm, time
/// in ms; see `nucleide-mcpl-io`).
fn mcpl_particle_to_dict(py: Python<'_>, p: &nucleide_mcpl_io::Particle) -> PyResult<Py<PyAny>> {
    use pyo3::types::PyDict;
    let d = PyDict::new(py);
    d.set_item("ekin", p.ekin)?;
    d.set_item("polarisation", p.polarisation.to_vec())?;
    d.set_item("position", p.position.to_vec())?;
    d.set_item("direction", p.direction.to_vec())?;
    d.set_item("time", p.time)?;
    d.set_item("weight", p.weight)?;
    d.set_item("pdgcode", p.pdgcode)?;
    d.set_item("userflags", p.userflags)?;
    Ok(d.into_any().unbind())
}

fn mcpl_particle_from_dict(d: &Bound<'_, PyAny>) -> PyResult<nucleide_mcpl_io::Particle> {
    let get_f64 = |key: &str| -> PyResult<f64> {
        d.get_item(key)
            .map_err(|e| PyValueError::new_err(format!("particle missing `{key}`: {e}")))?
            .extract()
            .map_err(|_| PyValueError::new_err(format!("particle `{key}` must be a float")))
    };
    let get_vec3 = |key: &str| -> PyResult<[f64; 3]> {
        let v: Vec<f64> = d
            .get_item(key)
            .map_err(|e| PyValueError::new_err(format!("particle missing `{key}`: {e}")))?
            .extract()
            .map_err(|_| PyValueError::new_err(format!("particle `{key}` must be a 3-list")))?;
        if v.len() != 3 {
            return Err(PyValueError::new_err(format!(
                "particle `{key}` must have exactly 3 entries"
            )));
        }
        Ok([v[0], v[1], v[2]])
    };
    let pdgcode: i32 = d
        .get_item("pdgcode")
        .map_err(|e| PyValueError::new_err(format!("particle missing `pdgcode`: {e}")))?
        .extract()
        .map_err(|_| PyValueError::new_err("particle `pdgcode` must be an int"))?;
    let userflags: u32 = d
        .get_item("userflags")
        .map_err(|e| PyValueError::new_err(format!("particle missing `userflags`: {e}")))?
        .extract()
        .map_err(|_| PyValueError::new_err("particle `userflags` must be an int"))?;
    Ok(nucleide_mcpl_io::Particle {
        ekin: get_f64("ekin")?,
        polarisation: get_vec3("polarisation")?,
        position: get_vec3("position")?,
        direction: get_vec3("direction")?,
        time: get_f64("time")?,
        weight: get_f64("weight")?,
        pdgcode,
        userflags,
    })
}

/// Parsed MCPL particle-list file (header eagerly; particles on demand).
#[pyclass(name = "McplFile")]
struct PyMcplFile {
    inner: nucleide_mcpl_io::McplFile,
}

#[pymethods]
impl PyMcplFile {
    /// Format version (2 or 3 on read; writers always emit 3).
    #[getter]
    fn version(&self) -> u16 {
        self.inner.header.version
    }
    /// Stored particle count.
    #[getter]
    fn nparticles(&self) -> u64 {
        self.inner.header.nparticles
    }
    /// Source name from the header.
    #[getter]
    fn srcname(&self) -> &str {
        &self.inner.header.srcname
    }
    /// Header comment strings (round-tripped verbatim, never interpreted).
    #[getter]
    fn comments(&self) -> Vec<String> {
        self.inner.header.comments.clone()
    }
    /// Whether per-particle user flags are stored.
    #[getter]
    fn has_userflags(&self) -> bool {
        self.inner.header.has_userflags
    }
    /// Whether per-particle polarisation vectors are stored.
    #[getter]
    fn has_polarisation(&self) -> bool {
        self.inner.header.has_polarisation
    }
    /// `true` = double precision, `false` = single precision.
    #[getter]
    fn double_prec(&self) -> bool {
        self.inner.header.double_prec
    }
    /// File-wide PDG code when set (`None` = per-particle codes).
    #[getter]
    fn universal_pdgcode(&self) -> Option<i32> {
        self.inner.header.universal_pdgcode
    }
    /// File-wide weight when set (`None` = per-particle weights).
    #[getter]
    fn universal_weight(&self) -> Option<f64> {
        self.inner.header.universal_weight
    }
    /// Header blobs as `(key, bytes)` pairs.
    #[getter]
    fn blobs(&self) -> Vec<(String, Vec<u8>)> {
        self.inner
            .header
            .blobs
            .iter()
            .map(|b| (b.key.clone(), b.data.clone()))
            .collect()
    }
    /// All particle records as dicts (`ekin`, `polarisation`, `position`,
    /// `direction`, `time`, `weight`, `pdgcode`, `userflags`).
    fn particles(&self, py: Python<'_>) -> PyResult<Vec<Py<PyAny>>> {
        let ps = self
            .inner
            .particles()
            .map_err(|e| PyValueError::new_err(e.to_string()))?;
        ps.iter().map(|p| mcpl_particle_to_dict(py, p)).collect()
    }
}

/// Read an MCPL particle-list file (`.gz` reads through gzip transparently).
#[pyfunction]
fn read_mcpl(path: &str) -> PyResult<PyMcplFile> {
    nucleide_mcpl_io::McplFile::open(path)
        .map(|inner| PyMcplFile { inner })
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Write an MCPL particle-list file from a header dict and particle dicts.
///
/// `header` keys: `srcname` (str), `comments` (list of str),
/// `has_userflags`/`has_polarisation`/`double_prec` (bool),
/// `universal_pdgcode` (int or None), `universal_weight` (float or None),
/// `blobs` (list of `(key, bytes)` pairs). `particles` holds one dict per
/// record with the same keys as `McplFile.particles()`. A `.gz` suffix
/// compresses through gzip transparently. Thin wrapper over
/// `nucleide-mcpl-io`.
#[pyfunction]
fn write_mcpl(
    path: &str,
    header: &Bound<'_, PyAny>,
    particles: Vec<Bound<'_, PyAny>>,
) -> PyResult<()> {
    use nucleide_mcpl_io::{Blob, Header};
    let get = |key: &str| header.get_item(key);
    let srcname: String = get("srcname")
        .map_err(|_| PyValueError::new_err("header missing `srcname`"))?
        .extract()
        .map_err(|_| PyValueError::new_err("header `srcname` must be a str"))?;
    let comments: Vec<String> = get("comments")
        .map_err(|_| PyValueError::new_err("header missing `comments`"))?
        .extract()
        .map_err(|_| PyValueError::new_err("header `comments` must be a list of str"))?;
    let flag = |key: &str| -> PyResult<bool> {
        get(key)
            .map_err(|_| PyValueError::new_err(format!("header missing `{key}`")))?
            .extract()
            .map_err(|_| PyValueError::new_err(format!("header `{key}` must be a bool")))
    };
    let universal_pdgcode: Option<i32> = get("universal_pdgcode")
        .map_err(|_| PyValueError::new_err("header missing `universal_pdgcode`"))?
        .extract()
        .map_err(|_| PyValueError::new_err("header `universal_pdgcode` must be an int or None"))?;
    let universal_weight: Option<f64> = get("universal_weight")
        .map_err(|_| PyValueError::new_err("header missing `universal_weight`"))?
        .extract()
        .map_err(|_| PyValueError::new_err("header `universal_weight` must be a float or None"))?;
    let blob_pairs: Vec<(String, Vec<u8>)> = get("blobs")
        .map_err(|_| PyValueError::new_err("header missing `blobs`"))?
        .extract()
        .map_err(|_| {
            PyValueError::new_err("header `blobs` must be a list of (key, bytes) pairs")
        })?;
    let h = Header {
        has_userflags: flag("has_userflags")?,
        has_polarisation: flag("has_polarisation")?,
        double_prec: flag("double_prec")?,
        universal_pdgcode,
        universal_weight,
        srcname,
        comments,
        blobs: blob_pairs
            .into_iter()
            .map(|(key, data)| Blob { key, data })
            .collect(),
        ..Header::default()
    };
    let ps: Vec<nucleide_mcpl_io::Particle> = particles
        .iter()
        .map(mcpl_particle_from_dict)
        .collect::<PyResult<_>>()?;
    nucleide_mcpl_io::write_to_path(path, &h, &ps).map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Convert an SSW surface-source file to an MCPL particle-list file
/// (SSW-PDG table; see `nucleide-mcpl-io` `ssw`).
///
/// The SSW format stores no per-track surface id or particle kind, so every
/// track needs an explicit caller parameter: `surfs[i]`/`kinds[i]` pair with
/// track `i` (`kinds` holds `"neutron"`/`"gamma"`/`"electron"`/`"positron"`/
/// `"proton"`). `options` (dict or None) holds
/// `double_prec`/`surf_to_userflags`/`gzip`/`universal_pdg`/
/// `universal_weight` (bool), `polarisation` (3-list or None),
/// `srcname` (str), `comments` (list of str), and `deck_blob`
/// (`(key, bytes)` pair or None); absent keys take the crate defaults.
/// Output is gzip-compressed when `options["gzip"]` is set or `mcpl_path`
/// ends in `.gz`. Returns the particle count. Thin wrapper over
/// `nucleide-mcpl-io`.
#[pyfunction]
#[pyo3(signature = (ssw_path, mcpl_path, surfs, kinds, options=None))]
fn ssw2mcpl(
    ssw_path: &str,
    mcpl_path: &str,
    surfs: Vec<u32>,
    kinds: Vec<String>,
    options: Option<Bound<'_, PyAny>>,
) -> PyResult<u64> {
    use nucleide_mcnp_io::surfsrc::SurfSrc;
    use nucleide_mcpl_io::ssw::{SswParticleKind, SswTrack};
    let ssw = SurfSrc::open(ssw_path).map_err(|e| PyValueError::new_err(e.to_string()))?;
    let raw = ssw
        .read_tracklist()
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    if raw.len() != surfs.len() || raw.len() != kinds.len() {
        return Err(PyValueError::new_err(format!(
            "ssw2mcpl: SSW holds {} tracks but got {} surfs and {} kinds \
             (one surf+kind per track required)",
            raw.len(),
            surfs.len(),
            kinds.len()
        )));
    }
    let mut tracks = Vec::with_capacity(raw.len());
    for (i, (t, surf, kind)) in raw
        .iter()
        .zip(surfs)
        .zip(kinds.iter())
        .map(|((t, s), k)| (t, s, k))
        .enumerate()
    {
        let kind = SswParticleKind::parse(kind).ok_or_else(|| {
            PyValueError::new_err(format!(
                "track {i} kind `{kind}` unknown (expected one of \
                 \"neutron\", \"gamma\", \"electron\", \"positron\", \"proton\")"
            ))
        })?;
        tracks.push(SswTrack {
            ekin: t.erg,
            time_shakes: t.tme,
            position: [t.x, t.y, t.z],
            direction: [t.u, t.v, t.cs],
            weight: t.wgt,
            surf,
            kind,
        });
    }
    let mut opts = parse_ssw2mcpl_options(options.as_ref())?;
    if mcpl_path.ends_with(".gz") {
        opts.gzip = true;
    }
    let bytes = nucleide_mcpl_io::ssw::ssw2mcpl_bytes(&tracks, &opts)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    std::fs::write(mcpl_path, bytes).map_err(|e| PyValueError::new_err(e.to_string()))?;
    Ok(tracks.len() as u64)
}

/// Parse the `ssw2mcpl` options dict (None = crate defaults).
fn parse_ssw2mcpl_options(
    options: Option<&Bound<'_, PyAny>>,
) -> PyResult<nucleide_mcpl_io::ssw::Ssw2McplOptions> {
    use nucleide_mcpl_io::ssw::{DeckBlob, Ssw2McplOptions};
    let mut opts = Ssw2McplOptions::default();
    let Some(d) = options else {
        return Ok(opts);
    };
    if !d.is_instance_of::<pyo3::types::PyDict>() {
        return Err(PyValueError::new_err("options must be a dict or None"));
    }
    let flag = |key: &str| -> PyResult<Option<bool>> {
        match d.get_item(key) {
            Ok(v) => v
                .extract()
                .map(Some)
                .map_err(|_| PyValueError::new_err(format!("options `{key}` must be a bool"))),
            Err(_) => Ok(None),
        }
    };
    if let Some(v) = flag("double_prec")? {
        opts.double_prec = v;
    }
    if let Some(v) = flag("surf_to_userflags")? {
        opts.surf_to_userflags = v;
    }
    if let Some(v) = flag("gzip")? {
        opts.gzip = v;
    }
    if let Some(v) = flag("universal_pdg")? {
        opts.universal_pdg = v;
    }
    if let Some(v) = flag("universal_weight")? {
        opts.universal_weight = v;
    }
    if let Ok(v) = d.get_item("polarisation") {
        if v.is_none() {
            opts.polarisation = None;
        } else {
            let vec: Vec<f64> = v.extract().map_err(|_| {
                PyValueError::new_err("options `polarisation` must be a 3-list or None")
            })?;
            if vec.len() != 3 {
                return Err(PyValueError::new_err(
                    "options `polarisation` must have exactly 3 entries",
                ));
            }
            opts.polarisation = Some([vec[0], vec[1], vec[2]]);
        }
    }
    if let Ok(v) = d.get_item("srcname") {
        opts.srcname = v
            .extract()
            .map_err(|_| PyValueError::new_err("options `srcname` must be a str"))?;
    }
    if let Ok(v) = d.get_item("comments") {
        opts.comments = v
            .extract()
            .map_err(|_| PyValueError::new_err("options `comments` must be a list of str"))?;
    }
    if let Ok(v) = d.get_item("deck_blob") {
        if !v.is_none() {
            let (key, data): (String, Vec<u8>) = v.extract().map_err(|_| {
                PyValueError::new_err("options `deck_blob` must be a (key, bytes) pair or None")
            })?;
            opts.deck_blob = Some(DeckBlob { key, data });
        }
    }
    Ok(opts)
}

/// Convert an MCPL particle-list file back to an SSW surface-source file
/// (SSW-PDG table; see `nucleide-mcpl-io` `ssw`).
///
/// The output header clones `reference_ssw_path` (code/version/deck
/// passthrough) with `nrss`/`np1`/`orignp1` patched to the particle count and
/// `niss` passed through unless `niss` stamps an explicit value. Surface ids
/// come from each particle's `userflags`; pass `surface` to stamp one id on
/// every track instead (either way `[1, 999999]` is enforced). PDG codes
/// outside the SSW-PDG table (2112/22/11/-11/2212) are errors. Pass
/// `force_cs_to_one=True` to reproduce the upstream 2.2.8 `cs = 1.0`
/// spelling (default keeps the true cosine); pass `allow_polarisation=True`
/// to drop non-zero input polarisation (default rejects it). Returns the
/// track count. Thin wrapper over `nucleide-mcpl-io`.
#[pyfunction]
#[pyo3(signature = (mcpl_path, reference_ssw_path, ssw_out_path, surface=None, force_cs_to_one=false, niss=None, allow_polarisation=false))]
fn mcpl2ssw(
    mcpl_path: &str,
    reference_ssw_path: &str,
    ssw_out_path: &str,
    surface: Option<u32>,
    force_cs_to_one: bool,
    niss: Option<i64>,
    allow_polarisation: bool,
) -> PyResult<u64> {
    use nucleide_mcnp_io::surfsrc::SurfSrc;
    use nucleide_mcpl_io::ssw::Mcpl2SswOptions;
    let mcpl = nucleide_mcpl_io::McplFile::open(mcpl_path)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    let particles = mcpl
        .particles()
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    let reference =
        SurfSrc::open(reference_ssw_path).map_err(|e| PyValueError::new_err(e.to_string()))?;
    let (header, tracks) = nucleide_mcpl_io::ssw::mcpl2ssw(
        &particles,
        &reference.header,
        &Mcpl2SswOptions {
            surface,
            force_cs_to_one,
            niss_override: niss,
            allow_polarisation,
        },
    )
    .map_err(|e| PyValueError::new_err(e.to_string()))?;
    nucleide_mcnp_io::surfsrc::write_to_path(ssw_out_path, &header, &tracks)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    Ok(tracks.len() as u64)
}

/// Merge MCPL particle-list files into a new file (see `nucleide-mcpl-io`).
///
/// The first file's header wins (`srcname`, `comments`, `blobs`) and a
/// provenance comment is appended; `stat:sum` sums are never synthesized or
/// updated. All inputs must agree on the header options except
/// floating-point precision, which promotes to double on mixed input (the
/// lossless direction). Input order is the particle order of the output.
/// A `.gz` suffix on `out_path` compresses through gzip transparently.
/// Returns the merged particle count. Thin wrapper over `nucleide-mcpl-io`.
#[pyfunction]
fn merge_mcpl(paths: Vec<String>, out_path: &str) -> PyResult<u64> {
    let mut files = Vec::with_capacity(paths.len());
    for (i, p) in paths.iter().enumerate() {
        files.push(
            nucleide_mcpl_io::McplFile::open(p)
                .map_err(|e| PyValueError::new_err(format!("merge_mcpl: input {i} {p}: {e}")))?,
        );
    }
    let (header, particles) =
        nucleide_mcpl_io::merge_mcpl(&files).map_err(|e| PyValueError::new_err(e.to_string()))?;
    nucleide_mcpl_io::write_to_path(out_path, &header, &particles)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    Ok(particles.len() as u64)
}

/// Parsed `extract_mcpl` options: the selection rule plus, for the predicate
/// form, the handle where a Python callback exception is parked until the
/// Rust-side extraction returns.
struct ParsedExtract {
    spec: nucleide_mcpl_io::ExtractSpec,
    pending: Option<std::rc::Rc<std::cell::RefCell<Option<PyErr>>>>,
}

/// Parse the `extract_mcpl` options dict (see the `extract_mcpl` docs).
fn parse_extract_spec(
    options: Option<&Bound<'_, PyAny>>,
    nparticles: usize,
) -> PyResult<ParsedExtract> {
    let Some(d) = options else {
        return Ok(ParsedExtract {
            spec: nucleide_mcpl_io::ExtractSpec::Range(0..nparticles),
            pending: None,
        });
    };
    if !d.is_instance_of::<pyo3::types::PyDict>() {
        return Err(PyValueError::new_err("options must be a dict or None"));
    }
    let opt_usize = |key: &str| -> PyResult<Option<usize>> {
        match d.get_item(key) {
            Err(_) => Ok(None),
            Ok(v) if v.is_none() => Ok(None),
            Ok(v) => v.extract::<usize>().map(Some).map_err(|_| {
                PyValueError::new_err(format!("options `{key}` must be a non-negative int"))
            }),
        }
    };
    let start = opt_usize("start")?;
    let stop = opt_usize("stop")?;
    if let Ok(cb) = d.get_item("predicate") {
        if !cb.is_none() {
            if start.is_some() || stop.is_some() {
                return Err(PyValueError::new_err(
                    "options `start`/`stop` and `predicate` cannot be combined",
                ));
            }
            if !cb.is_callable() {
                return Err(PyValueError::new_err(
                    "options `predicate` must be callable",
                ));
            }
            let cb = cb.unbind();
            let pending: std::rc::Rc<std::cell::RefCell<Option<PyErr>>> =
                std::rc::Rc::new(std::cell::RefCell::new(None));
            let pending_inner = std::rc::Rc::clone(&pending);
            let spec = nucleide_mcpl_io::ExtractSpec::Predicate(Box::new(
                move |p: &nucleide_mcpl_io::Particle| -> bool {
                    if pending_inner.borrow().is_some() {
                        return false;
                    }
                    Python::attach(|py| {
                        let dict = match mcpl_particle_to_dict(py, p) {
                            Ok(d) => d,
                            Err(e) => {
                                *pending_inner.borrow_mut() = Some(e);
                                return false;
                            }
                        };
                        match cb.call1(py, (dict,)) {
                            Ok(v) => match v.is_truthy(py) {
                                Ok(t) => t,
                                Err(e) => {
                                    *pending_inner.borrow_mut() = Some(e);
                                    false
                                }
                            },
                            Err(e) => {
                                *pending_inner.borrow_mut() = Some(e);
                                false
                            }
                        }
                    })
                },
            ));
            return Ok(ParsedExtract {
                spec,
                pending: Some(pending),
            });
        }
    }
    Ok(ParsedExtract {
        spec: nucleide_mcpl_io::ExtractSpec::Range(start.unwrap_or(0)..stop.unwrap_or(nparticles)),
        pending: None,
    })
}

/// Extract a particle subset from an MCPL file into a new file (see
/// `nucleide-mcpl-io`).
///
/// The source header (`srcname`, `comments`, `blobs`, option flags) is
/// preserved verbatim on the output; only the particle count is patched.
/// `options` (dict or None) selects the subset: `start`/`stop` (ints) for
/// the half-open index range `[start, stop)`, or `predicate` (callable over
/// one particle dict) to keep selected records; absent options copy the
/// whole file. A `.gz` suffix on either path is transparent. Returns the
/// extracted particle count. Thin wrapper over `nucleide-mcpl-io`.
#[pyfunction]
#[pyo3(signature = (src_path, out_path, options=None))]
fn extract_mcpl(
    src_path: &str,
    out_path: &str,
    options: Option<Bound<'_, PyAny>>,
) -> PyResult<u64> {
    let file = nucleide_mcpl_io::McplFile::open(src_path)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    let nparticles = file.header.nparticles as usize;
    let parsed = parse_extract_spec(options.as_ref(), nparticles)?;
    let (header, particles) = nucleide_mcpl_io::extract_mcpl(&file, &parsed.spec)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    // Surface a predicate callback exception raised mid-extraction.
    if let Some(err) = parsed.pending.and_then(|p| p.borrow_mut().take()) {
        return Err(err);
    }
    nucleide_mcpl_io::write_to_path(out_path, &header, &particles)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    Ok(particles.len() as u64)
}

/// Compute record statistics over an MCPL file (see `nucleide-mcpl-io`).
///
/// Returns a dict with `nparticles`, `ekin_sum`/`ekin_min`/`ekin_max`/
/// `ekin_mean` (MeV; the `min`/`max`/`mean` entries are `None` for an empty
/// file), `weight_sum`, and `pdg_counts` (list of `(pdgcode, count)` pairs
/// sorted by PDG code). Thin wrapper over `nucleide-mcpl-io`.
#[pyfunction]
fn mcpl_stats(py: Python<'_>, path: &str) -> PyResult<Py<PyAny>> {
    use pyo3::types::PyDict;
    let file =
        nucleide_mcpl_io::McplFile::open(path).map_err(|e| PyValueError::new_err(e.to_string()))?;
    let s =
        nucleide_mcpl_io::mcpl_stats(&file).map_err(|e| PyValueError::new_err(e.to_string()))?;
    let d = PyDict::new(py);
    d.set_item("nparticles", s.nparticles)?;
    d.set_item("ekin_sum", s.ekin_sum)?;
    d.set_item("ekin_min", s.ekin_min)?;
    d.set_item("ekin_max", s.ekin_max)?;
    d.set_item("ekin_mean", s.ekin_mean)?;
    d.set_item("weight_sum", s.weight_sum)?;
    d.set_item("pdg_counts", s.pdg_counts)?;
    Ok(d.into_any().unbind())
}

/// Repair an MCPL file that was never properly closed (see `nucleide-mcpl-io`).
///
/// Recomputes the stored particle count from the file size (complete
/// records only, ignoring a partially written trailing record) and rewrites
/// the header in place; record bytes and format version pass through
/// untouched. A `.gz` suffix reads and writes through gzip transparently.
/// Returns the repaired particle count. Thin wrapper over `nucleide-mcpl-io`.
#[pyfunction]
fn repair_mcpl(path: &str) -> PyResult<u64> {
    let file =
        nucleide_mcpl_io::McplFile::open(path).map_err(|e| PyValueError::new_err(e.to_string()))?;
    let repaired = nucleide_mcpl_io::repair_mcpl(&file);
    let n = nucleide_mcpl_io::McplFile::from_bytes(repaired.clone())
        .map_err(|e| PyValueError::new_err(e.to_string()))?
        .header
        .nparticles;
    nucleide_mcpl_io::write_bytes_to_path(path, &repaired)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    Ok(n)
}

/// Parsed ENDL evaluation file (EEDL/EPDL scope).
#[pyclass(name = "EndlLibrary")]
struct PyEndlLibrary {
    inner: nucleide_mcnp_io::endl::Library,
}

#[pymethods]
impl PyEndlLibrary {
    /// Distinct nucleus ids in file order.
    fn nuclides(&self) -> Vec<i64> {
        self.inner.nuclides()
    }
    /// Reaction data for one selector set.
    ///
    /// `nuc` is an integer nucleus id (e.g. `820000000` for natural Pb) or a
    /// fully-specified isotope name (`"Pb208"`); bare element names do not
    /// resolve. `x1`/`p_out` filter by subshell/outgoing particle when given.
    /// Returns rows of `fields_for_rprop(rprop)` floats.
    #[pyo3(signature = (nuc, p_in, rdesc, rprop, x1=None, p_out=None))]
    fn get_rx(
        &self,
        nuc: &Bound<'_, PyAny>,
        p_in: i32,
        rdesc: i32,
        rprop: i32,
        x1: Option<i32>,
        p_out: Option<i32>,
    ) -> PyResult<Vec<Vec<f64>>> {
        let id = if let Ok(n) = nuc.extract::<i64>() {
            n
        } else if let Ok(name) = nuc.extract::<&str>() {
            NuclideId::from_name(name).map_err(wrap_nucid_err)?.nucid() as i64
        } else {
            return Err(PyTypeError::new_err("expected int nucleus id or str name"));
        };
        self.inner
            .get_rx(id, p_in, rdesc, rprop, x1, p_out)
            .map(|rows| rows.to_vec())
            .map_err(|e| PyValueError::new_err(e.to_string()))
    }
}

/// Read an ENDL evaluation file (EEDL/EPDL scope).
#[pyfunction]
fn read_endl(path: &str) -> PyResult<PyEndlLibrary> {
    nucleide_mcnp_io::endl::Library::open(path)
        .map(|inner| PyEndlLibrary { inner })
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Convert one 11-character ENDL number field to float.
#[pyfunction]
fn endl_endftod(field: &str) -> f64 {
    nucleide_mcnp_io::endl::endftod(field)
}

/// Combine several SSW surface-source files into one (`ssw_combine.py` port).
///
/// Headers must agree on kod/ver/loddat, particle type, surface counts and
/// per-surface records; the output header carries the signed `orignp1` sum
/// and the plain `nrss` sum, with later files' track `nps` shifted
/// sign-preservingly. Raises `ValueError` on incompatible inputs (upstream
/// returns `False`).
#[pyfunction]
fn combine_ssw_files(output: &str, inputs: Vec<String>) -> PyResult<()> {
    nucleide_mcnp_io::surfsrc::combine_files(&inputs, output)
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

// ---------------------------------------------------------------------------
// Depletion / CRAM
// ---------------------------------------------------------------------------

/// A parsed depletion chain (XML format).
#[pyclass(name = "Chain")]
struct PyChain {
    inner: std::sync::Arc<nucleide_depletion::Chain>,
}

#[pymethods]
impl PyChain {
    /// Nuclide names in chain order.
    #[getter]
    fn nuclides(&self) -> Vec<String> {
        self.inner.nuclides.iter().map(|n| n.name.clone()).collect()
    }

    fn index_of(&self, name: &str) -> Option<usize> {
        self.inner.index_of(name)
    }
}

/// Parse a depletion-chain XML file.
#[pyfunction]
fn read_chain(path: &str) -> PyResult<PyChain> {
    nucleide_depletion::Chain::from_file(path)
        .map(|inner| PyChain {
            inner: std::sync::Arc::new(inner),
        })
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// One-group reaction rates keyed by "NuclideName:reaction".
type RateMap = BTreeMap<String, f64>;

/// Pre-built depletion system for repeated CRAM solves.
#[pyclass(name = "DepletionSystem")]
struct PyDepletionSystem {
    inner: std::sync::Arc<nucleide_depletion::DepletionSystem>,
}

#[pymethods]
impl PyDepletionSystem {
    /// Solve one depletion step with the pre-built system.
    ///
    /// `order` selects the CRAM order (16 or 48); `method` selects the
    /// solver kernel (`"cram16"`, `"cram48"`, `"bateman"`, `"bateman_hp"`,
    /// default `"cram48"`). An explicitly non-default `method` overrides
    /// `order`; the default `method` defers to `order` for backwards
    /// compatibility. `Bateman` arms fall back to CRAM-48 on non-decay
    /// systems.
    #[pyo3(signature = (n0, dt, order=48, method="cram48"))]
    fn solve(
        &self,
        n0: BTreeMap<String, f64>,
        dt: f64,
        order: u8,
        method: &str,
    ) -> PyResult<BTreeMap<String, f64>> {
        let method = resolve_method(order, method)?;
        nucleide_depletion::deplete_with_method(&self.inner, method, &n0, dt)
            .map(|r| r.atoms)
            .map_err(|e| PyValueError::new_err(e.to_string()))
    }

    /// Solve one depletion step using pre-built index vectors.
    ///
    /// `n0` and the returned vector are in chain index order; this avoids the
    /// name-to-index mapping overhead of `solve()` for tight timing loops.
    /// `method` behaves as in [`PyDepletionSystem::solve`].
    #[pyo3(signature = (n0, dt, order=48, method="cram48"))]
    fn solve_vec(&self, n0: Vec<f64>, dt: f64, order: u8, method: &str) -> PyResult<Vec<f64>> {
        let method = resolve_method(order, method)?;
        nucleide_depletion::solve_with_method(&self.inner, method, &n0, dt)
            .map_err(|e| PyValueError::new_err(e.to_string()))
    }
}

/// Build a reusable depletion system from a chain and reaction rates.
#[pyfunction]
fn build_depletion_system(chain: &PyChain, rates: RateMap) -> PyResult<PyDepletionSystem> {
    let rs = split_rates(&rates, &chain.inner)?;
    nucleide_depletion::DepletionSystem::build((*chain.inner).clone(), &rs)
        .map(|sys| PyDepletionSystem {
            inner: std::sync::Arc::new(sys),
        })
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

fn parse_order(order: u8) -> PyResult<nucleide_depletion::Order> {
    match order {
        16 => Ok(nucleide_depletion::Order::Order16),
        48 => Ok(nucleide_depletion::Order::Order48),
        other => Err(PyValueError::new_err(format!(
            "unsupported CRAM order {other} (supported: 16, 48)"
        ))),
    }
}

/// Parse a solver `method=` spelling (`"cram16"`, `"cram48"`, `"bateman"`,
/// `"bateman_hp"`; case-insensitive, `-`/`_` interchangeable).
fn parse_method(name: &str) -> PyResult<nucleide_depletion::Method> {
    name.parse().map_err(|e: String| PyValueError::new_err(e))
}

/// Resolve the legacy `order` (16|48) plus `method=` into a core [`Method`].
///
/// An explicitly non-default `method` wins; the default `"cram48"` defers to
/// `order` so existing `order=16` calls keep working unchanged.
fn resolve_method(order: u8, method: &str) -> PyResult<nucleide_depletion::Method> {
    let parsed = parse_method(method)?;
    if parsed == nucleide_depletion::Method::default_cram() {
        parse_order(order).map(nucleide_depletion::Method::Cram)
    } else {
        Ok(parsed)
    }
}

fn split_rates(
    rates: &RateMap,
    chain: &nucleide_depletion::Chain,
) -> PyResult<nucleide_depletion::ReactionRates> {
    let mut out = nucleide_depletion::ReactionRates::new();
    for (key, v) in rates {
        let (nuc, rx) = key.split_once(':').ok_or_else(|| {
            PyValueError::new_err(format!("rate key `{key}` must be `Name:reaction`"))
        })?;
        let idx = chain
            .index_of(nuc)
            .ok_or_else(|| PyValueError::new_err(format!("rate for unknown nuclide `{nuc}`")))?;
        out.entry(idx).or_default().insert(rx.to_string(), *v);
    }
    Ok(out)
}

/// Solve one depletion step with IPF CRAM or the analytic Bateman fast path.
///
/// `n0` maps nuclide names to initial atom counts; `rates` maps
/// `"Name:(n,gamma)"`-style keys to one-group rates [1/s]; `dt` is the step
/// length in seconds; `order` is 16 or 48; `method` selects the solver
/// kernel (`"cram16"`, `"cram48"`, `"bateman"`, `"bateman_hp"`, default
/// `"cram48"` — an explicitly non-default `method` overrides `order`).
/// `Bateman` arms fall back to CRAM-48 on non-decay systems (rates on,
/// cyclic topology, near-degenerate half-lives).
#[pyfunction]
#[pyo3(signature = (chain, n0, dt, rates=None, order=48, method="cram48"))]
fn deplete(
    chain: &PyChain,
    n0: BTreeMap<String, f64>,
    dt: f64,
    rates: Option<RateMap>,
    order: u8,
    method: &str,
) -> PyResult<BTreeMap<String, f64>> {
    let method = resolve_method(order, method)?;
    let rates = split_rates(rates.as_ref().unwrap_or(&BTreeMap::new()), &chain.inner)?;
    let sys = nucleide_depletion::DepletionSystem::build((*chain.inner).clone(), &rates)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    nucleide_depletion::deplete_with_method(&sys, method, &n0, dt)
        .map(|r| r.atoms)
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

// ---------------------------------------------------------------------------
// Serpent / FLUKA / variance reduction + writers
// ---------------------------------------------------------------------------

/// Parse a Serpent .m output file ("res", "dep", or "det") into a plain
/// Python dict keyed by variable name. Scalars become floats/strings, vectors
/// become 1-D lists, and matrices become 2-D lists of row lists (one row per
/// Serpent block). A matrix holding non-numeric values raises `ValueError`.
#[pyfunction]
fn read_serpent(path: &str, kind: &str) -> PyResult<Py<PyAny>> {
    let text = std::fs::read_to_string(path).map_err(|e| PyValueError::new_err(e.to_string()))?;
    let table = match kind {
        "res" => nucleide_serpent_io::parse_res(&text),
        "dep" => nucleide_serpent_io::parse_dep(&text),
        "det" => nucleide_serpent_io::parse_det(&text),
        other => {
            return Err(PyValueError::new_err(format!(
                "kind must be res|dep|det, got `{other}`"
            )))
        }
    }
    .map_err(|e| PyValueError::new_err(e.to_string()))?;
    fn entry_to_py(py: Python<'_>, e: &nucleide_serpent_io::Entry) -> PyResult<Py<PyAny>> {
        use nucleide_serpent_io::Entry as E;
        let value = match e {
            E::Scalar(nucleide_serpent_io::Value::Num(n)) => {
                n.into_pyobject(py).unwrap().unbind().into_any()
            }
            E::Scalar(nucleide_serpent_io::Value::Str(s)) => {
                s.into_pyobject(py).unwrap().unbind().into_any()
            }
            E::Vector(vs) => vs
                .iter()
                .map(|v| match v {
                    nucleide_serpent_io::Value::Num(n) => {
                        n.into_pyobject(py).unwrap().unbind().into_any()
                    }
                    nucleide_serpent_io::Value::Str(s) => {
                        s.into_pyobject(py).unwrap().unbind().into_any()
                    }
                })
                .collect::<Vec<_>>()
                .into_pyobject(py)
                .unwrap()
                .unbind()
                .into_any(),
            E::Matrix(m) => m
                .to_rows_f64()
                .map_err(|err| PyValueError::new_err(err.to_string()))?
                .into_pyobject(py)
                .unwrap()
                .unbind()
                .into_any(),
        };
        Ok(value)
    }
    Python::attach(|py| {
        let dict = pyo3::types::PyDict::new(py);
        for (k, e) in table.iter() {
            dict.set_item(k, entry_to_py(py, e)?)?;
        }
        Ok(dict.into_any().unbind())
    })
}

/// One FLUKA USRBIN detector.
#[pyclass(name = "UsrbinTally")]
struct PyUsrbinTally {
    inner: nucleide_fluka_io::usrbin::UsrbinTally,
}

#[pymethods]
impl PyUsrbinTally {
    #[getter]
    fn name(&self) -> &str {
        &self.inner.name
    }
    #[getter]
    fn particle(&self) -> &str {
        &self.inner.particle
    }
    #[getter]
    fn nx(&self) -> usize {
        self.inner.x_info.bins
    }
    #[getter]
    fn ny(&self) -> usize {
        self.inner.y_info.bins
    }
    #[getter]
    fn nz(&self) -> usize {
        self.inner.z_info.bins
    }
    #[getter]
    fn x_bounds(&self) -> Vec<f64> {
        self.inner.x_bounds.clone()
    }
    #[getter]
    fn y_bounds(&self) -> Vec<f64> {
        self.inner.y_bounds.clone()
    }
    #[getter]
    fn z_bounds(&self) -> Vec<f64> {
        self.inner.z_bounds.clone()
    }
    /// Scored values, x slowest -> z fastest.
    #[getter]
    fn data(&self) -> Vec<f64> {
        self.inner.part_data.clone()
    }
    /// Statistical errors, same layout as `data`.
    #[getter]
    fn error(&self) -> Vec<f64> {
        self.inner.error_data.clone()
    }
    fn dims(&self) -> [usize; 3] {
        [self.nx(), self.ny(), self.nz()]
    }
}

/// Parse all USRBIN tallies from a FLUKA .lis file.
#[pyfunction]
fn read_usrbin(path: &str) -> PyResult<Vec<PyUsrbinTally>> {
    let tallies = nucleide_fluka_io::usrbin::read_usrbin_file(path)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    Ok(tallies
        .into_iter()
        .map(|inner| PyUsrbinTally { inner })
        .collect())
}

/// MAGIC weight-window output.
#[pyclass(name = "MagicOutput")]
struct PyMagicOutput {
    inner: nucleide_vr_tools::magic::MagicOutput,
}

#[pymethods]
impl PyMagicOutput {
    /// Flat lower bounds ([ve] in total mode, [ve*g+g] per-group).
    #[getter]
    fn lower_bounds_ww(&self) -> Vec<f64> {
        self.inner.lower_bounds_ww.clone()
    }
    #[getter]
    fn groups_per_ve(&self) -> usize {
        self.inner.groups_per_ve
    }
    #[getter]
    fn scale_factors(&self) -> Vec<f64> {
        self.inner.scale_factors.clone()
    }
    #[getter]
    fn e_upper_bounds(&self) -> Vec<f64> {
        self.inner.e_upper_bounds.clone()
    }
    #[getter]
    fn ww_tag_name(&self) -> &str {
        &self.inner.ww_tag_name
    }
}

/// Generate MAGIC weight-window lower bounds from a meshtal tally.
#[pyfunction]
#[pyo3(signature = (tally, per_group=false, tolerance=0.5))]
fn magic(tally: &PyMeshTally, per_group: bool, tolerance: f64) -> PyResult<PyMagicOutput> {
    let selection = if per_group {
        nucleide_vr_tools::magic::MagicSelection::PerGroup
    } else {
        nucleide_vr_tools::magic::MagicSelection::Total
    };
    let params = nucleide_vr_tools::magic::MagicParams {
        tolerance,
        ..Default::default()
    };
    nucleide_vr_tools::magic::magic_with(&tally.inner, selection, params)
        .map(|inner| PyMagicOutput { inner })
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Walker alias table for discrete sampling.
#[pyclass(name = "AliasTable")]
struct PyAliasTable {
    inner: nucleide_vr_tools::sampling::AliasTable,
}

#[pymethods]
impl PyAliasTable {
    /// Build from a probability density (normalized internally).
    #[new]
    fn new(pdf: Vec<f64>) -> PyResult<Self> {
        nucleide_vr_tools::sampling::AliasTable::new(&pdf)
            .map(|inner| PyAliasTable { inner })
            .map_err(|e| PyValueError::new_err(e.to_string()))
    }
    /// Sample an index from two uniform random numbers.
    fn sample(&self, r1: f64, r2: f64) -> usize {
        self.inner.sample(r1, r2)
    }
    #[getter]
    fn pdf(&self) -> Vec<f64> {
        self.inner.pdf().to_vec()
    }
    fn __len__(&self) -> usize {
        self.inner.len()
    }
}

/// Mesh source sampler over a meshtal tally (ANALOG/UNIFORM/USER modes).
#[pyclass(name = "MeshSourceSampler")]
struct PyMeshSourceSampler {
    inner: nucleide_vr_tools::sampling::MeshSourceSampler,
}

#[pymethods]
impl PyMeshSourceSampler {
    /// mode: "analog" | "uniform" | "user" (user requires user_pdf).
    #[new]
    #[pyo3(signature = (tally, mode, user_pdf=None))]
    fn new(tally: &PyMeshTally, mode: &str, user_pdf: Option<Vec<f64>>) -> PyResult<Self> {
        let user = if matches!(mode, "user") {
            Some(user_pdf.ok_or_else(|| PyValueError::new_err("user mode needs user_pdf"))?)
        } else {
            None
        };
        let m = match mode {
            "analog" => nucleide_vr_tools::sampling::Mode::Analog,
            "uniform" => nucleide_vr_tools::sampling::Mode::Uniform,
            "user" => nucleide_vr_tools::sampling::Mode::User,
            other => {
                return Err(PyValueError::new_err(format!(
                    "mode must be analog|uniform|user, got `{other}`"
                )))
            }
        };
        nucleide_vr_tools::sampling::MeshSourceSampler::new(&tally.inner, m, user.as_deref())
            .map(|inner| PyMeshSourceSampler { inner })
            .map_err(|e| PyValueError::new_err(e.to_string()))
    }
    /// Sample a voxel; returns dict(index, i, j, k, weight).
    fn sample(&self, r1: f64, r2: f64) -> BTreeMap<String, f64> {
        let s = self.inner.sample(r1, r2);
        let mut d = BTreeMap::new();
        d.insert("index".into(), s.index as f64);
        d.insert("i".into(), s.i as f64);
        d.insert("j".into(), s.j as f64);
        d.insert("k".into(), s.k as f64);
        d.insert("weight".into(), s.weight);
        d
    }
    /// The bias mode this sampler was constructed with.
    fn mode(&self) -> &'static str {
        match self.inner.mode() {
            nucleide_vr_tools::sampling::Mode::Analog => "analog",
            nucleide_vr_tools::sampling::Mode::Uniform => "uniform",
            nucleide_vr_tools::sampling::Mode::User => "user",
        }
    }
    /// Number of voxels in the sampling domain.
    fn num_voxels(&self) -> usize {
        self.inner.num_voxels()
    }
    /// Length of the underlying alias table (one entry per voxel).
    fn table_len(&self) -> usize {
        self.inner.table().len()
    }
}

/// Gaussian KDE sampler over caller particle vectors (KDSource-class).
#[pyclass(name = "KdeSampler")]
struct PyKdeSampler {
    inner: nucleide_vr_tools::kde::KdeSampler,
}

#[pymethods]
impl PyKdeSampler {
    /// Fit over `samples` (rectangular row lists); `bandwidth` is
    /// "silverman" (default) or a per-dimension width list.
    #[new]
    #[pyo3(signature = (samples, bandwidth=None))]
    fn new(samples: Vec<Vec<f64>>, bandwidth: Option<&Bound<'_, PyAny>>) -> PyResult<Self> {
        let rule = match bandwidth {
            None => nucleide_vr_tools::kde::Bandwidth::Silverman,
            Some(b) => {
                if let Ok(name) = b.extract::<String>() {
                    match name.as_str() {
                        "silverman" => nucleide_vr_tools::kde::Bandwidth::Silverman,
                        other => {
                            return Err(PyValueError::new_err(format!(
                                "bandwidth must be silverman or a width list, got `{other}`"
                            )))
                        }
                    }
                } else {
                    let widths = b.extract::<Vec<f64>>().map_err(|_| {
                        PyValueError::new_err("bandwidth must be silverman or a width list")
                    })?;
                    nucleide_vr_tools::kde::Bandwidth::Fixed(widths)
                }
            }
        };
        nucleide_vr_tools::kde::KdeSampler::fit(&samples, rule)
            .map(|inner| PyKdeSampler { inner })
            .map_err(|e| PyValueError::new_err(e.to_string()))
    }
    /// KDE density at `point`.
    fn pdf(&self, point: Vec<f64>) -> PyResult<f64> {
        self.inner
            .pdf(&point)
            .map_err(|e| PyValueError::new_err(e.to_string()))
    }
    /// Resample: `u` in [0, 1) picks the centre, `normals` perturbs it.
    fn draw(&self, u: f64, normals: Vec<f64>) -> PyResult<Vec<f64>> {
        self.inner
            .draw(u, &normals)
            .map_err(|e| PyValueError::new_err(e.to_string()))
    }
    /// Fitted per-dimension bandwidths.
    fn bandwidths(&self) -> Vec<f64> {
        self.inner.bandwidths().to_vec()
    }
    /// Number of fitted samples.
    fn n_samples(&self) -> usize {
        self.inner.n_samples()
    }
}

/// Write a SurfSrc file back to disk. `tracks` defaults to re-reading the
/// original file's tracks.
#[pyfunction]
#[pyo3(signature = (ssw, path, tracks=None))]
fn write_ssw(
    ssw: &PySurfSrc,
    path: &str,
    tracks: Option<Vec<BTreeMap<String, f64>>>,
) -> PyResult<()> {
    let header = ssw.inner.header.clone();
    let track_data: Vec<nucleide_mcnp_io::surfsrc::TrackData> = match tracks {
        Some(dict_tracks) => dict_tracks
            .iter()
            .map(|d| {
                let g = |k: &str| d.get(k).copied().unwrap_or(0.0);
                let mut record = vec![0.0f64; nucleide_mcnp_io::surfsrc::TrackData::RECORD_WIDTH];
                record[0] = g("nps");
                record[1] = g("bitarray");
                record[2] = g("wgt");
                record[3] = g("erg");
                record[4] = g("tme");
                record[5] = g("x");
                record[6] = g("y");
                record[7] = g("z");
                record[8] = g("u");
                record[9] = g("v");
                record[10] = g("cs");
                nucleide_mcnp_io::surfsrc::TrackData::from_record(record)
            })
            .collect(),
        None => ssw
            .inner
            .read_tracklist()
            .map_err(|e| PyValueError::new_err(e.to_string()))?,
    };
    let mut f = std::fs::File::create(path).map_err(|e| PyValueError::new_err(e.to_string()))?;
    nucleide_mcnp_io::surfsrc::write_to(&mut f, &header, &track_data)
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Generate MCNP input-deck text from a structured mesh.
#[pyfunction]
fn mesh_to_geom(
    x_bounds: Vec<f64>,
    y_bounds: Vec<f64>,
    z_bounds: Vec<f64>,
    cell_materials: Vec<Option<(String, f64)>>,
    title_card: &str,
) -> String {
    let opts = nucleide_mcnp_io::deck::DeckOptions {
        title_card: title_card.to_string(),
        frac_type: nucleide_mcnp_io::deck::FracType::Mass,
    };
    nucleide_mcnp_io::deck::mesh_to_geom(&x_bounds, &y_bounds, &z_bounds, &cell_materials, &opts)
}

// ---------------------------------------------------------------------------
// ALARA I/O (thin glue over `alara-io`; solver stays out of scope)
// ---------------------------------------------------------------------------

/// Parse an ALARA input deck into plain Python containers.
///
/// Returns a dict with `block_kinds` (list[str] in file order), `geometry`
/// (str | None), `mixtures` (list of {name, entries}), `fluxes` (list of
/// {name, file, scale, skip, format}), `cooling_times_s` (list[float]),
/// `schedules`, `pulse_histories`, `outputs`, and `truncation`.
#[pyfunction]
fn alara_parse_deck(py: Python<'_>, text: &str) -> PyResult<Py<PyAny>> {
    let owned = text.to_owned();
    let deck = py
        .detach(move || nucleide_alara_io::AlaraDeck::parse(&owned))
        .map_err(ala_err)?;
    Ok(deck_to_py(py, &deck))
}

fn ala_err(e: nucleide_alara_io::Error) -> PyErr {
    PyValueError::new_err(e.to_string())
}

fn deck_to_py(py: Python<'_>, deck: &nucleide_alara_io::AlaraDeck) -> Py<PyAny> {
    use pyo3::types::PyDict;
    let out = PyDict::new(py);
    let block_kinds: Vec<&str> = deck.block_kinds();
    out.set_item("block_kinds", block_kinds).ok();
    out.set_item("geometry", deck.geometry.as_ref().map(|g| g.kind.clone()))
        .ok();
    let mixtures: Vec<Py<PyAny>> = deck.mixtures.iter().map(|m| mixture_to_py(py, m)).collect();
    out.set_item("mixtures", mixtures).ok();
    let fluxes: Vec<Py<PyAny>> = deck.fluxes.iter().map(|f| fluxdef_to_py(py, f)).collect();
    out.set_item("fluxes", fluxes).ok();
    out.set_item(
        "cooling_times_s",
        deck.cooling
            .as_ref()
            .map(|c| c.times_s.clone())
            .unwrap_or_default(),
    )
    .ok();
    let schedules: Vec<Py<PyAny>> = deck
        .schedules
        .iter()
        .map(|s| {
            let d = PyDict::new(py);
            let items: Vec<Vec<String>> = s.items.iter().map(|it| it.tokens.clone()).collect();
            d.set_item("name", &s.name).ok();
            d.set_item("items", items).ok();
            d.into_any().unbind()
        })
        .collect();
    out.set_item("schedules", schedules).ok();
    let histories: Vec<Py<PyAny>> = deck
        .pulse_histories
        .iter()
        .map(|h| {
            let d = PyDict::new(py);
            let levels: Vec<Py<PyAny>> = h
                .levels
                .iter()
                .map(|l| {
                    let e = PyDict::new(py);
                    e.set_item("pulses", l.pulses).ok();
                    e.set_item("delay_s", l.delay_s).ok();
                    e.into_any().unbind()
                })
                .collect();
            d.set_item("name", &h.name).ok();
            d.set_item("levels", levels).ok();
            d.into_any().unbind()
        })
        .collect();
    out.set_item("pulse_histories", histories).ok();
    let outputs: Vec<Py<PyAny>> = deck
        .outputs
        .iter()
        .map(|o| {
            let d = PyDict::new(py);
            d.set_item("resolution", &o.resolution).ok();
            d.set_item("entries", o.entries.clone()).ok();
            d.into_any().unbind()
        })
        .collect();
    out.set_item("outputs", outputs).ok();
    out.set_item("truncation", deck.truncation.as_ref().map(|t| t.tolerance))
        .ok();
    out.into_any().unbind()
}

fn mixture_to_py(py: Python<'_>, mix: &nucleide_alara_io::deck::Mixture) -> Py<PyAny> {
    use pyo3::types::PyDict;
    let entries: Vec<Py<PyAny>> = mix
        .entries
        .iter()
        .map(|e| mixture_entry_to_py(py, e))
        .collect();
    let d = PyDict::new(py);
    d.set_item("name", &mix.name).ok();
    d.set_item("entries", entries).ok();
    d.into_any().unbind()
}

fn mixture_entry_to_py(py: Python<'_>, entry: &nucleide_alara_io::deck::MixtureEntry) -> Py<PyAny> {
    use nucleide_alara_io::deck::MixtureEntry as E;
    use pyo3::types::PyDict;
    let d = PyDict::new(py);
    match entry {
        E::Material {
            name,
            rel_density,
            vol_fraction,
        } => {
            d.set_item("kind", "material").ok();
            d.set_item("name", name).ok();
            d.set_item("rel_density", *rel_density).ok();
            d.set_item("vol_fraction", *vol_fraction).ok();
        }
        E::Element {
            symbol,
            rel_density,
            vol_fraction,
        } => {
            d.set_item("kind", "element").ok();
            d.set_item("symbol", symbol).ok();
            d.set_item("rel_density", *rel_density).ok();
            d.set_item("vol_fraction", *vol_fraction).ok();
        }
        E::Like {
            mixture,
            rel_density,
        } => {
            d.set_item("kind", "like").ok();
            d.set_item("mixture", mixture).ok();
            d.set_item("rel_density", *rel_density).ok();
        }
        E::Target { target_kind, name } => {
            d.set_item("kind", "target").ok();
            d.set_item("target_kind", target_kind).ok();
            d.set_item("name", name).ok();
        }
    }
    d.into_any().unbind()
}

fn fluxdef_to_py(py: Python<'_>, flux: &nucleide_alara_io::deck::FluxDef) -> Py<PyAny> {
    use pyo3::types::PyDict;
    let d = PyDict::new(py);
    d.set_item("name", &flux.name).ok();
    d.set_item("file", &flux.file).ok();
    d.set_item("scale", flux.scale).ok();
    d.set_item("skip", flux.skip).ok();
    d.set_item("format", &flux.format).ok();
    d.into_any().unbind()
}

/// Parse an ALARA default-format group-flux file into plain containers.
///
/// Returns a dict with `name`, `groups_per_interval`, `num_intervals`,
/// `totals` (per-interval sums), `total` (grand sum), and `intervals`.
#[pyfunction]
fn alara_parse_flux(py: Python<'_>, text: &str, name: &str) -> PyResult<Py<PyAny>> {
    let owned_text = text.to_owned();
    let owned_name = name.to_owned();
    let spectra = py
        .detach(move || nucleide_alara_io::FluxSpectra::parse(&owned_name, &owned_text))
        .map_err(ala_err)?;
    use pyo3::types::PyDict;
    let d = PyDict::new(py);
    d.set_item("name", spectra.name.clone()).ok();
    d.set_item("groups_per_interval", spectra.groups_per_interval)
        .ok();
    d.set_item("num_intervals", spectra.num_intervals()).ok();
    let totals: Vec<f64> = spectra.intervals.iter().map(|iv| iv.iter().sum()).collect();
    d.set_item("totals", totals).ok();
    d.set_item("total", spectra.total()).ok();
    d.set_item("intervals", spectra.intervals.clone()).ok();
    Ok(d.into_any().unbind())
}

/// Parse an ALARA activation-output listing into a list of row dicts.
///
/// Each row carries the 11 `ResponseRow` fields as plain floats/strings/ints:
/// `time_s`, `time_label`, `nuclide`, `half_life_s`, `run_lbl`, `block`,
/// `block_name`, `block_num`, `variable`, `var_unit`, `value`.
#[pyfunction]
fn alara_parse_output(
    py: Python<'_>,
    text: &str,
    run_lbl: &str,
) -> PyResult<Vec<BTreeMap<String, Py<PyAny>>>> {
    let owned_text = text.to_owned();
    let owned_lbl = run_lbl.to_owned();
    let rows = py
        .detach(move || {
            nucleide_alara_io::output::ResponseFrame::parse(&owned_text, &owned_lbl).map(|f| f.rows)
        })
        .map_err(ala_err)?;
    Ok(rows
        .iter()
        .map(|r| {
            let mut d = BTreeMap::new();
            d.insert(
                "time_s".to_string(),
                r.time_s.into_pyobject(py).unwrap().unbind().into_any(),
            );
            d.insert(
                "time_label".to_string(),
                r.time_label
                    .clone()
                    .into_pyobject(py)
                    .unwrap()
                    .unbind()
                    .into_any(),
            );
            d.insert(
                "nuclide".to_string(),
                r.nuclide
                    .clone()
                    .into_pyobject(py)
                    .unwrap()
                    .unbind()
                    .into_any(),
            );
            d.insert(
                "half_life_s".to_string(),
                r.half_life_s.into_pyobject(py).unwrap().unbind().into_any(),
            );
            d.insert(
                "run_lbl".to_string(),
                r.run_lbl
                    .clone()
                    .into_pyobject(py)
                    .unwrap()
                    .unbind()
                    .into_any(),
            );
            d.insert(
                "block".to_string(),
                r.block
                    .as_str()
                    .into_pyobject(py)
                    .unwrap()
                    .unbind()
                    .into_any(),
            );
            d.insert(
                "block_name".to_string(),
                r.block_name
                    .clone()
                    .into_pyobject(py)
                    .unwrap()
                    .unbind()
                    .into_any(),
            );
            d.insert(
                "block_num".to_string(),
                r.block_num.into_pyobject(py).unwrap().unbind().into_any(),
            );
            d.insert(
                "variable".to_string(),
                r.variable
                    .as_str()
                    .into_pyobject(py)
                    .unwrap()
                    .unbind()
                    .into_any(),
            );
            d.insert(
                "var_unit".to_string(),
                r.var_unit
                    .clone()
                    .into_pyobject(py)
                    .unwrap()
                    .unbind()
                    .into_any(),
            );
            d.insert(
                "value".to_string(),
                r.value.into_pyobject(py).unwrap().unbind().into_any(),
            );
            d
        })
        .collect())
}

/// Expand a deck's schedule hierarchy into flat irradiation/cooling steps.
///
/// Choice: takes deck text (plus optional top schedule name) instead of JSON
/// schedule/history blobs, so callers reuse the already-parsed deck blocks
/// without a parallel JSON schema. Returns a list of
/// {duration_s, flux, is_cooling} dicts.
#[pyfunction]
#[pyo3(signature = (deck_text, top=None))]
fn alara_expand_schedule(
    py: Python<'_>,
    deck_text: &str,
    top: Option<&str>,
) -> PyResult<Vec<BTreeMap<String, Py<PyAny>>>> {
    let owned_text = deck_text.to_owned();
    let owned_top = top.map(str::to_owned);
    let steps = py
        .detach(move || expand_deck_schedules(&owned_text, owned_top.as_deref()))
        .map_err(PyValueError::new_err)?;
    Ok(steps
        .into_iter()
        .map(|s| {
            let mut d = BTreeMap::new();
            let cooling = s.is_cooling();
            d.insert(
                "duration_s".to_string(),
                s.duration_s.into_pyobject(py).unwrap().unbind().into_any(),
            );
            d.insert(
                "flux".to_string(),
                s.flux
                    .clone()
                    .into_pyobject(py)
                    .unwrap()
                    .unbind()
                    .into_any(),
            );
            d.insert(
                "is_cooling".to_string(),
                pyo3::types::PyBool::new(py, cooling)
                    .to_owned()
                    .into_any()
                    .unbind(),
            );
            d
        })
        .collect())
}

fn expand_deck_schedules(
    deck_text: &str,
    top: Option<&str>,
) -> Result<Vec<nucleide_alara_io::FlatStep>, String> {
    let deck = nucleide_alara_io::AlaraDeck::parse(deck_text).map_err(|e| e.to_string())?;
    let mut scheds = Vec::with_capacity(deck.schedules.len());
    for raw in &deck.schedules {
        let mut items = Vec::with_capacity(raw.items.len());
        for entry in &raw.items {
            items.push(
                parse_deck_sched_item(&entry.tokens)
                    .map_err(|m| format!("schedule `{}` line {}: {m}", raw.name, entry.line))?,
            );
        }
        scheds.push(nucleide_alara_io::schedule::ScheduleDef {
            name: raw.name.clone(),
            items,
        });
    }
    let histories: Vec<nucleide_alara_io::schedule::PulseHistory> = deck
        .pulse_histories
        .iter()
        .map(|h| nucleide_alara_io::schedule::PulseHistory {
            name: h.name.clone(),
            levels: h
                .levels
                .iter()
                .map(|l| nucleide_alara_io::schedule::PulseLevel {
                    count: l.pulses,
                    delay_s: l.delay_s,
                })
                .collect(),
        })
        .collect();
    match top {
        Some(name) => {
            nucleide_alara_io::expand_from(name, &scheds, &histories).map_err(|e| e.to_string())
        }
        None => nucleide_alara_io::expand(&scheds, &histories).map_err(|e| e.to_string()),
    }
}

fn parse_deck_sched_item(tokens: &[String]) -> Result<nucleide_alara_io::SchedItem, String> {
    match tokens {
        [op_text, op_unit, flux, history, delay_text, delay_unit] => {
            let op: f64 = op_text
                .parse()
                .map_err(|_| format!("expected operating time, found `{op_text}`"))?;
            let delay: f64 = delay_text
                .parse()
                .map_err(|_| format!("expected delay, found `{delay_text}`"))?;
            let op_time_s =
                nucleide_alara_io::parse_time_to_seconds(op, op_unit).map_err(|e| e.to_string())?;
            let delay_s = nucleide_alara_io::parse_time_to_seconds(delay, delay_unit)
                .map_err(|e| e.to_string())?;
            Ok(nucleide_alara_io::SchedItem::Pulse {
                op_time_s,
                flux: flux.clone(),
                history: history.clone(),
                delay_s,
            })
        }
        [name, history, delay_text, delay_unit] => {
            let delay: f64 = delay_text
                .parse()
                .map_err(|_| format!("expected delay, found `{delay_text}`"))?;
            let delay_s = nucleide_alara_io::parse_time_to_seconds(delay, delay_unit)
                .map_err(|e| e.to_string())?;
            Ok(nucleide_alara_io::SchedItem::SubSchedule {
                name: name.clone(),
                history: history.clone(),
                delay_s,
            })
        }
        _ => Err(format!(
            "expected 4- or 6-token schedule item, found {}",
            tokens.join(" ")
        )),
    }
}

// ---------------------------------------------------------------------------
// Data accessors, input parsing, enrichment, materials
// ---------------------------------------------------------------------------

/// Half-life [s] for a nucid integer or name string.
#[pyfunction]
fn half_life(key: &Bound<'_, PyAny>) -> PyResult<Option<f64>> {
    lookup(key, nucleide_nuclei::data::half_life)
}

/// Decay constant lambda = ln2 / t_half [1/s].
#[pyfunction]
fn decay_constant(key: &Bound<'_, PyAny>) -> PyResult<Option<f64>> {
    lookup(key, nucleide_nuclei::data::decay_constant)
}

/// Neutron-capture Q value computed from AME2020 masses [MeV].
#[pyfunction]
fn q_value_capture(key: &Bound<'_, PyAny>) -> PyResult<Option<f64>> {
    lookup(key, nucleide_nuclei::data::q_value_neutron_capture)
}

/// Alpha-decay Q value from AME2020 masses [MeV].
#[pyfunction]
fn q_value_alpha(key: &Bound<'_, PyAny>) -> PyResult<Option<f64>> {
    lookup(key, nucleide_nuclei::data::q_value_alpha)
}

/// Parse MCNP material cards from an input deck.
/// Returns a list of dicts: {number, fractions: {NuclideName: frac},
/// fraction_type: "atom"|"mass", density, comments}.
#[pyfunction]
fn read_inp(path: &str) -> PyResult<Vec<BTreeMap<String, Py<PyAny>>>> {
    let mats = nucleide_mcnp_io::inp::materials_from_file(path)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    Python::attach(|py| {
        Ok(mats
            .into_iter()
            .map(|m| {
                let mut d = BTreeMap::new();
                d.insert(
                    "number".to_string(),
                    m.number.into_pyobject(py).unwrap().unbind().into_any(),
                );
                let fr: BTreeMap<String, f64> = m
                    .fractions
                    .iter()
                    .map(|(id, f)| (id.to_name(), *f))
                    .collect();
                d.insert(
                    "fractions".to_string(),
                    fr.into_pyobject(py).unwrap().unbind().into_any(),
                );
                d.insert(
                    "fraction_type".to_string(),
                    match m.fraction_type {
                        nucleide_mcnp_io::inp::FracKind::Atom => "atom",
                        nucleide_mcnp_io::inp::FracKind::Mass => "mass",
                    }
                    .into_pyobject(py)
                    .unwrap()
                    .unbind()
                    .into_any(),
                );
                d.insert(
                    "density".to_string(),
                    m.density.into_pyobject(py).unwrap().unbind().into_any(),
                );
                d.insert(
                    "comments".to_string(),
                    m.comments
                        .join(" ")
                        .into_pyobject(py)
                        .unwrap()
                        .unbind()
                        .into_any(),
                );
                d
            })
            .collect())
    })
}

fn comp_to_material(comp: BTreeMap<String, f64>) -> PyResult<nucleide_material::Material> {
    let mut mat = nucleide_material::Material::new();
    for (name, grams) in &comp {
        let id = nucleide_nuclei::NuclideId::from_name(name)
            .map_err(|e| PyValueError::new_err(format!("`{name}`: {e}")))?;
        mat.add_nuclide(id, *grams);
    }
    Ok(mat)
}

/// Expand a chemical formula into a natural-isotope composition dict
/// ({nuclide_name: atom_fraction}) using AME2020 masses + abundances.
#[pyfunction]
fn from_formula(formula: &str) -> PyResult<BTreeMap<String, f64>> {
    use nucleide_material::AbundanceProvider;
    let parsed = nucleide_material::parse_formula(formula)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    // Build a temporary element-count material then expand via abundances:
    let mut nat = Vec::new();
    for (z, count) in &parsed {
        if let Some(isotopes) = nucleide_material::NaturalAbundances.natural_isotopes(*z) {
            for (id, frac) in isotopes {
                nat.push((id, frac * count));
            }
        }
    }
    let total: f64 = nat.iter().map(|(_, c)| c).sum();
    if total <= 0.0 {
        return Err(PyValueError::new_err("empty formula expansion"));
    }
    let mut out: BTreeMap<String, f64> = BTreeMap::new();
    for (id, atoms) in nat {
        *out.entry(id.to_name()).or_insert(0.0) += atoms / total;
    }
    Ok(out)
}

/// Activity [Bq] per nuclide plus whole-material specific activity.
/// Returns {name: Bq} entries and "specific" = Bq/g of the composition.
#[pyfunction]
fn activity(comp: BTreeMap<String, f64>) -> PyResult<BTreeMap<String, f64>> {
    let mat = comp_to_material(comp)?;
    let analytics = nucleide_material::Analytics {
        masses: &nucleide_material::Ame2020,
        decays: &nucleide_material::ChainDecays,
    };
    let per_nuc = mat
        .activity(&analytics)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    let specific = mat
        .specific_activity(&analytics)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    let mut out: BTreeMap<String, f64> = per_nuc
        .into_iter()
        .map(|(id, v)| (id.to_name(), v))
        .collect();
    out.insert("specific".to_string(), specific);
    Ok(out)
}

/// Serialize a composition dictionary to a `<material>` XML fragment.
#[pyfunction]
fn to_xml(comp: BTreeMap<String, f64>, name: &str, density: f64, units: &str) -> PyResult<String> {
    let mat = comp_to_material(comp)?;
    mat.to_xml(name, density, units)
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Enrichment cascade with numeric multicomponent solving.
#[pyclass(name = "Cascade")]
struct PyCascade {
    inner: std::sync::Mutex<nucleide_enrichment::Cascade>,
}

#[pymethods]
impl PyCascade {
    /// Natural-uranium default cascade (alpha=1.05, Mstar=236, j=U235, k=U238).
    #[staticmethod]
    fn default_uranium() -> Self {
        Self {
            inner: std::sync::Mutex::new(nucleide_enrichment::default_uranium_cascade()),
        }
    }

    /// Build a cascade from full parameters. `mat_feed` is a dict of
    /// nuclide-name strings to mass fractions.
    #[new]
    #[allow(non_snake_case)]
    #[allow(clippy::too_many_arguments)]
    fn new(
        alpha: f64,
        Mstar: f64,
        j: u32,
        k: u32,
        N: f64,
        M: f64,
        x_feed_j: f64,
        x_prod_j: f64,
        x_tail_j: f64,
        mat_feed: BTreeMap<String, f64>,
    ) -> PyResult<Self> {
        let mut feed = BTreeMap::new();
        for (name, frac) in mat_feed {
            let id = NuclideId::from_name(&name).map_err(wrap_nucid_err)?;
            feed.insert(id, frac);
        }
        let casc = nucleide_enrichment::Cascade {
            alpha,
            Mstar,
            j: NuclideId::from_nucid(j),
            k: NuclideId::from_nucid(k),
            N,
            M,
            x_feed_j,
            x_prod_j,
            x_tail_j,
            mat_feed: nucleide_enrichment::Stream::with_total_mass(feed, 1.0),
            mat_prod: nucleide_enrichment::Stream::new(),
            mat_tail: nucleide_enrichment::Stream::new(),
            l_t_per_feed: 0.0,
            swu_per_feed: 0.0,
            swu_per_prod: 0.0,
        };
        Ok(Self {
            inner: std::sync::Mutex::new(casc),
        })
    }

    /// Solve via the numeric fixed-point + secant scheme in place.
    #[pyo3(signature = (tolerance=None, max_iterations=None))]
    fn solve(&self, tolerance: Option<f64>, max_iterations: Option<u32>) -> PyResult<()> {
        let tol = tolerance.unwrap_or(nucleide_enrichment::DEFAULT_TOLERANCE);
        let iters = max_iterations.unwrap_or(nucleide_enrichment::DEFAULT_MAX_ITER);
        let mut c = self
            .inner
            .lock()
            .map_err(|_| PyValueError::new_err("cascade lock poisoned"))?;
        *c = nucleide_enrichment::solve_numeric(&c, tol, iters)
            .map_err(|e| PyValueError::new_err(e.to_string()))?;
        Ok(())
    }

    /// Solve and optimize `M*` for a multicomponent feed in place.
    #[pyo3(signature = (tolerance=None, max_iterations=None))]
    fn solve_multicomponent(
        &self,
        tolerance: Option<f64>,
        max_iterations: Option<u32>,
    ) -> PyResult<()> {
        let tol = tolerance.unwrap_or(nucleide_enrichment::DEFAULT_TOLERANCE);
        let iters = max_iterations.unwrap_or(nucleide_enrichment::DEFAULT_MAX_ITER);
        let mut c = self
            .inner
            .lock()
            .map_err(|_| PyValueError::new_err("cascade lock poisoned"))?;
        *c = nucleide_enrichment::multicomponent(&c, tol, iters)
            .map_err(|e| PyValueError::new_err(e.to_string()))?;
        Ok(())
    }

    #[getter]
    fn alpha(&self) -> PyResult<f64> {
        Ok(self
            .inner
            .lock()
            .map_err(|_| PyValueError::new_err("cascade lock poisoned"))?
            .alpha)
    }
    #[getter]
    #[allow(non_snake_case)]
    fn Mstar(&self) -> PyResult<f64> {
        Ok(self
            .inner
            .lock()
            .map_err(|_| PyValueError::new_err("cascade lock poisoned"))?
            .Mstar)
    }
    #[getter]
    #[allow(non_snake_case)]
    fn N(&self) -> PyResult<f64> {
        Ok(self
            .inner
            .lock()
            .map_err(|_| PyValueError::new_err("cascade lock poisoned"))?
            .N)
    }
    #[getter]
    #[allow(non_snake_case)]
    fn M(&self) -> PyResult<f64> {
        Ok(self
            .inner
            .lock()
            .map_err(|_| PyValueError::new_err("cascade lock poisoned"))?
            .M)
    }
    #[getter]
    fn x_feed_j(&self) -> PyResult<f64> {
        Ok(self
            .inner
            .lock()
            .map_err(|_| PyValueError::new_err("cascade lock poisoned"))?
            .x_feed_j)
    }
    #[getter]
    fn x_prod_j(&self) -> PyResult<f64> {
        Ok(self
            .inner
            .lock()
            .map_err(|_| PyValueError::new_err("cascade lock poisoned"))?
            .x_prod_j)
    }
    #[getter]
    fn x_tail_j(&self) -> PyResult<f64> {
        Ok(self
            .inner
            .lock()
            .map_err(|_| PyValueError::new_err("cascade lock poisoned"))?
            .x_tail_j)
    }
    #[getter]
    fn l_t_per_feed(&self) -> PyResult<f64> {
        Ok(self
            .inner
            .lock()
            .map_err(|_| PyValueError::new_err("cascade lock poisoned"))?
            .l_t_per_feed)
    }
    #[getter]
    fn swu_per_feed(&self) -> PyResult<f64> {
        Ok(self
            .inner
            .lock()
            .map_err(|_| PyValueError::new_err("cascade lock poisoned"))?
            .swu_per_feed)
    }
    #[getter]
    fn swu_per_prod(&self) -> PyResult<f64> {
        Ok(self
            .inner
            .lock()
            .map_err(|_| PyValueError::new_err("cascade lock poisoned"))?
            .swu_per_prod)
    }
    /// Feed composition as {nuclide_name: mass_fraction}.
    #[getter]
    fn mat_feed(&self) -> PyResult<BTreeMap<String, f64>> {
        Ok(self
            .inner
            .lock()
            .map_err(|_| PyValueError::new_err("cascade lock poisoned"))?
            .mat_feed
            .comp
            .iter()
            .map(|(id, frac)| (id.to_name(), *frac))
            .collect())
    }
    /// Product composition as {nuclide_name: mass_fraction}.
    #[getter]
    fn mat_prod(&self) -> PyResult<BTreeMap<String, f64>> {
        Ok(self
            .inner
            .lock()
            .map_err(|_| PyValueError::new_err("cascade lock poisoned"))?
            .mat_prod
            .comp
            .iter()
            .map(|(id, frac)| (id.to_name(), *frac))
            .collect())
    }
    /// Tails composition as {nuclide_name: mass_fraction}.
    #[getter]
    fn mat_tail(&self) -> PyResult<BTreeMap<String, f64>> {
        Ok(self
            .inner
            .lock()
            .map_err(|_| PyValueError::new_err("cascade lock poisoned"))?
            .mat_tail
            .comp
            .iter()
            .map(|(id, frac)| (id.to_name(), *frac))
            .collect())
    }
    /// Separative work per product [kg SWU/kg] from the key assays.
    fn separative_work_per_product(&self) -> PyResult<f64> {
        let c = self
            .inner
            .lock()
            .map_err(|_| PyValueError::new_err("cascade lock poisoned"))?;
        Ok(nucleide_enrichment::swu_per_prod(
            c.x_feed_j, c.x_prod_j, c.x_tail_j,
        ))
    }

    fn __repr__(&self) -> PyResult<String> {
        let c = self
            .inner
            .lock()
            .map_err(|_| PyValueError::new_err("cascade lock poisoned"))?;
        Ok(format!(
            "Cascade(alpha={}, Mstar={}, x_prod_j={:.5})",
            c.alpha, c.Mstar, c.x_prod_j
        ))
    }
}

/// Dirac separation potential `V(x) = (2x - 1) ln(x / (1 - x))`.
///
/// Thin wrapper over `nucleide_enrichment::value_func`.
#[pyfunction]
fn enrichment_value_func(x: f64) -> f64 {
    nucleide_enrichment::value_func(x)
}

/// SWU per unit mass of feed for assays `x_feed`, `x_prod`, `x_tail`.
///
/// Thin wrapper over `nucleide_enrichment::swu_per_feed`.
#[pyfunction]
fn enrichment_swu_per_feed(x_feed: f64, x_prod: f64, x_tail: f64) -> f64 {
    nucleide_enrichment::swu_per_feed(x_feed, x_prod, x_tail)
}

/// SWU per unit mass of product for assays `x_feed`, `x_prod`, `x_tail`.
///
/// Thin wrapper over `nucleide_enrichment::swu_per_prod`.
#[pyfunction]
fn enrichment_swu_per_prod(x_feed: f64, x_prod: f64, x_tail: f64) -> f64 {
    nucleide_enrichment::swu_per_prod(x_feed, x_prod, x_tail)
}

/// SWU per unit mass of tails for assays `x_feed`, `x_prod`, `x_tail`.
///
/// Thin wrapper over `nucleide_enrichment::swu_per_tail`.
#[pyfunction]
fn enrichment_swu_per_tail(x_feed: f64, x_prod: f64, x_tail: f64) -> f64 {
    nucleide_enrichment::swu_per_tail(x_feed, x_prod, x_tail)
}

/// PNNL/DOE Materials Compendium library (411 named materials).
#[pyclass(name = "MaterialsCompendium")]
struct PyMaterialsCompendium {
    inner: nucleide_material::MaterialsLibrary,
}

#[pymethods]
impl PyMaterialsCompendium {
    /// Load from the official MaterialsCompendium.json.
    #[staticmethod]
    fn load(path: &str) -> PyResult<Self> {
        nucleide_material::MaterialsLibrary::from_file(path)
            .map(|inner| PyMaterialsCompendium { inner })
            .map_err(|e| PyValueError::new_err(e.to_string()))
    }

    fn __len__(&self) -> usize {
        self.inner.len()
    }

    /// All display names in file order.
    fn names(&self) -> Vec<String> {
        self.inner.names().into_iter().map(String::from).collect()
    }

    /// Case-insensitive lookup by name; returns
    /// {name, mat_num, density, fractions: {ZAID: weight_fraction}} or None.
    /// With as_material=True fractions are keyed by nuclide name instead.
    #[pyo3(signature = (name, as_material=false))]
    #[allow(clippy::type_complexity)]
    fn get(&self, name: &str, as_material: bool) -> PyResult<Option<BTreeMap<String, Py<PyAny>>>> {
        let entry = match self.inner.get(name) {
            Some(e) => e,
            None => return Ok(None),
        };
        // Material conversion needs no GIL; do it before attaching.
        let named_fractions = if as_material {
            Some(
                entry
                    .to_material()
                    .map_err(|e| PyValueError::new_err(e.to_string()))?,
            )
        } else {
            None
        };

        Ok(Python::attach(|py| {
            let mut d: BTreeMap<String, Py<PyAny>> = BTreeMap::new();
            d.insert(
                "name".into(),
                entry
                    .name
                    .as_str()
                    .into_pyobject(py)
                    .unwrap()
                    .unbind()
                    .into_any(),
            );
            d.insert(
                "mat_num".into(),
                entry.mat_num.into_pyobject(py).unwrap().unbind().into_any(),
            );
            d.insert(
                "density".into(),
                entry.density.into_pyobject(py).unwrap().unbind().into_any(),
            );
            match &named_fractions {
                Some(mat) => {
                    let fr: BTreeMap<String, f64> =
                        mat.comp.iter().map(|(id, g)| (id.to_name(), *g)).collect();
                    d.insert(
                        "fractions".into(),
                        fr.into_pyobject(py).unwrap().unbind().into_any(),
                    );
                }
                None => {
                    let fr = entry.weight_fractions();
                    d.insert(
                        "fractions".into(),
                        fr.into_pyobject(py).unwrap().unbind().into_any(),
                    );
                }
            }
            Some(d)
        }))
    }
}

// ---------------------------------------------------------------------------
// CCCC I/O (thin glue over `cccc-io`; no solver)
// ---------------------------------------------------------------------------

/// Parse ISOTXS text into plain Python containers.
///
/// Returns a dict with `nuclides` (list of {label, zaid, groups, total_xs}
/// in file order).
#[pyfunction]
fn isotxs_parse(py: Python<'_>, text: &str) -> PyResult<Py<PyAny>> {
    let owned = text.to_owned();
    let lib = py
        .detach(move || nucleide_cccc_io::IsotxsLib::parse(&owned))
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    Ok(isotxs_to_py(py, &lib))
}

fn isotxs_to_py(py: Python<'_>, lib: &nucleide_cccc_io::IsotxsLib) -> Py<PyAny> {
    use pyo3::types::PyDict;
    let out = PyDict::new(py);
    let nuclides: Vec<Py<PyAny>> = lib
        .nuclides
        .iter()
        .map(|n| {
            let d = PyDict::new(py);
            d.set_item("label", &n.label).ok();
            d.set_item("zaid", &n.zaid).ok();
            d.set_item("groups", n.groups).ok();
            d.set_item("total_xs", n.total_xs.clone()).ok();
            d.into_any().unbind()
        })
        .collect();
    out.set_item("nuclides", nuclides).ok();
    out.into_any().unbind()
}

/// Parse an RTFLUX/ATFLUX/RZFLUX flux file into plain containers.
///
/// `kind` selects the expected header keyword (`rtflux`|`atflux`|`rzflux`,
/// case-insensitive). Returns a dict with `kind`, `groups`, `per_point`,
/// `npoints`, `values`, and `total`.
#[pyfunction]
#[pyo3(signature = (text, kind="rtflux"))]
fn rtflux_parse(py: Python<'_>, text: &str, kind: &str) -> PyResult<Py<PyAny>> {
    let flux_kind = match kind.to_ascii_lowercase().as_str() {
        "rtflux" => nucleide_cccc_io::rtflux::FluxKind::Rtflux,
        "atflux" => nucleide_cccc_io::rtflux::FluxKind::Atflux,
        "rzflux" => nucleide_cccc_io::rtflux::FluxKind::Rzflux,
        other => {
            return Err(PyValueError::new_err(format!(
                "kind must be rtflux|atflux|rzflux, got `{other}`"
            )))
        }
    };
    let owned = text.to_owned();
    let flux = py
        .detach(move || nucleide_cccc_io::FluxFile::parse(flux_kind, &owned))
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    use pyo3::types::PyDict;
    let d = PyDict::new(py);
    d.set_item("kind", flux.kind.keyword()).ok();
    d.set_item("groups", flux.groups).ok();
    d.set_item("per_point", flux.per_point).ok();
    d.set_item("npoints", flux.npoints()).ok();
    d.set_item("values", flux.values.clone()).ok();
    d.set_item("total", flux.total()).ok();
    Ok(d.into_any().unbind())
}

fn partisn_deck_from_dict(
    deck: &Bound<'_, pyo3::types::PyDict>,
) -> PyResult<nucleide_cccc_io::PartisnDeck> {
    let title: String = match deck.get_item("title")? {
        Some(v) => v
            .extract()
            .map_err(|_| PyValueError::new_err("partisn deck `title` must be str"))?,
        None => return Err(PyValueError::new_err("partisn deck missing `title`")),
    };
    let dim: u8 = match deck.get_item("dim")? {
        Some(v) => v
            .extract()
            .map_err(|_| PyValueError::new_err("partisn deck `dim` must be 1, 2, or 3"))?,
        None => return Err(PyValueError::new_err("partisn deck missing `dim`")),
    };
    let zones_value = match deck.get_item("zones")? {
        Some(v) => v,
        None => return Err(PyValueError::new_err("partisn deck missing `zones`")),
    };
    let zone_dicts: Vec<Bound<'_, pyo3::types::PyDict>> = zones_value
        .extract()
        .map_err(|_| PyValueError::new_err("partisn deck `zones` must be a list of dicts"))?;
    let mut zones = Vec::with_capacity(zone_dicts.len());
    for z in &zone_dicts {
        let id: u32 = match z.get_item("id")? {
            Some(v) => v
                .extract()
                .map_err(|_| PyValueError::new_err("partisn zone `id` must be int"))?,
            None => return Err(PyValueError::new_err("partisn zone missing `id`")),
        };
        let material: String = match z.get_item("material")? {
            Some(v) => v
                .extract()
                .map_err(|_| PyValueError::new_err("partisn zone `material` must be str"))?,
            None => return Err(PyValueError::new_err("partisn zone missing `material`")),
        };
        let isotxs_labels: Vec<String> = match z.get_item("isotxs_labels")? {
            Some(v) => v.extract().map_err(|_| {
                PyValueError::new_err("partisn zone `isotxs_labels` must be a list of str")
            })?,
            None => {
                return Err(PyValueError::new_err(
                    "partisn zone missing `isotxs_labels`",
                ))
            }
        };
        let density: f64 = match z.get_item("density")? {
            Some(v) => v
                .extract()
                .map_err(|_| PyValueError::new_err("partisn zone `density` must be float"))?,
            None => return Err(PyValueError::new_err("partisn zone missing `density`")),
        };
        zones.push(nucleide_cccc_io::partisn::PartisnZone {
            id,
            material,
            isotxs_labels,
            density,
        });
    }
    let source: Option<String> = match deck.get_item("source")? {
        Some(v) if v.is_none() => None,
        Some(v) => Some(
            v.extract()
                .map_err(|_| PyValueError::new_err("partisn deck `source` must be str or None"))?,
        ),
        None => None,
    };
    Ok(nucleide_cccc_io::PartisnDeck {
        title,
        dim,
        zones,
        source,
    })
}

/// Render a PARTISN deck dict to PARTISN input text.
///
/// Deck shape: {title: str, dim: 1|2|3, zones: [{id, material,
/// isotxs_labels, density}], source: str | None}.
#[pyfunction]
fn partisn_render(py: Python<'_>, deck: &Bound<'_, pyo3::types::PyDict>) -> PyResult<String> {
    let rust_deck = partisn_deck_from_dict(deck)?;
    Ok(py.detach(move || rust_deck.render()))
}

/// Validate a PARTISN deck dict against ISOTXS text.
///
/// Raises `ValueError` when `dim` is not 1/2/3 or a zone names an ISOTXS
/// label absent from the library.
#[pyfunction]
fn partisn_validate(
    py: Python<'_>,
    deck: &Bound<'_, pyo3::types::PyDict>,
    isotxs_text: &str,
) -> PyResult<()> {
    let rust_deck = partisn_deck_from_dict(deck)?;
    let owned = isotxs_text.to_owned();
    let lib = py
        .detach(move || nucleide_cccc_io::IsotxsLib::parse(&owned))
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    rust_deck
        .validate(&lib)
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

// ---------------------------------------------------------------------------
// FISPACT-II output (thin glue over `fispact-io`; reuses ResponseFrame)
// ---------------------------------------------------------------------------

fn fispact_row_to_map(
    py: Python<'_>,
    r: &nucleide_alara_io::output::ResponseRow,
) -> BTreeMap<String, Py<PyAny>> {
    let mut d = BTreeMap::new();
    d.insert(
        "time_s".to_string(),
        r.time_s.into_pyobject(py).unwrap().unbind().into_any(),
    );
    d.insert(
        "time_label".to_string(),
        r.time_label
            .clone()
            .into_pyobject(py)
            .unwrap()
            .unbind()
            .into_any(),
    );
    d.insert(
        "nuclide".to_string(),
        r.nuclide
            .clone()
            .into_pyobject(py)
            .unwrap()
            .unbind()
            .into_any(),
    );
    d.insert(
        "half_life_s".to_string(),
        r.half_life_s.into_pyobject(py).unwrap().unbind().into_any(),
    );
    d.insert(
        "run_lbl".to_string(),
        r.run_lbl
            .clone()
            .into_pyobject(py)
            .unwrap()
            .unbind()
            .into_any(),
    );
    d.insert(
        "block".to_string(),
        r.block
            .as_str()
            .into_pyobject(py)
            .unwrap()
            .unbind()
            .into_any(),
    );
    d.insert(
        "block_name".to_string(),
        r.block_name
            .clone()
            .into_pyobject(py)
            .unwrap()
            .unbind()
            .into_any(),
    );
    d.insert(
        "block_num".to_string(),
        r.block_num.into_pyobject(py).unwrap().unbind().into_any(),
    );
    d.insert(
        "variable".to_string(),
        r.variable
            .as_str()
            .into_pyobject(py)
            .unwrap()
            .unbind()
            .into_any(),
    );
    d.insert(
        "var_unit".to_string(),
        r.var_unit
            .clone()
            .into_pyobject(py)
            .unwrap()
            .unbind()
            .into_any(),
    );
    d.insert(
        "value".to_string(),
        r.value.into_pyobject(py).unwrap().unbind().into_any(),
    );
    d
}

/// Parse a FISPACT-II inventory listing into a list of row dicts.
///
/// Each row carries the 11 `ResponseRow` fields as plain floats/strings/ints:
/// `time_s`, `time_label`, `nuclide`, `half_life_s`, `run_lbl`, `block`,
/// `block_name`, `block_num`, `variable`, `var_unit`, `value`.
#[pyfunction]
fn fispact_parse_output(
    py: Python<'_>,
    text: &str,
    run_lbl: &str,
) -> PyResult<Vec<BTreeMap<String, Py<PyAny>>>> {
    let owned_text = text.to_owned();
    let owned_lbl = run_lbl.to_owned();
    let rows = py
        .detach(move || {
            nucleide_fispact_io::parse_to_frame(&owned_text, &owned_lbl).map(|f| f.rows)
        })
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    Ok(rows.iter().map(|r| fispact_row_to_map(py, r)).collect())
}

/// Parse the FISPACT-II clearance block (wide `HAZARDS` + `CLEAR` inventory
/// table) into a list of row dicts.
///
/// Each row carries: `interval` (int), `time_s`, `time_label`, `cooling`
/// (bool), `nuclide` (dialect spelling, e.g. `"Co-60"`, `"Rb-86m"`), `flags`
/// (str), `activity_bq`, `clearance_index`, `half_life_s` (`-1.0` for
/// `Stable`). The grammar is the real FISPACT-II main-output inventory
/// section (see the `fispact-io` `clearance` module docs for the citable
/// on-disk source). Raises `ValueError` on malformed headers/rows.
#[pyfunction]
fn fispact_parse_clearance(
    py: Python<'_>,
    text: &str,
) -> PyResult<Vec<BTreeMap<String, Py<PyAny>>>> {
    let owned_text = text.to_owned();
    let scan = py
        .detach(move || nucleide_fispact_io::parse_clearance(&owned_text))
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    Ok(scan
        .rows
        .iter()
        .map(|row| {
            let mut d = BTreeMap::new();
            d.insert(
                "interval".to_string(),
                row.interval.into_pyobject(py).unwrap().unbind().into_any(),
            );
            d.insert(
                "time_s".to_string(),
                row.time_s.into_pyobject(py).unwrap().unbind().into_any(),
            );
            d.insert(
                "time_label".to_string(),
                row.time_label
                    .clone()
                    .into_pyobject(py)
                    .unwrap()
                    .unbind()
                    .into_any(),
            );
            d.insert(
                "cooling".to_string(),
                pyo3::types::PyBool::new(py, row.cooling)
                    .to_owned()
                    .into_any()
                    .unbind(),
            );
            d.insert(
                "nuclide".to_string(),
                row.nuclide
                    .clone()
                    .into_pyobject(py)
                    .unwrap()
                    .unbind()
                    .into_any(),
            );
            d.insert(
                "flags".to_string(),
                row.flags
                    .clone()
                    .into_pyobject(py)
                    .unwrap()
                    .unbind()
                    .into_any(),
            );
            d.insert(
                "activity_bq".to_string(),
                row.activity_bq
                    .into_pyobject(py)
                    .unwrap()
                    .unbind()
                    .into_any(),
            );
            d.insert(
                "clearance_index".to_string(),
                row.clearance_index
                    .into_pyobject(py)
                    .unwrap()
                    .unbind()
                    .into_any(),
            );
            d.insert(
                "half_life_s".to_string(),
                row.half_life_s
                    .into_pyobject(py)
                    .unwrap()
                    .unbind()
                    .into_any(),
            );
            d
        })
        .collect())
}

// ---------------------------------------------------------------------------
// ORIGEN TAPE readers (thin glue over `origen-io`; scoped TAPE5/6/9)
// ---------------------------------------------------------------------------

/// Parse ORIGEN TAPE5 input-echo text into plain containers.
///
/// Returns a dict with `titles` (list[str]), `irradiation_steps`
/// (list of {flux, days}), and `materials` (list of {name, entries:
/// [{nuclide, grams}]}).
#[pyfunction]
fn origen_parse_tape5(py: Python<'_>, text: &str) -> PyResult<Py<PyAny>> {
    let owned = text.to_owned();
    let tape = py
        .detach(move || nucleide_origen_io::Tape5::parse(&owned))
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    use pyo3::types::PyDict;
    let out = PyDict::new(py);
    out.set_item("titles", tape.titles.clone()).ok();
    let steps: Vec<Py<PyAny>> = tape
        .irradiation_steps
        .iter()
        .map(|s| {
            let d = PyDict::new(py);
            d.set_item("flux", s.flux).ok();
            d.set_item("days", s.days).ok();
            d.into_any().unbind()
        })
        .collect();
    out.set_item("irradiation_steps", steps).ok();
    let materials: Vec<Py<PyAny>> = tape
        .materials
        .iter()
        .map(|m| {
            let d = PyDict::new(py);
            d.set_item("name", &m.name).ok();
            let entries: Vec<Py<PyAny>> = m
                .grams
                .iter()
                .map(|(nuclide, grams)| {
                    let e = PyDict::new(py);
                    e.set_item("nuclide", nuclide).ok();
                    e.set_item("grams", *grams).ok();
                    e.into_any().unbind()
                })
                .collect();
            d.set_item("entries", entries).ok();
            d.into_any().unbind()
        })
        .collect();
    out.set_item("materials", materials).ok();
    Ok(out.into_any().unbind())
}

/// Parse ORIGEN TAPE6 output-inventory text into plain containers.
///
/// Returns a dict with `records` (list of {nuclide, grams, activity_bq} in
/// file order) and `total_activity` (sum over records).
#[pyfunction]
fn origen_parse_tape6(py: Python<'_>, text: &str) -> PyResult<Py<PyAny>> {
    let owned = text.to_owned();
    let tape = py
        .detach(move || nucleide_origen_io::Tape6::parse(&owned))
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    use pyo3::types::PyDict;
    let out = PyDict::new(py);
    let records: Vec<Py<PyAny>> = tape
        .records
        .iter()
        .map(|r| {
            let d = PyDict::new(py);
            d.set_item("nuclide", &r.nuclide).ok();
            d.set_item("grams", r.grams).ok();
            d.set_item("activity_bq", r.activity_bq).ok();
            d.into_any().unbind()
        })
        .collect();
    out.set_item("records", records).ok();
    out.set_item("total_activity", tape.total_activity()).ok();
    Ok(out.into_any().unbind())
}

/// Parse ORIGEN TAPE9 decay-constant text into a list of row dicts.
///
/// Each entry is {nuclide, decay_const} in file order.
#[pyfunction]
fn origen_parse_tape9(py: Python<'_>, text: &str) -> PyResult<Vec<BTreeMap<String, Py<PyAny>>>> {
    let owned = text.to_owned();
    let entries = py
        .detach(move || nucleide_origen_io::Tape9Entry::parse(&owned))
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    Ok(entries
        .iter()
        .map(|e| {
            let mut d = BTreeMap::new();
            d.insert(
                "nuclide".to_string(),
                e.nuclide
                    .clone()
                    .into_pyobject(py)
                    .unwrap()
                    .unbind()
                    .into_any(),
            );
            d.insert(
                "decay_const".to_string(),
                e.decay_const.into_pyobject(py).unwrap().unbind().into_any(),
            );
            d
        })
        .collect())
}

// ---------------------------------------------------------------------------
// R2S workflow builder (thin glue over `r2s`; no transport/activation solve)
// ---------------------------------------------------------------------------

fn r2s_workflow_to_py(py: Python<'_>, workflow: &nucleide_r2s::R2sWorkflow) -> Py<PyAny> {
    use pyo3::types::PyDict;
    let out = PyDict::new(py);
    let steps: Vec<Py<PyAny>> = workflow
        .steps
        .iter()
        .map(|s| {
            let d = PyDict::new(py);
            d.set_item("zone", &s.zone).ok();
            d.set_item("flux", &s.flux).ok();
            d.into_any().unbind()
        })
        .collect();
    out.set_item("steps", steps).ok();
    out.set_item("cooling_s", workflow.cooling_s.clone()).ok();
    out.set_item("top_schedule", &workflow.top_schedule).ok();
    out.into_any().unbind()
}

fn r2s_workflow_from_dict(
    workflow: &Bound<'_, pyo3::types::PyDict>,
) -> PyResult<nucleide_r2s::R2sWorkflow> {
    let steps_value = match workflow.get_item("steps")? {
        Some(v) => v,
        None => return Err(PyValueError::new_err("r2s workflow missing `steps`")),
    };
    let step_dicts: Vec<Bound<'_, pyo3::types::PyDict>> = steps_value
        .extract()
        .map_err(|_| PyValueError::new_err("r2s workflow `steps` must be a list of dicts"))?;
    let mut steps = Vec::with_capacity(step_dicts.len());
    for s in &step_dicts {
        let zone: String = match s.get_item("zone")? {
            Some(v) => v
                .extract()
                .map_err(|_| PyValueError::new_err("r2s step `zone` must be str"))?,
            None => return Err(PyValueError::new_err("r2s step missing `zone`")),
        };
        let flux: String = match s.get_item("flux")? {
            Some(v) => v
                .extract()
                .map_err(|_| PyValueError::new_err("r2s step `flux` must be str"))?,
            None => return Err(PyValueError::new_err("r2s step missing `flux`")),
        };
        steps.push(nucleide_r2s::R2sStep { zone, flux });
    }
    let cooling_s: Vec<f64> = match workflow.get_item("cooling_s")? {
        Some(v) => v.extract().map_err(|_| {
            PyValueError::new_err("r2s workflow `cooling_s` must be a list of float")
        })?,
        None => return Err(PyValueError::new_err("r2s workflow missing `cooling_s`")),
    };
    let top_schedule: String = match workflow.get_item("top_schedule")? {
        Some(v) => v
            .extract()
            .map_err(|_| PyValueError::new_err("r2s workflow `top_schedule` must be str"))?,
        None => return Err(PyValueError::new_err("r2s workflow missing `top_schedule`")),
    };
    Ok(nucleide_r2s::R2sWorkflow {
        steps,
        cooling_s,
        top_schedule,
    })
}

/// Derive an R2S workflow summary from an ALARA deck.
///
/// Returns a dict with `steps` (list of {zone, flux}), `cooling_s`
/// (list[float]), and `top_schedule` (str).
#[pyfunction]
fn r2s_from_deck(py: Python<'_>, deck_text: &str) -> PyResult<Py<PyAny>> {
    let owned = deck_text.to_owned();
    let workflow = py
        .detach(move || {
            let deck = nucleide_alara_io::AlaraDeck::parse(&owned)
                .map_err(|e| nucleide_r2s::Error::Invalid(e.to_string()))?;
            nucleide_r2s::R2sWorkflow::from_deck(&deck)
        })
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    Ok(r2s_workflow_to_py(py, &workflow))
}

/// Validate an R2S workflow dict against an ALARA deck.
///
/// Raises `ValueError` when a step zone/flux is unknown or cooling histories
/// are missing.
#[pyfunction]
fn r2s_validate(
    py: Python<'_>,
    workflow: &Bound<'_, pyo3::types::PyDict>,
    deck_text: &str,
) -> PyResult<()> {
    let rust_workflow = r2s_workflow_from_dict(workflow)?;
    let owned = deck_text.to_owned();
    let deck = py
        .detach(move || nucleide_alara_io::AlaraDeck::parse(&owned))
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    rust_workflow
        .validate_against(&deck)
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Expand an ALARA deck's irradiation hierarchy into flat steps via R2S.
///
/// Returns a list of {duration_s, flux, is_cooling} dicts. When `top` is
/// given it overrides the workflow's discovered top schedule.
#[pyfunction]
#[pyo3(signature = (deck_text, top=None))]
fn r2s_expand(
    py: Python<'_>,
    deck_text: &str,
    top: Option<&str>,
) -> PyResult<Vec<BTreeMap<String, Py<PyAny>>>> {
    let owned_text = deck_text.to_owned();
    let owned_top = top.map(str::to_owned);
    let steps = py
        .detach(move || {
            let deck = nucleide_alara_io::AlaraDeck::parse(&owned_text)
                .map_err(|e| nucleide_r2s::Error::Invalid(e.to_string()))?;
            let mut workflow = nucleide_r2s::R2sWorkflow::from_deck(&deck)?;
            if let Some(top) = owned_top {
                workflow.top_schedule = top;
            }
            workflow.expand(&deck, &[])
        })
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    Ok(steps
        .into_iter()
        .map(|s| {
            let mut d = BTreeMap::new();
            let cooling = s.is_cooling();
            d.insert(
                "duration_s".to_string(),
                s.duration_s.into_pyobject(py).unwrap().unbind().into_any(),
            );
            d.insert(
                "flux".to_string(),
                s.flux.into_pyobject(py).unwrap().unbind().into_any(),
            );
            d.insert(
                "is_cooling".to_string(),
                pyo3::types::PyBool::new(py, cooling)
                    .to_owned()
                    .into_any()
                    .unbind(),
            );
            d
        })
        .collect())
}

/// Assemble a uniform-split photon source summary for `zone`.
///
/// Parses an ALARA activation-output listing, sums shutdown
/// `SpecificActivity` over the zone's nuclide rows (skipping `total`
/// aggregates), and splits the total uniformly over `groups` energy groups.
/// Returns a dict with `zone`, `groups` (list[float]), and `total`.
///
/// Approximation: the uniform split preserves only the total shutdown
/// strength; real decay photons follow the nuclide- and energy-dependent
/// lines in ALARA `.photonSrc` spectra.
#[pyfunction]
fn r2s_assemble(
    py: Python<'_>,
    output_text: &str,
    run_lbl: &str,
    zone: &str,
    groups: usize,
) -> PyResult<Py<PyAny>> {
    let owned_text = output_text.to_owned();
    let owned_lbl = run_lbl.to_owned();
    let owned_zone = zone.to_owned();
    let source = py
        .detach(move || {
            let frame = nucleide_alara_io::output::ResponseFrame::parse(&owned_text, &owned_lbl)
                .map_err(|e| nucleide_r2s::Error::Invalid(e.to_string()))?;
            Ok::<_, nucleide_r2s::Error>(nucleide_r2s::photon::assemble(
                &frame,
                &owned_zone,
                groups,
            ))
        })
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    use pyo3::types::PyDict;
    let out = PyDict::new(py);
    out.set_item("zone", source.zone.clone()).ok();
    out.set_item("groups", source.groups.clone()).ok();
    out.set_item("total", source.total()).ok();
    Ok(out.into_any().unbind())
}

/// Map zone totals onto voxels (`zone_of_voxel` holds zone indices).
///
/// `totals` carries one total source strength per zone; with `split=False`
/// every voxel copies its zone total (tag-as-attribute), with `split=True`
/// each zone total is divided conservatively over its voxels. Returns a
/// dict with `n_zones`, `zone_of_voxel`, `source_strength`,
/// `decay_time_s` (all shutdown `0.0`), and `total`. Thin wrapper over
/// `nucleide-r2s` `tag_zone_totals` / `split_zone_totals`.
#[pyfunction]
#[pyo3(signature = (totals, zone_of_voxel, split=false))]
fn r2s_tag_zone_strength(
    py: Python<'_>,
    totals: Vec<f64>,
    zone_of_voxel: Vec<usize>,
    split: bool,
) -> PyResult<Py<PyAny>> {
    let zones: Vec<nucleide_r2s::photon::ZonePhotonSource> = totals
        .into_iter()
        .enumerate()
        .map(|(i, total)| {
            let groups = if total == 0.0 {
                Vec::new()
            } else {
                vec![total]
            };
            nucleide_r2s::photon::ZonePhotonSource {
                zone: format!("zone{i}"),
                groups,
            }
        })
        .collect();
    let tags = if split {
        nucleide_r2s::tags::split_zone_totals(&zones, &zone_of_voxel)
    } else {
        nucleide_r2s::tags::tag_zone_totals(&zones, &zone_of_voxel)
    }
    .map_err(|e| PyValueError::new_err(e.to_string()))?;
    use pyo3::types::PyDict;
    let out = PyDict::new(py);
    out.set_item("n_zones", tags.n_zones).ok();
    out.set_item("zone_of_voxel", tags.zone_of_voxel.clone())
        .ok();
    out.set_item("source_strength", tags.source_strength.clone())
        .ok();
    out.set_item("decay_time_s", tags.decay_time_s.clone()).ok();
    out.set_item("total", tags.total_strength()).ok();
    Ok(out.into_any().unbind())
}

/// Select and sum `.photonSrc` group spectra for `nuclides` at `time_s`.
///
/// Parses ALARA photon-source text, keeps rows matching the named nuclides
/// at exactly `time_s` seconds (shutdown `0.0`), and adds them element-wise
/// in ALARA group order. Returns a dict with `groups` (matching
/// `{nuclide, time_s, strengths}` rows), `sums`, and `total`. No rescaling:
/// strengths keep the file's normalization. Thin wrapper over
/// `nucleide-r2s` `photon_groups_at` / `sum_group_strengths`.
#[pyfunction]
fn r2s_photon_group_sums(
    py: Python<'_>,
    photon_text: &str,
    nuclides: Vec<String>,
    time_s: f64,
) -> PyResult<Py<PyAny>> {
    let source = nucleide_alara_io::photon::PhotonSource::from_str(photon_text)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    let names: Vec<&str> = nuclides.iter().map(String::as_str).collect();
    let at = nucleide_r2s::tags::photon_groups_at(&source, &names, time_s);
    let sums = nucleide_r2s::tags::sum_group_strengths(&at)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    use pyo3::types::PyDict;
    let out = PyDict::new(py);
    let rows: Vec<Py<PyAny>> = at
        .iter()
        .map(|g| {
            let d = PyDict::new(py);
            d.set_item("nuclide", g.nuclide.clone()).ok();
            d.set_item("time_s", g.time_s).ok();
            d.set_item("strengths", g.strengths.clone()).ok();
            d.into_any().unbind()
        })
        .collect();
    out.set_item("groups", rows).ok();
    out.set_item("sums", sums.clone()).ok();
    out.set_item("total", sums.iter().sum::<f64>()).ok();
    Ok(out.into_any().unbind())
}

fn snapshot_dict_str(
    zone: &Bound<'_, pyo3::types::PyDict>,
    key: &str,
    what: &str,
) -> PyResult<String> {
    match zone.get_item(key)? {
        Some(v) => v
            .extract()
            .map_err(|_| PyValueError::new_err(format!("snapshot {what} `{key}` must be str"))),
        None => Err(PyValueError::new_err(format!(
            "snapshot {what} missing `{key}`"
        ))),
    }
}

fn snapshot_dict_opt_str(
    zone: &Bound<'_, pyo3::types::PyDict>,
    key: &str,
    what: &str,
) -> PyResult<Option<String>> {
    match zone.get_item(key)? {
        Some(v) if v.is_none() => Ok(None),
        Some(v) => v
            .extract::<String>()
            .map(Some)
            .map_err(|_| PyValueError::new_err(format!("snapshot {what} `{key}` must be str"))),
        None => Ok(None),
    }
}

fn snapshot_dict_f64(
    zone: &Bound<'_, pyo3::types::PyDict>,
    key: &str,
    what: &str,
) -> PyResult<f64> {
    match zone.get_item(key)? {
        Some(v) => v
            .extract()
            .map_err(|_| PyValueError::new_err(format!("snapshot {what} `{key}` must be float"))),
        None => Err(PyValueError::new_err(format!(
            "snapshot {what} missing `{key}`"
        ))),
    }
}

fn snapshot_dict_opt_f64(
    zone: &Bound<'_, pyo3::types::PyDict>,
    key: &str,
    what: &str,
) -> PyResult<Option<f64>> {
    match zone.get_item(key)? {
        Some(v) if v.is_none() => Ok(None),
        Some(v) => v
            .extract::<f64>()
            .map(Some)
            .map_err(|_| PyValueError::new_err(format!("snapshot {what} `{key}` must be float"))),
        None => Ok(None),
    }
}

fn snapshot_zone_from_dict(
    zone: &Bound<'_, pyo3::types::PyDict>,
) -> PyResult<nucleide_r2s::snapshot::SnapshotZone> {
    let id = snapshot_dict_str(zone, "id", "zone")?;
    let volume_cm3 = snapshot_dict_f64(zone, "volume_cm3", "zone")?;
    let composition: BTreeMap<String, f64> = match zone.get_item("composition")? {
        Some(v) => v.extract().map_err(|_| {
            PyValueError::new_err("snapshot zone `composition` must be a dict of str to float")
        })?,
        None => return Err(PyValueError::new_err("snapshot zone missing `composition`")),
    };
    Ok(nucleide_r2s::snapshot::SnapshotZone {
        zone: id,
        volume_cm3,
        zbottom_cm: snapshot_dict_opt_f64(zone, "zbottom_cm", "zone")?,
        ztop_cm: snapshot_dict_opt_f64(zone, "ztop_cm", "zone")?,
        material: snapshot_dict_opt_str(zone, "material", "zone")?,
        xs_type: snapshot_dict_opt_str(zone, "xs_type", "zone")?,
        temperature_c: snapshot_dict_opt_f64(zone, "temperature_C", "zone")?,
        composition: composition.into_iter().collect(),
        flux_name: snapshot_dict_opt_str(zone, "flux", "zone")?,
    })
}

fn snapshot_input_from_dict(
    snapshot: &Bound<'_, pyo3::types::PyDict>,
) -> PyResult<nucleide_r2s::snapshot::SnapshotInput> {
    let zone_dicts: Vec<Bound<'_, pyo3::types::PyDict>> = match snapshot.get_item("zones")? {
        Some(v) => v
            .extract()
            .map_err(|_| PyValueError::new_err("snapshot `zones` must be a list of dicts"))?,
        None => return Err(PyValueError::new_err("snapshot missing `zones`")),
    };
    let mut zones = Vec::with_capacity(zone_dicts.len());
    for z in &zone_dicts {
        zones.push(snapshot_zone_from_dict(z)?);
    }
    let flux_dicts: Vec<Bound<'_, pyo3::types::PyDict>> = match snapshot.get_item("flux_defs")? {
        Some(v) => v
            .extract()
            .map_err(|_| PyValueError::new_err("snapshot `flux_defs` must be a list of dicts"))?,
        None => return Err(PyValueError::new_err("snapshot missing `flux_defs`")),
    };
    let mut flux_defs = Vec::with_capacity(flux_dicts.len());
    for f in &flux_dicts {
        flux_defs.push(nucleide_r2s::snapshot::SnapshotFluxDef {
            name: snapshot_dict_str(f, "name", "flux")?,
            file: snapshot_dict_str(f, "file", "flux")?,
            scale: snapshot_dict_f64(f, "scale", "flux")?,
        });
    }
    let cooling_s: Vec<f64> = match snapshot.get_item("cooling_s")? {
        Some(v) => v
            .extract()
            .map_err(|_| PyValueError::new_err("snapshot `cooling_s` must be a list of float"))?,
        None => return Err(PyValueError::new_err("snapshot missing `cooling_s`")),
    };
    Ok(nucleide_r2s::snapshot::SnapshotInput {
        zones,
        flux_defs,
        cooling_s,
        schedule_text: snapshot_dict_opt_str(snapshot, "schedule_text", "snapshot")?,
        output: snapshot_dict_opt_str(snapshot, "output", "snapshot")?,
    })
}

/// Total facility inventory over snapshot zones (flow accounting).
///
/// Same `snapshot` dict shape as [`r2s_from_snapshot`]; returns
/// `{ARMI-name: total atoms}` (`N × V × 1e-24` summed over zones) for
/// differencing facility snapshots. Raises `ValueError` on invalid input.
#[pyfunction]
fn r2s_snapshot_inventory(
    snapshot: &Bound<'_, pyo3::types::PyDict>,
) -> PyResult<BTreeMap<String, f64>> {
    let input = snapshot_input_from_dict(snapshot)?;
    nucleide_r2s::snapshot::snapshot_inventory(&input)
        .map(|totals| totals.into_iter().collect())
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Expand sweep axes to cartesian case bundles (WATTS-class parameter sweep).
///
/// `axes` is a list of `{name, values}` dicts; returns a list of
/// `{name, params}` dicts (`params` maps axis names to values).
/// Raises `ValueError` on empty/duplicate axes or non-finite values.
#[pyfunction]
fn r2s_expand_sweep(
    axes: Vec<BTreeMap<String, Bound<'_, pyo3::types::PyAny>>>,
) -> PyResult<Vec<BTreeMap<String, String>>> {
    use pyo3::types::PyAnyMethods;
    let mut parsed = Vec::with_capacity(axes.len());
    for axis in &axes {
        let name: String = axis
            .get("name")
            .and_then(|v| v.extract().ok())
            .ok_or_else(|| PyValueError::new_err("sweep axis needs a `name` string"))?;
        let values: Vec<f64> = axis
            .get("values")
            .and_then(|v| v.extract().ok())
            .ok_or_else(|| PyValueError::new_err("sweep axis needs a `values` float list"))?;
        parsed.push(
            nucleide_r2s::sweep::SweepAxis::new(&name, values)
                .map_err(|e| PyValueError::new_err(e.to_string()))?,
        );
    }
    let cases = nucleide_r2s::sweep::expand_sweep(&parsed)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    Ok(cases
        .into_iter()
        .map(|c| {
            let mut d = BTreeMap::new();
            d.insert("name".to_string(), c.name);
            d.insert(
                "params".to_string(),
                c.params
                    .iter()
                    .map(|(k, v)| format!("{k}={v}"))
                    .collect::<Vec<_>>()
                    .join(","),
            );
            d
        })
        .collect())
}
///
/// Build an R2S workflow bundle from a versionless ARMI DB snapshot dict.
///
/// `snapshot` mirrors `nucleide_r2s::snapshot::SnapshotInput`: `zones` (list
/// of `{id, volume_cm3, composition: {ARMI-name: ndens}}` with optional
/// `zbottom_cm`/`ztop_cm`/`material`/`xs_type`/`temperature_C`/`flux`),
/// `flux_defs` (list of `{name, file, scale}`), `cooling_s` (list[float]),
/// plus optional `schedule_text` and `output`. Returns `{workflow, deck,
/// decks}`: the workflow summary (same shape as `r2s_from_deck`), the
/// canonical template deck text, and one canonical deck text per step.
///
/// Composition keys follow the emit ARMI-input rule (post-expansion nuclide
/// keys; elemental keys, bare `AM242`, and unknown names are `ValueError`s);
/// densities are atoms/barn-cm. Empty `cooling_s` is a `ValueError` via
/// workflow validation. Raises `ValueError` on any invalid input or dangling
/// cross-reference.
#[pyfunction]
fn r2s_from_snapshot(
    py: Python<'_>,
    snapshot: &Bound<'_, pyo3::types::PyDict>,
) -> PyResult<Py<PyAny>> {
    let input = snapshot_input_from_dict(snapshot)?;
    let (workflow, template, decks) = py
        .detach(move || nucleide_r2s::snapshot::snapshot_workflow(&input))
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    use pyo3::types::PyDict;
    let out = PyDict::new(py);
    out.set_item("workflow", r2s_workflow_to_py(py, &workflow))
        .ok();
    out.set_item("deck", template.to_string()).ok();
    let deck_texts: Vec<String> = decks.iter().map(ToString::to_string).collect();
    out.set_item("decks", deck_texts).ok();
    Ok(out.into_any().unbind())
}

// ---------------------------------------------------------------------------
// 0.3.0 series driver, data accessors, list helpers
// ---------------------------------------------------------------------------
//
// Thin facade only (core tables and integrators live in `nucleide-nuclei` /
// `nucleide-material` / `nucleide-depletion`; nothing duplicated here):
//
// - `deplete_series` wraps the core `integrate` series (`predictor`/`cecm`/
//   `cf4`), omitting the core `t = 0` row so there is one output per step.
// - `simple_xs` / `scattering_length` / `decay_energy` / `decay_heat` are
//   thin wrappers over the vendored TSV tables + material analytics.
// - `MeshTally::to_list` / `totals_list` are plain-copy helpers alongside the
//   landed zero-copy NumPy bridge (`result_array()` / `totals_array()`):
//   `numpy = "0.28"` is a bindings-only
//   dependency (abi3-py310 inherited from the workspace PyO3).

/// Supported `deplete_series` integrators (core `Integrator` variants).
fn parse_integrator(name: &str) -> PyResult<nucleide_depletion::Integrator> {
    use nucleide_depletion::Integrator as I;
    if name.eq_ignore_ascii_case("predictor") {
        return Ok(I::Predictor);
    }
    if name.eq_ignore_ascii_case("cecm") {
        return Ok(I::Cecm);
    }
    if name.eq_ignore_ascii_case("cf4") {
        return Ok(I::Cf4);
    }
    Err(PyValueError::new_err(format!(
        "unsupported integrator `{name}` (supported: predictor, cecm, cf4)"
    )))
}

/// Solve a multi-step depletion series with the chosen core integrator.
///
/// Thin wrapper over `nucleide_depletion::integrate`: one [`Step`] per `dt`
/// (per-step `rates`/`rates_list`, `None` meaning decay-only), `n0` keyed by
/// nuclide name. `method` selects the solver kernel (`"cram16"`,
/// `"cram48"`, `"bateman"`, `"bateman_hp"`, default `"cram48"` — an
/// explicitly non-default `method` overrides `order`; Bateman steps with
/// live rates fall back to CRAM-48). Returns a dict with `times`
/// (cumulative seconds, one entry per step — the core `t = 0` initial row is
/// omitted so `atoms[k]` matches a single `deplete` call over `dts[k]`),
/// `atoms`, `activity` ([Bq]), and `decay_heat` ([W] per nuclide via the
/// shared chain → ENDF/B-VII.1 → 0.0 energy resolution).
#[pyfunction]
#[pyo3(signature = (chain, n0, dts, rates=None, rates_list=None, integrator="predictor", order=48, method="cram48"))]
#[allow(clippy::too_many_arguments)]
fn deplete_series(
    chain: &PyChain,
    n0: BTreeMap<String, f64>,
    dts: Vec<f64>,
    rates: Option<RateMap>,
    rates_list: Option<Vec<Option<RateMap>>>,
    integrator: &str,
    order: u8,
    method: &str,
) -> PyResult<Py<PyAny>> {
    use nucleide_depletion::{DepletionSystem, ReactionRates, Step};
    let integrator = parse_integrator(integrator)?;
    let method = resolve_method(order, method)?;
    if let Some(list) = &rates_list {
        if list.len() != dts.len() {
            return Err(PyValueError::new_err(format!(
                "rates_list has {} entries but dts has {}",
                list.len(),
                dts.len()
            )));
        }
    }
    if dts.is_empty() {
        return Err(PyValueError::new_err("dts must not be empty"));
    }
    // Atom vector in chain order; unknown names fail loudly like `deplete`.
    let mut n0_vec = vec![0.0; chain.inner.len()];
    for (name, value) in &n0 {
        let idx = chain.inner.index_of(name).ok_or_else(|| {
            PyValueError::new_err(format!("unknown nuclide `{name}` for this chain"))
        })?;
        n0_vec[idx] = *value;
    }
    let empty = BTreeMap::new();
    let mut steps = Vec::with_capacity(dts.len());
    for (i, dt) in dts.iter().enumerate() {
        let step_rates = rates_list
            .as_ref()
            .and_then(|list| list[i].as_ref())
            .or(rates.as_ref())
            .unwrap_or(&empty);
        let rs = split_rates(step_rates, &chain.inner)?;
        steps.push(Step::new(*dt, rs));
    }
    // Template system: `integrate` rebuilds the matrix per step from the
    // chain + step rates; the template's own rates are unused.
    let template = DepletionSystem::build((*chain.inner).clone(), &ReactionRates::new())
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    // NOTE: plain (GIL held) call by design, matching the other CRAM
    // bindings; batch sizes here are small.
    let series =
        nucleide_depletion::integrate_with_method(&template, &n0_vec, &steps, integrator, method)
            .map_err(|e| PyValueError::new_err(e.to_string()))?;
    let names: Vec<&str> = template
        .chain
        .nuclides
        .iter()
        .map(|nuc| nuc.name.as_str())
        .collect();
    let keyed = |rows: &[Vec<f64>]| -> Vec<BTreeMap<String, f64>> {
        rows.iter()
            .map(|row| {
                names
                    .iter()
                    .zip(row)
                    .map(|(name, v)| ((*name).to_string(), *v))
                    .collect()
            })
            .collect()
    };
    // Skip the t = 0 initial row: one output entry per requested step.
    let atoms = keyed(&series.atoms[1..]);
    let activity = keyed(&series.activity[1..]);
    let decay_heat = keyed(&series.decay_heat[1..]);
    let times = series.times[1..].to_vec();
    Ok(Python::attach(|py| {
        use pyo3::types::PyDict;
        let out = PyDict::new(py);
        out.set_item("times", &times).ok();
        out.set_item("atoms", &atoms).ok();
        out.set_item("activity", &activity).ok();
        out.set_item("decay_heat", &decay_heat).ok();
        out.into_any().unbind()
    }))
}

/// Thermal/fast cross sections [barn] for a nuclide name.
///
/// Screening-level values from the `nucleide-nuclei` table (thermal 2200 m/s
/// total + 14-MeV total); `None` for nuclides outside the table.
#[pyfunction]
fn simple_xs(name: &str) -> PyResult<Option<(f64, f64)>> {
    NuclideId::from_name(name).map_err(wrap_nucid_err)?;
    Ok(nucleide_nuclei::data::simple_xs_by_name(name))
}

/// Coherent scattering length [fm] for a nuclide name.
///
/// First element of the `nucleide-nuclei` (coherent, incoherent) pair;
/// `None` for nuclides outside the table.
#[pyfunction]
fn scattering_length(name: &str) -> PyResult<Option<f64>> {
    NuclideId::from_name(name).map_err(wrap_nucid_err)?;
    Ok(nucleide_nuclei::data::scattering_length_by_name(name).map(|(b_coh, _)| b_coh))
}

/// Mean decay energy per disintegration [MeV] for a nuclide name.
///
/// Screening-level placeholder values (NOT ENSDF); `None` when unknown.
#[pyfunction]
fn decay_energy(name: &str) -> PyResult<Option<f64>> {
    NuclideId::from_name(name).map_err(wrap_nucid_err)?;
    Ok(nucleide_nuclei::data::decay_energy_mev_by_name(name))
}

/// Evaluated decay branches for a nuclide name.
///
/// One `(progeny GNDS name, branching fraction, mode)` tuple per kept
/// ENDF/B-VIII.0 branch (SF/fission branches dropped); empty when the
/// nuclide has no branch rows (stable nuclides).
#[pyfunction]
fn decay_branches(name: &str) -> PyResult<Vec<(String, f64, String)>> {
    NuclideId::from_name(name).map_err(wrap_nucid_err)?;
    Ok(nucleide_nuclei::data::decay_branches_by_name(name)
        .unwrap_or_default()
        .into_iter()
        .map(|b| {
            (
                nucleide_nuclei::NuclideId::from_nucid(b.progeny).to_name(),
                b.branching_fraction,
                b.mode.as_str().to_string(),
            )
        })
        .collect())
}

/// Branching fraction from parent to progeny (GNDS names), if tabulated.
///
/// Evaluated ENDF/B-VIII.0 value, verbatim; `None` when the branch is
/// absent (including dropped SF branches). Named apart from the
/// chain-scoped `branching_fraction` (which takes a chain argument).
#[pyfunction]
fn decay_branch_fraction(parent: &str, progeny: &str) -> PyResult<Option<f64>> {
    NuclideId::from_name(parent).map_err(wrap_nucid_err)?;
    NuclideId::from_name(progeny).map_err(wrap_nucid_err)?;
    Ok(nucleide_nuclei::data::branching_fraction_by_name(
        parent, progeny,
    ))
}

/// Evaluated fission product yields for a nuclide name.
///
/// One `(energy_eV, [(daughter GNDS name, yield, uncertainty), ...])` tuple
/// per incident-energy set, lowest energy first; empty when the parent has
/// no evaluation for the requested `origin`/`kind`. `origin` is `n`
/// (neutron-induced, default) or `sf` (spontaneous); `kind` is
/// `independent` (MF8/MT454, default — what depletion consumes) or
/// `cumulative` (MF8/MT459). An uncertainty of `0.0` means the tape
/// evaluates none (the zero-yield rows of this sublibrary).
type PyFissionYieldSets = Vec<(f64, Vec<(String, f64, f64)>)>;

#[pyfunction]
#[pyo3(signature = (parent, origin="n", kind="independent"))]
fn fission_yields(parent: &str, origin: &str, kind: &str) -> PyResult<PyFissionYieldSets> {
    NuclideId::from_name(parent).map_err(wrap_nucid_err)?;
    let origin = nucleide_nuclei::data::FissionYieldOrigin::parse(origin).ok_or_else(|| {
        PyValueError::new_err(format!(
            "unknown fission-yield origin `{origin}` (expected `n` or `sf`)"
        ))
    })?;
    let kind = nucleide_nuclei::data::FissionYieldKind::parse(kind).ok_or_else(|| {
        PyValueError::new_err(format!(
            "unknown fission-yield kind `{kind}` (expected `independent` or `cumulative`)"
        ))
    })?;
    Ok(
        nucleide_nuclei::data::fission_yields_by_name(parent, origin, kind)
            .unwrap_or_default()
            .into_iter()
            .map(|set| {
                (
                    set.energy_ev,
                    set.products
                        .into_iter()
                        .map(|p| {
                            (
                                nucleide_nuclei::NuclideId::from_nucid(p.progeny).to_name(),
                                p.yield_fraction,
                                p.uncertainty,
                            )
                        })
                        .collect(),
                )
            })
            .collect(),
    )
}

/// Independent neutron-induced fission yield of one daughter (GNDS names).
///
/// Uses the parent's lowest-energy yield set — the OpenMC
/// `get_default_fission_yields` depletion convention. `None` when either
/// nuclide is outside the table; the uncertainty and the other energy sets
/// are available through `fission_yields`.
#[pyfunction]
fn fission_yield(parent: &str, progeny: &str) -> PyResult<Option<f64>> {
    NuclideId::from_name(parent).map_err(wrap_nucid_err)?;
    NuclideId::from_name(progeny).map_err(wrap_nucid_err)?;
    Ok(nucleide_nuclei::data::fission_yield_by_name(
        parent, progeny,
    ))
}

/// Normalize a nuclide name in any accepted dialect to canonical GNDS form.
///
/// Accepts symbol-first (`Pu241`, `Pu-241`, `Ba137m`), mass-first (`241Pu`,
/// `40K`), and isomer suffix letters (`Ir-192n` → second isomer); see
/// `nucleide_nuclei::dialects::normalize_nuclide_name`.
#[pyfunction]
fn normalize_nuclide(name: &str) -> PyResult<String> {
    Ok(nucleide_nuclei::dialects::normalize_nuclide_name(name)
        .map_err(|e| PyValueError::new_err(e.to_string()))?
        .to_name())
}

/// Decay heat [W] of a composition dict ({nuclide name: grams}).
///
/// Screening-level estimate via `Material::total_decay_heat` (Ame2020 masses,
/// ENDF/B-VIII.0 decay constants, placeholder decay energies). Stable
/// nuclides (known mass, no decay constant) contribute 0. Errors when a
/// nuclide lacks mass data, or a radioactive nuclide lacks energy data.
#[pyfunction]
fn decay_heat(comp: BTreeMap<String, f64>) -> PyResult<f64> {
    let mat = comp_to_material(comp)?;
    let analytics = nucleide_material::Analytics {
        masses: &nucleide_material::Ame2020,
        decays: &nucleide_material::ChainDecays,
    };
    mat.total_decay_heat(&analytics, &nucleide_material::DecayEnergies)
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

fn parse_dose_pathway(s: &str) -> PyResult<nucleide_material::DosePathway> {
    nucleide_material::DosePathway::parse(s).ok_or_else(|| {
        PyValueError::new_err(format!(
            "unknown dose pathway `{s}` (supported: air, soil, ingest, inhale)"
        ))
    })
}

fn parse_dose_source(s: &str) -> PyResult<nucleide_material::DoseSource> {
    nucleide_material::DoseSource::parse(s).ok_or_else(|| {
        PyValueError::new_err(format!(
            "unknown dose source `{s}` (supported: EPA, DOE, GENII)"
        ))
    })
}

/// Raw dose factor for a nuclide name, pathway, and source.
///
/// Pathway is one of `air`/`soil`/`ingest`/`inhale` (`ext_air`/`ext_soil`
/// aliases accepted); source is one of `EPA`/`DOE`/`GENII` (default `EPA`,
/// matching PyNE source id 0). Returns `None` when the nuclide has no row;
/// GENII/DOE air resolve to `-1.0` (PyNE missing-air sentinel).
#[pyfunction]
#[pyo3(signature = (name, pathway, source="EPA"))]
fn dose_factor(name: &str, pathway: &str, source: &str) -> PyResult<Option<f64>> {
    NuclideId::from_name(name).map_err(wrap_nucid_err)?;
    let p = parse_dose_pathway(pathway)?;
    let s = parse_dose_source(source)?;
    Ok(nucleide_nuclei::data::dose_factor_by_name(name, p, s))
}

fn wrap_fgr15_err(e: nucleide_nuclei::fgr15::Error) -> PyErr {
    PyValueError::new_err(e.to_string())
}

/// Parse one EPA FGR 15 `Table_4_*.DAT` member (table text) into a dict.
///
/// Thin wrapper over `nucleide_nuclei::fgr15::parse_table`. Returns
/// `{"scenario": str, "units": str, "coefficients": {name: [6 floats]}}`
/// with coefficient lists in canonical age order (newborn, 1-yr, 5-yr,
/// 10-yr, 15-yr, adult) and nuclide names in FGR 15 spelling (`H-3`,
/// `Ba-137m`, `Sb-124n`). `expected_rows` is the exact nuclide-row count the
/// table must hold (1,252 for the published EPA tables); structural
/// problems, malformed rows, duplicates, and row-count mismatches are loud
/// errors. Screening-level only — not for safety decisions.
#[pyfunction]
#[pyo3(signature = (text, expected_rows))]
fn parse_fgr15_table<'py>(
    py: Python<'py>,
    text: &str,
    expected_rows: usize,
) -> PyResult<pyo3::Bound<'py, pyo3::types::PyDict>> {
    let table = nucleide_nuclei::fgr15::parse_table(text, expected_rows).map_err(wrap_fgr15_err)?;
    let out = pyo3::types::PyDict::new(py);
    out.set_item("scenario", table.scenario().as_str())?;
    out.set_item("units", table.units())?;
    let coefficients = pyo3::types::PyDict::new(py);
    for (nucid, row) in table.iter() {
        coefficients.set_item(
            nucleide_nuclei::fgr15::name_of(NuclideId::from_nucid(nucid)),
            row.to_vec(),
        )?;
    }
    out.set_item("coefficients", coefficients)?;
    Ok(out)
}

/// Column index (0-5) of an EPA FGR 15 age group.
///
/// Accepts `newborn`/`adult`, bare years (`1`, `5`, `10`, `15`), and
/// spelled variants (`1yr`, `1-yr`, `1-yr-old`, ...). Raises `ValueError`
/// for anything else.
#[pyfunction]
fn fgr15_age_index(age: &str) -> PyResult<usize> {
    nucleide_nuclei::fgr15::Fgr15Age::parse(age)
        .map(|a| a.index())
        .ok_or_else(|| {
            PyValueError::new_err(format!(
                "unknown FGR 15 age group `{age}` (supported: newborn, 1, 5, 10, 15, adult)"
            ))
        })
}

/// Total dose per gram of a composition dict ({nuclide name: grams}).
///
/// Thin wrapper over `Material::total_dose_per_g` (Ame2020 masses,
/// ENDF/B-VIII.0 decay constants, HNF-5636/PyNE dose factors). Pathway is one
/// of `air`/`soil`/`ingest`/`inhale`; source is `EPA`/`DOE`/`GENII` (default
/// `EPA`). Units follow the table: air `mrem/h per g per m^3`, soil
/// `mrem/h per g per m^2`, ingest/inhale `mrem per g`. Screening-level only —
/// not for safety decisions. Stable nuclides (known mass, no decay constant)
/// contribute 0 without a dose-factor lookup. Errors when a nuclide lacks
/// mass data, or a radioactive nuclide lacks dose data (including `-1`
/// GENII/DOE air sentinels).
#[pyfunction]
#[pyo3(signature = (comp, pathway, source="EPA"))]
fn dose_per_g(comp: BTreeMap<String, f64>, pathway: &str, source: &str) -> PyResult<f64> {
    let mat = comp_to_material(comp)?;
    let analytics = nucleide_material::Analytics {
        masses: &nucleide_material::Ame2020,
        decays: &nucleide_material::ChainDecays,
    };
    let p = parse_dose_pathway(pathway)?;
    let s = parse_dose_source(source)?;
    mat.total_dose_per_g(&analytics, &nucleide_material::DoseFactors, p, s)
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Split a composition dict into product and tails dicts by per-nuclide
/// separation efficiency.
///
/// `comp` maps nuclide names to grams; `effs` maps nuclide names to
/// efficiencies in `[0, 1]` (unlisted nuclides go entirely to tails).
/// Returns `(product, tails)` with per-nuclide mass conserved. Thin wrapper
/// over `Material::separate`.
#[pyfunction]
#[allow(clippy::type_complexity)]
fn separate_material(
    comp: BTreeMap<String, f64>,
    effs: BTreeMap<String, f64>,
) -> PyResult<(BTreeMap<String, f64>, BTreeMap<String, f64>)> {
    let mat = comp_to_material(comp)?;
    let mut table = Vec::with_capacity(effs.len());
    for (name, eff) in &effs {
        let id = NuclideId::from_name(name)
            .map_err(|e| PyValueError::new_err(format!("`{name}`: {e}")))?;
        table.push((id, *eff));
    }
    let (product, tails) = mat
        .separate(&table)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    let named =
        |m: nucleide_material::Material| m.comp.iter().map(|(id, g)| (id.to_name(), *g)).collect();
    Ok((named(product), named(tails)))
}

/// Blend composition dicts at fixed ratios with explicit normalization.
///
/// `parts` holds `(comp, ratio)` pairs; ratios are normalized by their sum
/// and the output is the weighted average. Errors on empty, all-zero, or
/// negative ratios (never a silent uniform split). Thin wrapper over
/// `Material::blend`.
#[pyfunction]
fn blend_material(parts: Vec<(BTreeMap<String, f64>, f64)>) -> PyResult<BTreeMap<String, f64>> {
    let mats: Vec<nucleide_material::Material> = parts
        .iter()
        .map(|(comp, _)| comp_to_material(comp.clone()))
        .collect::<PyResult<_>>()?;
    let refs: Vec<(&nucleide_material::Material, f64)> =
        mats.iter().zip(parts.iter().map(|(_, r)| *r)).collect();
    let out = nucleide_material::Material::blend(&refs)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    Ok(out.comp.iter().map(|(id, g)| (id.to_name(), *g)).collect())
}

/// One-sided upper Page CUSUM change detector with Welford statistics.
///
/// Thin stateful wrapper over `nucleide_material::Cusum`: `update(x)`
/// feeds one observation and returns the alarm status; `status()` reads it
/// without consuming input; `statistic()` reads the CUSUM value;
/// `reset()` drops all observations (tuning kept). Non-finite inputs to
/// `update` are ignored.
#[pyclass(name = "Cusum")]
struct PyCusum {
    inner: nucleide_material::Cusum,
}

#[pymethods]
impl PyCusum {
    /// Build a detector (`ref_shift_k = 0.5`, `alarm_h = 4.0`,
    /// `startup = 10` by default).
    #[new]
    #[pyo3(signature = (ref_shift_k=0.5, alarm_h=4.0, startup=10))]
    fn new(ref_shift_k: f64, alarm_h: f64, startup: usize) -> PyResult<Self> {
        nucleide_material::Cusum::new(ref_shift_k, alarm_h, startup)
            .map(|inner| Self { inner })
            .map_err(|e| PyValueError::new_err(e.to_string()))
    }

    /// Feed one observation; returns the resulting alarm status.
    fn update(&mut self, x: f64) -> bool {
        self.inner.update(x)
    }

    /// Whether the detector is currently alarmed.
    fn status(&self) -> bool {
        self.inner.status()
    }

    /// Current CUSUM statistic (`>= 0`).
    fn statistic(&self) -> f64 {
        self.inner.statistic()
    }

    /// Running observation count.
    fn count(&self) -> usize {
        self.inner.count()
    }

    /// Running mean of the observations seen so far.
    fn mean(&self) -> f64 {
        self.inner.mean()
    }

    /// Running sample variance (`0` with fewer than 2 points).
    fn variance(&self) -> f64 {
        self.inner.variance()
    }

    /// Running sample standard deviation.
    fn std(&self) -> f64 {
        self.inner.std()
    }

    /// Drop all observations; tuning parameters are kept.
    fn reset(&mut self) {
        self.inner.reset();
    }
}

// ---------------------------------------------------------------------------
// 0.3.0 Tier 1: deck round-trip, decay inventories, ARMI dialects, checks
// ---------------------------------------------------------------------------

/// A parsed MCNP input deck with format-preserving write-back.
#[pyclass(name = "DeckProblem")]
struct PyDeckProblem {
    inner: std::sync::Mutex<nucleide_mcnp_io::problem::DeckProblem>,
}

fn deck_cell_dict(cell: &nucleide_mcnp_io::cell::CellCard) -> BTreeMap<String, String> {
    let mut d = BTreeMap::new();
    d.insert("num".to_string(), cell.num.to_string());
    d.insert("mat".to_string(), cell.mat.to_string());
    d.insert(
        "dens".to_string(),
        cell.dens.map(|v| v.to_string()).unwrap_or_default(),
    );
    d.insert("geom".to_string(), cell.geom.render());
    d.insert("params".to_string(), cell.params.join(" "));
    d
}

#[pymethods]
impl PyDeckProblem {
    /// Parse a deck from text.
    #[staticmethod]
    fn loads(text: &str) -> PyResult<Self> {
        nucleide_mcnp_io::problem::parse_deck(text)
            .map(|inner| Self {
                inner: std::sync::Mutex::new(inner),
            })
            .map_err(|e| PyValueError::new_err(e.to_string()))
    }

    /// Message (first) line.
    #[getter]
    fn message(&self) -> PyResult<String> {
        Ok(self
            .inner
            .lock()
            .map_err(|_| PyValueError::new_err("deck lock poisoned"))?
            .message
            .clone())
    }

    /// Title card (second line).
    #[getter]
    fn title(&self) -> PyResult<String> {
        Ok(self
            .inner
            .lock()
            .map_err(|_| PyValueError::new_err("deck lock poisoned"))?
            .title
            .clone())
    }

    /// Cell cards as `{num, mat, dens, geom, params}` dicts (`dens` is `""`
    /// for void cells).
    #[getter]
    fn cells(&self) -> PyResult<Vec<BTreeMap<String, String>>> {
        Ok(self
            .inner
            .lock()
            .map_err(|_| PyValueError::new_err("deck lock poisoned"))?
            .cells
            .iter()
            .map(deck_cell_dict)
            .collect())
    }

    /// Surface cards as `{num, reflecting, transform, periodic, kind, coeffs}`
    /// dicts (`transform`/`periodic` are `""` when absent).
    #[getter]
    fn surfs(&self) -> PyResult<Vec<BTreeMap<String, String>>> {
        Ok(self
            .inner
            .lock()
            .map_err(|_| PyValueError::new_err("deck lock poisoned"))?
            .surfs
            .iter()
            .map(|s| {
                let mut d = BTreeMap::new();
                d.insert("num".to_string(), s.num.to_string());
                d.insert("reflecting".to_string(), s.reflecting.to_string());
                d.insert(
                    "transform".to_string(),
                    s.transform.map(|v| v.to_string()).unwrap_or_default(),
                );
                d.insert(
                    "periodic".to_string(),
                    s.periodic.map(|v| v.to_string()).unwrap_or_default(),
                );
                d.insert("kind".to_string(), s.kind.keyword().to_string());
                d.insert(
                    "coeffs".to_string(),
                    s.coeffs
                        .iter()
                        .map(|v| v.to_string())
                        .collect::<Vec<_>>()
                        .join(" "),
                );
                d
            })
            .collect())
    }

    /// Material numbers in file order.
    #[getter]
    fn material_numbers(&self) -> PyResult<Vec<u32>> {
        Ok(self
            .inner
            .lock()
            .map_err(|_| PyValueError::new_err("deck lock poisoned"))?
            .materials
            .iter()
            .map(|m| m.number)
            .collect())
    }

    /// Data-card names in file order (`MODE`, `M1`, `KCODE`, ...).
    #[getter]
    fn data_names(&self) -> PyResult<Vec<String>> {
        Ok(self
            .inner
            .lock()
            .map_err(|_| PyValueError::new_err("deck lock poisoned"))?
            .data
            .iter()
            .map(|d| d.name.clone())
            .collect())
    }

    /// Serialize back to MCNP input text (byte-identical when unedited).
    fn dumps(&self) -> PyResult<String> {
        let guard = self
            .inner
            .lock()
            .map_err(|_| PyValueError::new_err("deck lock poisoned"))?;
        Ok(nucleide_mcnp_io::problem::write_deck(&guard))
    }

    /// Set a cell's density (re-renders that card canonically).
    fn set_cell_density(&self, cell: u32, dens: f64) -> PyResult<()> {
        self.inner
            .lock()
            .map_err(|_| PyValueError::new_err("deck lock poisoned"))?
            .set_cell_density(cell, dens)
            .map_err(|e| PyValueError::new_err(e.to_string()))
    }

    /// Set a cell's material number (re-renders that card canonically).
    fn set_cell_material(&self, cell: u32, mat: u32) -> PyResult<()> {
        self.inner
            .lock()
            .map_err(|_| PyValueError::new_err("deck lock poisoned"))?
            .set_cell_material(cell, mat)
            .map_err(|e| PyValueError::new_err(e.to_string()))
    }

    /// Typed `MODE` card as `{particles}` (`particles` is space-joined).
    #[getter]
    fn mode(&self) -> PyResult<BTreeMap<String, String>> {
        let mode = self
            .inner
            .lock()
            .map_err(|_| PyValueError::new_err("deck lock poisoned"))?
            .mode()
            .map_err(|e| PyValueError::new_err(e.to_string()))?;
        let mut d = BTreeMap::new();
        d.insert("particles".to_string(), mode.particles.join(" "));
        Ok(d)
    }

    /// Typed `TRn` cards as `{number, displacement, rotation, in_degrees,
    /// main_to_aux, hidden}` dicts (vectors are space-joined).
    #[getter]
    fn transforms(&self) -> PyResult<Vec<BTreeMap<String, String>>> {
        let transforms = self
            .inner
            .lock()
            .map_err(|_| PyValueError::new_err("deck lock poisoned"))?
            .transforms()
            .map_err(|e| PyValueError::new_err(e.to_string()))?;
        Ok(transforms
            .iter()
            .map(|t| {
                let mut d = BTreeMap::new();
                d.insert("number".to_string(), t.number.to_string());
                d.insert(
                    "displacement".to_string(),
                    t.displacement
                        .iter()
                        .map(|v| v.to_string())
                        .collect::<Vec<_>>()
                        .join(" "),
                );
                d.insert(
                    "rotation".to_string(),
                    t.rotation
                        .iter()
                        .map(|v| v.to_string())
                        .collect::<Vec<_>>()
                        .join(" "),
                );
                d.insert("in_degrees".to_string(), t.is_in_degrees.to_string());
                d.insert("main_to_aux".to_string(), t.is_main_to_aux.to_string());
                d.insert("hidden".to_string(), t.hidden.to_string());
                d
            })
            .collect())
    }

    /// Auto-created universes as `{number, cells, not_truncated}` dicts
    /// (cell lists are space-joined).
    #[getter]
    fn universes(&self) -> PyResult<Vec<BTreeMap<String, String>>> {
        let universes = self
            .inner
            .lock()
            .map_err(|_| PyValueError::new_err("deck lock poisoned"))?
            .universes()
            .map_err(|e| PyValueError::new_err(e.to_string()))?;
        Ok(universes
            .iter()
            .map(|u| {
                let mut d = BTreeMap::new();
                d.insert("number".to_string(), u.number.to_string());
                d.insert(
                    "cells".to_string(),
                    u.cells
                        .iter()
                        .map(|v| v.to_string())
                        .collect::<Vec<_>>()
                        .join(" "),
                );
                d.insert(
                    "not_truncated".to_string(),
                    u.not_truncated
                        .iter()
                        .map(|v| v.to_string())
                        .collect::<Vec<_>>()
                        .join(" "),
                );
                d
            })
            .collect())
    }

    /// Cell `LAT` assignments as `{cell, lattice}` dicts.
    #[getter]
    fn lattices(&self) -> PyResult<Vec<BTreeMap<String, String>>> {
        let lattices = self
            .inner
            .lock()
            .map_err(|_| PyValueError::new_err("deck lock poisoned"))?
            .lattices()
            .map_err(|e| PyValueError::new_err(e.to_string()))?;
        Ok(lattices
            .iter()
            .map(|l| {
                let mut d = BTreeMap::new();
                d.insert("cell".to_string(), l.cell.to_string());
                d.insert("lattice".to_string(), l.lattice.to_string());
                d
            })
            .collect())
    }

    /// Cell `FILL` assignments as `{cell, kind, universe, min_index,
    /// max_index, universes, transform, hidden_transform, in_degrees}` dicts
    /// (`kind` is `single` or `matrix`; matrix empties render as `-`).
    #[getter]
    fn fills(&self) -> PyResult<Vec<BTreeMap<String, String>>> {
        use nucleide_mcnp_io::semantic::{FillTarget, FillTransform};
        let fills = self
            .inner
            .lock()
            .map_err(|_| PyValueError::new_err("deck lock poisoned"))?
            .fills()
            .map_err(|e| PyValueError::new_err(e.to_string()))?;
        Ok(fills
            .iter()
            .map(|f| {
                let mut d = BTreeMap::new();
                d.insert("cell".to_string(), f.cell.to_string());
                match &f.target {
                    FillTarget::Single(u) => {
                        d.insert("kind".to_string(), "single".to_string());
                        d.insert("universe".to_string(), u.to_string());
                        d.insert("min_index".to_string(), String::new());
                        d.insert("max_index".to_string(), String::new());
                        d.insert("universes".to_string(), String::new());
                    }
                    FillTarget::Matrix {
                        min_index,
                        max_index,
                        universes,
                    } => {
                        d.insert("kind".to_string(), "matrix".to_string());
                        d.insert("universe".to_string(), String::new());
                        d.insert(
                            "min_index".to_string(),
                            min_index
                                .iter()
                                .map(|v| v.to_string())
                                .collect::<Vec<_>>()
                                .join(" "),
                        );
                        d.insert(
                            "max_index".to_string(),
                            max_index
                                .iter()
                                .map(|v| v.to_string())
                                .collect::<Vec<_>>()
                                .join(" "),
                        );
                        d.insert(
                            "universes".to_string(),
                            universes
                                .iter()
                                .map(|u| {
                                    u.map(|v| v.to_string()).unwrap_or_else(|| "-".to_string())
                                })
                                .collect::<Vec<_>>()
                                .join(" "),
                        );
                    }
                }
                match &f.transform {
                    None => {
                        d.insert("transform".to_string(), String::new());
                        d.insert("hidden_transform".to_string(), String::new());
                    }
                    Some(FillTransform::Reference(n)) => {
                        d.insert("transform".to_string(), n.to_string());
                        d.insert("hidden_transform".to_string(), String::new());
                    }
                    Some(FillTransform::Hidden(t)) => {
                        d.insert("transform".to_string(), String::new());
                        let mut coords: Vec<String> =
                            t.displacement.iter().map(|v| v.to_string()).collect();
                        coords.extend(t.rotation.iter().map(|v| v.to_string()));
                        d.insert("hidden_transform".to_string(), coords.join(" "));
                    }
                }
                d.insert("in_degrees".to_string(), f.in_degrees.to_string());
                d
            })
            .collect())
    }

    /// Cell importance entries as `{cell, particle, value}` dicts.
    #[getter]
    fn importances(&self) -> PyResult<Vec<BTreeMap<String, String>>> {
        let importances = self
            .inner
            .lock()
            .map_err(|_| PyValueError::new_err("deck lock poisoned"))?
            .importances()
            .map_err(|e| PyValueError::new_err(e.to_string()))?;
        Ok(importances
            .iter()
            .map(|v| {
                let mut d = BTreeMap::new();
                d.insert("cell".to_string(), v.cell.to_string());
                d.insert("particle".to_string(), v.particle.clone());
                d.insert("value".to_string(), v.value.to_string());
                d
            })
            .collect())
    }

    /// Manual cell volumes as `{cell, volume}` dicts.
    #[getter]
    fn volumes(&self) -> PyResult<Vec<BTreeMap<String, String>>> {
        let volumes = self
            .inner
            .lock()
            .map_err(|_| PyValueError::new_err("deck lock poisoned"))?
            .volumes()
            .map_err(|e| PyValueError::new_err(e.to_string()))?;
        Ok(volumes
            .iter()
            .map(|v| {
                let mut d = BTreeMap::new();
                d.insert("cell".to_string(), v.cell.to_string());
                d.insert("volume".to_string(), v.volume.to_string());
                d
            })
            .collect())
    }

    /// Typed tallies as `{number, type, particles, entries, fm, e_bins}` dicts
    /// (lists are space-joined, absent groups are `""`).
    #[getter]
    fn tallies(&self) -> PyResult<Vec<BTreeMap<String, String>>> {
        let tallies = self
            .inner
            .lock()
            .map_err(|_| PyValueError::new_err("deck lock poisoned"))?
            .tallies()
            .map_err(|e| PyValueError::new_err(e.to_string()))?;
        Ok(tallies
            .iter()
            .map(|t| {
                let mut d = BTreeMap::new();
                d.insert("number".to_string(), t.number.to_string());
                d.insert("type".to_string(), t.tally_type.to_string());
                d.insert("particles".to_string(), t.particles.join(","));
                d.insert("entries".to_string(), t.entries.join(" "));
                d.insert("fm".to_string(), t.fm.clone().unwrap_or_default().join(" "));
                d.insert(
                    "e_bins".to_string(),
                    t.e_bins.clone().unwrap_or_default().join(" "),
                );
                d
            })
            .collect())
    }

    /// Typed `SDEF` fixed-source card as a dict (`None` when the deck has no
    /// `SDEF` card). See [`parse_sdef`] for the dict shape.
    #[getter]
    fn sdef(&self, py: Python<'_>) -> PyResult<Option<Py<PyAny>>> {
        let guard = self
            .inner
            .lock()
            .map_err(|_| PyValueError::new_err("deck lock poisoned"))?;
        let sdef = guard
            .sdef()
            .map_err(|e| PyValueError::new_err(e.to_string()))?;
        sdef.map(|s| sdef_to_py(py, &s)).transpose()
    }

    /// Validate every L3 semantic rule (duplicate numbers, dangling links,
    /// redundant definitions, write-time state, lattice/fill cross-checks).
    fn validate(&self) -> PyResult<()> {
        self.inner
            .lock()
            .map_err(|_| PyValueError::new_err("deck lock poisoned"))?
            .validate()
            .map_err(|e| PyValueError::new_err(e.to_string()))
    }

    /// Non-fatal validation notes (particle/mode mismatches).
    fn validation_notes(&self) -> PyResult<Vec<String>> {
        Ok(self
            .inner
            .lock()
            .map_err(|_| PyValueError::new_err("deck lock poisoned"))?
            .validation_notes())
    }

    /// Set the `MODE` card particles (re-renders that card canonically).
    fn set_mode(&self, particles: Vec<String>) -> PyResult<()> {
        self.inner
            .lock()
            .map_err(|_| PyValueError::new_err("deck lock poisoned"))?
            .set_mode(particles)
            .map_err(|e| PyValueError::new_err(e.to_string()))
    }

    /// Set a cell's universe (`not_truncated` writes `U=-n`).
    fn set_cell_universe(&self, cell: u32, universe: u32, not_truncated: bool) -> PyResult<()> {
        self.inner
            .lock()
            .map_err(|_| PyValueError::new_err("deck lock poisoned"))?
            .set_cell_universe(cell, universe, not_truncated)
            .map_err(|e| PyValueError::new_err(e.to_string()))
    }

    /// Set (`1`/`2`) or clear (`None`) a cell's lattice.
    fn set_cell_lattice(&self, cell: u32, lattice: Option<u8>) -> PyResult<()> {
        self.inner
            .lock()
            .map_err(|_| PyValueError::new_err("deck lock poisoned"))?
            .set_cell_lattice(cell, lattice)
            .map_err(|e| PyValueError::new_err(e.to_string()))
    }

    /// Set a cell's fill to a single universe.
    fn set_cell_fill(&self, cell: u32, universe: u32) -> PyResult<()> {
        self.inner
            .lock()
            .map_err(|_| PyValueError::new_err("deck lock poisoned"))?
            .set_cell_fill(cell, universe)
            .map_err(|e| PyValueError::new_err(e.to_string()))
    }
}

/// Parse an MCNP input deck file into a [`PyDeckProblem`].
#[pyfunction]
fn read_deck(path: &str) -> PyResult<PyDeckProblem> {
    nucleide_mcnp_io::problem::parse_deck_file(path)
        .map(|inner| PyDeckProblem {
            inner: std::sync::Mutex::new(inner),
        })
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Parse MCNP input deck text into a [`PyDeckProblem`].
#[pyfunction]
fn parse_deck(text: &str) -> PyResult<PyDeckProblem> {
    PyDeckProblem::loads(text)
}

/// Render a typed `SDEF` source as a Python dict.
///
/// Shape: `{pos, cell, surf, vec, dir, erg, nrm, par, wgt, tme}` (canonical
/// strings, `""` when absent; `Dn` references render as `D<n>`),
/// `ignored` (verbatim out-of-subset keyword tokens), `distributions`
/// (`[{number, si_option, si, sp_option, sp, sb_option, sb}]`, value lists
/// space-joined, absent `SPn`/`SBn` groups render as `""`), and `card` (the
/// canonical re-emission, so `parse_sdef(d["card"])["card"] == d["card"]`).
fn sdef_to_py(py: Python<'_>, sdef: &nucleide_mcnp_io::sdef::SdefProblem) -> PyResult<Py<PyAny>> {
    use pyo3::types::PyDict;
    let opt3 = |v: &Option<nucleide_mcnp_io::sdef::SdefRef<[f64; 3]>>| {
        v.as_ref().map(|r| r.render()).unwrap_or_default()
    };
    let opt1 = |v: &Option<nucleide_mcnp_io::sdef::SdefRef<f64>>| {
        v.as_ref().map(|r| r.render()).unwrap_or_default()
    };
    let optu = |v: &Option<nucleide_mcnp_io::sdef::SdefRef<u32>>| {
        v.as_ref().map(|r| r.render()).unwrap_or_default()
    };
    let d = PyDict::new(py);
    d.set_item("pos", opt3(&sdef.card.pos))?;
    d.set_item("cell", optu(&sdef.card.cell))?;
    d.set_item("surf", optu(&sdef.card.surf))?;
    d.set_item("vec", opt3(&sdef.card.vec))?;
    d.set_item("dir", opt1(&sdef.card.dir))?;
    d.set_item("axs", opt3(&sdef.card.axs))?;
    d.set_item("rad", opt1(&sdef.card.rad))?;
    d.set_item("ext", opt1(&sdef.card.ext))?;
    d.set_item("erg", opt1(&sdef.card.erg))?;
    d.set_item("nrm", opt1(&sdef.card.nrm))?;
    d.set_item(
        "par",
        sdef.card
            .par
            .as_ref()
            .map(|r| r.render())
            .unwrap_or_default(),
    )?;
    d.set_item("wgt", opt1(&sdef.card.wgt))?;
    d.set_item("tme", opt1(&sdef.card.tme))?;
    d.set_item("ignored", sdef.card.ignored.clone())?;
    let dists: Vec<Py<PyAny>> = sdef
        .dists
        .iter()
        .map(|dist| {
            let m = PyDict::new(py);
            m.set_item("number", dist.number.to_string())?;
            m.set_item("si_option", "L")?;
            m.set_item("si", dist.si_text())?;
            m.set_item(
                "sp_option",
                dist.sp.as_ref().map(|_| "D").unwrap_or_default(),
            )?;
            m.set_item("sp", dist.sp_text())?;
            m.set_item(
                "sb_option",
                dist.sb.as_ref().map(|_| "D").unwrap_or_default(),
            )?;
            m.set_item("sb", dist.sb_text())?;
            Ok(m.into_any().unbind())
        })
        .collect::<PyResult<Vec<_>>>()?;
    d.set_item("distributions", dists)?;
    d.set_item("card", sdef.emit())?;
    Ok(d.into_any().unbind())
}

/// Parse standalone `SDEF` card text (plus `SI`/`SP`/`SB` cards, e.g. the
/// decay-source emitter's output) into the [`sdef_to_py`] dict shape.
/// Raises `ValueError` when no `SDEF` card is present or any validation rule
/// fails (duplicate cards, non-discrete distribution forms, dangling `Dn`
/// references, orphan `SPn`/`SBn` cards, entry-count mismatches).
#[pyfunction]
fn parse_sdef(py: Python<'_>, text: &str) -> PyResult<Py<PyAny>> {
    let sdef = nucleide_mcnp_io::sdef::parse_sdef_text(text)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    sdef_to_py(py, &sdef)
}

/// Translate one deck's CSG to OpenMC `geometry.xml`.
///
/// Returns `(xml, drift)` where `drift` is `[{scope, target, action,
/// reason}]` (all strings; `target` is the cell/surface number, `"0"` for
/// deck scope). Scoped v1: surfaces, cells, and a material stub only;
/// transforms, universes, tallies, and sources raise `ValueError`.
fn csg_to_openmc_inner(
    deck: &nucleide_mcnp_io::problem::DeckProblem,
) -> PyResult<(String, Vec<BTreeMap<String, String>>)> {
    let (xml, table) = nucleide_csg_xlate::deck_csg_to_openmc_xml(deck)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    Ok((
        xml,
        table
            .entries
            .into_iter()
            .map(|e| {
                let mut d = BTreeMap::new();
                d.insert("scope".to_string(), e.scope.to_string());
                d.insert("target".to_string(), e.target.to_string());
                d.insert("action".to_string(), e.action);
                d.insert("reason".to_string(), e.reason);
                d
            })
            .collect(),
    ))
}

/// Translate MCNP deck text to OpenMC `geometry.xml` plus drift report.
/// See [`csg_to_openmc_inner`].
#[pyfunction]
fn parse_csg_to_openmc(text: &str) -> PyResult<(String, Vec<BTreeMap<String, String>>)> {
    let deck = nucleide_mcnp_io::problem::parse_deck(text)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    csg_to_openmc_inner(&deck)
}

/// Translate an MCNP deck file to OpenMC `geometry.xml` plus drift report.
/// See [`csg_to_openmc_inner`].
#[pyfunction]
fn read_csg_to_openmc(path: &str) -> PyResult<(String, Vec<BTreeMap<String, String>>)> {
    let deck = nucleide_mcnp_io::problem::parse_deck_file(path)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    csg_to_openmc_inner(&deck)
}

/// Translate one deck's CSG to Serpent input (`surf`/`cell` cards).
///
/// Returns `(text, drift)` with the same drift shape as
/// [`csg_to_openmc_inner`]. Same v2 scope (surfaces, cells, nested
/// universes, material-name stub); reflecting and periodic boundaries
/// raise `ValueError` (no verified Serpent mapping).
fn csg_to_serpent_inner(
    deck: &nucleide_mcnp_io::problem::DeckProblem,
) -> PyResult<(String, Vec<BTreeMap<String, String>>)> {
    let (text, table) = nucleide_csg_xlate::deck_csg_to_serpent_input(deck)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    Ok((
        text,
        table
            .entries
            .into_iter()
            .map(|e| {
                let mut d = BTreeMap::new();
                d.insert("scope".to_string(), e.scope.to_string());
                d.insert("target".to_string(), e.target.to_string());
                d.insert("action".to_string(), e.action);
                d.insert("reason".to_string(), e.reason);
                d
            })
            .collect(),
    ))
}

/// Translate MCNP deck text to Serpent input plus drift report.
/// See [`csg_to_serpent_inner`].
#[pyfunction]
fn parse_csg_to_serpent(text: &str) -> PyResult<(String, Vec<BTreeMap<String, String>>)> {
    let deck = nucleide_mcnp_io::problem::parse_deck(text)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    csg_to_serpent_inner(&deck)
}

/// Translate an MCNP deck file to Serpent input plus drift report.
/// See [`csg_to_serpent_inner`].
#[pyfunction]
fn read_csg_to_serpent(path: &str) -> PyResult<(String, Vec<BTreeMap<String, String>>)> {
    let deck = nucleide_mcnp_io::problem::parse_deck_file(path)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    csg_to_serpent_inner(&deck)
}

/// Translate one deck's CSG to PHITS `[Surface]`/`[Cell]` sections.
///
/// Returns `(text, drift)` with the same drift shape as
/// [`csg_to_openmc_inner`]. Same v2 scope with PHITS-native spellings
/// (verbatim surface symbols, native `#` complement, `U=`/`FILL=` params,
/// `*` reflective surfaces, outer-void `-1` heuristic); periodic pointers
/// raise `ValueError` (no PHITS spelling).
fn csg_to_phits_inner(
    deck: &nucleide_mcnp_io::problem::DeckProblem,
) -> PyResult<(String, Vec<BTreeMap<String, String>>)> {
    let (text, table) = nucleide_csg_xlate::deck_csg_to_phits_input(deck)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    Ok((
        text,
        table
            .entries
            .into_iter()
            .map(|e| {
                let mut d = BTreeMap::new();
                d.insert("scope".to_string(), e.scope.to_string());
                d.insert("target".to_string(), e.target.to_string());
                d.insert("action".to_string(), e.action);
                d.insert("reason".to_string(), e.reason);
                d
            })
            .collect(),
    ))
}

/// Translate MCNP deck text to PHITS sections plus drift report.
/// See [`csg_to_phits_inner`].
#[pyfunction]
fn parse_csg_to_phits(text: &str) -> PyResult<(String, Vec<BTreeMap<String, String>>)> {
    let deck = nucleide_mcnp_io::problem::parse_deck(text)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    csg_to_phits_inner(&deck)
}

/// Translate an MCNP deck file to PHITS sections plus drift report.
/// See [`csg_to_phits_inner`].
#[pyfunction]
fn read_csg_to_phits(path: &str) -> PyResult<(String, Vec<BTreeMap<String, String>>)> {
    let deck = nucleide_mcnp_io::problem::parse_deck_file(path)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    csg_to_phits_inner(&deck)
}

/// Translate one deck's CSG to a GDML (Geant4) document.
///
/// Returns `(xml, drift)` with the same drift shape as
/// [`csg_to_openmc_inner`]. Same v3 scope: surfaces, cells, nested
/// universes (as `<assembly>` volumes), rectangular `LAT=1` lattices
/// (expanded to per-element placements), and `mat_<n>` material stubs the
/// caller replaces; reflecting and periodic boundaries raise `ValueError`
/// (no GDML spelling).
fn csg_to_gdml_inner(
    deck: &nucleide_mcnp_io::problem::DeckProblem,
) -> PyResult<(String, Vec<BTreeMap<String, String>>)> {
    let (xml, table) = nucleide_csg_xlate::deck_csg_to_gdml(deck)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    Ok((
        xml,
        table
            .entries
            .into_iter()
            .map(|e| {
                let mut d = BTreeMap::new();
                d.insert("scope".to_string(), e.scope.to_string());
                d.insert("target".to_string(), e.target.to_string());
                d.insert("action".to_string(), e.action);
                d.insert("reason".to_string(), e.reason);
                d
            })
            .collect(),
    ))
}

/// Translate MCNP deck text to a GDML document plus drift report.
/// See [`csg_to_gdml_inner`].
#[pyfunction]
fn parse_csg_to_gdml(text: &str) -> PyResult<(String, Vec<BTreeMap<String, String>>)> {
    let deck = nucleide_mcnp_io::problem::parse_deck(text)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    csg_to_gdml_inner(&deck)
}

/// Translate an MCNP deck file to a GDML document plus drift report.
/// See [`csg_to_gdml_inner`].
#[pyfunction]
fn read_csg_to_gdml(path: &str) -> PyResult<(String, Vec<BTreeMap<String, String>>)> {
    let deck = nucleide_mcnp_io::problem::parse_deck_file(path)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    csg_to_gdml_inner(&deck)
}

/// A unit-aware decay inventory over a depletion chain.
#[pyclass(name = "Inventory")]
struct PyInventory {
    chain: std::sync::Arc<nucleide_depletion::Chain>,
    atoms: BTreeMap<String, f64>,
}

fn inventory_sys(
    chain: &nucleide_depletion::Chain,
    rates: &RateMap,
) -> PyResult<nucleide_depletion::DepletionSystem> {
    let rs = split_rates(rates, chain)?;
    nucleide_depletion::DepletionSystem::build(chain.clone(), &rs)
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

fn parse_quantity_unit(unit: &str) -> PyResult<nucleide_depletion::QuantityUnit> {
    nucleide_depletion::QuantityUnit::from_str(unit)
        .map_err(|e| PyValueError::new_err(format!("{e:?}")))
}

#[pymethods]
impl PyInventory {
    /// Build from quantities in `units` (atom counts, `Bq`/`Ci` activity,
    /// `g`/`kg` mass, `mol`, ... — see `QuantityUnit`).
    #[new]
    #[pyo3(signature = (chain, comp, units="atoms"))]
    fn new(chain: &PyChain, comp: BTreeMap<String, f64>, units: &str) -> PyResult<Self> {
        let unit = parse_quantity_unit(units)?;
        let sys = inventory_sys(&chain.inner, &BTreeMap::new())?;
        let inv = nucleide_depletion::DecayInventory::from_units(&comp, unit, &sys)
            .map_err(|e| PyValueError::new_err(e.to_string()))?;
        Ok(Self {
            chain: chain.inner.clone(),
            atoms: inv.atoms,
        })
    }

    /// Atom counts by nuclide name.
    fn numbers(&self) -> BTreeMap<String, f64> {
        self.atoms.clone()
    }

    /// Decay over `dt` in `time_unit` (`s`, `m`, `h`, `d`, `y`); optional
    /// one-group `rates` (`"Name:reaction"` keys), CRAM `order`, and solver
    /// `method` (`"cram16"`, `"cram48"`, `"bateman"`, `"bateman_hp"`,
    /// default `"cram48"` — an explicitly non-default `method` overrides
    /// `order`). Unlike the decay-only core inventory, this honors `rates`;
    /// a Bateman `method` with live rates falls back to CRAM-48.
    #[pyo3(signature = (dt, time_unit="s", rates=None, order=48, method="cram48"))]
    fn decay(
        &self,
        dt: f64,
        time_unit: &str,
        rates: Option<RateMap>,
        order: u8,
        method: &str,
    ) -> PyResult<Self> {
        let method = resolve_method(order, method)?;
        let unit = nucleide_depletion::inventory::time_unit_from_str(time_unit)
            .map_err(|e| PyValueError::new_err(e.to_string()))?;
        let seconds = dt * unit.as_seconds();
        let empty = BTreeMap::new();
        let step_rates = rates.as_ref().unwrap_or(&empty);
        let template = inventory_sys(&self.chain, step_rates)?;
        // Route through the core series: predictor over one step equals the
        // single-kernel solve, and rates/method stay honored.
        let steps = vec![nucleide_depletion::Step::new(
            seconds,
            split_rates(step_rates, &self.chain)?,
        )];
        let series = nucleide_depletion::integrate_with_method(
            &template,
            &chain_vec(&self.chain, &self.atoms)?,
            &steps,
            nucleide_depletion::Integrator::Predictor,
            method,
        )
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
        let names: Vec<String> = self.chain.nuclides.iter().map(|n| n.name.clone()).collect();
        let atoms = names
            .iter()
            .zip(series.atoms.last().cloned().unwrap_or_default())
            .map(|(n, v)| (n.clone(), v))
            .collect();
        Ok(Self {
            chain: self.chain.clone(),
            atoms,
        })
    }

    /// Activity per nuclide in `units`.
    fn activities(&self, units: &str) -> PyResult<BTreeMap<String, f64>> {
        let unit = parse_quantity_unit(units)?;
        let sys = inventory_sys(&self.chain, &BTreeMap::new())?;
        let inv = nucleide_depletion::DecayInventory {
            atoms: self.atoms.clone(),
        };
        inv.activities(&sys, unit)
            .map_err(|e| PyValueError::new_err(e.to_string()))
    }

    /// Mass per nuclide in `units`.
    fn masses(&self, units: &str) -> PyResult<BTreeMap<String, f64>> {
        let unit = parse_quantity_unit(units)?;
        let inv = nucleide_depletion::DecayInventory {
            atoms: self.atoms.clone(),
        };
        inv.masses(unit)
            .map_err(|e| PyValueError::new_err(e.to_string()))
    }

    /// Moles per nuclide in `units`.
    fn moles(&self, units: &str) -> PyResult<BTreeMap<String, f64>> {
        let unit = parse_quantity_unit(units)?;
        let inv = nucleide_depletion::DecayInventory {
            atoms: self.atoms.clone(),
        };
        inv.moles(unit)
            .map_err(|e| PyValueError::new_err(e.to_string()))
    }

    /// Activity fractions by nuclide name.
    fn activity_fractions(&self) -> PyResult<BTreeMap<String, f64>> {
        let sys = inventory_sys(&self.chain, &BTreeMap::new())?;
        let inv = nucleide_depletion::DecayInventory {
            atoms: self.atoms.clone(),
        };
        inv.activity_fractions(&sys)
            .map_err(|e| PyValueError::new_err(e.to_string()))
    }

    /// Mass fractions by nuclide name.
    fn mass_fractions(&self) -> PyResult<BTreeMap<String, f64>> {
        let inv = nucleide_depletion::DecayInventory {
            atoms: self.atoms.clone(),
        };
        inv.mass_fractions()
            .map_err(|e| PyValueError::new_err(e.to_string()))
    }

    /// Mole fractions by nuclide name.
    fn mole_fractions(&self) -> BTreeMap<String, f64> {
        nucleide_depletion::DecayInventory {
            atoms: self.atoms.clone(),
        }
        .mole_fractions()
    }

    /// Human-readable half-lives (`"3.2 d"`, `"stable"`, `"unknown"`).
    fn half_lives_readable(&self) -> BTreeMap<String, String> {
        nucleide_depletion::DecayInventory {
            atoms: self.atoms.clone(),
        }
        .half_lives_readable()
    }

    /// Add two inventories (atom counts sum).
    fn add(&self, other: &Self) -> Self {
        let a = nucleide_depletion::DecayInventory {
            atoms: self.atoms.clone(),
        };
        let b = nucleide_depletion::DecayInventory {
            atoms: other.atoms.clone(),
        };
        Self {
            chain: self.chain.clone(),
            atoms: a.add(&b).atoms,
        }
    }

    /// Subtract (clamped at zero).
    fn sub(&self, other: &Self) -> Self {
        let a = nucleide_depletion::DecayInventory {
            atoms: self.atoms.clone(),
        };
        let b = nucleide_depletion::DecayInventory {
            atoms: other.atoms.clone(),
        };
        Self {
            chain: self.chain.clone(),
            atoms: a.sub(&b).atoms,
        }
    }

    /// Scale by a scalar.
    fn mul(&self, scalar: f64) -> Self {
        let a = nucleide_depletion::DecayInventory {
            atoms: self.atoms.clone(),
        };
        Self {
            chain: self.chain.clone(),
            atoms: a.mul(scalar).atoms,
        }
    }

    /// Divide by a scalar.
    fn div(&self, scalar: f64) -> Self {
        let a = nucleide_depletion::DecayInventory {
            atoms: self.atoms.clone(),
        };
        Self {
            chain: self.chain.clone(),
            atoms: a.div(scalar).atoms,
        }
    }

    /// Serialize as `nuclide,atoms` CSV rows.
    fn to_csv(&self) -> String {
        nucleide_depletion::DecayInventory {
            atoms: self.atoms.clone(),
        }
        .to_csv()
    }

    /// Parse `to_csv` output back into an inventory over `chain`.
    #[staticmethod]
    fn from_csv(chain: &PyChain, text: &str) -> PyResult<Self> {
        // Validate names against the chain (core from_csv is chain-free).
        let inv = nucleide_depletion::DecayInventory::from_csv(text)
            .map_err(|e| PyValueError::new_err(e.to_string()))?;
        for name in inv.atoms.keys() {
            if chain.inner.index_of(name).is_none() {
                return Err(PyValueError::new_err(format!(
                    "unknown nuclide `{name}` for this chain"
                )));
            }
        }
        Ok(Self {
            chain: chain.inner.clone(),
            atoms: inv.atoms,
        })
    }
}

/// Atom vector in chain order for an inventory map (unknown names error).
fn chain_vec(
    chain: &nucleide_depletion::Chain,
    atoms: &BTreeMap<String, f64>,
) -> PyResult<Vec<f64>> {
    let mut vec = vec![0.0; chain.len()];
    for (name, value) in atoms {
        let idx = chain.index_of(name).ok_or_else(|| {
            PyValueError::new_err(format!("unknown nuclide `{name}` for this chain"))
        })?;
        vec[idx] = *value;
    }
    Ok(vec)
}

/// Time-integrated decays per nuclide over one step (chain order → names).
#[pyfunction]
#[pyo3(signature = (chain, n0, dt, rates=None))]
fn cumulative_decays(
    chain: &PyChain,
    n0: BTreeMap<String, f64>,
    dt: f64,
    rates: Option<RateMap>,
) -> PyResult<BTreeMap<String, f64>> {
    let empty = BTreeMap::new();
    let sys = inventory_sys(&chain.inner, rates.as_ref().unwrap_or(&empty))?;
    let vec = chain_vec(&chain.inner, &n0)?;
    let out = nucleide_depletion::cumulative_decays(&sys, &vec, dt)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    Ok(chain
        .inner
        .nuclides
        .iter()
        .zip(out)
        .map(|(nuc, v)| (nuc.name.clone(), v))
        .collect())
}

/// `(child, branching_ratio, decay_mode)` triples for a chain nuclide.
#[pyfunction]
fn progeny(chain: &PyChain, name: &str) -> Vec<(String, f64, String)> {
    nucleide_depletion::progeny(&chain.inner, name)
}

/// Branching fraction from parent to child, if the decay exists.
#[pyfunction]
fn branching_fraction(chain: &PyChain, parent: &str, child: &str) -> Option<f64> {
    nucleide_depletion::branching_fraction(&chain.inner, parent, child)
}

/// Decay-mode label from parent to child, if the decay exists.
#[pyfunction]
fn decay_mode(chain: &PyChain, parent: &str, child: &str) -> Option<String> {
    nucleide_depletion::decay_mode(&chain.inner, parent, child)
}

/// `(parent, child, branching_ratio, decay_mode)` edges of a chain.
#[pyfunction]
fn chain_edges(chain: &PyChain) -> Vec<(String, String, f64, String)> {
    nucleide_depletion::chain_edges(&chain.inner)
}

/// Parse an ARMI nuclide label (`nU235`, `92235`, ...) into a [`PyNuclide`].
#[pyfunction]
fn armi_to_nucid(name: &str) -> PyResult<PyNuclide> {
    nucleide_nuclei::armi::armi_name_to_nucid(name)
        .map(|inner| PyNuclide { inner })
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Render a nuclide in ARMI database-label form.
#[pyfunction]
fn nucid_to_armi(nuclide: &PyNuclide) -> String {
    nucleide_nuclei::armi::nucid_to_armi_label(nuclide.inner)
}

/// Parse an MCC3-style nuclide label into a [`PyNuclide`].
#[pyfunction]
fn mcc3_to_nucid(name: &str) -> PyResult<PyNuclide> {
    nucleide_nuclei::armi::mcc3_to_nucid(name)
        .map(|inner| PyNuclide { inner })
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Truncated-label collisions in a composition at DIF3D/MC2 widths.
///
/// `comp` maps nuclide names to grams; `widths` defaults to `[6, 8]`.
/// Returns `[{truncated, width, members}]`.
#[pyfunction]
#[pyo3(signature = (comp, widths=None))]
fn check_labels(
    comp: BTreeMap<String, f64>,
    widths: Option<Vec<usize>>,
) -> PyResult<Vec<BTreeMap<String, Py<PyAny>>>> {
    let mat = comp_to_material(comp)?;
    let widths = widths.unwrap_or_else(|| nucleide_material::DEFAULT_WIDTHS.to_vec());
    let collisions = nucleide_material::check_labels(&mat, &widths);
    Python::attach(|py| {
        Ok(collisions
            .into_iter()
            .map(|c| {
                let mut d = BTreeMap::new();
                d.insert(
                    "truncated".to_string(),
                    c.truncated.into_pyobject(py).unwrap().unbind().into_any(),
                );
                d.insert(
                    "width".to_string(),
                    c.width.into_pyobject(py).unwrap().unbind().into_any(),
                );
                let members: Vec<String> = c.members.iter().map(|id| id.to_name()).collect();
                d.insert(
                    "members".to_string(),
                    members.into_pyobject(py).unwrap().unbind().into_any(),
                );
                d
            })
            .collect())
    })
}

/// Conservation audit of a composition: `[{kind, detail}]` (empty = clean).
#[pyfunction]
fn audit_material(comp: BTreeMap<String, f64>) -> PyResult<Vec<BTreeMap<String, String>>> {
    let mat = comp_to_material(comp)?;
    Ok(nucleide_material::audit(&mat, &nucleide_material::Ame2020)
        .into_iter()
        .map(|issue| {
            let mut d = BTreeMap::new();
            d.insert("kind".to_string(), format!("{:?}", issue.kind));
            d.insert("detail".to_string(), issue.detail);
            d
        })
        .collect())
}

/// Emit one composition through all five code dialects (MCNP, Serpent, FLUKA,
/// ALARA, PARTISN). Returns `{code: card_text}`.
///
/// `comp` maps nuclide names to grams; `density` is mass density [g/cm³] for
/// dialects that need one (falls back to none — Serpent/FLUKA/PARTISN error
/// without it).
#[pyfunction]
#[pyo3(signature = (comp, name, density=None, mcnp_number=1, xs_suffix="80c", serpent_lib="03c", fluka_fid=1, partisn_zone=1))]
#[allow(clippy::too_many_arguments)]
fn emit_cards(
    comp: BTreeMap<String, f64>,
    name: &str,
    density: Option<f64>,
    mcnp_number: u32,
    xs_suffix: &str,
    serpent_lib: &str,
    fluka_fid: u32,
    partisn_zone: u32,
) -> PyResult<BTreeMap<String, String>> {
    let (emitted, _) = emit_drift_inner(
        comp,
        name,
        density,
        mcnp_number,
        xs_suffix,
        serpent_lib,
        fluka_fid,
        partisn_zone,
    )?;
    Ok(emitted
        .into_iter()
        .map(|e| (e.code.to_string(), e.text))
        .collect())
}

/// Mass-drift report for one composition across all five code dialects.
/// Returns `[{code, mass_in, mass_out, rel_drift, dropped: [{nuclide, mass,
/// reason}], reparsed}]`.
#[pyfunction]
#[pyo3(signature = (comp, name, density=None, mcnp_number=1, xs_suffix="80c", serpent_lib="03c", fluka_fid=1, partisn_zone=1))]
#[allow(clippy::too_many_arguments)]
fn emit_drift_table(
    comp: BTreeMap<String, f64>,
    name: &str,
    density: Option<f64>,
    mcnp_number: u32,
    xs_suffix: &str,
    serpent_lib: &str,
    fluka_fid: u32,
    partisn_zone: u32,
) -> PyResult<Vec<BTreeMap<String, Py<PyAny>>>> {
    let (_, table) = emit_drift_inner(
        comp,
        name,
        density,
        mcnp_number,
        xs_suffix,
        serpent_lib,
        fluka_fid,
        partisn_zone,
    )?;
    drift_table_to_py(table)
}

fn drift_table_to_py(
    table: nucleide_emit::DriftTable,
) -> PyResult<Vec<BTreeMap<String, Py<PyAny>>>> {
    Python::attach(|py| {
        Ok(table
            .rows
            .into_iter()
            .map(|r| {
                let mut d = BTreeMap::new();
                d.insert(
                    "code".to_string(),
                    r.code
                        .to_string()
                        .into_pyobject(py)
                        .unwrap()
                        .unbind()
                        .into_any(),
                );
                d.insert(
                    "mass_in".to_string(),
                    r.mass_in.into_pyobject(py).unwrap().unbind().into_any(),
                );
                d.insert(
                    "mass_out".to_string(),
                    r.mass_out.into_pyobject(py).unwrap().unbind().into_any(),
                );
                d.insert(
                    "rel_drift".to_string(),
                    r.rel_drift.into_pyobject(py).unwrap().unbind().into_any(),
                );
                let dropped: Vec<BTreeMap<String, Py<PyAny>>> = r
                    .dropped
                    .into_iter()
                    .map(|x| {
                        let mut dd = BTreeMap::new();
                        dd.insert(
                            "nuclide".to_string(),
                            x.id.to_name()
                                .into_pyobject(py)
                                .unwrap()
                                .unbind()
                                .into_any(),
                        );
                        dd.insert(
                            "mass".to_string(),
                            x.mass.into_pyobject(py).unwrap().unbind().into_any(),
                        );
                        dd.insert(
                            "reason".to_string(),
                            x.reason.into_pyobject(py).unwrap().unbind().into_any(),
                        );
                        dd
                    })
                    .collect();
                d.insert(
                    "dropped".to_string(),
                    dropped.into_pyobject(py).unwrap().unbind().into_any(),
                );
                d.insert(
                    "reparsed".to_string(),
                    pyo3::types::PyBool::new(py, r.reparsed)
                        .to_owned()
                        .into_any()
                        .unbind(),
                );
                d
            })
            .collect())
    })
}

#[allow(clippy::too_many_arguments)]
fn emit_drift_inner(
    comp: BTreeMap<String, f64>,
    name: &str,
    density: Option<f64>,
    mcnp_number: u32,
    xs_suffix: &str,
    serpent_lib: &str,
    fluka_fid: u32,
    partisn_zone: u32,
) -> PyResult<(Vec<nucleide_emit::Emitted>, nucleide_emit::DriftTable)> {
    let mut mat = comp_to_material(comp)?;
    mat.set_density(density);
    emit_drift_with_mat(
        mat,
        name,
        mcnp_number,
        xs_suffix,
        serpent_lib,
        fluka_fid,
        partisn_zone,
    )
}

#[allow(clippy::too_many_arguments)]
fn emit_drift_with_mat(
    mat: nucleide_material::Material,
    name: &str,
    mcnp_number: u32,
    xs_suffix: &str,
    serpent_lib: &str,
    fluka_fid: u32,
    partisn_zone: u32,
) -> PyResult<(Vec<nucleide_emit::Emitted>, nucleide_emit::DriftTable)> {
    let mut opts = nucleide_emit::EmitOptions::new(name);
    opts.mcnp_number = mcnp_number;
    opts.xs_suffix = xs_suffix.to_string();
    opts.serpent_lib = serpent_lib.to_string();
    opts.fluka_fid = fluka_fid;
    opts.partisn_zone = partisn_zone;
    nucleide_emit::emit_drift(&mat, &opts).map_err(|e| PyValueError::new_err(e.to_string()))
}

#[allow(clippy::too_many_arguments)]
fn emit_armi_drift_inner(
    comp: BTreeMap<String, f64>,
    name: &str,
    density: Option<f64>,
    mcnp_number: u32,
    xs_suffix: &str,
    serpent_lib: &str,
    fluka_fid: u32,
    partisn_zone: u32,
) -> PyResult<(Vec<nucleide_emit::Emitted>, nucleide_emit::DriftTable)> {
    // `from_armi_mass_fracs` sets the density exactly like `emit_drift_inner`
    // (`set_density(density)`), so the material is emission-ready here.
    let mat = nucleide_emit::armi::from_armi_mass_fracs(comp, density)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    emit_drift_with_mat(
        mat,
        name,
        mcnp_number,
        xs_suffix,
        serpent_lib,
        fluka_fid,
        partisn_zone,
    )
}

/// Emit one ARMI-keyed composition through all five code dialects (MCNP,
/// Serpent, FLUKA, ALARA, PARTISN). Returns `{code: card_text}`.
///
/// `comp` maps ARMI nuclide keys (`nU235`, `92235`, `U-2355`, ...) to grams;
/// keys resolve via `nucleide_emit::armi::from_armi_mass_fracs` (elemental
/// keys, bare `AM242`, and negative/non-finite masses are `ValueError`s).
/// `density` is the hot mass density [g/cm³] for dialects that need one.
#[pyfunction]
#[pyo3(signature = (comp, name, density=None, mcnp_number=1, xs_suffix="80c", serpent_lib="03c", fluka_fid=1, partisn_zone=1))]
#[allow(clippy::too_many_arguments)]
fn emit_armi_cards(
    comp: BTreeMap<String, f64>,
    name: &str,
    density: Option<f64>,
    mcnp_number: u32,
    xs_suffix: &str,
    serpent_lib: &str,
    fluka_fid: u32,
    partisn_zone: u32,
) -> PyResult<BTreeMap<String, String>> {
    let (emitted, _) = emit_armi_drift_inner(
        comp,
        name,
        density,
        mcnp_number,
        xs_suffix,
        serpent_lib,
        fluka_fid,
        partisn_zone,
    )?;
    Ok(emitted
        .into_iter()
        .map(|e| (e.code.to_string(), e.text))
        .collect())
}

/// Mass-drift report for one ARMI-keyed composition across all five code
/// dialects. Returns `[{code, mass_in, mass_out, rel_drift, dropped:
/// [{nuclide, mass, reason}], reparsed}]`.
#[pyfunction]
#[pyo3(signature = (comp, name, density=None, mcnp_number=1, xs_suffix="80c", serpent_lib="03c", fluka_fid=1, partisn_zone=1))]
#[allow(clippy::too_many_arguments)]
fn emit_armi_drift_table(
    comp: BTreeMap<String, f64>,
    name: &str,
    density: Option<f64>,
    mcnp_number: u32,
    xs_suffix: &str,
    serpent_lib: &str,
    fluka_fid: u32,
    partisn_zone: u32,
) -> PyResult<Vec<BTreeMap<String, Py<PyAny>>>> {
    let (_, table) = emit_armi_drift_inner(
        comp,
        name,
        density,
        mcnp_number,
        xs_suffix,
        serpent_lib,
        fluka_fid,
        partisn_zone,
    )?;
    drift_table_to_py(table)
}

// ---------------------------------------------------------------------------
// Point kinetics (thin glue over `nucleide-kinetics`; solver stays in core)
// ---------------------------------------------------------------------------

/// Parse a reactivity-spec dict into the core [`Reactivity`].
///
/// `kind` selects the schedule (`"constant"`, `"step"`, `"impulse"`,
/// `"ramp"`, `"polyline"`); all reactivities are in Δk and all times in
/// seconds. Keys per kind: constant (`rho`); step (`t_step`, `rho_init`,
/// `rho_final`); impulse (`t_start`, `t_end`, `rho_init`, `rho_max`); ramp
/// (`t_start`, `t_end`, `rho_init`, `rho_rise`, `rho_final`); polyline
/// (`times`, `values`).
fn parse_reactivity(
    spec: &BTreeMap<String, Py<PyAny>>,
    py: Python<'_>,
) -> PyResult<nucleide_kinetics::Reactivity> {
    use nucleide_kinetics::Reactivity as R;
    let kind: String = get_str(spec, py, "kind", "reactivity spec needs a `kind`")?;
    let num = |key: &str| -> PyResult<f64> { get_num(spec, py, key) };
    let vec = |key: &str| -> PyResult<Vec<f64>> { get_vec(spec, py, key) };
    let r = match kind.as_str() {
        "constant" => R::Constant { rho: num("rho")? },
        "step" => R::Step {
            t_step: num("t_step")?,
            rho_init: num("rho_init")?,
            rho_final: num("rho_final")?,
        },
        "impulse" => R::Impulse {
            t_start: num("t_start")?,
            t_end: num("t_end")?,
            rho_init: num("rho_init")?,
            rho_max: num("rho_max")?,
        },
        "ramp" => R::Ramp {
            t_start: num("t_start")?,
            t_end: num("t_end")?,
            rho_init: num("rho_init")?,
            rho_rise: num("rho_rise")?,
            rho_final: num("rho_final")?,
        },
        "polyline" => R::Polyline {
            times: vec("times")?,
            values: vec("values")?,
        },
        other => {
            return Err(PyValueError::new_err(format!(
                "unknown reactivity kind `{other}` (supported: constant, step, impulse, ramp, polyline)"
            )))
        }
    };
    r.validate()
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    Ok(r)
}

fn get_str(
    spec: &BTreeMap<String, Py<PyAny>>,
    py: Python<'_>,
    key: &str,
    missing: &str,
) -> PyResult<String> {
    spec.get(key)
        .ok_or_else(|| PyValueError::new_err(missing.to_string()))?
        .extract::<String>(py)
        .map_err(|_| PyValueError::new_err(format!("`{key}` must be a string")))
}

fn get_num(spec: &BTreeMap<String, Py<PyAny>>, py: Python<'_>, key: &str) -> PyResult<f64> {
    spec.get(key)
        .ok_or_else(|| PyValueError::new_err(format!("reactivity spec missing `{key}`")))?
        .extract::<f64>(py)
        .map_err(|_| PyValueError::new_err(format!("`{key}` must be a number")))
}

fn get_vec(spec: &BTreeMap<String, Py<PyAny>>, py: Python<'_>, key: &str) -> PyResult<Vec<f64>> {
    spec.get(key)
        .ok_or_else(|| PyValueError::new_err(format!("reactivity spec missing `{key}`")))?
        .extract::<Vec<f64>>(py)
        .map_err(|_| PyValueError::new_err(format!("`{key}` must be a list of numbers")))
}

fn kinetics_params(
    betas: Vec<f64>,
    lambdas: Vec<f64>,
    lambda_gen: f64,
) -> PyResult<nucleide_kinetics::KineticParams> {
    nucleide_kinetics::KineticParams::new(betas, lambdas, lambda_gen)
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Solve a prescribed-reactivity point-kinetics transient.
///
/// Thin wrapper over `nucleide_kinetics::solve`: `betas`/`lambdas`/`Lambda`
/// carry the delayed-neutron data (see `KineticParams::from_ifp` for the
/// OpenMC provenance note — decay constants are caller-supplied), `rho` is
/// a spec dict (see `parse_reactivity`), `t` the output grid in seconds,
/// `n0` the initial neutron level, `C0` the optional initial precursors
/// (defaults to equilibrium). `method` is `"trapezoidal"` (default) or
/// `"backward_euler"`. Returns a dict with `times`, `n`, `C`
/// (`[time][group]`), and the echo of the initial state (`n0`, `C0`).
#[pyfunction]
#[pyo3(signature = (betas, lambdas, lambda_gen, rho, t, n0, c0=None, method="trapezoidal", rtol=1e-9, atol=1e-12, dt_min=1e-14, dt_max=None, max_steps=1000000))]
#[allow(clippy::too_many_arguments)]
fn kinetics_solve(
    py: Python<'_>,
    betas: Vec<f64>,
    lambdas: Vec<f64>,
    lambda_gen: f64,
    rho: BTreeMap<String, Py<PyAny>>,
    t: Vec<f64>,
    n0: f64,
    c0: Option<Vec<f64>>,
    method: &str,
    rtol: f64,
    atol: f64,
    dt_min: f64,
    dt_max: Option<f64>,
    max_steps: usize,
) -> PyResult<Py<PyAny>> {
    use nucleide_kinetics::{Method as M, SolverOptions};
    let params = kinetics_params(betas, lambdas, lambda_gen)?;
    let rho = parse_reactivity(&rho, py)?;
    let grid =
        nucleide_kinetics::TimeGrid::new(t).map_err(|e| PyValueError::new_err(e.to_string()))?;
    let state = nucleide_kinetics::State::new(&params, n0, c0)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    let method = if method.eq_ignore_ascii_case("trapezoidal") {
        M::Trapezoidal
    } else if method.eq_ignore_ascii_case("backward_euler") {
        M::BackwardEuler
    } else {
        return Err(PyValueError::new_err(format!(
            "unknown kinetics method `{method}` (supported: trapezoidal, backward_euler)"
        )));
    };
    let opts = SolverOptions {
        method,
        rtol,
        atol,
        dt_min,
        dt_max: dt_max.unwrap_or(f64::INFINITY),
        max_steps,
    };
    let sol = nucleide_kinetics::solve(&params, &rho, &grid, &state, &opts)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    use pyo3::types::PyDict;
    let out = PyDict::new(py);
    out.set_item("times", &sol.times).ok();
    out.set_item("n", &sol.n).ok();
    out.set_item("C", &sol.c).ok();
    out.set_item("n0", sol.initial.n0).ok();
    out.set_item("C0", &sol.initial.c0).ok();
    Ok(out.into_any().unbind())
}

/// Equilibrium precursor populations `C_i = beta_i/(lambda_i*Lambda)*n0`.
#[pyfunction]
fn kinetics_equilibrium(
    betas: Vec<f64>,
    lambdas: Vec<f64>,
    lambda_gen: f64,
    n0: f64,
) -> PyResult<Vec<f64>> {
    kinetics_params(betas, lambdas, lambda_gen)?
        .equilibrium_precursors(n0)
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Initial rate `dn/dt` at `t = 0` for the given schedule and initials.
#[pyfunction]
#[pyo3(signature = (betas, lambdas, lambda_gen, rho, n0, c0=None))]
fn kinetics_initial_rate(
    py: Python<'_>,
    betas: Vec<f64>,
    lambdas: Vec<f64>,
    lambda_gen: f64,
    rho: BTreeMap<String, Py<PyAny>>,
    n0: f64,
    c0: Option<Vec<f64>>,
) -> PyResult<f64> {
    let params = kinetics_params(betas, lambdas, lambda_gen)?;
    let rho = parse_reactivity(&rho, py)?;
    let state = nucleide_kinetics::State::new(&params, n0, c0)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    Ok(nucleide_kinetics::solve::initial_rate(
        &params, &rho, &state,
    ))
}

/// Inhour right-hand side `rho(omega)` [Δk] for the given data.
#[pyfunction]
fn kinetics_inhour_rho(
    betas: Vec<f64>,
    lambdas: Vec<f64>,
    lambda_gen: f64,
    omega: f64,
) -> PyResult<f64> {
    let params = kinetics_params(betas, lambdas, lambda_gen)?;
    nucleide_kinetics::rho_of_omega(&params, omega)
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Stable period `T = 1/omega` [s] at reactivity `rho` [Δk] (`0 < rho < beta`).
#[pyfunction]
fn kinetics_stable_period(
    betas: Vec<f64>,
    lambdas: Vec<f64>,
    lambda_gen: f64,
    rho: f64,
) -> PyResult<f64> {
    let params = kinetics_params(betas, lambdas, lambda_gen)?;
    nucleide_kinetics::stable_period(&params, rho).map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Prompt-jump estimate `n_before*(beta - rho_before)/(beta - rho_after)`.
///
/// Needs `rho_after < beta_total`; `beta_total` is the caller's total
/// delayed fraction (pass `sum(betas)`).
#[pyfunction]
fn kinetics_prompt_jump(
    n_before: f64,
    rho_before: f64,
    rho_after: f64,
    beta_total: f64,
) -> PyResult<f64> {
    nucleide_kinetics::prompt_jump(n_before, rho_before, rho_after, beta_total)
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

// ---------------------------------------------------------------------------
// Neutron spectrum unfolding (thin glue over `nucleide-unfold`; model stays in core)
// ---------------------------------------------------------------------------

/// SAND-II iterative spectral adjustment (McElroy et al., AFWL-TR-67-41, 1967).
///
/// Thin wrapper over `nucleide_unfold::sandii::unfold`: `response` holds one
/// row per detector/reaction (all rows one value per energy group),
/// `rates` the measured rate per detector, and `guess` one strictly positive
/// value per energy group. `tolerance` is the largest per-group relative
/// change between successive adjustments the run converges under (strictly
/// below); `max_iterations` is the explicit adjustment cap — exhausting it
/// raises a `ValueError` (non-convergence is a hard fail, never a silent
/// partial spectrum). Returns a dict with `spectrum`, the folded `rates`,
/// per-detector `rate_factors` (measured/folded), `iterations`, the echo of
/// `tolerance`, and the final `max_rel_change`.
#[pyfunction]
#[pyo3(signature = (response, rates, guess, tolerance=1e-3, max_iterations=200))]
fn unfold_sandii(
    py: Python<'_>,
    response: Vec<Vec<f64>>,
    rates: Vec<f64>,
    guess: Vec<f64>,
    tolerance: f64,
    max_iterations: usize,
) -> PyResult<Py<PyAny>> {
    let sol = nucleide_unfold::sandii::unfold(&response, &rates, &guess, tolerance, max_iterations)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    use pyo3::types::PyDict;
    let out = PyDict::new(py);
    out.set_item("spectrum", &sol.spectrum).ok();
    out.set_item("rates", &sol.rates).ok();
    out.set_item("rate_factors", &sol.rate_factors).ok();
    out.set_item("iterations", sol.iterations).ok();
    out.set_item("tolerance", sol.tolerance).ok();
    out.set_item("max_rel_change", sol.max_rel_change).ok();
    Ok(out.into_any().unbind())
}

/// Forward operator: fold a spectrum through a response matrix (one rate per
/// detector row). This is the map the unfolding adjusts against — also the
/// natural way to synthesize round-trip rates from a known spectrum.
#[pyfunction]
fn unfold_forward_fold(response: Vec<Vec<f64>>, spectrum: Vec<f64>) -> PyResult<Vec<f64>> {
    nucleide_unfold::forward_fold(&response, &spectrum)
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

// ---------------------------------------------------------------------------
// Tokamak fusion sources (thin glue over `nucleide-plasma-source`; model stays in core)
// ---------------------------------------------------------------------------

/// Parse a reaction name (`"dt"`, `"dd"`, case/separator-insensitive).
fn parse_plasma_reaction(name: &str) -> PyResult<nucleide_plasma_source::FusionReaction> {
    use nucleide_plasma_source::FusionReaction as R;
    match name
        .to_ascii_lowercase()
        .replace(['-', '_', ' '], "")
        .as_str()
    {
        "dt" => Ok(R::Dt),
        "dd" => Ok(R::Dd),
        other => Err(PyValueError::new_err(format!(
            "unknown fusion reaction `{other}` (supported: dt, dd)"
        ))),
    }
}

/// A parsed source spec: ring/point or parametric plasma.
enum PyPlasmaSource {
    Basic(nucleide_plasma_source::PlasmaSourceConfig),
    Parametric(nucleide_plasma_source::ParametricPlasmaConfig),
}

/// Parse a source-spec dict into a ring/point [`PlasmaSourceConfig`].
fn parse_plasma_basic_spec(
    spec: &BTreeMap<String, Py<PyAny>>,
    py: Python<'_>,
    kind: &str,
) -> PyResult<nucleide_plasma_source::PlasmaSourceConfig> {
    use nucleide_plasma_source as ps;
    let num = |key: &str| -> PyResult<f64> {
        spec.get(key)
            .ok_or_else(|| PyValueError::new_err(format!("source spec missing `{key}`")))?
            .extract::<f64>(py)
            .map_err(|_| PyValueError::new_err(format!("`{key}` must be a number")))
    };
    let reaction = parse_plasma_reaction(&get_str(
        spec,
        py,
        "reaction",
        "source spec missing `reaction`",
    )?)?;
    let model = match kind {
        "point" => {
            let position: Vec<f64> = spec
                .get("position")
                .ok_or_else(|| PyValueError::new_err("point source needs `position` [cm]"))?
                .extract::<Vec<f64>>(py)
                .map_err(|_| PyValueError::new_err("`position` must be a list of numbers"))?;
            if position.len() != 3 {
                return Err(PyValueError::new_err(
                    "`position` must have exactly three entries",
                ));
            }
            ps::SourceModel::Point(ps::PointSource {
                x_cm: position[0],
                y_cm: position[1],
                z_cm: position[2],
            })
        }
        "ring" => ps::SourceModel::Ring(ps::RingSource {
            radius_cm: num("radius")?,
            height_cm: num("height")?,
        }),
        other => {
            return Err(PyValueError::new_err(format!(
                "unknown source kind `{other}` (supported: point, ring, parametric)"
            )))
        }
    };
    let mut config = ps::PlasmaSourceConfig {
        model,
        reaction,
        ion_temperature_kev: num("ion_temperature_kev")?,
        weight: 1.0,
    };
    if let Some(weight) = spec.get("weight") {
        let weight = weight
            .extract::<f64>(py)
            .map_err(|_| PyValueError::new_err("`weight` must be a number"))?;
        config = config.with_weight(weight);
    }
    config
        .validate()
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    Ok(config)
}

/// Parse the parametric-plasma keys into a [`ParametricPlasmaConfig`].
///
/// Keys: `major_radius`, `minor_radius`, `elongation`, `triangularity`,
/// `shafranov_factor` (cm except the dimensionless shape factors), `mode`
/// (`"L"`/`"H"`/`"A"`), `pedestal_radius` (cm), the
/// `ion_density_{centre,peaking_factor,pedestal,separatrix}` parameters
/// (m⁻³ and dimensionless), and the
/// `ion_temperature_{centre,peaking_factor,beta,pedestal,separatrix}`
/// parameters (keV and dimensionless). Profiles are caller inputs. Fuel
/// mixtures (`fuel` dict) and toroidal sectors (`start_angle`/
/// `rotation_angle`) are the documented loud boundary — Eriksson-weighted
/// reactant distributions are not implemented.
fn parse_plasma_parametric_spec(
    spec: &BTreeMap<String, Py<PyAny>>,
    py: Python<'_>,
) -> PyResult<nucleide_plasma_source::ParametricPlasmaConfig> {
    use nucleide_plasma_source as ps;
    let num = |key: &str| -> PyResult<f64> {
        spec.get(key)
            .ok_or_else(|| PyValueError::new_err(format!("parametric spec missing `{key}`")))?
            .extract::<f64>(py)
            .map_err(|_| PyValueError::new_err(format!("`{key}` must be a number")))
    };
    for key in ["fuel", "start_angle", "rotation_angle"] {
        if spec.contains_key(key) {
            return Err(PyValueError::new_err(format!(
                "plasma-source: not yet supported: `{key}` (fuel mixtures are \
                 Eriksson-weighted reactant distributions; sectors need a \
                 toroidal-angle distribution — both outside the parametric model)"
            )));
        }
    }
    let mode = ps::ProfileMode::parse(&get_str(
        spec,
        py,
        "mode",
        "parametric spec missing `mode`",
    )?)
    .map_err(|e| PyValueError::new_err(e.to_string()))?;
    let fuel = parse_plasma_reaction(&get_str(
        spec,
        py,
        "reaction",
        "parametric spec missing `reaction`",
    )?)?;
    let mut config = ps::ParametricPlasmaConfig {
        geometry: ps::MillerGeometry {
            major_radius_cm: num("major_radius")?,
            minor_radius_cm: num("minor_radius")?,
            elongation: num("elongation")?,
            triangularity: num("triangularity")?,
            shafranov_factor_cm: num("shafranov_factor")?,
        },
        mode,
        ion_density: ps::DensityProfile {
            centre_m3: num("ion_density_centre")?,
            peaking_factor: num("ion_density_peaking_factor")?,
            pedestal_m3: num("ion_density_pedestal")?,
            separatrix_m3: num("ion_density_separatrix")?,
        },
        ion_temperature: ps::TemperatureProfile {
            centre_kev: num("ion_temperature_centre")?,
            peaking_factor: num("ion_temperature_peaking_factor")?,
            beta: num("ion_temperature_beta")?,
            pedestal_kev: num("ion_temperature_pedestal")?,
            separatrix_kev: num("ion_temperature_separatrix")?,
        },
        pedestal_radius_cm: num("pedestal_radius")?,
        fuel,
        weight: 1.0,
    };
    if let Some(weight) = spec.get("weight") {
        let weight = weight
            .extract::<f64>(py)
            .map_err(|_| PyValueError::new_err("`weight` must be a number"))?;
        config.weight = weight;
    }
    config
        .validate()
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    Ok(config)
}

/// Parse a source-spec dict: `kind` selects ring/point (`"point"`,
/// `"ring"`) or the parametric plasma (`"parametric"`).
fn parse_plasma_source_spec(
    spec: &BTreeMap<String, Py<PyAny>>,
    py: Python<'_>,
) -> PyResult<PyPlasmaSource> {
    let kind: String = spec
        .get("kind")
        .ok_or_else(|| PyValueError::new_err("source spec needs a `kind`"))?
        .extract::<String>(py)
        .map_err(|_| PyValueError::new_err("`kind` must be a string"))?;
    match kind.as_str() {
        "point" | "ring" => Ok(PyPlasmaSource::Basic(parse_plasma_basic_spec(
            spec, py, &kind,
        )?)),
        "parametric" => Ok(PyPlasmaSource::Parametric(parse_plasma_parametric_spec(
            spec, py,
        )?)),
        other => Err(PyValueError::new_err(format!(
            "unknown source kind `{other}` (supported: point, ring, parametric)"
        ))),
    }
}

/// Drift report rows as a list of dicts (`quantity`, `accounted`,
/// `rel_drift`, `reparsed`, `note`).
fn plasma_drift_rows(
    py: Python<'_>,
    report: &nucleide_plasma_source::DriftReport,
) -> PyResult<Vec<Py<pyo3::types::PyDict>>> {
    use pyo3::types::PyDict;
    let mut rows = Vec::with_capacity(report.rows.len());
    for row in &report.rows {
        let d = PyDict::new(py);
        d.set_item("quantity", &row.quantity)?;
        d.set_item("accounted", row.accounted)?;
        d.set_item("rel_drift", row.rel_drift)?;
        d.set_item("reparsed", row.reparsed)?;
        d.set_item("note", &row.note)?;
        rows.push(d.unbind());
    }
    Ok(rows)
}

/// Sample `n` source particles into per-field float64 NumPy arrays.
///
/// Thin wrapper over the ring/point `SourceSampler` and the parametric
/// `ParametricSampler` (seeded, deterministic per platform): `spec` is the
/// source-spec dict (see [`parse_plasma_source_spec`]), `seed` pins the
/// stream. Returns `x`, `y`, `z` \[cm\], direction cosines `u`, `v`, `w`
/// (unit vectors), `energy` \[MeV\], and `weight`. MCPL projection stays
/// caller-side: write the arrays with `nucleide.mcpl` / `nucleide.mcnp` if
/// a file is wanted.
#[pyfunction]
#[pyo3(signature = (spec, n, seed))]
fn plasma_source_particles(
    py: Python<'_>,
    spec: BTreeMap<String, Py<PyAny>>,
    n: usize,
    seed: u64,
) -> PyResult<Py<PyAny>> {
    use nucleide_plasma_source as ps;
    let particles = match parse_plasma_source_spec(&spec, py)? {
        PyPlasmaSource::Basic(config) => ps::SourceSampler::new(config, seed)
            .map_err(|e| PyValueError::new_err(e.to_string()))?
            .sample_n(n),
        PyPlasmaSource::Parametric(config) => ps::ParametricSampler::new(config, seed)
            .map_err(|e| PyValueError::new_err(e.to_string()))?
            .sample_n(n),
    };
    let mut x = Vec::with_capacity(n);
    let mut y = Vec::with_capacity(n);
    let mut z = Vec::with_capacity(n);
    let mut u = Vec::with_capacity(n);
    let mut v = Vec::with_capacity(n);
    let mut w = Vec::with_capacity(n);
    let mut energy = Vec::with_capacity(n);
    let mut weight = Vec::with_capacity(n);
    for p in &particles {
        x.push(p.position_cm[0]);
        y.push(p.position_cm[1]);
        z.push(p.position_cm[2]);
        u.push(p.direction[0]);
        v.push(p.direction[1]);
        w.push(p.direction[2]);
        energy.push(p.energy_mev);
        weight.push(p.weight);
    }
    use pyo3::types::PyDict;
    let out = PyDict::new(py);
    out.set_item("x", x.into_pyarray(py))?;
    out.set_item("y", y.into_pyarray(py))?;
    out.set_item("z", z.into_pyarray(py))?;
    out.set_item("u", u.into_pyarray(py))?;
    out.set_item("v", v.into_pyarray(py))?;
    out.set_item("w", w.into_pyarray(py))?;
    out.set_item("energy", energy.into_pyarray(py))?;
    out.set_item("weight", weight.into_pyarray(py))?;
    Ok(out.into_any().unbind())
}

/// Emit MCNP `SDEF` and Serpent `src` source cards plus drift reports.
///
/// Thin wrapper over `nucleide_plasma_source::{emit_sdef, emit_serpent}`
/// (ring/point) and `{emit_sdef_parametric, emit_serpent_parametric}`.
/// `spec` is the source-spec dict (optional `mcnp_version`, 5 or 6, default
/// 5); `bins` sets the tabulation bin count. Returns `sdef` and `serpent`,
/// each `{"card": str, "drift": [row dicts]}`, plus `spectrum` moments
/// (`nominal_mev`, `mean_mev`, `sigma_mev`, `mono` — for a parametric
/// source these are the magnetic-axis moments). The SDEF card round-trips
/// through `nucleide.mcnp.parse_sdef` byte-identically; Serpent drift rows
/// are analytic by design (no Serpent source reader in the workspace).
#[pyfunction]
#[pyo3(signature = (spec, bins=21))]
fn plasma_source_emit_cards(
    py: Python<'_>,
    spec: BTreeMap<String, Py<PyAny>>,
    bins: usize,
) -> PyResult<Py<PyAny>> {
    use nucleide_plasma_source as ps;
    let source = parse_plasma_source_spec(&spec, py)?;
    let version = match spec.get("mcnp_version") {
        Some(v) => v
            .extract::<u32>(py)
            .map_err(|_| PyValueError::new_err("`mcnp_version` must be an integer (5 or 6)"))?,
        None => 5,
    };
    let emit = |card: ps::EmittedCard| -> PyResult<Py<pyo3::types::PyDict>> {
        use pyo3::types::PyDict;
        let d = PyDict::new(py);
        d.set_item("card", card.text)?;
        d.set_item("drift", plasma_drift_rows(py, &card.drift)?)?;
        Ok(d.unbind())
    };
    use pyo3::types::PyDict;
    let out = PyDict::new(py);
    let (nominal, mean, sigma, mono) = match &source {
        PyPlasmaSource::Basic(config) => {
            let sdef = ps::emit_sdef(config, version, bins)
                .map_err(|e| PyValueError::new_err(e.to_string()))?;
            let serpent =
                ps::emit_serpent(config, bins).map_err(|e| PyValueError::new_err(e.to_string()))?;
            let spectrum = config
                .spectrum()
                .map_err(|e| PyValueError::new_err(e.to_string()))?;
            let sigma = match spectrum {
                ps::SpectrumSpec::Gaussian { sigma_mev, .. } => sigma_mev,
                ps::SpectrumSpec::Mono { .. } => 0.0,
            };
            out.set_item("sdef", emit(sdef)?)?;
            out.set_item("serpent", emit(serpent)?)?;
            (
                config.reaction.nominal_energy_mev(),
                spectrum.mean_mev(),
                sigma,
                spectrum.is_mono(),
            )
        }
        PyPlasmaSource::Parametric(config) => {
            let sdef = ps::emit_sdef_parametric(config, version, bins)
                .map_err(|e| PyValueError::new_err(e.to_string()))?;
            let serpent = ps::emit_serpent_parametric(config, bins)
                .map_err(|e| PyValueError::new_err(e.to_string()))?;
            // Magnetic-axis spectrum summary (the profile peak).
            let (mean, sigma) = config
                .fuel
                .moments_mev(config.temperature_kev(0.0))
                .map_err(|e| PyValueError::new_err(e.to_string()))?;
            out.set_item("sdef", emit(sdef)?)?;
            out.set_item("serpent", emit(serpent)?)?;
            (config.fuel.nominal_energy_mev(), mean, sigma, sigma == 0.0)
        }
    };
    let spec_out = PyDict::new(py);
    spec_out.set_item("nominal_mev", nominal)?;
    spec_out.set_item("mean_mev", mean)?;
    spec_out.set_item("sigma_mev", sigma)?;
    spec_out.set_item("mono", mono)?;
    out.set_item("spectrum", spec_out)?;
    Ok(out.into_any().unbind())
}

/// Closed-form spectrum moments of a fusion reaction at an ion temperature.
///
/// Returns `nominal_mev` (the `T_i = 0` line), `mean_mev`, and `sigma_mev`
/// (0 when the line is monoenergetic). `reaction` is `"dt"` or `"dd"`;
/// `ion_temperature_kev` is in keV. Moments follow Brysk (1973) as fitted by
/// Ballabio et al. (1998).
#[pyfunction]
fn plasma_source_spectrum_moments(
    py: Python<'_>,
    reaction: &str,
    ion_temperature_kev: f64,
) -> PyResult<Py<PyAny>> {
    use nucleide_plasma_source::FusionReaction as R;
    let reaction = parse_plasma_reaction(reaction)?;
    let (mean, sigma) = reaction
        .moments_mev(ion_temperature_kev)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    use pyo3::types::PyDict;
    let out = PyDict::new(py);
    out.set_item(
        "reaction",
        match reaction {
            R::Dt => "dt",
            R::Dd => "dd",
        },
    )?;
    out.set_item("label", reaction.label())?;
    out.set_item("nominal_mev", reaction.nominal_energy_mev())?;
    out.set_item("mean_mev", mean)?;
    out.set_item("sigma_mev", sigma)?;
    Ok(out.into_any().unbind())
}

/// Thermonuclear reactivity ⟨σv⟩ \[m³/s\] of a fusion reaction at an ion
/// temperature \[keV\] (Bosch & Hale, Nucl. Fusion 32 (1992) 611, in the
/// Atzeni–Meyer-ter-Vehn parametrization). Zero at `T_i = 0`.
#[pyfunction]
fn plasma_source_reactivity(reaction: &str, ion_temperature_kev: f64) -> PyResult<f64> {
    parse_plasma_reaction(reaction)?
        .reactivity_m3_per_s(ion_temperature_kev)
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

// ---------------------------------------------------------------------------
// Damage and gas-production metrics (thin glue over `nucleide-damage`)
// ---------------------------------------------------------------------------

/// Parse a nuclide key (int nucid or str name) into the core [`NuclideId`].
fn parse_damage_nuclide(key: &Bound<'_, PyAny>) -> PyResult<NuclideId> {
    if let Ok(nucid) = key.extract::<u32>() {
        return NuclideId::try_from_nucid(nucid).map_err(wrap_nucid_err);
    }
    if let Ok(name) = key.extract::<&str>() {
        return NuclideId::from_name(name).map_err(wrap_nucid_err);
    }
    Err(PyTypeError::new_err("expected int nucid or str name"))
}

/// NRT-dpa: fold caller dpa cross sections (barns) over the group flux.
///
/// `flux` is the per-group integrated flux (n/cm²/s), `bounds` the G+1 MeV
/// group boundaries, `seconds` the exposure time. Piecewise-constant per
/// group; zero-flux groups contribute exactly 0.
#[pyfunction]
#[pyo3(signature = (flux, response, bounds, seconds))]
fn damage_nrt_dpa(
    flux: Vec<f64>,
    response: Vec<f64>,
    bounds: Vec<f64>,
    seconds: f64,
) -> PyResult<f64> {
    nucleide_damage::nrt_dpa(&flux, &response, &bounds, seconds)
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// arc-dpa fold: same as `damage_nrt_dpa` with arc-corrected cross sections.
#[pyfunction]
#[pyo3(signature = (flux, response, bounds, seconds))]
fn damage_arc_dpa(
    flux: Vec<f64>,
    response: Vec<f64>,
    bounds: Vec<f64>,
    seconds: f64,
) -> PyResult<f64> {
    nucleide_damage::arc_dpa(&flux, &response, &bounds, seconds)
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Gas production in atomic parts per million (He or H, whichever gas the
/// caller's `response` counts), by the same fold with the appm normalization.
#[pyfunction]
#[pyo3(signature = (flux, response, bounds, seconds))]
fn damage_gas_appm(
    flux: Vec<f64>,
    response: Vec<f64>,
    bounds: Vec<f64>,
    seconds: f64,
) -> PyResult<f64> {
    nucleide_damage::gas_appm(&flux, &response, &bounds, seconds)
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// He/dpa ratio (appm per dpa) from one fold of the He production and
/// damage cross sections over the same flux. Zero dpa is a loud error,
/// never `inf`.
#[pyfunction]
#[pyo3(signature = (flux, he_response, damage_response, bounds, seconds))]
fn damage_he_dpa_ratio(
    flux: Vec<f64>,
    he_response: Vec<f64>,
    damage_response: Vec<f64>,
    bounds: Vec<f64>,
    seconds: f64,
) -> PyResult<f64> {
    nucleide_damage::he_dpa_ratio(&flux, &he_response, &damage_response, &bounds, seconds)
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Lindhard partition fraction `P(ε) = 1/(1 + k_L·g(ε))` for a recoil of
/// energy `t_ev` (eV) stopped in a lattice; nuclides accept an int nucid or
/// a name string.
#[pyfunction]
#[pyo3(signature = (t_ev, recoil, lattice))]
fn damage_lindhard_partition(
    t_ev: f64,
    recoil: &Bound<'_, PyAny>,
    lattice: &Bound<'_, PyAny>,
) -> PyResult<f64> {
    let recoil = parse_damage_nuclide(recoil)?;
    let lattice = parse_damage_nuclide(lattice)?;
    nucleide_damage::lindhard_partition(t_ev, &recoil, &lattice)
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Lindhard damage energy `T_dam = T·P(ε)` in eV.
#[pyfunction]
#[pyo3(signature = (t_ev, recoil, lattice))]
fn damage_damage_energy(
    t_ev: f64,
    recoil: &Bound<'_, PyAny>,
    lattice: &Bound<'_, PyAny>,
) -> PyResult<f64> {
    let recoil = parse_damage_nuclide(recoil)?;
    let lattice = parse_damage_nuclide(lattice)?;
    nucleide_damage::damage_energy(t_ev, &recoil, &lattice)
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// NRT displacement function `N_d(T)` for a self-recoil `target` (int nucid
/// or name) with average threshold displacement energy `ed_ev` (eV).
#[pyfunction]
#[pyo3(signature = (t_ev, ed_ev, target))]
fn damage_nrt_displacements(t_ev: f64, ed_ev: f64, target: &Bound<'_, PyAny>) -> PyResult<f64> {
    let target = parse_damage_nuclide(target)?;
    nucleide_damage::nrt_displacements(t_ev, ed_ev, &target)
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// arc-dpa efficiency `ξ(T_d)` (Nordlund 2018 Eq. (7)) at damage energy
/// `t_dam_ev` for threshold `ed_ev` and constants `b_arc`/`c_arc`.
#[pyfunction]
#[pyo3(signature = (t_dam_ev, ed_ev, b_arc, c_arc))]
fn damage_arc_efficiency(t_dam_ev: f64, ed_ev: f64, b_arc: f64, c_arc: f64) -> PyResult<f64> {
    let params = nucleide_damage::ArcParams::new(b_arc, c_arc)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    nucleide_damage::arc_efficiency(t_dam_ev, ed_ev, &params)
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// arc-dpa displacement function for a self-recoil `target` with threshold
/// `ed_ev` (eV) and arc constants `b_arc`/`c_arc`.
#[pyfunction]
#[pyo3(signature = (t_ev, ed_ev, target, b_arc, c_arc))]
fn damage_arc_displacements(
    t_ev: f64,
    ed_ev: f64,
    target: &Bound<'_, PyAny>,
    b_arc: f64,
    c_arc: f64,
) -> PyResult<f64> {
    let target = parse_damage_nuclide(target)?;
    let params = nucleide_damage::ArcParams::new(b_arc, c_arc)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    nucleide_damage::arc_displacements(t_ev, ed_ev, &target, &params)
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// UQ sweep over the fold: seeded MVN draws over the caller's relative
/// `[flux, response]` block, refolded per draw, gated at `k` standard
/// errors against the exact expectation and the first-order propagated
/// standard deviation (the landed U1–U4/U7 pattern). `metric` is one of
/// `"nrt_dpa"`, `"arc_dpa"`, `"gas_appm"` (`"he_dpa_ratio"` is a loud
/// named-open). Returns the sample/analytic moments plus the gate verdict.
#[pyfunction]
#[pyo3(signature = (metric, flux, response, bounds, seconds, mean, cov, n, seed, k))]
#[allow(clippy::too_many_arguments)] // mirrors the core fold_uq signature plus the PyO3 py handle
fn damage_fold_uq(
    py: Python<'_>,
    metric: &str,
    flux: Vec<f64>,
    response: Vec<f64>,
    bounds: Vec<f64>,
    seconds: f64,
    mean: Vec<f64>,
    cov: Vec<Vec<f64>>,
    n: usize,
    seed: u64,
    k: f64,
) -> PyResult<Py<PyAny>> {
    use nucleide_damage::FoldMetric as M;
    let metric = match metric
        .to_ascii_lowercase()
        .replace(['-', ' '], "_")
        .as_str()
    {
        "nrt_dpa" => M::NrtDpa,
        "arc_dpa" => M::ArcDpa,
        "gas_appm" => M::GasAppm,
        "he_dpa_ratio" => M::HeDpaRatio,
        other => {
            return Err(PyValueError::new_err(format!(
                "unknown fold metric `{other}` (supported: nrt_dpa, arc_dpa, gas_appm)"
            )))
        }
    };
    let s = nucleide_damage::fold_uq(
        metric, &flux, &response, &bounds, seconds, &mean, &cov, n, seed, k,
    )
    .map_err(|e| PyValueError::new_err(e.to_string()))?;
    use pyo3::types::PyDict;
    let out = PyDict::new(py);
    out.set_item("metric", s.metric.name())?;
    out.set_item("nominal", s.nominal)?;
    out.set_item("mean", s.mean)?;
    out.set_item("std", s.std)?;
    out.set_item("expected", s.expected)?;
    out.set_item("analytic_std", s.analytic_std)?;
    out.set_item("k", s.k)?;
    out.set_item("n", s.n)?;
    out.set_item("seed", s.seed)?;
    out.set_item("passed", s.passed)?;
    Ok(out.into_any().unbind())
}

// ---------------------------------------------------------------------------
// Tritium transport (thin glue over `nucleide-tritium`; solver stays in core)
// ---------------------------------------------------------------------------

/// Parse a boundary-spec dict into the core [`Boundary`].
///
/// `kind` selects the surface law (`"dirichlet"`, `"sieverts"`, `"henry"`,
/// `"recombination"`, `"zero_flux"`). Keys per kind: dirichlet (`value`
/// [mol/m³]); sieverts/henry (`solubility`, `pressure` [Pa]);
/// recombination (`rate`); zero_flux (no keys). Recombination ends close
/// per solve — steady (G5) and transient (G6) alike.
fn parse_tritium_boundary(
    spec: &BTreeMap<String, Py<PyAny>>,
    py: Python<'_>,
) -> PyResult<nucleide_tritium::Boundary> {
    use nucleide_tritium::Boundary as B;
    let kind: String = spec
        .get("kind")
        .ok_or_else(|| PyValueError::new_err("boundary spec needs a `kind`"))?
        .extract::<String>(py)
        .map_err(|_| PyValueError::new_err("`kind` must be a string"))?;
    let num = |key: &str| -> PyResult<f64> {
        spec.get(key)
            .ok_or_else(|| PyValueError::new_err(format!("boundary spec missing `{key}`")))?
            .extract::<f64>(py)
            .map_err(|_| PyValueError::new_err(format!("`{key}` must be a number")))
    };
    let b = match kind.as_str() {
        "dirichlet" => B::dirichlet(num("value")?),
        "sieverts" => B::sieverts(num("solubility")?, num("pressure")?),
        "henry" => B::henry(num("solubility")?, num("pressure")?),
        "recombination" => B::recombination(num("rate")?),
        "zero_flux" => Ok(B::ZeroFlux),
        other => {
            return Err(PyValueError::new_err(format!(
                "unknown boundary kind `{other}` (supported: dirichlet, sieverts, henry, recombination, zero_flux)"
            )))
        }
    };
    b.map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Parse a trap-spec dict into the core [`TrapSpec`].
///
/// Keys: `k0` [m³/mol/s], `p0` [1/s], `site_density` [mol/m³] (required);
/// `e_k`/`e_p` [J/mol] (optional, default 0 = constant rates).
fn parse_tritium_trap(
    spec: &BTreeMap<String, Py<PyAny>>,
    py: Python<'_>,
) -> PyResult<nucleide_tritium::TrapSpec> {
    let num = |key: &str| -> PyResult<f64> {
        spec.get(key)
            .ok_or_else(|| PyValueError::new_err(format!("trap spec missing `{key}`")))?
            .extract::<f64>(py)
            .map_err(|_| PyValueError::new_err(format!("`{key}` must be a number")))
    };
    let opt = |key: &str| -> PyResult<f64> {
        match spec.get(key) {
            None => Ok(0.0),
            Some(v) => v
                .extract::<f64>(py)
                .map_err(|_| PyValueError::new_err(format!("`{key}` must be a number"))),
        }
    };
    nucleide_tritium::TrapSpec::new(
        num("k0")?,
        opt("e_k")?,
        num("p0")?,
        opt("e_p")?,
        num("site_density")?,
    )
    .map_err(|e| PyValueError::new_err(e.to_string()))
}

#[allow(clippy::too_many_arguments)]
fn tritium_params(
    py: Python<'_>,
    length: f64,
    cells: usize,
    d0: f64,
    e_d: f64,
    traps: Vec<BTreeMap<String, Py<PyAny>>>,
    temperature: Vec<f64>,
    source: Option<Vec<f64>>,
) -> PyResult<nucleide_tritium::TransportParams> {
    let parsed: Vec<nucleide_tritium::TrapSpec> = traps
        .iter()
        .map(|s| parse_tritium_trap(s, py))
        .collect::<PyResult<_>>()?;
    nucleide_tritium::TransportParams::new(
        length,
        cells,
        d0,
        e_d,
        parsed,
        temperature,
        source.unwrap_or_default(),
    )
    .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Trap-free-style steady state of (T1–T2).
///
/// Thin wrapper over `nucleide_tritium::steady_state`: `traps` holds one
/// spec dict per species (see `parse_tritium_trap`), `temperature` is one
/// value (uniform) or one per cell, `source` is None (zero), one value, or
/// one per cell, and `left`/`right` are boundary-spec dicts (see
/// `parse_tritium_boundary`). Returns a dict with `centres`, `mobile`,
/// `trapped` (`[cell][trap]`), `flux_left`, `flux_right`,
/// `inventory_mobile`, and `inventory_trapped`.
#[pyfunction]
#[pyo3(signature = (length, cells, d0, e_d, traps, temperature, source, left, right))]
#[allow(clippy::too_many_arguments)]
fn tritium_steady(
    py: Python<'_>,
    length: f64,
    cells: usize,
    d0: f64,
    e_d: f64,
    traps: Vec<BTreeMap<String, Py<PyAny>>>,
    temperature: Vec<f64>,
    source: Option<Vec<f64>>,
    left: BTreeMap<String, Py<PyAny>>,
    right: BTreeMap<String, Py<PyAny>>,
) -> PyResult<Py<PyAny>> {
    let params = tritium_params(py, length, cells, d0, e_d, traps, temperature, source)?;
    let left = parse_tritium_boundary(&left, py)?;
    let right = parse_tritium_boundary(&right, py)?;
    let s = nucleide_tritium::steady_state(&params, &left, &right)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    use pyo3::types::PyDict;
    let out = PyDict::new(py);
    out.set_item("centres", &s.centres).ok();
    out.set_item("mobile", &s.mobile).ok();
    out.set_item("trapped", &s.trapped).ok();
    out.set_item("flux_left", s.flux_left).ok();
    out.set_item("flux_right", s.flux_right).ok();
    out.set_item("inventory_mobile", s.inventory_mobile).ok();
    out.set_item("inventory_trapped", s.inventory_trapped).ok();
    Ok(out.into_any().unbind())
}

/// Solve the (T1–T2) transient over the output grid `t`.
///
/// Thin wrapper over `nucleide_tritium::solve` with the same slab/trap/BC
/// arguments as `tritium_steady` plus the output times `t` [s], the
/// optional initial profiles (`mobile0` per cell, `trapped0` as
/// `[cell][trap]`; both default to zero), and the solver options
/// (`method` is `"crank_nicolson"` (default) or `"backward_euler"`).
/// Returns a dict with `times`, `mobile` (`[time][cell]`), `trapped`
/// (`[time][cell][trap]`), `flux_left`, and `flux_right`.
#[pyfunction]
#[pyo3(signature = (length, cells, d0, e_d, traps, temperature, source, left, right, t, mobile0=None, trapped0=None, method="crank_nicolson", rtol=1e-9, atol=1e-12, dt_min=1e-14, dt_max=None, max_steps=1000000))]
#[allow(clippy::too_many_arguments)]
fn tritium_transient(
    py: Python<'_>,
    length: f64,
    cells: usize,
    d0: f64,
    e_d: f64,
    traps: Vec<BTreeMap<String, Py<PyAny>>>,
    temperature: Vec<f64>,
    source: Option<Vec<f64>>,
    left: BTreeMap<String, Py<PyAny>>,
    right: BTreeMap<String, Py<PyAny>>,
    t: Vec<f64>,
    mobile0: Option<Vec<f64>>,
    trapped0: Option<Vec<Vec<f64>>>,
    method: &str,
    rtol: f64,
    atol: f64,
    dt_min: f64,
    dt_max: Option<f64>,
    max_steps: usize,
) -> PyResult<Py<PyAny>> {
    use nucleide_tritium::{SolverOptions, Theta};
    let params = tritium_params(py, length, cells, d0, e_d, traps, temperature, source)?;
    let left = parse_tritium_boundary(&left, py)?;
    let right = parse_tritium_boundary(&right, py)?;
    let grid =
        nucleide_tritium::TimeGrid::new(t).map_err(|e| PyValueError::new_err(e.to_string()))?;
    let ntraps = params.traps.len();
    let mobile = mobile0.unwrap_or_else(|| vec![0.0; params.cells]);
    let trapped = trapped0.unwrap_or_else(|| vec![vec![0.0; ntraps]; params.cells]);
    let initial = nucleide_tritium::InitialState::new(&params, mobile, trapped)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    let theta = if method.eq_ignore_ascii_case("crank_nicolson") {
        Theta::CrankNicolson
    } else if method.eq_ignore_ascii_case("backward_euler") {
        Theta::BackwardEuler
    } else {
        return Err(PyValueError::new_err(format!(
            "unknown tritium method `{method}` (supported: crank_nicolson, backward_euler)"
        )));
    };
    let opts = SolverOptions {
        theta,
        rtol,
        atol,
        dt_min,
        dt_max: dt_max.unwrap_or(f64::INFINITY),
        max_steps,
    };
    let sol = nucleide_tritium::solve(&params, &left, &right, &grid, &initial, &opts)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    use pyo3::types::PyDict;
    let out = PyDict::new(py);
    out.set_item("times", &sol.times).ok();
    out.set_item("mobile", &sol.mobile).ok();
    out.set_item("trapped", &sol.trapped).ok();
    out.set_item("flux_left", &sol.flux_left).ok();
    out.set_item("flux_right", &sol.flux_right).ok();
    Ok(out.into_any().unbind())
}

/// Permeation time lag `t_lag = L²/6D` [s] (G2-lag).
#[pyfunction]
fn tritium_time_lag(length: f64, diffusivity: f64) -> PyResult<f64> {
    nucleide_tritium::time_lag(length, diffusivity)
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Normalized outlet flux `J(L,t)/J_ss` at each time (G2 series).
#[pyfunction]
fn tritium_breakthrough(diffusivity: f64, length: f64, times: Vec<f64>) -> PyResult<Vec<f64>> {
    times
        .iter()
        .map(|t| {
            nucleide_tritium::breakthrough_ratio(diffusivity, length, *t)
                .map_err(|e| PyValueError::new_err(e.to_string()))
        })
        .collect()
}

/// Oriani effective diffusivity `D_eff = D/(1 + K N)` [m²/s] (G3a).
#[pyfunction]
fn tritium_oriani(diffusivity: f64, equilibrium_constant: f64, site_density: f64) -> PyResult<f64> {
    nucleide_tritium::effective_diffusivity(diffusivity, equilibrium_constant, site_density)
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Langmuir equilibrium load `c_t = N K c/(1 + K c)` [mol/m³] (T2-eq).
#[pyfunction]
fn tritium_langmuir(site_density: f64, equilibrium_constant: f64, c_mobile: f64) -> PyResult<f64> {
    nucleide_tritium::equilibrium_trapped(site_density, equilibrium_constant, c_mobile)
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Irreversible-trap fill `c_t(t) = N(1 − e^{−kct})` [mol/m³] at each time (G3c).
#[pyfunction]
fn tritium_irreversible_fill(
    rate_k: f64,
    c_mobile: f64,
    site_density: f64,
    times: Vec<f64>,
) -> PyResult<Vec<f64>> {
    times
        .iter()
        .map(|t| {
            nucleide_tritium::irreversible_fill(rate_k, c_mobile, site_density, *t)
                .map_err(|e| PyValueError::new_err(e.to_string()))
        })
        .collect()
}

/// Sieverts surface concentration `c = K_S sqrt(p)` [mol/m³] (G4).
#[pyfunction]
fn tritium_sieverts(solubility: f64, pressure: f64) -> PyResult<f64> {
    nucleide_tritium::sieverts_concentration(solubility, pressure)
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Recombination rate `K_r = kr0 * exp(-e_r / R / temp)` [m⁴/mol/s] (G5).
#[pyfunction]
fn tritium_recombination_rate(kr0: f64, e_r: f64, temp: f64) -> PyResult<f64> {
    nucleide_tritium::recombination_rate_arrhenius(kr0, e_r, temp)
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Parse a layer-spec dict into the core [`nucleide_tritium::LayerSpec`].
///
/// Keys: `thickness` [m], `cells`, `D` [m²/s], `solubility` `K_S`
/// [mol/m³/Pa¹ᐟ²] (required); `E_D` [J/mol] (optional, default 0 = constant
/// diffusivity); `traps` (optional list of trap-spec dicts, default none),
/// `temperature` (optional, default [500]), `source` (optional). Internal
/// interfaces between consecutive layers are Sieverts conditions in v1
/// (`c/K_S` continuous, flux continuous); Henry/recombination interface
/// laws are loud core errors, not expressible here.
fn parse_tritium_layer(
    spec: &BTreeMap<String, Py<PyAny>>,
    py: Python<'_>,
) -> PyResult<nucleide_tritium::LayerSpec> {
    let num = |key: &str| -> PyResult<f64> {
        spec.get(key)
            .ok_or_else(|| PyValueError::new_err(format!("layer spec missing `{key}`")))?
            .extract::<f64>(py)
            .map_err(|_| PyValueError::new_err(format!("`{key}` must be a number")))
    };
    let opt = |key: &str| -> PyResult<f64> {
        match spec.get(key) {
            None => Ok(0.0),
            Some(v) => v
                .extract::<f64>(py)
                .map_err(|_| PyValueError::new_err(format!("`{key}` must be a number"))),
        }
    };
    let traps = match spec.get("traps") {
        None => Vec::new(),
        Some(v) => v
            .extract::<Vec<BTreeMap<String, Py<PyAny>>>>(py)
            .map_err(|_| PyValueError::new_err("`traps` must be a list of dicts"))?
            .iter()
            .map(|s| parse_tritium_trap(s, py))
            .collect::<PyResult<_>>()?,
    };
    let temperature: Vec<f64> = match spec.get("temperature") {
        None => vec![500.0],
        Some(v) => v
            .extract::<Vec<f64>>(py)
            .map_err(|_| PyValueError::new_err("`temperature` must be a list of numbers"))?,
    };
    let source: Vec<f64> = match spec.get("source") {
        None => Vec::new(),
        Some(v) => v
            .extract::<Vec<f64>>(py)
            .map_err(|_| PyValueError::new_err("`source` must be a list of numbers"))?,
    };
    let cells: usize = spec
        .get("cells")
        .ok_or_else(|| PyValueError::new_err("layer spec missing `cells`"))?
        .extract::<usize>(py)
        .map_err(|_| PyValueError::new_err("`cells` must be an integer"))?;
    nucleide_tritium::LayerSpec::new(
        num("thickness")?,
        cells,
        num("D")?,
        opt("E_D")?,
        num("solubility")?,
        traps,
        temperature,
        source,
    )
    .map_err(|e| PyValueError::new_err(e.to_string()))
}

fn tritium_layer_stack(
    py: Python<'_>,
    layers: Vec<BTreeMap<String, Py<PyAny>>>,
) -> PyResult<nucleide_tritium::LayerStack> {
    let parsed: Vec<nucleide_tritium::LayerSpec> = layers
        .iter()
        .map(|s| parse_tritium_layer(s, py))
        .collect::<PyResult<_>>()?;
    let interfaces = vec![nucleide_tritium::Interface::Sieverts; parsed.len().saturating_sub(1)];
    nucleide_tritium::LayerStack::new(parsed, interfaces)
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Trap-free-style steady state of a multi-layer series stack (G7).
///
/// Thin wrapper over `nucleide_tritium::steady_layers`: `layers` holds one
/// spec dict per layer (see `parse_tritium_layer`; internal interfaces are
/// Sieverts conditions in v1) and `left`/`right` are boundary-spec dicts
/// (see `parse_tritium_boundary`). A one-layer stack reproduces
/// `tritium_steady` exactly. Returns a dict with `centres`, `mobile`,
/// `trapped` (`[cell][trap]`), `flux_left`, `flux_right`,
/// `inventory_mobile`, and `inventory_trapped`.
#[pyfunction]
fn tritium_layers_steady(
    py: Python<'_>,
    layers: Vec<BTreeMap<String, Py<PyAny>>>,
    left: BTreeMap<String, Py<PyAny>>,
    right: BTreeMap<String, Py<PyAny>>,
) -> PyResult<Py<PyAny>> {
    let stack = tritium_layer_stack(py, layers)?;
    let left = parse_tritium_boundary(&left, py)?;
    let right = parse_tritium_boundary(&right, py)?;
    let s = nucleide_tritium::steady_layers(&stack, &left, &right)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    use pyo3::types::PyDict;
    let out = PyDict::new(py);
    out.set_item("centres", &s.centres).ok();
    out.set_item("mobile", &s.mobile).ok();
    out.set_item("trapped", &s.trapped).ok();
    out.set_item("flux_left", s.flux_left).ok();
    out.set_item("flux_right", s.flux_right).ok();
    out.set_item("inventory_mobile", s.inventory_mobile).ok();
    out.set_item("inventory_trapped", s.inventory_trapped).ok();
    Ok(out.into_any().unbind())
}

/// Solve the multi-layer (T1–T2) transient over the output grid `t` (G8).
///
/// Thin wrapper over `nucleide_tritium::solve_layers` with the same layer
/// stack and boundary arguments as `tritium_layers_steady` plus the output
/// times `t` [s], the optional initial profiles (`mobile0` per cell,
/// `trapped0` as `[cell][trap]` matching each layer's trap count; both
/// default to zero), and the solver options (`method` is
/// `"crank_nicolson"` (default) or `"backward_euler"`). Returns a dict with
/// `times`, `mobile` (`[time][cell]`), `trapped` (`[time][cell][trap]`),
/// `flux_left`, and `flux_right`.
#[pyfunction]
#[pyo3(signature = (layers, left, right, t, mobile0=None, trapped0=None, method="crank_nicolson", rtol=1e-9, atol=1e-12, dt_min=1e-14, dt_max=None, max_steps=1000000))]
#[allow(clippy::too_many_arguments)]
fn tritium_layers_transient(
    py: Python<'_>,
    layers: Vec<BTreeMap<String, Py<PyAny>>>,
    left: BTreeMap<String, Py<PyAny>>,
    right: BTreeMap<String, Py<PyAny>>,
    t: Vec<f64>,
    mobile0: Option<Vec<f64>>,
    trapped0: Option<Vec<Vec<f64>>>,
    method: &str,
    rtol: f64,
    atol: f64,
    dt_min: f64,
    dt_max: Option<f64>,
    max_steps: usize,
) -> PyResult<Py<PyAny>> {
    use nucleide_tritium::{SolverOptions, Theta};
    let stack = tritium_layer_stack(py, layers)?;
    let left = parse_tritium_boundary(&left, py)?;
    let right = parse_tritium_boundary(&right, py)?;
    let grid =
        nucleide_tritium::TimeGrid::new(t).map_err(|e| PyValueError::new_err(e.to_string()))?;
    let mobile = mobile0.unwrap_or_else(|| vec![0.0; stack.total_cells()]);
    let trapped = trapped0.unwrap_or_else(|| stack.zero_state().trapped);
    let initial = nucleide_tritium::InitialState { mobile, trapped };
    let theta = if method.eq_ignore_ascii_case("crank_nicolson") {
        Theta::CrankNicolson
    } else if method.eq_ignore_ascii_case("backward_euler") {
        Theta::BackwardEuler
    } else {
        return Err(PyValueError::new_err(format!(
            "unknown tritium method `{method}` (supported: crank_nicolson, backward_euler)"
        )));
    };
    let opts = SolverOptions {
        theta,
        rtol,
        atol,
        dt_min,
        dt_max: dt_max.unwrap_or(f64::INFINITY),
        max_steps,
    };
    let sol = nucleide_tritium::solve_layers(&stack, &left, &right, &grid, &initial, &opts)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    use pyo3::types::PyDict;
    let out = PyDict::new(py);
    out.set_item("times", &sol.times).ok();
    out.set_item("mobile", &sol.mobile).ok();
    out.set_item("trapped", &sol.trapped).ok();
    out.set_item("flux_left", &sol.flux_left).ok();
    out.set_item("flux_right", &sol.flux_right).ok();
    Ok(out.into_any().unbind())
}

// ---------------------------------------------------------------------------
// Spectroscopy (thin glue over `nucleide-spectroscopy`; algorithms stay in core)
// ---------------------------------------------------------------------------

/// Rectangular smoothing (E1): `m` must be odd and at least 3.
#[pyfunction]
fn spectroscopy_rect_smooth(counts: Vec<f64>, m: i64) -> PyResult<Vec<f64>> {
    let w = usize::try_from(m).map_err(|_| {
        PyValueError::new_err(format!("spectroscopy: smoothing width {m} is less than 3"))
    })?;
    nucleide_spectroscopy::rect_smooth(&counts, w).map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Five-point smoothing (E2); the first/last two channels are copied.
#[pyfunction]
fn spectroscopy_five_point_smooth(counts: Vec<f64>) -> PyResult<Vec<f64>> {
    nucleide_spectroscopy::five_point_smooth(&counts)
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Background under a peak (E3, `m == 1` only).
#[pyfunction]
fn spectroscopy_calc_bg(
    counts: Vec<f64>,
    channels: Vec<f64>,
    c1: i64,
    c2: i64,
    m: i64,
) -> PyResult<f64> {
    nucleide_spectroscopy::calc_bg(&counts, &channels, c1, c2, m)
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Gross counts between two channels, half-open (E4, excludes `c2`).
#[pyfunction]
fn spectroscopy_gross_count(
    counts: Vec<f64>,
    channels: Vec<f64>,
    c1: i64,
    c2: i64,
) -> PyResult<f64> {
    nucleide_spectroscopy::gross_count(&counts, &channels, c1, c2)
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Net counts: gross minus background (E5).
#[pyfunction]
fn spectroscopy_net_counts(
    counts: Vec<f64>,
    channels: Vec<f64>,
    c1: i64,
    c2: i64,
    m: i64,
) -> PyResult<f64> {
    nucleide_spectroscopy::net_counts(&counts, &channels, c1, c2, m)
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Energy per channel from the `[a0, a1, a2]` fit (E6).
#[pyfunction]
fn spectroscopy_energy_bins(channels: Vec<f64>, calib_e_fit: Vec<f64>) -> PyResult<Vec<f64>> {
    nucleide_spectroscopy::energy_bins(&channels, &calib_e_fit)
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Detector efficiency at `energy_mev` (E7, energy in MeV, `eff_fit` 1 or 2).
#[pyfunction]
fn spectroscopy_detector_efficiency(
    energy_mev: f64,
    eff_coeff: Vec<f64>,
    eff_fit: i64,
) -> PyResult<f64> {
    nucleide_spectroscopy::detector_efficiency(energy_mev, &eff_coeff, eff_fit)
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Efficiency-coefficient fit (E7-fit): log-space weighted least squares over
/// caller `(energies_mev, effs, weights)` points with `order + 1` coefficients
/// under the `eff_fit` 1 (`(ln E)^j`) or 2 (`(1/E)^j`) basis. Thin wrapper
/// over `nucleide-spectroscopy` `fit_efficiency` (which solves through the
/// workspace `nucleide-linalg` least-squares kernel).
#[pyfunction]
#[pyo3(signature = (energies, effs, weights, order, eff_fit=1))]
fn spectroscopy_fit_efficiency(
    energies: Vec<f64>,
    effs: Vec<f64>,
    weights: Vec<f64>,
    order: usize,
    eff_fit: i64,
) -> PyResult<Vec<f64>> {
    nucleide_spectroscopy::fit_efficiency(&energies, &effs, &weights, order, eff_fit)
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Fetch one caller-supplied atomic constant or raise a `ValueError`.
fn atomic_key(atomic: &BTreeMap<String, f64>, key: &str) -> PyResult<f64> {
    atomic
        .get(key)
        .copied()
        .ok_or_else(|| PyValueError::new_err(format!("atomic constants missing `{key}`")))
}

/// X-ray lines (E8) as `[(energy_kev, intensity); Ka1, Ka2, Kb, L]`.
///
/// `atomic` carries the nine caller-supplied constants (`k_shell_fluor`,
/// `l_shell_fluor`, `prob`, `kb_to_ka`, `ka2_to_ka1`, `ka1_en_kev`,
/// `ka2_en_kev`, `kb_en_kev`, `l_en_kev`). `None` (or NaN, the upstream
/// sentinel) marks a conversion absent. Upstream exposes no combined
/// function for this routine — only a material method — so this explicit
/// entry point is the documented Nucleide surface.
#[pyfunction]
#[pyo3(signature = (atomic, k_conv=None, l_conv=None))]
fn spectroscopy_xray_lines(
    atomic: BTreeMap<String, f64>,
    k_conv: Option<f64>,
    l_conv: Option<f64>,
) -> PyResult<Vec<(f64, f64)>> {
    let data = nucleide_spectroscopy::AtomicData {
        k_shell_fluor: atomic_key(&atomic, "k_shell_fluor")?,
        l_shell_fluor: atomic_key(&atomic, "l_shell_fluor")?,
        prob: atomic_key(&atomic, "prob")?,
        kb_to_ka: atomic_key(&atomic, "kb_to_ka")?,
        ka2_to_ka1: atomic_key(&atomic, "ka2_to_ka1")?,
        ka1_en_kev: atomic_key(&atomic, "ka1_en_kev")?,
        ka2_en_kev: atomic_key(&atomic, "ka2_en_kev")?,
        kb_en_kev: atomic_key(&atomic, "kb_en_kev")?,
        l_en_kev: atomic_key(&atomic, "l_en_kev")?,
    };
    // NaN plays the upstream "conversion absent" sentinel role.
    let present = |v: Option<f64>| v.filter(|x| !x.is_nan());
    Ok(
        nucleide_spectroscopy::xray_lines(&data, present(k_conv), present(l_conv))
            .iter()
            .map(|l| (l.energy_kev, l.intensity))
            .collect(),
    )
}

/// SDEF decay-source card (E9) as `(normalized_bins, card_text)`.
///
/// `lines` carries caller-supplied `(energy_mev, intensity)` pairs; every
/// energy and intensity is an input (no evaluated data is vendored).
/// Intensities are merged at duplicate energies, sorted ascending, and
/// normalized to probabilities summing to 1.0. The card keeps the upstream
/// monoenergetic point-source field order (`POS`, optional `VEC ... DIR=1`,
/// `ERG`, `WGT`, `PAR`); one surviving line renders inline `ERG=<E>`, while
/// several render the discrete-distribution form `ERG=D1` with paired
/// `SI1 L` / `SP1 D` cards. That distribution syntax is parser-verified
/// surface only — MCNP sampling semantics are the caller's responsibility.
/// `particle` parses through the `nucleide-nuclei` dialect (`"Neutron"`,
/// `"Photon"`, `"Electron"`, ...); `version` is 5 or 6 and selects the
/// `PAR=` designator.
#[pyfunction]
#[pyo3(signature = (lines, x=0.0, y=0.0, z=0.0, u=0.0, v=0.0, w=0.0, weight=1.0, particle="Neutron", version=5))]
#[allow(clippy::too_many_arguments)]
fn spectroscopy_sdef_decay_source(
    lines: Vec<(f64, f64)>,
    x: f64,
    y: f64,
    z: f64,
    u: f64,
    v: f64,
    w: f64,
    weight: f64,
    particle: &str,
    version: u32,
) -> PyResult<(Vec<(f64, f64)>, String)> {
    let particle = particle
        .parse::<nucleide_nuclei::particles::ParticleId>()
        .map_err(|e| PyValueError::new_err(format!("spectroscopy: particle {e}")))?;
    let source = nucleide_spectroscopy::PointSource {
        x,
        y,
        z,
        u,
        v,
        w,
        weight,
        particle,
    };
    nucleide_spectroscopy::sdef_card(&lines, &source, version)
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Render a parsed spectrum as a Python dict.
fn spectrum_to_py(
    py: Python<'_>,
    spec: &nucleide_spectroscopy::GammaSpectrum,
) -> PyResult<Py<PyAny>> {
    use pyo3::types::PyDict;
    let d = PyDict::new(py);
    let s = &spec.spectrum;
    d.set_item("spec_name", &s.spec_name)?;
    d.set_item("start_chan_num", s.start_chan_num)?;
    d.set_item("num_channels", s.num_channels)?;
    d.set_item("channels", &s.channels)?;
    d.set_item("counts", &s.counts)?;
    d.set_item("ebin", &s.ebin)?;
    d.set_item("real_time", spec.real_time)?;
    d.set_item("live_time", spec.live_time)?;
    d.set_item("dead_time", spec.dead_time())?;
    d.set_item("det_id", &spec.det_id)?;
    d.set_item("det_descp", &spec.det_descp)?;
    d.set_item("start_date", &spec.start_date)?;
    d.set_item("start_time", &spec.start_time)?;
    d.set_item("calib_e_fit", &spec.calib_e_fit)?;
    d.set_item("calib_fwhm_fit", &spec.calib_fwhm_fit)?;
    d.set_item("file_name", &spec.file_name)?;
    Ok(d.into_any().unbind())
}

/// Parse dollar-format `.spe` text (first line must be `$SPEC_ID:`).
#[pyfunction]
fn spectroscopy_parse_dollar_spe(py: Python<'_>, text: &str) -> PyResult<Py<PyAny>> {
    let spec = nucleide_spectroscopy::parse_dollar_spe(text, "")
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    spectrum_to_py(py, &spec)
}

/// Parse plain-format `.spe` text (rejects the `$SPEC_ID:` magic).
#[pyfunction]
fn spectroscopy_parse_spe(py: Python<'_>, text: &str) -> PyResult<Py<PyAny>> {
    let spec = nucleide_spectroscopy::parse_plain_spe(text, "")
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    spectrum_to_py(py, &spec)
}

/// Read a dollar-format `.spe` file.
#[pyfunction]
fn spectroscopy_read_dollar_spe(py: Python<'_>, path: &str) -> PyResult<Py<PyAny>> {
    let text = std::fs::read_to_string(path).map_err(|e| PyValueError::new_err(e.to_string()))?;
    let spec = nucleide_spectroscopy::parse_dollar_spe(&text, path)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    spectrum_to_py(py, &spec)
}

/// Read a plain-format `.spe` file.
#[pyfunction]
fn spectroscopy_read_spe(py: Python<'_>, path: &str) -> PyResult<Py<PyAny>> {
    let text = std::fs::read_to_string(path).map_err(|e| PyValueError::new_err(e.to_string()))?;
    let spec = nucleide_spectroscopy::parse_plain_spe(&text, path)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    spectrum_to_py(py, &spec)
}

/// Parse decay-lines interchange TSV text into `(energy_MeV, intensity)`
/// pairs (`#` comments and blank lines skipped; E9 normalization stays in
/// `sdef_decay_source`).
#[pyfunction]
fn spectroscopy_parse_lines_tsv(text: &str) -> PyResult<Vec<(f64, f64)>> {
    nucleide_spectroscopy::parse_lines_tsv(text).map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Read a decay-lines interchange TSV file (same grammar as
/// `spectroscopy_parse_lines_tsv`).
#[pyfunction]
fn spectroscopy_read_decay_lines(path: &str) -> PyResult<Vec<(f64, f64)>> {
    let text = std::fs::read_to_string(path).map_err(|e| PyValueError::new_err(e.to_string()))?;
    nucleide_spectroscopy::parse_lines_tsv(&text).map_err(|e| PyValueError::new_err(e.to_string()))
}

// ---------------------------------------------------------------------------
// UQ-lite sampling kernel (thin glue over `linalg`; decay-only sub-scope)
// ---------------------------------------------------------------------------

fn uq_sample_err(e: nucleide_linalg::sample::SampleError) -> PyErr {
    PyValueError::new_err(e.to_string())
}

fn uq_decay_err(e: nucleide_linalg::decay::DecayError) -> PyErr {
    PyValueError::new_err(e.to_string())
}

/// Seeded multivariate-normal draws over a caller-supplied covariance block.
///
/// Returns a dict with `samples` (list of `n` row lists), `method`
/// (`"cholesky"` or `"eigen_clip"`), and the unclipped `min_eigen` /
/// `max_eigen` (`None` on the Cholesky path). Same
/// `(mean, cov, n, seed)` inputs always yield identical samples. Thin
/// wrapper over `nucleide-linalg` `sample`.
#[pyfunction]
fn uq_sample_mvn(
    py: Python<'_>,
    mean: Vec<f64>,
    cov: Vec<Vec<f64>>,
    n: usize,
    seed: u64,
) -> PyResult<Py<PyAny>> {
    use pyo3::types::PyDict;
    let set = nucleide_linalg::sample::sample_mvn(&mean, &cov, n, seed).map_err(uq_sample_err)?;
    let d = PyDict::new(py);
    d.set_item("samples", set.samples)?;
    d.set_item("method", set.method.name())?;
    match &set.method {
        nucleide_linalg::sample::FactorMethod::Cholesky => {
            d.set_item("min_eigen", py.None())?;
            d.set_item("max_eigen", py.None())?;
        }
        nucleide_linalg::sample::FactorMethod::EigenClip {
            min_eigen,
            max_eigen,
        } => {
            d.set_item("min_eigen", *min_eigen)?;
            d.set_item("max_eigen", *max_eigen)?;
        }
    }
    Ok(d.into_any().unbind())
}

/// Sample mean over draws (one entry per dimension).
#[pyfunction]
fn uq_sample_mean(samples: Vec<Vec<f64>>) -> PyResult<Vec<f64>> {
    nucleide_linalg::sample::sample_mean(&samples).map_err(uq_sample_err)
}

/// Unbiased sample covariance (`1/(n-1)`, matching SANDY `Samples.get_cov`).
#[pyfunction]
fn uq_sample_cov(samples: Vec<Vec<f64>>) -> PyResult<Vec<Vec<f64>>> {
    nucleide_linalg::sample::sample_cov(&samples).map_err(uq_sample_err)
}

/// Sample mean/covariance convergence diagnostics à la SANDY.
///
/// Returns a dict with `mean_err_max`, `cov_err_fro`, the echoed
/// `mean_tol`/`cov_tol`, and `passed`. Thin wrapper over
/// `nucleide-linalg` `sample`.
#[pyfunction]
fn uq_check_convergence(
    py: Python<'_>,
    mean: Vec<f64>,
    cov: Vec<Vec<f64>>,
    samples: Vec<Vec<f64>>,
    mean_tol: f64,
    cov_tol: f64,
) -> PyResult<Py<PyAny>> {
    use pyo3::types::PyDict;
    let rep = nucleide_linalg::sample::check_convergence(&mean, &cov, &samples, mean_tol, cov_tol)
        .map_err(uq_sample_err)?;
    let d = PyDict::new(py);
    d.set_item("mean_err_max", rep.mean_err_max)?;
    d.set_item("cov_err_fro", rep.cov_err_fro)?;
    d.set_item("mean_tol", rep.mean_tol)?;
    d.set_item("cov_tol", rep.cov_tol)?;
    d.set_item("passed", rep.passed)?;
    Ok(d.into_any().unbind())
}

/// Perturb one parent's kept branch fractions with relative deltas,
/// preserving the incoming `1 - BR(SF)` deficit by renormalisation.
#[pyfunction]
fn uq_perturb_branches(base: Vec<f64>, rel: Vec<f64>) -> PyResult<Vec<f64>> {
    nucleide_linalg::decay::perturb_branches(&base, &rel).map_err(uq_decay_err)
}

/// Perturb decay energies under `convention`
/// (`"relative"`/`"absolute"`/`"lognormal"`); negative results clamp to zero
/// (a no-op for lognormal draws, which stay positive for non-negative bases).
#[pyfunction]
fn uq_perturb_energies(base: Vec<f64>, delta: Vec<f64>, convention: &str) -> PyResult<Vec<f64>> {
    let conv = nucleide_linalg::sample::PerturbConvention::parse(convention)
        .map_err(PyValueError::new_err)?;
    nucleide_linalg::decay::perturb_energies(&base, &delta, conv).map_err(uq_decay_err)
}

/// Seeded log-normal draws: `x ~ N(mean_log, cov_log)` via the shared MVN
/// factor path and RNG, then `y = exp(x)` elementwise.
///
/// Returns the same dict shape as [`uq_sample_mvn`]; `mean_log`/`cov_log`
/// are log-space MVN parameters (never the moments of `y`). Thin wrapper
/// over `nucleide-linalg` `sample`.
#[pyfunction]
fn uq_sample_lognormal(
    py: Python<'_>,
    mean_log: Vec<f64>,
    cov: Vec<Vec<f64>>,
    n: usize,
    seed: u64,
) -> PyResult<Py<PyAny>> {
    use pyo3::types::PyDict;
    let set = nucleide_linalg::sample::sample_lognormal(&mean_log, &cov, n, seed)
        .map_err(uq_sample_err)?;
    let d = PyDict::new(py);
    d.set_item("samples", set.samples)?;
    d.set_item("method", set.method.name())?;
    match &set.method {
        nucleide_linalg::sample::FactorMethod::Cholesky => {
            d.set_item("min_eigen", py.None())?;
            d.set_item("max_eigen", py.None())?;
        }
        nucleide_linalg::sample::FactorMethod::EigenClip {
            min_eigen,
            max_eigen,
        } => {
            d.set_item("min_eigen", *min_eigen)?;
            d.set_item("max_eigen", *max_eigen)?;
        }
    }
    Ok(d.into_any().unbind())
}

/// Seeded Latin-hypercube draws over a caller-supplied covariance block.
///
/// Stratified `U(0,1)` draws (one jittered draw per stratum per dimension)
/// through the hand-rolled inverse-normal CDF, then the shared MVN factor
/// path and `x = μ + Bz` application. Returns the same dict shape as
/// [`uq_sample_mvn`]. Thin wrapper over `nucleide-linalg` `sample`.
#[pyfunction]
fn uq_sample_lhs(
    py: Python<'_>,
    mean: Vec<f64>,
    cov: Vec<Vec<f64>>,
    n: usize,
    seed: u64,
) -> PyResult<Py<PyAny>> {
    use pyo3::types::PyDict;
    let set = nucleide_linalg::sample::sample_lhs(&mean, &cov, n, seed).map_err(uq_sample_err)?;
    let d = PyDict::new(py);
    d.set_item("samples", set.samples)?;
    d.set_item("method", set.method.name())?;
    match &set.method {
        nucleide_linalg::sample::FactorMethod::Cholesky => {
            d.set_item("min_eigen", py.None())?;
            d.set_item("max_eigen", py.None())?;
        }
        nucleide_linalg::sample::FactorMethod::EigenClip {
            min_eigen,
            max_eigen,
        } => {
            d.set_item("min_eigen", *min_eigen)?;
            d.set_item("max_eigen", *max_eigen)?;
        }
    }
    Ok(d.into_any().unbind())
}

/// Closed-form log-normal mean `E[y_i] = exp(mu_i + C_ii/2)` over the
/// log-space `(mean_log, cov)` parameters.
#[pyfunction]
fn uq_lognormal_mean(mean_log: Vec<f64>, cov: Vec<Vec<f64>>) -> PyResult<Vec<f64>> {
    nucleide_linalg::sample::lognormal_mean(&mean_log, &cov).map_err(uq_sample_err)
}

/// Closed-form log-normal covariance
/// `Cov(y_i, y_j) = exp(mu_i + mu_j + (C_ii + C_jj)/2) (exp(C_ij) - 1)`.
#[pyfunction]
fn uq_lognormal_cov(mean_log: Vec<f64>, cov: Vec<Vec<f64>>) -> PyResult<Vec<Vec<f64>>> {
    nucleide_linalg::sample::lognormal_cov(&mean_log, &cov).map_err(uq_sample_err)
}

/// Passthrough copy of a perturbation vector (finiteness-checked).
#[pyfunction]
fn uq_passthrough(delta: Vec<f64>) -> PyResult<Vec<f64>> {
    nucleide_linalg::decay::passthrough(&delta).map_err(uq_decay_err)
}

/// Fission-yield perturbation over a caller-supplied block (same deficit
/// discipline as `perturb_branches`, preserving the incoming sum).
#[pyfunction]
fn uq_perturb_fission_yields(base: Vec<f64>, rel: Vec<f64>) -> PyResult<Vec<f64>> {
    nucleide_linalg::decay::perturb_fission_yields(&base, &rel).map_err(uq_decay_err)
}

// ---------------------------------------------------------------------------
// Thin reader facade bundle over existing Rust (no new math/data)
// ---------------------------------------------------------------------------

fn parse_projectile(flag: &str) -> PyResult<nucleide_nuclei::rxname::Projectile> {
    flag.parse::<nucleide_nuclei::rxname::Projectile>()
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

fn resolve_rx_id(spec: &Bound<'_, PyAny>) -> PyResult<u32> {
    if let Ok(id) = spec.extract::<u32>() {
        return Ok(id);
    }
    if let Ok(s) = spec.extract::<&str>() {
        return nucleide_nuclei::rxname::name_to_id(s)
            .map_err(|e| PyValueError::new_err(e.to_string()));
    }
    Err(PyTypeError::new_err(
        "expected reaction id (int) or name (str)",
    ))
}

/// Short `"(z,a)"`-style label for a reaction id ("" when unknown).
#[pyfunction]
fn rxname_label(id: u32) -> &'static str {
    nucleide_nuclei::rxname::label(id)
}

/// Long documentation string for a reaction id ("" when unknown).
#[pyfunction]
fn rxname_doc(id: u32) -> &'static str {
    nucleide_nuclei::rxname::doc(id)
}

/// Registry row for a reaction id as {id, name, mt, label, doc}, or None.
#[pyfunction]
fn rxname_reaction(py: Python<'_>, id: u32) -> PyResult<Option<Py<PyAny>>> {
    use pyo3::types::PyDict;
    Ok(nucleide_nuclei::rxname::reaction(id).map(|r| {
        let d = PyDict::new(py);
        d.set_item("id", r.id).ok();
        d.set_item("name", r.name).ok();
        d.set_item("mt", r.mt).ok();
        d.set_item("label", r.label).ok();
        d.set_item("doc", r.doc).ok();
        d.into_any().unbind()
    }))
}

/// Reaction channel connecting `from_nucid` to `to_nucid` under `projectile`.
#[pyfunction]
#[pyo3(signature = (from_nucid, to_nucid, projectile="n"))]
fn rxname_id_from_nucdelta(from_nucid: u32, to_nucid: u32, projectile: &str) -> PyResult<u32> {
    let p = parse_projectile(projectile)?;
    nucleide_nuclei::rxname::id_from_nucdelta(from_nucid, to_nucid, p)
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Daughter nuclide (GNDS name) when `parent` undergoes `rx` under `projectile`.
#[pyfunction]
#[pyo3(signature = (parent, rx, projectile="n"))]
fn rxname_child(parent: &str, rx: &Bound<'_, PyAny>, projectile: &str) -> PyResult<String> {
    let p = parse_projectile(projectile)?;
    let rx = resolve_rx_id(rx)?;
    let parent_id = NuclideId::from_name(parent)
        .map_err(|e| PyValueError::new_err(format!("`{parent}`: {e}")))?;
    nucleide_nuclei::rxname::child(parent_id, rx, p)
        .map(|id| id.to_name())
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Parent nuclide (GNDS name) whose `rx` under `projectile` yields `child`.
#[pyfunction]
#[pyo3(signature = (child, rx, projectile="n"))]
fn rxname_parent(child: &str, rx: &Bound<'_, PyAny>, projectile: &str) -> PyResult<String> {
    let p = parse_projectile(projectile)?;
    let rx = resolve_rx_id(rx)?;
    let child_id = NuclideId::from_name(child)
        .map_err(|e| PyValueError::new_err(format!("`{child}`: {e}")))?;
    nucleide_nuclei::rxname::parent(child_id, rx, p)
        .map(|id| id.to_name())
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// True when `spec` names a particle or a nuclide (hydrogen or heavy ion).
#[pyfunction]
fn particle_is_valid(spec: &str) -> bool {
    nucleide_nuclei::particles::is_valid(spec)
}

/// True when `n` is a registered PDC number.
#[pyfunction]
fn particle_is_valid_pdc(n: i32) -> bool {
    nucleide_nuclei::particles::is_valid_pdc(n)
}

/// True when `spec` is ground-state hydrogen.
#[pyfunction]
fn particle_is_hydrogen(spec: &str) -> bool {
    nucleide_nuclei::particles::is_hydrogen(spec)
}

/// True when `spec` is a nuclide heavier than ground-state hydrogen.
#[pyfunction]
fn particle_is_heavy_ion(spec: &str) -> bool {
    nucleide_nuclei::particles::is_heavy_ion(spec)
}

/// Gut-uptake fraction `f1` for ingestion rows, or None (source default EPA).
#[pyfunction]
#[pyo3(signature = (name, source="EPA"))]
fn dose_f1(name: &str, source: &str) -> PyResult<Option<f64>> {
    NuclideId::from_name(name).map_err(wrap_nucid_err)?;
    let s = parse_dose_source(source)?;
    Ok(nucleide_nuclei::data::dose_f1_by_name(name, s))
}

/// Lung-clearance class for inhalation rows, or None (source default EPA).
#[pyfunction]
#[pyo3(signature = (name, source="EPA"))]
fn dose_lung_model(name: &str, source: &str) -> PyResult<Option<char>> {
    NuclideId::from_name(name).map_err(wrap_nucid_err)?;
    let s = parse_dose_source(source)?;
    Ok(nucleide_nuclei::data::dose_lung_model_by_name(name, s))
}

/// Canonical element symbol for a bare-symbol comp key, or None.
fn bare_element_z(name: &str) -> Option<u32> {
    let t = name.trim();
    if t.is_empty() {
        return None;
    }
    let mut chars = t.chars();
    let first = chars.next()?.to_uppercase().next()?;
    let rest: String = chars.collect::<String>().to_lowercase();
    let canon = format!("{first}{rest}");
    nucleide_nuclei::element_z(&canon)
}

fn mat_from_comp_elements(comp: BTreeMap<String, f64>) -> PyResult<nucleide_material::Material> {
    let mut mat = nucleide_material::Material::new();
    for (name, grams) in &comp {
        let id = match NuclideId::from_name(name) {
            Ok(id) => id,
            Err(_) => match bare_element_z(name) {
                Some(z) => NuclideId::from_nucid(z * 10_000_000),
                None => {
                    return Err(PyValueError::new_err(format!(
                        "`{name}`: unknown nuclide or element"
                    )));
                }
            },
        };
        mat.add_nuclide(id, *grams);
    }
    Ok(mat)
}

fn mat_to_comp_elements(mat: &nucleide_material::Material) -> BTreeMap<String, f64> {
    let mut out = BTreeMap::new();
    for (&id, &grams) in &mat.comp {
        let key = if id.a() == 0 && id.state() == 0 {
            nucleide_nuclei::element_symbol(id.z())
                .unwrap_or("X")
                .to_string()
        } else {
            id.to_name()
        };
        *out.entry(key).or_insert(0.0) += grams;
    }
    out
}

/// Mix streams weighted by relative mass amounts (thin wrapper over
/// `Material::mix_by_mass`). Bare element symbols map to natural-element
/// placeholders; collapsed/elemental keys round-trip as symbols.
#[pyfunction]
fn mix_by_mass(parts: Vec<(BTreeMap<String, f64>, f64)>) -> PyResult<BTreeMap<String, f64>> {
    let mats: Vec<nucleide_material::Material> = parts
        .iter()
        .map(|(comp, _)| mat_from_comp_elements(comp.clone()))
        .collect::<PyResult<_>>()?;
    let refs: Vec<(&nucleide_material::Material, f64)> =
        mats.iter().zip(parts.iter().map(|(_, w)| *w)).collect();
    let out = nucleide_material::Material::mix_by_mass(&refs)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    Ok(mat_to_comp_elements(&out))
}

/// Mix streams weighted by relative volumes, converting through each
/// stream's density (thin wrapper over `Material::mix_by_volume`).
/// `parts` holds `(comp, volume, density)` triples.
#[pyfunction]
fn mix_by_volume(parts: Vec<(BTreeMap<String, f64>, f64, f64)>) -> PyResult<BTreeMap<String, f64>> {
    let mut mats: Vec<nucleide_material::Material> = Vec::with_capacity(parts.len());
    for (comp, _, density) in &parts {
        let mut m = mat_from_comp_elements(comp.clone())?;
        m.set_density(Some(*density));
        mats.push(m);
    }
    let refs: Vec<(&nucleide_material::Material, f64)> =
        mats.iter().zip(parts.iter().map(|(_, v, _)| *v)).collect();
    let out = nucleide_material::Material::mix_by_volume(&refs)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    Ok(mat_to_comp_elements(&out))
}

/// Specific activity of a composition in Bq/g (AME2020 + chain decays).
#[pyfunction]
fn specific_activity(comp: BTreeMap<String, f64>) -> PyResult<f64> {
    let mat = mat_from_comp_elements(comp)?;
    let analytics = nucleide_material::Analytics {
        masses: &nucleide_material::Ame2020,
        decays: &nucleide_material::ChainDecays,
    };
    mat.specific_activity(&analytics)
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Serialize a `<materials>` document bundling named materials.
/// `entries` holds `(name, comp, density)` triples; `cross_sections`
/// sets the root attribute when given.
#[pyfunction]
#[pyo3(signature = (entries, cross_sections=None))]
fn materials_doc_to_xml(
    entries: Vec<(String, BTreeMap<String, f64>, f64)>,
    cross_sections: Option<String>,
) -> PyResult<String> {
    let mut doc = nucleide_material::MaterialsDoc::new();
    if let Some(path) = cross_sections {
        doc = doc.cross_sections(path);
    }
    for (name, comp, density) in entries {
        let mut mat = mat_from_comp_elements(comp)?;
        mat.set_density(Some(density));
        doc = doc.push(name, mat);
    }
    doc.to_xml()
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Replace natural-element placeholders with isotopic breakdowns (AME2020 +
/// natural abundances). Bare element symbols are placeholders; nuclide
/// names pass through untouched.
#[pyfunction]
fn expand_elements(comp: BTreeMap<String, f64>) -> PyResult<BTreeMap<String, f64>> {
    let mut mat = mat_from_comp_elements(comp)?;
    mat.expand_elements(
        &nucleide_material::Ame2020,
        &nucleide_material::NaturalAbundances,
    )
    .map_err(|e| PyValueError::new_err(e.to_string()))?;
    Ok(mat_to_comp_elements(&mat))
}

/// Fold every nuclide into its element placeholder (bare-symbol keys).
#[pyfunction]
fn collapse_elements(comp: BTreeMap<String, f64>) -> PyResult<BTreeMap<String, f64>> {
    let mat = mat_from_comp_elements(comp)?;
    Ok(mat_to_comp_elements(&mat.collapse_elements()))
}

fn parse_fluka_nuc(spec: &str) -> PyResult<nucleide_fluka_io::material::FlukaNuc> {
    use nucleide_fluka_io::material::FlukaNuc;
    if let Ok(id) = NuclideId::from_name(spec) {
        return Ok(FlukaNuc::Nuclide(id));
    }
    if let Some(z) = bare_element_z(spec) {
        return Ok(FlukaNuc::Element(z));
    }
    if let Ok(z) = spec.trim().parse::<u32>() {
        if nucleide_nuclei::element_symbol(z).is_some() {
            return Ok(FlukaNuc::Element(z));
        }
    }
    Err(PyValueError::new_err(format!(
        "`{spec}`: unknown nuclide or element"
    )))
}

/// Render the MATERIAL record for an elemental nuclide ("", when builtin).
#[pyfunction]
fn fluka_material_str(fid: u32, nuc: &str, density: f64) -> PyResult<String> {
    let parsed = parse_fluka_nuc(nuc)?;
    nucleide_fluka_io::material::material_str(fid, parsed, density)
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Render MATERIAL + COMPOUND records for a compound.
/// `frac_type` is "mass" (default) or "atom"; `components` holds
/// `(nuclide-or-element, fraction)` pairs.
#[pyfunction]
#[pyo3(signature = (fid, compound_name, density, frac_type="mass", components=None))]
fn fluka_compound_str(
    fid: u32,
    compound_name: &str,
    density: f64,
    frac_type: &str,
    components: Option<Vec<(String, f64)>>,
) -> PyResult<String> {
    use nucleide_fluka_io::material::{Component, FracType};
    let frac = match frac_type.trim().to_ascii_lowercase().as_str() {
        "mass" => FracType::Mass,
        "atom" => FracType::Atom,
        other => {
            return Err(PyValueError::new_err(format!(
                "frac_type must be mass|atom, got `{other}`"
            )));
        }
    };
    let pairs = components.unwrap_or_default();
    let comps: Vec<Component> = pairs
        .iter()
        .map(|(nuc, frac)| parse_fluka_nuc(nuc).map(|n| Component::new(n, *frac)))
        .collect::<PyResult<_>>()?;
    nucleide_fluka_io::material::compound_str(fid, compound_name, density, frac, &comps)
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Sorted built-in FLUKA material names.
#[pyfunction]
fn fluka_builtin_set() -> Vec<String> {
    let mut out: Vec<String> = nucleide_fluka_io::material::builtin_set()
        .into_iter()
        .map(str::to_string)
        .collect();
    out.sort();
    out
}

/// Validate an ALARA deck's cross-references (parse + `validate`).
#[pyfunction]
fn alara_validate_deck(text: &str) -> PyResult<()> {
    let deck = nucleide_alara_io::AlaraDeck::parse(text)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    deck.validate()
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Reject an unknown ALARA block keyword (`line` is 1-based).
#[pyfunction]
fn alara_check_block(block: &str, line: usize) -> PyResult<()> {
    nucleide_alara_io::AlaraDeck::check_block(block, line)
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Sum of an ALARA group-flux spectrum over its groups.
#[pyfunction]
fn alara_flux_total(name: &str, text: &str) -> PyResult<f64> {
    nucleide_alara_io::FluxSpec::parse(name, text)
        .map(|f| f.total())
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Number of groups in an ALARA group-flux spectrum.
#[pyfunction]
fn alara_flux_len(name: &str, text: &str) -> PyResult<usize> {
    nucleide_alara_io::FluxSpec::parse(name, text)
        .map(|f| f.len())
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Keep only the `total` aggregate rows of an ALARA/FISPACT response frame.
#[pyfunction]
fn alara_output_totals(
    py: Python<'_>,
    text: &str,
    run_lbl: &str,
) -> PyResult<Vec<BTreeMap<String, Py<PyAny>>>> {
    let owned_text = text.to_owned();
    let owned_lbl = run_lbl.to_owned();
    let frame = py
        .detach(move || {
            nucleide_alara_io::output::ResponseFrame::parse(&owned_text, &owned_lbl)
                .map(|f| f.totals())
        })
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    Ok(frame
        .rows
        .iter()
        .map(|r| fispact_row_to_map(py, r))
        .collect())
}

/// Sum of `value` over SpecificActivity rows of a response frame.
#[pyfunction]
fn alara_output_total_activity(text: &str, run_lbl: &str) -> PyResult<f64> {
    nucleide_alara_io::output::ResponseFrame::parse(text, run_lbl)
        .map(|f| f.total_activity())
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Sum over every group and strength of a `.photonSrc` listing.
#[pyfunction]
fn alara_photon_total_strength(text: &str) -> PyResult<f64> {
    nucleide_alara_io::PhotonSource::from_str(text)
        .map(|p| p.total_strength())
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Total schedule time in seconds over a deck's expanded flat steps.
#[pyfunction]
#[pyo3(signature = (deck_text, top=None))]
fn alara_schedule_total_time(deck_text: &str, top: Option<&str>) -> PyResult<f64> {
    let owned = deck_text.to_owned();
    let owned_top = top.map(str::to_owned);
    let steps =
        expand_deck_schedules(&owned, owned_top.as_deref()).map_err(PyValueError::new_err)?;
    Ok(nucleide_alara_io::schedule::total_time(&steps))
}

/// Vendored EU 2013/59/Euratom Annex VII Table A clearance levels.
///
/// Returns a dict mapping nuclide names (GNDS spelling, e.g. `"H-3"`,
/// `"Co-60"`) to activity-concentration clearance levels in Bq/g (numerically
/// identical to the directive's kBq/kg). Official legal text transcribed from
/// EUR-Lex CELEX:32013L0059 (Annex VII Table A, accessed 2026-09-15),
/// reusable with attribution per Decision (EU) 2011/833. Screening default
/// only — see `nucleide-alara-io` `clearance` for the unit-basis contract.
#[pyfunction]
fn alara_clearance_eu_table() -> BTreeMap<String, f64> {
    nucleide_alara_io::ClearanceTable::eu_annex_vii()
        .iter()
        .map(|(nuc, limit)| (nucleide_nuclei::dialects::serpent(nuc), limit))
        .collect()
}

/// Resolve a caller-supplied inventory/limits dict key to a `NuclideId`.
fn clearance_key(key: &str) -> PyResult<NuclideId> {
    nucleide_nuclei::dialects::normalize_nuclide_name(key)
        .map_err(|e| PyValueError::new_err(format!("bad nuclide name `{key}`: {e}")))
}

/// Build `(NuclideId, f64)` pairs from a `{name: value}` dict.
fn clearance_pairs(map: &BTreeMap<String, f64>, what: &str) -> PyResult<Vec<(NuclideId, f64)>> {
    map.iter()
        .map(|(name, value)| Ok((clearance_key(name)?, *value)))
        .collect::<PyResult<_>>()
        .map_err(|e| PyValueError::new_err(format!("{what}: {e}")))
}

/// Build a caller-supplied clearance table from a `{name: limit_Bq_per_g}` dict.
fn clearance_table_from(
    map: &BTreeMap<String, f64>,
) -> PyResult<nucleide_alara_io::ClearanceTable> {
    let mut table = nucleide_alara_io::ClearanceTable::new();
    for (nuc, limit) in clearance_pairs(map, "limits")? {
        table
            .insert(nuc, limit)
            .map_err(|e| PyValueError::new_err(e.to_string()))?;
    }
    Ok(table)
}

/// Clearance index CI = sum_i A_i / CL_i over a parsed inventory.
///
/// `inventory` maps nuclide names to activities; `limits` maps nuclide names
/// to clearance levels (a dict, or None for the vendored EU 2013/59/Euratom
/// Annex VII Table A default in Bq/g). Activities and limits must share one
/// unit basis (Bq/g against the default table). Every inventory nuclide must
/// have a limit entry; negative/non-finite activities raise `ValueError`.
#[pyfunction]
#[pyo3(signature = (inventory, limits=None))]
fn alara_clearance_index(
    inventory: BTreeMap<String, f64>,
    limits: Option<BTreeMap<String, f64>>,
) -> PyResult<f64> {
    let table = match limits {
        Some(map) => clearance_table_from(&map)?,
        None => nucleide_alara_io::ClearanceTable::eu_annex_vii(),
    };
    let pairs = clearance_pairs(&inventory, "inventory")?;
    nucleide_alara_io::clearance_index(&pairs, &table)
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Sum-of-fractions screening over a parsed inventory.
///
/// Same inputs as `alara_clearance_index`. Returns a dict with `sum`
/// (sum_i A_i / CL_i), `class` ("satisfied" when the sum does not exceed 1,
/// boundary included; "exceeded" otherwise), `max_fraction`, and
/// `max_nuclide` (dominant contributor, or None for an empty inventory).
/// RS-G-1.7 §5 rule referenced by
/// designation; screening arithmetic, not a compliance decision.
#[pyfunction]
#[pyo3(signature = (inventory, limits=None))]
fn alara_sum_of_fractions(
    py: Python<'_>,
    inventory: BTreeMap<String, f64>,
    limits: Option<BTreeMap<String, f64>>,
) -> PyResult<BTreeMap<String, Py<PyAny>>> {
    let table = match limits {
        Some(map) => clearance_table_from(&map)?,
        None => nucleide_alara_io::ClearanceTable::eu_annex_vii(),
    };
    let pairs = clearance_pairs(&inventory, "inventory")?;
    let out = nucleide_alara_io::sum_of_fractions(&pairs, &table)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    let mut d = BTreeMap::new();
    d.insert(
        "sum".to_string(),
        out.sum.into_pyobject(py).unwrap().unbind().into_any(),
    );
    d.insert(
        "class".to_string(),
        out.class
            .to_string()
            .into_pyobject(py)
            .unwrap()
            .unbind()
            .into_any(),
    );
    d.insert(
        "max_fraction".to_string(),
        out.max_fraction
            .into_pyobject(py)
            .unwrap()
            .unbind()
            .into_any(),
    );
    d.insert(
        "max_nuclide".to_string(),
        out.max_nuclide
            .map(nucleide_nuclei::dialects::serpent)
            .into_pyobject(py)
            .unwrap()
            .unbind()
            .into_any(),
    );
    Ok(d)
}

/// Find a TAPE6 record by nuclide name, or None.
#[pyfunction]
fn origen_tape6_find(py: Python<'_>, text: &str, nuclide: &str) -> PyResult<Option<Py<PyAny>>> {
    use pyo3::types::PyDict;
    let owned = text.to_owned();
    let query = nuclide.to_owned();
    let found = py
        .detach(move || nucleide_origen_io::Tape6::parse(&owned).map(|t| t.find(&query).cloned()))
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    Ok(found.map(|r| {
        let d = PyDict::new(py);
        d.set_item("nuclide", &r.nuclide).ok();
        d.set_item("grams", r.grams).ok();
        d.set_item("activity_bq", r.activity_bq).ok();
        d.into_any().unbind()
    }))
}

/// Total TAPE6 inventory activity in becquerel.
#[pyfunction]
fn origen_tape6_total_activity(text: &str) -> PyResult<f64> {
    nucleide_origen_io::Tape6::parse(text)
        .map(|t| t.total_activity())
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Find a TAPE9 decay entry by nuclide name, or None.
#[pyfunction]
fn origen_tape9_find(py: Python<'_>, text: &str, nuclide: &str) -> PyResult<Option<Py<PyAny>>> {
    use pyo3::types::PyDict;
    let owned = text.to_owned();
    let query = nuclide.to_owned();
    let found = py
        .detach(move || {
            nucleide_origen_io::Tape9Entry::parse(&owned)
                .map(|entries| nucleide_origen_io::Tape9Entry::find(&entries, &query).cloned())
        })
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    Ok(found.map(|e| {
        let d = PyDict::new(py);
        d.set_item("nuclide", &e.nuclide).ok();
        d.set_item("decay_const", e.decay_const).ok();
        d.into_any().unbind()
    }))
}

/// Number of spatial points in an RTFLUX/ATFLUX/RZFLUX file.
#[pyfunction]
#[pyo3(signature = (text, kind="rtflux"))]
fn cccc_rtflux_npoints(text: &str, kind: &str) -> PyResult<usize> {
    let flux_kind = parse_flux_kind(kind)?;
    nucleide_cccc_io::FluxFile::parse(flux_kind, text)
        .map(|f| f.npoints())
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Flux vector for point `i`, or None when out of range.
#[pyfunction]
#[pyo3(signature = (text, kind="rtflux", index=0))]
fn cccc_rtflux_point(text: &str, kind: &str, index: usize) -> PyResult<Option<Vec<f64>>> {
    let flux_kind = parse_flux_kind(kind)?;
    let flux = nucleide_cccc_io::FluxFile::parse(flux_kind, text)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    Ok(flux.point(index).map(<[f64]>::to_vec))
}

/// Sum of all flux values in an RTFLUX/ATFLUX/RZFLUX file.
#[pyfunction]
#[pyo3(signature = (text, kind="rtflux"))]
fn cccc_rtflux_total(text: &str, kind: &str) -> PyResult<f64> {
    let flux_kind = parse_flux_kind(kind)?;
    nucleide_cccc_io::FluxFile::parse(flux_kind, text)
        .map(|f| f.total())
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

fn parse_flux_kind(kind: &str) -> PyResult<nucleide_cccc_io::rtflux::FluxKind> {
    match kind.to_ascii_lowercase().as_str() {
        "rtflux" => Ok(nucleide_cccc_io::rtflux::FluxKind::Rtflux),
        "atflux" => Ok(nucleide_cccc_io::rtflux::FluxKind::Atflux),
        "rzflux" => Ok(nucleide_cccc_io::rtflux::FluxKind::Rzflux),
        other => Err(PyValueError::new_err(format!(
            "kind must be rtflux|atflux|rzflux, got `{other}`"
        ))),
    }
}

/// Find an ISOTXS nuclide by label, or None.
#[pyfunction]
fn cccc_isotxs_find(py: Python<'_>, text: &str, label: &str) -> PyResult<Option<Py<PyAny>>> {
    use pyo3::types::PyDict;
    let owned = text.to_owned();
    let query = label.to_owned();
    let found = py
        .detach(move || {
            nucleide_cccc_io::IsotxsLib::parse(&owned).map(|lib| lib.find(&query).cloned())
        })
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    Ok(found.map(|n| {
        let d = PyDict::new(py);
        d.set_item("label", &n.label).ok();
        d.set_item("zaid", &n.zaid).ok();
        d.set_item("groups", n.groups).ok();
        d.set_item("total_xs", n.total_xs.clone()).ok();
        d.into_any().unbind()
    }))
}

/// Number of nuclides in an ISOTXS library.
#[pyfunction]
fn cccc_isotxs_len(text: &str) -> PyResult<usize> {
    nucleide_cccc_io::IsotxsLib::parse(text)
        .map(|lib| lib.len())
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Identify a FISPACT-II output by its `.fis` suffix convention.
#[pyfunction]
fn fispact_is_output(path: &str) -> bool {
    nucleide_fispact_io::is_fispact_output(path)
}

/// Product-per-feed mass ratio for assays `x_feed`, `x_prod`, `x_tail`.
#[pyfunction]
fn enrichment_prod_per_feed(x_feed: f64, x_prod: f64, x_tail: f64) -> f64 {
    nucleide_enrichment::prod_per_feed(x_feed, x_prod, x_tail)
}

/// Tails-per-feed mass ratio.
#[pyfunction]
fn enrichment_tail_per_feed(x_feed: f64, x_prod: f64, x_tail: f64) -> f64 {
    nucleide_enrichment::tail_per_feed(x_feed, x_prod, x_tail)
}

/// Tails-per-product mass ratio.
#[pyfunction]
fn enrichment_tail_per_prod(x_feed: f64, x_prod: f64, x_tail: f64) -> f64 {
    nucleide_enrichment::tail_per_prod(x_feed, x_prod, x_tail)
}

/// Feed-per-product mass ratio.
#[pyfunction]
fn enrichment_feed_per_prod(x_feed: f64, x_prod: f64, x_tail: f64) -> f64 {
    nucleide_enrichment::feed_per_prod(x_feed, x_prod, x_tail)
}

/// Feed-per-tails mass ratio.
#[pyfunction]
fn enrichment_feed_per_tail(x_feed: f64, x_prod: f64, x_tail: f64) -> f64 {
    nucleide_enrichment::feed_per_tail(x_feed, x_prod, x_tail)
}

/// Product-per-tails mass ratio.
#[pyfunction]
fn enrichment_prod_per_tail(x_feed: f64, x_prod: f64, x_tail: f64) -> f64 {
    nucleide_enrichment::prod_per_tail(x_feed, x_prod, x_tail)
}

/// Stage separation factor for a component of mass `m_i`.
#[pyfunction]
#[allow(non_snake_case)]
fn enrichment_alphastar_i(alpha: f64, Mstar: f64, M_i: f64) -> f64 {
    nucleide_enrichment::alphastar_i(alpha, Mstar, M_i)
}

/// Validated delayed-neutron data from OpenMC IFP kinetics data.
///
/// OpenMC's IFP estimator reports effective delayed fractions (`betas`)
/// and the generation time (`lambda_gen`) but no precursor decay
/// constants: the caller supplies `lambdas` from the same data library.
/// Returns {betas, lambdas, lambda_gen, beta_total, groups}.
#[pyfunction]
fn kinetics_from_ifp(
    py: Python<'_>,
    betas: Vec<f64>,
    lambda_gen: f64,
    lambdas: Vec<f64>,
) -> PyResult<Py<PyAny>> {
    use pyo3::types::PyDict;
    let params = nucleide_kinetics::KineticParams::from_ifp(betas, lambda_gen, lambdas)
        .map_err(|e| PyValueError::new_err(e.to_string()))?;
    let d = PyDict::new(py);
    d.set_item("betas", params.betas()).ok();
    d.set_item("lambdas", params.lambdas()).ok();
    d.set_item("lambda_gen", params.lambda_gen()).ok();
    d.set_item("beta_total", params.beta_total()).ok();
    d.set_item("groups", params.groups()).ok();
    Ok(d.into_any().unbind())
}

/// Run MAGIC with explicit array selection and parameters.
/// `selection` is "total" (default) or "per_group".
#[pyfunction]
#[pyo3(signature = (tally, selection="total", tolerance=0.5, null_value=0.0))]
fn magic_with(
    tally: &PyMeshTally,
    selection: &str,
    tolerance: f64,
    null_value: f64,
) -> PyResult<PyMagicOutput> {
    let sel = match selection.trim().to_ascii_lowercase().as_str() {
        "total" => nucleide_vr_tools::magic::MagicSelection::Total,
        "per_group" | "pergroup" | "per-group" => {
            nucleide_vr_tools::magic::MagicSelection::PerGroup
        }
        other => {
            return Err(PyValueError::new_err(format!(
                "selection must be total|per_group, got `{other}`"
            )));
        }
    };
    let params = nucleide_vr_tools::magic::MagicParams {
        tolerance,
        null_value,
    };
    nucleide_vr_tools::magic::magic_with(&tally.inner, sel, params)
        .map(|inner| PyMagicOutput { inner })
        .map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Emit MAGIC weight windows as an OpenMC `settings.xml` fragment (`<mesh>`
/// + `<weight_windows>` elements to paste inside the existing `<settings>`
/// root). Returns `{"xml": str, "notes": list[str]}`.
#[pyfunction]
#[pyo3(signature = (tally, output, mesh_id=1, window_id=1, upper_bound_ratio=5.0, survival_ratio=3.0, max_split=10, weight_cutoff=1e-38))]
#[allow(clippy::too_many_arguments)]
fn emit_openmc_weight_windows(
    py: Python<'_>,
    tally: &PyMeshTally,
    output: &PyMagicOutput,
    mesh_id: u32,
    window_id: u32,
    upper_bound_ratio: f64,
    survival_ratio: f64,
    max_split: u32,
    weight_cutoff: f64,
) -> PyResult<Py<PyAny>> {
    use pyo3::types::PyDict;
    let options = nucleide_vr_tools::windows::OpenMcOptions {
        mesh_id,
        window_id,
        upper_bound_ratio,
        survival_ratio,
        max_split,
        weight_cutoff,
    };
    let out = nucleide_vr_tools::windows::emit_openmc_weight_windows(
        &output.inner,
        &tally.inner,
        &options,
    )
    .map_err(|e| PyValueError::new_err(e.to_string()))?;
    let d = PyDict::new(py);
    d.set_item("xml", out.xml)?;
    d.set_item("notes", out.notes)?;
    Ok(d.into_any().unbind())
}

/// Emit MAGIC weight windows as a Serpent-readable weight-window file in the
/// MCNP WWINP text spelling (`wwin <name> wf "<file>" 2`). Returns
/// `{"text": str, "card": str, "notes": list[str]}`.
#[pyfunction]
#[pyo3(signature = (tally, output, name="ww1", file="wwindows.wwd"))]
fn emit_serpent_wwin(
    py: Python<'_>,
    tally: &PyMeshTally,
    output: &PyMagicOutput,
    name: &str,
    file: &str,
) -> PyResult<Py<PyAny>> {
    use pyo3::types::PyDict;
    let out =
        nucleide_vr_tools::windows::emit_serpent_wwin(&output.inner, &tally.inner, name, file)
            .map_err(|e| PyValueError::new_err(e.to_string()))?;
    let d = PyDict::new(py);
    d.set_item("text", out.text)?;
    d.set_item("card", out.card)?;
    d.set_item("notes", out.notes)?;
    Ok(d.into_any().unbind())
}

/// Check one `stat:sum:<key>:<24-char value>` MCPL header comment.
#[pyfunction]
fn mcpl_statsum_validate(comment: &str) -> PyResult<String> {
    nucleide_mcpl_io::statsum_validate(comment)
        .map(str::to_string)
        .map_err(PyValueError::new_err)
}

/// Build a well-formed `stat:sum:` MCPL header comment.
#[pyfunction]
fn mcpl_statsum_comment(key: &str, value: f64) -> PyResult<String> {
    nucleide_mcpl_io::statsum_comment(key, value).map_err(|e| PyValueError::new_err(e.to_string()))
}

/// Python module entry point.
#[pymodule]
fn _internal(m: &Bound<'_, PyModule>) -> PyResult<()> {
    m.add_function(wrap_pyfunction!(version, m)?)?;
    m.add_function(wrap_pyfunction!(from_zaid, m)?)?;
    m.add_function(wrap_pyfunction!(atomic_mass, m)?)?;
    m.add_function(wrap_pyfunction!(natural_abundance, m)?)?;
    m.add_function(wrap_pyfunction!(rxname_id, m)?)?;
    m.add_function(wrap_pyfunction!(rxname_name, m)?)?;
    m.add_function(wrap_pyfunction!(rxname_mt, m)?)?;
    m.add_function(wrap_pyfunction!(rxname_label, m)?)?;
    m.add_function(wrap_pyfunction!(rxname_doc, m)?)?;
    m.add_function(wrap_pyfunction!(rxname_reaction, m)?)?;
    m.add_function(wrap_pyfunction!(rxname_id_from_nucdelta, m)?)?;
    m.add_function(wrap_pyfunction!(rxname_child, m)?)?;
    m.add_function(wrap_pyfunction!(rxname_parent, m)?)?;
    m.add_function(wrap_pyfunction!(particle_is_valid, m)?)?;
    m.add_function(wrap_pyfunction!(particle_is_valid_pdc, m)?)?;
    m.add_function(wrap_pyfunction!(particle_is_hydrogen, m)?)?;
    m.add_function(wrap_pyfunction!(particle_is_heavy_ion, m)?)?;
    m.add_function(wrap_pyfunction!(dose_f1, m)?)?;
    m.add_function(wrap_pyfunction!(dose_lung_model, m)?)?;
    m.add_function(wrap_pyfunction!(read_xsdir, m)?)?;
    m.add_function(wrap_pyfunction!(read_meshtal, m)?)?;
    m.add_function(wrap_pyfunction!(read_wwinp, m)?)?;
    m.add_function(wrap_pyfunction!(read_mctal, m)?)?;
    m.add_function(wrap_pyfunction!(read_ssw, m)?)?;
    m.add_function(wrap_pyfunction!(read_ptrac, m)?)?;
    m.add_function(wrap_pyfunction!(read_mcpl, m)?)?;
    m.add_function(wrap_pyfunction!(write_mcpl, m)?)?;
    m.add_function(wrap_pyfunction!(ssw2mcpl, m)?)?;
    m.add_function(wrap_pyfunction!(mcpl2ssw, m)?)?;
    m.add_function(wrap_pyfunction!(merge_mcpl, m)?)?;
    m.add_function(wrap_pyfunction!(extract_mcpl, m)?)?;
    m.add_function(wrap_pyfunction!(mcpl_stats, m)?)?;
    m.add_function(wrap_pyfunction!(repair_mcpl, m)?)?;
    m.add_function(wrap_pyfunction!(read_endl, m)?)?;
    m.add_function(wrap_pyfunction!(endl_endftod, m)?)?;
    m.add_function(wrap_pyfunction!(combine_ssw_files, m)?)?;
    m.add_function(wrap_pyfunction!(read_chain, m)?)?;
    m.add_function(wrap_pyfunction!(build_depletion_system, m)?)?;
    m.add_function(wrap_pyfunction!(deplete, m)?)?;
    m.add_function(wrap_pyfunction!(deplete_series, m)?)?;
    m.add_function(wrap_pyfunction!(simple_xs, m)?)?;
    m.add_function(wrap_pyfunction!(scattering_length, m)?)?;
    m.add_function(wrap_pyfunction!(decay_energy, m)?)?;
    m.add_function(wrap_pyfunction!(decay_branches, m)?)?;
    m.add_function(wrap_pyfunction!(decay_branch_fraction, m)?)?;
    m.add_function(wrap_pyfunction!(fission_yields, m)?)?;
    m.add_function(wrap_pyfunction!(fission_yield, m)?)?;
    m.add_function(wrap_pyfunction!(normalize_nuclide, m)?)?;
    m.add_function(wrap_pyfunction!(decay_heat, m)?)?;
    m.add_function(wrap_pyfunction!(dose_factor, m)?)?;
    m.add_function(wrap_pyfunction!(dose_per_g, m)?)?;
    m.add_function(wrap_pyfunction!(parse_fgr15_table, m)?)?;
    m.add_function(wrap_pyfunction!(fgr15_age_index, m)?)?;
    m.add_function(wrap_pyfunction!(mix_by_mass, m)?)?;
    m.add_function(wrap_pyfunction!(mix_by_volume, m)?)?;
    m.add_function(wrap_pyfunction!(specific_activity, m)?)?;
    m.add_function(wrap_pyfunction!(materials_doc_to_xml, m)?)?;
    m.add_function(wrap_pyfunction!(expand_elements, m)?)?;
    m.add_function(wrap_pyfunction!(collapse_elements, m)?)?;
    m.add_function(wrap_pyfunction!(read_serpent, m)?)?;
    m.add_function(wrap_pyfunction!(read_usrbin, m)?)?;
    m.add_function(wrap_pyfunction!(fluka_material_str, m)?)?;
    m.add_function(wrap_pyfunction!(fluka_compound_str, m)?)?;
    m.add_function(wrap_pyfunction!(fluka_builtin_set, m)?)?;
    m.add_function(wrap_pyfunction!(magic, m)?)?;
    m.add_function(wrap_pyfunction!(magic_with, m)?)?;
    m.add_function(wrap_pyfunction!(emit_openmc_weight_windows, m)?)?;
    m.add_function(wrap_pyfunction!(emit_serpent_wwin, m)?)?;
    m.add_function(wrap_pyfunction!(write_ssw, m)?)?;
    m.add_function(wrap_pyfunction!(mesh_to_geom, m)?)?;
    m.add_function(wrap_pyfunction!(half_life, m)?)?;
    m.add_function(wrap_pyfunction!(decay_constant, m)?)?;
    m.add_function(wrap_pyfunction!(q_value_capture, m)?)?;
    m.add_function(wrap_pyfunction!(q_value_alpha, m)?)?;
    m.add_function(wrap_pyfunction!(read_inp, m)?)?;
    m.add_function(wrap_pyfunction!(from_formula, m)?)?;
    m.add_function(wrap_pyfunction!(activity, m)?)?;
    m.add_function(wrap_pyfunction!(to_xml, m)?)?;
    m.add_function(wrap_pyfunction!(alara_parse_deck, m)?)?;
    m.add_function(wrap_pyfunction!(alara_parse_flux, m)?)?;
    m.add_function(wrap_pyfunction!(alara_parse_output, m)?)?;
    m.add_function(wrap_pyfunction!(alara_expand_schedule, m)?)?;
    m.add_function(wrap_pyfunction!(alara_validate_deck, m)?)?;
    m.add_function(wrap_pyfunction!(alara_check_block, m)?)?;
    m.add_function(wrap_pyfunction!(alara_flux_total, m)?)?;
    m.add_function(wrap_pyfunction!(alara_flux_len, m)?)?;
    m.add_function(wrap_pyfunction!(alara_output_totals, m)?)?;
    m.add_function(wrap_pyfunction!(alara_output_total_activity, m)?)?;
    m.add_function(wrap_pyfunction!(alara_photon_total_strength, m)?)?;
    m.add_function(wrap_pyfunction!(alara_schedule_total_time, m)?)?;
    m.add_function(wrap_pyfunction!(alara_clearance_eu_table, m)?)?;
    m.add_function(wrap_pyfunction!(alara_clearance_index, m)?)?;
    m.add_function(wrap_pyfunction!(alara_sum_of_fractions, m)?)?;
    m.add_function(wrap_pyfunction!(isotxs_parse, m)?)?;
    m.add_function(wrap_pyfunction!(rtflux_parse, m)?)?;
    m.add_function(wrap_pyfunction!(cccc_rtflux_npoints, m)?)?;
    m.add_function(wrap_pyfunction!(cccc_rtflux_point, m)?)?;
    m.add_function(wrap_pyfunction!(cccc_rtflux_total, m)?)?;
    m.add_function(wrap_pyfunction!(cccc_isotxs_find, m)?)?;
    m.add_function(wrap_pyfunction!(cccc_isotxs_len, m)?)?;
    m.add_function(wrap_pyfunction!(partisn_render, m)?)?;
    m.add_function(wrap_pyfunction!(partisn_validate, m)?)?;
    m.add_function(wrap_pyfunction!(fispact_parse_output, m)?)?;
    m.add_function(wrap_pyfunction!(fispact_parse_clearance, m)?)?;
    m.add_function(wrap_pyfunction!(fispact_is_output, m)?)?;
    m.add_function(wrap_pyfunction!(origen_parse_tape5, m)?)?;
    m.add_function(wrap_pyfunction!(origen_parse_tape6, m)?)?;
    m.add_function(wrap_pyfunction!(origen_parse_tape9, m)?)?;
    m.add_function(wrap_pyfunction!(origen_tape6_find, m)?)?;
    m.add_function(wrap_pyfunction!(origen_tape6_total_activity, m)?)?;
    m.add_function(wrap_pyfunction!(origen_tape9_find, m)?)?;
    m.add_function(wrap_pyfunction!(r2s_from_deck, m)?)?;
    m.add_function(wrap_pyfunction!(r2s_from_snapshot, m)?)?;
    m.add_function(wrap_pyfunction!(r2s_validate, m)?)?;
    m.add_function(wrap_pyfunction!(r2s_expand, m)?)?;
    m.add_function(wrap_pyfunction!(r2s_assemble, m)?)?;
    m.add_function(wrap_pyfunction!(r2s_tag_zone_strength, m)?)?;
    m.add_function(wrap_pyfunction!(r2s_photon_group_sums, m)?)?;
    m.add_function(wrap_pyfunction!(r2s_snapshot_inventory, m)?)?;
    m.add_function(wrap_pyfunction!(r2s_expand_sweep, m)?)?;
    m.add_function(wrap_pyfunction!(kinetics_solve, m)?)?;
    m.add_function(wrap_pyfunction!(kinetics_equilibrium, m)?)?;
    m.add_function(wrap_pyfunction!(kinetics_initial_rate, m)?)?;
    m.add_function(wrap_pyfunction!(kinetics_inhour_rho, m)?)?;
    m.add_function(wrap_pyfunction!(kinetics_stable_period, m)?)?;
    m.add_function(wrap_pyfunction!(kinetics_prompt_jump, m)?)?;
    m.add_function(wrap_pyfunction!(kinetics_from_ifp, m)?)?;
    m.add_function(wrap_pyfunction!(unfold_sandii, m)?)?;
    m.add_function(wrap_pyfunction!(unfold_forward_fold, m)?)?;
    m.add_function(wrap_pyfunction!(plasma_source_particles, m)?)?;
    m.add_function(wrap_pyfunction!(plasma_source_emit_cards, m)?)?;
    m.add_function(wrap_pyfunction!(plasma_source_spectrum_moments, m)?)?;
    m.add_function(wrap_pyfunction!(plasma_source_reactivity, m)?)?;
    m.add_function(wrap_pyfunction!(damage_nrt_dpa, m)?)?;
    m.add_function(wrap_pyfunction!(damage_arc_dpa, m)?)?;
    m.add_function(wrap_pyfunction!(damage_gas_appm, m)?)?;
    m.add_function(wrap_pyfunction!(damage_he_dpa_ratio, m)?)?;
    m.add_function(wrap_pyfunction!(damage_lindhard_partition, m)?)?;
    m.add_function(wrap_pyfunction!(damage_damage_energy, m)?)?;
    m.add_function(wrap_pyfunction!(damage_nrt_displacements, m)?)?;
    m.add_function(wrap_pyfunction!(damage_arc_efficiency, m)?)?;
    m.add_function(wrap_pyfunction!(damage_arc_displacements, m)?)?;
    m.add_function(wrap_pyfunction!(damage_fold_uq, m)?)?;
    m.add_function(wrap_pyfunction!(tritium_steady, m)?)?;
    m.add_function(wrap_pyfunction!(tritium_transient, m)?)?;
    m.add_function(wrap_pyfunction!(tritium_time_lag, m)?)?;
    m.add_function(wrap_pyfunction!(tritium_breakthrough, m)?)?;
    m.add_function(wrap_pyfunction!(tritium_oriani, m)?)?;
    m.add_function(wrap_pyfunction!(tritium_langmuir, m)?)?;
    m.add_function(wrap_pyfunction!(tritium_irreversible_fill, m)?)?;
    m.add_function(wrap_pyfunction!(tritium_sieverts, m)?)?;
    m.add_function(wrap_pyfunction!(tritium_recombination_rate, m)?)?;
    m.add_function(wrap_pyfunction!(tritium_layers_steady, m)?)?;
    m.add_function(wrap_pyfunction!(tritium_layers_transient, m)?)?;
    m.add_function(wrap_pyfunction!(spectroscopy_rect_smooth, m)?)?;
    m.add_function(wrap_pyfunction!(spectroscopy_five_point_smooth, m)?)?;
    m.add_function(wrap_pyfunction!(spectroscopy_calc_bg, m)?)?;
    m.add_function(wrap_pyfunction!(spectroscopy_gross_count, m)?)?;
    m.add_function(wrap_pyfunction!(spectroscopy_net_counts, m)?)?;
    m.add_function(wrap_pyfunction!(spectroscopy_energy_bins, m)?)?;
    m.add_function(wrap_pyfunction!(spectroscopy_detector_efficiency, m)?)?;
    m.add_function(wrap_pyfunction!(spectroscopy_fit_efficiency, m)?)?;
    m.add_function(wrap_pyfunction!(spectroscopy_xray_lines, m)?)?;
    m.add_function(wrap_pyfunction!(spectroscopy_sdef_decay_source, m)?)?;
    m.add_function(wrap_pyfunction!(spectroscopy_parse_dollar_spe, m)?)?;
    m.add_function(wrap_pyfunction!(spectroscopy_parse_spe, m)?)?;
    m.add_function(wrap_pyfunction!(spectroscopy_read_dollar_spe, m)?)?;
    m.add_function(wrap_pyfunction!(spectroscopy_read_spe, m)?)?;
    m.add_function(wrap_pyfunction!(spectroscopy_parse_lines_tsv, m)?)?;
    m.add_function(wrap_pyfunction!(spectroscopy_read_decay_lines, m)?)?;
    m.add_function(wrap_pyfunction!(uq_sample_mvn, m)?)?;
    m.add_function(wrap_pyfunction!(uq_sample_lhs, m)?)?;
    m.add_function(wrap_pyfunction!(uq_sample_lognormal, m)?)?;
    m.add_function(wrap_pyfunction!(uq_lognormal_mean, m)?)?;
    m.add_function(wrap_pyfunction!(uq_lognormal_cov, m)?)?;
    m.add_function(wrap_pyfunction!(uq_sample_mean, m)?)?;
    m.add_function(wrap_pyfunction!(uq_sample_cov, m)?)?;
    m.add_function(wrap_pyfunction!(uq_check_convergence, m)?)?;
    m.add_function(wrap_pyfunction!(uq_perturb_branches, m)?)?;
    m.add_function(wrap_pyfunction!(uq_perturb_energies, m)?)?;
    m.add_function(wrap_pyfunction!(uq_passthrough, m)?)?;
    m.add_function(wrap_pyfunction!(uq_perturb_fission_yields, m)?)?;
    m.add_function(wrap_pyfunction!(parse_deck, m)?)?;
    m.add_function(wrap_pyfunction!(read_deck, m)?)?;
    m.add_function(wrap_pyfunction!(parse_sdef, m)?)?;
    m.add_function(wrap_pyfunction!(parse_csg_to_openmc, m)?)?;
    m.add_function(wrap_pyfunction!(read_csg_to_openmc, m)?)?;
    m.add_function(wrap_pyfunction!(parse_csg_to_serpent, m)?)?;
    m.add_function(wrap_pyfunction!(read_csg_to_serpent, m)?)?;
    m.add_function(wrap_pyfunction!(parse_csg_to_phits, m)?)?;
    m.add_function(wrap_pyfunction!(read_csg_to_phits, m)?)?;
    m.add_function(wrap_pyfunction!(parse_csg_to_gdml, m)?)?;
    m.add_function(wrap_pyfunction!(read_csg_to_gdml, m)?)?;
    m.add_function(wrap_pyfunction!(cumulative_decays, m)?)?;
    m.add_function(wrap_pyfunction!(progeny, m)?)?;
    m.add_function(wrap_pyfunction!(branching_fraction, m)?)?;
    m.add_function(wrap_pyfunction!(decay_mode, m)?)?;
    m.add_function(wrap_pyfunction!(chain_edges, m)?)?;
    m.add_function(wrap_pyfunction!(armi_to_nucid, m)?)?;
    m.add_function(wrap_pyfunction!(nucid_to_armi, m)?)?;
    m.add_function(wrap_pyfunction!(mcc3_to_nucid, m)?)?;
    m.add_function(wrap_pyfunction!(check_labels, m)?)?;
    m.add_function(wrap_pyfunction!(audit_material, m)?)?;
    m.add_function(wrap_pyfunction!(separate_material, m)?)?;
    m.add_function(wrap_pyfunction!(blend_material, m)?)?;
    m.add_function(wrap_pyfunction!(enrichment_value_func, m)?)?;
    m.add_function(wrap_pyfunction!(enrichment_swu_per_feed, m)?)?;
    m.add_function(wrap_pyfunction!(enrichment_swu_per_prod, m)?)?;
    m.add_function(wrap_pyfunction!(enrichment_swu_per_tail, m)?)?;
    m.add_function(wrap_pyfunction!(enrichment_prod_per_feed, m)?)?;
    m.add_function(wrap_pyfunction!(enrichment_tail_per_feed, m)?)?;
    m.add_function(wrap_pyfunction!(enrichment_tail_per_prod, m)?)?;
    m.add_function(wrap_pyfunction!(enrichment_feed_per_prod, m)?)?;
    m.add_function(wrap_pyfunction!(enrichment_feed_per_tail, m)?)?;
    m.add_function(wrap_pyfunction!(enrichment_prod_per_tail, m)?)?;
    m.add_function(wrap_pyfunction!(enrichment_alphastar_i, m)?)?;
    m.add_function(wrap_pyfunction!(mcpl_statsum_validate, m)?)?;
    m.add_function(wrap_pyfunction!(mcpl_statsum_comment, m)?)?;
    m.add_class::<PyCusum>()?;
    m.add_function(wrap_pyfunction!(emit_cards, m)?)?;
    m.add_function(wrap_pyfunction!(emit_drift_table, m)?)?;
    m.add_function(wrap_pyfunction!(emit_armi_cards, m)?)?;
    m.add_function(wrap_pyfunction!(emit_armi_drift_table, m)?)?;
    m.add_class::<PyNuclide>()?;
    m.add_class::<PyParticle>()?;
    m.add_class::<PyXsdir>()?;
    m.add_class::<PyXsdirTable>()?;
    m.add_class::<PyMeshtal>()?;
    m.add_class::<PyMeshTally>()?;
    m.add_class::<PyWwinp>()?;
    m.add_class::<PyMctal>()?;
    m.add_class::<PySurfSrc>()?;
    m.add_class::<PyPtracFile>()?;
    m.add_class::<PyMcplFile>()?;
    m.add_class::<PyEndlLibrary>()?;
    m.add_class::<PyChain>()?;
    m.add_class::<PyDepletionSystem>()?;
    m.add_class::<PyUsrbinTally>()?;
    m.add_class::<PyMagicOutput>()?;
    m.add_class::<PyAliasTable>()?;
    m.add_class::<PyMeshSourceSampler>()?;
    m.add_class::<PyKdeSampler>()?;
    m.add_class::<PyCascade>()?;
    m.add_class::<PyMaterialsCompendium>()?;
    m.add_class::<PyDeckProblem>()?;
    m.add_class::<PyInventory>()?;
    Ok(())
}