lindhard/input/electron/

schema.rs

//! The serde schema of the electron input: the `*Spec` and `*Choice` types
//! and their defaults.

use std::collections::BTreeMap;

use serde::{Deserialize, Serialize};

use crate::electron::elastic::table::{DEFAULT_MIN_ENERGY_EV, DEFAULT_POINTS_PER_DECADE};
use crate::electron::inelastic::{FitWeighting, MerminFitOptions, PennAlgorithm};
use crate::electron::transport::TransportConfig;
use crate::input::{DivergenceSpec, TargetSpec, VoxelTallySpec};
use crate::material::MaterialSpec;
use crate::tally::{PsfModel, PsfNormalization, SE_BSE_SPLIT_EV};

// Named only by intra-doc links in this module.
#[cfg(doc)]
use crate::electron::{
    boundary::{BandModel, BandStructure},
    data::OpticalElf,
    phonon::{FrohlichPhonon, PolaronTrapping},
    secondary::SecondaryModel,
    transport::{BoundaryModel, CutoffReference, EscapeRule},
};

/// The whole electron run description.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ElectronInput {
    /// Everything electron-specific.
    pub electron: ElectronSpec,
    /// Named materials (as in an ion run).
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    pub materials: BTreeMap<String, MaterialSpec>,
    /// The layered target (as in an ion run).
    pub target: TargetSpec,
    /// History count, seed and threads.
    pub run: ElectronRunSpec,
}

/// `[electron]`.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ElectronSpec {
    /// The primary electrons.
    pub beam: ElectronBeamSpec,
    /// Cutoff, faces, secondaries.
    pub transport: TransportSpec,
    /// Elastic model.
    pub elastic: ElasticSpec,
    /// Inelastic model.
    #[serde(default)]
    pub inelastic: InelasticSpec,
    /// Energy grid of the cross-section tables.
    #[serde(default)]
    pub tables: TableGridSpec,
    /// Electron data of each material the target uses, by the name the
    /// target gives it (a `[materials]` key or an element symbol).
    pub materials: BTreeMap<String, ElectronMaterialSpec>,
    /// What the run records.
    #[serde(default)]
    pub tally: ElectronTallySpec,
}

/// `[electron.beam]`.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ElectronBeamSpec {
    /// Kinetic energy of the primaries, eV: the vacuum energy with
    /// `boundary = "step-barrier"`, the energy inside the first layer
    /// otherwise.
    pub energy_ev: f64,
    /// Polar angle from the surface normal, degrees, in `[0, 90)`.
    #[serde(default)]
    pub tilt_deg: f64,
    /// Azimuth of the incidence plane, degrees.
    #[serde(default)]
    pub azimuth_deg: f64,
    /// Landing point `[y, z]` of the beam centre on the front face, nm
    /// (default `[0, 0]`).
    #[serde(default, skip_serializing_if = "is_origin")]
    pub landing_nm: [f64; 2],
    /// Lateral profile about the landing point (default: a point).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub profile: Option<BeamProfileSpec>,
    /// Angular spread about the nominal direction; the ion beam's
    /// `[beam.divergence]` laws ([`DivergenceSpec`]), with the same inward
    /// conditioning and width limit (default: none).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub divergence: Option<DivergenceSpec>,
}

fn is_origin(v: &[f64; 2]) -> bool {
    *v == [0.0; 2]
}

/// `[electron.beam.profile]`: the lateral profile of the beam on the front
/// face, selected by `model`; lengths in nm.
///
/// ```toml
/// [electron.beam.profile]
/// model = "gaussian"   # sigma_nm: standard deviation of each of y and z
/// sigma_nm = 5.0
/// # model = "disc"      # radius_nm: uniform in area
/// # model = "rectangle" # width_y_nm, width_z_nm: full widths, uniform
/// ```
///
/// See [`BeamProfile`](crate::electron::transport::BeamProfile) for the laws.
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
#[serde(tag = "model", rename_all = "kebab-case", deny_unknown_fields)]
pub enum BeamProfileSpec {
    /// Every primary lands at the landing point.
    Point,
    /// Gaussian spot.
    Gaussian {
        /// Standard deviation of each of `y` and `z`, nm, `> 0`.
        sigma_nm: f64,
    },
    /// Uniform disc.
    Disc {
        /// Radius, nm, `> 0`.
        radius_nm: f64,
    },
    /// Uniform rectangle centred on the landing point.
    Rectangle {
        /// Full width along `y`, nm, `> 0`.
        width_y_nm: f64,
        /// Full width along `z`, nm, `> 0`.
        width_z_nm: f64,
    },
}

/// Where the cutoff is measured from.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum CutoffReferenceChoice {
    /// [`CutoffReference::BandBottom`].
    #[default]
    BandBottom,
    /// [`CutoffReference::VacuumLevel`].
    VacuumLevel,
}

/// Escape rule at the faces.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum EscapeRuleChoice {
    /// [`EscapeRule::BothFaces`].
    #[default]
    BothFaces,
    /// [`EscapeRule::FrontOnly`].
    FrontOnly,
}

/// Secondary-electron model.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum SecondaryChoice {
    /// [`SecondaryModel::Off`].
    #[default]
    Off,
    /// [`SecondaryModel::KieftBosch`].
    KieftBosch,
}

/// Face model.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum BoundaryChoice {
    /// [`BoundaryModel::Transparent`].
    #[default]
    Transparent,
    /// [`BoundaryModel::StepBarrier`].
    StepBarrier,
}

fn default_max_events() -> u64 {
    TransportConfig::new(1.0).max_events
}

/// `[electron.transport]`: the [`TransportConfig`].
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct TransportSpec {
    /// Stopping cutoff, eV.
    pub cutoff_ev: f64,
    /// Where the cutoff is measured from.
    #[serde(default)]
    pub cutoff_reference: CutoffReferenceChoice,
    /// What the faces of the target do.
    #[serde(default)]
    pub escape_rule: EscapeRuleChoice,
    /// Collision and reflection cap per electron.
    #[serde(default = "default_max_events")]
    pub max_events: u64,
    /// Secondary-electron generation.
    #[serde(default)]
    pub secondaries: SecondaryChoice,
    /// Kieft-Bosch option: instantaneous momentum of the bound electron.
    /// Default `true` with `"kieft-bosch"`; not allowed with `"off"`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub instantaneous_momentum: Option<bool>,
    /// Kieft-Bosch option: deflect the primary to conserve momentum.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub momentum_conservation: Option<bool>,
    /// Face model.
    #[serde(default)]
    pub boundary: BoundaryChoice,
    /// Step-barrier option: quantum-mechanical transmission. Default `true`
    /// with `"step-barrier"`; not allowed with `"transparent"`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub quantum_transmission: Option<bool>,
    /// Step-barrier option: refraction on transmission.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub refraction: Option<bool>,
}

/// Elastic model. Only the Mott cross section from the radial-Dirac partial
/// waves exists.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum ElasticModelChoice {
    /// [`crate::electron::elastic`] and [`crate::electron::elastic::table`].
    #[default]
    Mott,
}

impl ElasticModelChoice {
    /// The stable label (the input spelling).
    pub fn label(self) -> &'static str {
        match self {
            Self::Mott => "mott",
        }
    }
}

/// Atomic potential of the elastic model.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum PotentialChoice {
    /// The Thomas-Fermi-length Yukawa **stand-in**
    /// ([`crate::electron::elastic::table::ThomasFermiYukawa`]).
    ThomasFermiYukawa,
    /// Salvat et al. (1987) DHFS
    /// ([`crate::electron::elastic::table::SalvatDhfsTable`]), Table I
    /// coefficients for Z = 1..92.
    SalvatDhfs,
}

impl PotentialChoice {
    /// The stable label.
    pub fn label(self) -> &'static str {
        match self {
            Self::ThomasFermiYukawa => "thomas-fermi-yukawa",
            Self::SalvatDhfs => "salvat-dhfs",
        }
    }
}

/// `[electron.elastic]`.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ElasticSpec {
    /// The elastic model.
    #[serde(default)]
    pub model: ElasticModelChoice,
    /// The atomic potential (required: the only one that runs is a
    /// stand-in, and the input must say so).
    pub potential: PotentialChoice,
    /// Furness-McCarthy exchange correction.
    #[serde(default)]
    pub exchange: bool,
    /// Correlation-polarization correction, absent for off.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub correlation_polarization: Option<CorrelationPolarizationSpec>,
}

/// One element's dipole polarizability and its source.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct PolarizabilitySpec {
    /// Static dipole polarizability, bohr³.
    pub bohr3: f64,
    /// Citation of the value (required, non-blank).
    pub source: String,
}

fn default_outer_radius() -> f64 {
    crate::electron::elastic::corrections::DEFAULT_OUTER_RADIUS
}

/// `[electron.elastic.correlation_polarization]`.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct CorrelationPolarizationSpec {
    /// `b_pol²` of the polarization cutoff; absent: Seltzer's
    /// `(E - 50 eV)/(16 eV)`, which needs every table energy above 50 eV.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub b_pol_squared: Option<f64>,
    /// Radius beyond which the polarization tail is dropped, bohr.
    #[serde(default = "default_outer_radius")]
    pub outer_radius_bohr: f64,
    /// Polarizability of every element of the target, by symbol.
    pub polarizability: BTreeMap<String, PolarizabilitySpec>,
}

/// `[electron.inelastic]`.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct InelasticSpec {
    /// `"penn-single-pole"`, `"penn-full"` or `"mermin-melf"`.
    #[serde(default = "default_inelastic_model")]
    pub model: String,
    /// Fermi energy of the model, eV, for the inelastic tables of materials
    /// without a band. Must be 0 if a material has a band: the table of a
    /// material with a band takes the band's (#241).
    #[serde(default)]
    pub fermi_energy_ev: f64,
}

fn default_inelastic_model() -> String {
    PennAlgorithm::SinglePole.label().to_string()
}

impl Default for InelasticSpec {
    fn default() -> Self {
        Self {
            model: default_inelastic_model(),
            fermi_energy_ev: 0.0,
        }
    }
}

fn default_min_energy() -> f64 {
    DEFAULT_MIN_ENERGY_EV
}

fn default_points_per_decade() -> f64 {
    DEFAULT_POINTS_PER_DECADE
}

/// `[electron.tables]`: the energy grid both tables of every layer share.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct TableGridSpec {
    /// Lowest grid energy, eV.
    #[serde(default = "default_min_energy")]
    pub min_energy_ev: f64,
    /// Highest grid energy, eV. Default: the beam energy (plus the largest
    /// inner potential with the step barrier).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub max_energy_ev: Option<f64>,
    /// Minimum points per decade.
    #[serde(default = "default_points_per_decade")]
    pub points_per_decade: f64,
}

impl Default for TableGridSpec {
    fn default() -> Self {
        Self {
            min_energy_ev: default_min_energy(),
            max_energy_ev: None,
            points_per_decade: default_points_per_decade(),
        }
    }
}

/// Band parameters of a material ([`BandStructure`]).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "kebab-case", deny_unknown_fields)]
pub enum BandSpec {
    /// [`BandModel::Metal`].
    Metal {
        /// Fermi energy above the band bottom, eV.
        fermi_ev: f64,
        /// Work function, eV.
        work_function_ev: f64,
        /// Binding energy below the Fermi level of the electron a valence
        /// event liberates, eV ([`BandStructure::with_valence_binding_ev`]);
        /// absent: the Fermi level, the default.
        #[serde(default, skip_serializing_if = "Option::is_none")]
        valence_binding_ev: Option<f64>,
        /// Source of the values.
        provenance: String,
    },
    /// [`BandModel::Insulator`].
    Insulator {
        /// Valence band width, eV.
        valence_band_width_ev: f64,
        /// Band gap, eV.
        band_gap_ev: f64,
        /// Electron affinity, eV.
        affinity_ev: f64,
        /// Source of the values.
        provenance: String,
    },
    /// [`BandStructure::free_electron_metal`]: the Fermi energy from the
    /// free-electron relation and the material's atom density.
    FreeElectronMetal {
        /// Valence electrons per atom (a model choice).
        valence_electrons_per_atom: f64,
        /// Work function, eV.
        work_function_ev: f64,
        /// As for [`BandSpec::Metal`].
        #[serde(default, skip_serializing_if = "Option::is_none")]
        valence_binding_ev: Option<f64>,
        /// Source of the work function and of the valence count (and of
        /// `valence_binding_ev`, if given).
        provenance: String,
    },
}

/// A Fröhlich LO-phonon channel: explicit parameters, or a preset the library
/// carries with its citation.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct PhononSpec {
    /// `"sio2-63mev"` or `"sio2-153mev"` ([`FrohlichPhonon::sio2`]); then
    /// only `temperature_k` may be given.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub preset: Option<String>,
    /// LO-phonon energy, eV.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub hbar_omega_ev: Option<f64>,
    /// Static relative permittivity.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub eps_static: Option<f64>,
    /// High-frequency relative permittivity.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub eps_high_frequency: Option<f64>,
    /// Lattice temperature, K.
    pub temperature_k: f64,
    /// Source of the values (required without a preset).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub provenance: Option<String>,
}

/// A polaron-trapping channel ([`PolaronTrapping`]).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct PolaronSpec {
    /// `C`, nm⁻¹.
    pub c_per_nm: f64,
    /// `γ`, eV⁻¹.
    pub gamma_per_ev: f64,
    /// Source of the values.
    pub provenance: String,
}

fn default_mermin_oscillators() -> usize {
    MerminFitOptions::default().n_oscillators
}

/// The `floor` of the default relative weighting of
/// [`MerminFitOptions::default`].
pub(super) fn default_relative_floor() -> f64 {
    match MerminFitOptions::default().weighting {
        FitWeighting::Relative { floor } => floor,
        FitWeighting::Uniform => unreachable!("the default fit weighting is relative"),
    }
}

/// Weighting of the residuals of the Mermin oscillator fit
/// ([`FitWeighting`]).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum MerminWeightingChoice {
    /// [`FitWeighting::Relative`] (the default).
    #[default]
    Relative,
    /// [`FitWeighting::Uniform`].
    Uniform,
}

/// `[electron.materials.<name>.mermin_fit]`: the options of the oscillator
/// fit of the `mermin-melf` model to this material's optical ELF
/// ([`MerminFitOptions`],
/// [`crate::electron::inelastic::fit_mermin_oscillators`]). Absent: exactly
/// [`MerminFitOptions::default`]. Only `n_oscillators` and `weighting` are
/// exposed; the starting point and the iteration cap keep their defaults.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct MerminFitSpec {
    /// Number of oscillators, `1..=MAX_OSCILLATORS` (16); default 3.
    #[serde(default = "default_mermin_oscillators")]
    pub oscillators: usize,
    /// `"relative"` (default) or `"uniform"`.
    #[serde(default)]
    pub weighting: MerminWeightingChoice,
    /// `floor` of the relative weighting, in `(0, 1]`; default 0.01. Not
    /// allowed with `"uniform"`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub relative_floor: Option<f64>,
}

/// `[electron.materials.<name>.inner_shells]`: inner-shell ionisation
/// channels of this material (single-pole Penn only). Each listed subshell of
/// every element of the material becomes a channel with a hydrogenic optical
/// ELF ([`crate::electron::inelastic::hydrogenic_shell_elfs`]) built from a
/// binding-energy table ([`crate::electron::data::SubshellBindingTable`]).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct InnerShellsSpec {
    /// Subshell labels: `"K"`, `"L1"`, `"L2"`, `"L3"` (the only ones with a
    /// hydrogenic formula). Not empty, no repeats.
    pub subshells: Vec<String>,
    /// Path of a binding-energy table in the TOML form of
    /// [`crate::electron::data::SubshellBindingTable::from_toml_str`],
    /// relative to the input file's directory; its `provenance` is
    /// required. Absent: the embedded EADL2017 table.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub binding: Option<String>,
}

/// `[electron.materials.<name>]`: the electron data of one material.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ElectronMaterialSpec {
    /// Path of the optical ELF file ([`OpticalElf`] TOML form), relative to
    /// the input file's directory.
    pub optical_elf: String,
    /// Band parameters; required with secondaries, the step barrier or the
    /// vacuum-level cutoff.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub band: Option<BandSpec>,
    /// Fröhlich LO-phonon channel (polar insulators only).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub phonon: Option<PhononSpec>,
    /// Polaron trapping (polar insulators only).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub polaron: Option<PolaronSpec>,
    /// Options of the Mermin oscillator fit (`mermin-melf` only); absent:
    /// [`MerminFitOptions::default`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub mermin_fit: Option<MerminFitSpec>,
    /// Inner-shell ionisation channels (`single-pole` only); absent: none.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub inner_shells: Option<InnerShellsSpec>,
    /// Mean energy per electron-hole pair `E_pair`, with its source. Absent:
    /// the report gives the ionisation energy of the material's layers only
    /// and no pair count; no default is supplied.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub e_pair: Option<EPairSpec>,
}

/// `[electron.materials.<name>.e_pair]`: the energy needed per electron-hole
/// pair, a per-material input that must carry its citation (for example the
/// Klein 1968 rule for a semiconductor, or a measured value for SiO2). Pairs
/// per incident electron are the ionisation energy divided by it, a
/// post-processing step; nothing in transport depends on it.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct EPairSpec {
    /// `E_pair`, eV (positive).
    pub ev: f64,
    /// Where the value comes from (required, non-blank).
    pub source: String,
}

/// A uniform binning in nm.
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct BinsNm {
    /// Lower edge, nm.
    pub lo_nm: f64,
    /// Upper edge, nm.
    pub hi_nm: f64,
    /// Number of bins.
    pub bins: usize,
}

/// `[electron.tally.cartesian]`.
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct CartesianSpec {
    /// Depth bins.
    pub x: BinsNm,
    /// Lateral `y` bins.
    pub y: BinsNm,
    /// Lateral `z` bins.
    pub z: BinsNm,
}

/// `[electron.tally.cylindrical]`.
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct CylindricalSpec {
    /// Radial bins (from `r >= 0`).
    pub r: BinsNm,
    /// Depth bins.
    pub depth: BinsNm,
}

/// A PSF form to fit (`fits` of `[electron.tally.psf]`).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum PsfFitSpec {
    /// Double Gaussian ([`PsfModel::DoubleGaussian`]).
    Double,
    /// Triple Gaussian ([`PsfModel::TripleGaussian`]).
    Triple,
}

impl From<PsfFitSpec> for PsfModel {
    fn from(f: PsfFitSpec) -> Self {
        match f {
            PsfFitSpec::Double => PsfModel::DoubleGaussian,
            PsfFitSpec::Triple => PsfModel::TripleGaussian,
        }
    }
}

/// How the energy scale of a PSF fit is set (`normalization`).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum PsfNormalizationSpec {
    /// Fixed to the slab energy ([`PsfNormalization::SlabTotal`]).
    #[default]
    SlabTotal,
    /// A free parameter ([`PsfNormalization::Free`]).
    Free,
}

impl From<PsfNormalizationSpec> for PsfNormalization {
    fn from(n: PsfNormalizationSpec) -> Self {
        match n {
            PsfNormalizationSpec::SlabTotal => PsfNormalization::SlabTotal,
            PsfNormalizationSpec::Free => PsfNormalization::Free,
        }
    }
}

pub(super) fn default_psf_fits() -> Vec<PsfFitSpec> {
    vec![PsfFitSpec::Double, PsfFitSpec::Triple]
}

/// `[electron.tally.psf]`: the radial profile of the energy deposited in a
/// depth slab, on log radial bins, and the PSF fits to it
/// ([`crate::tally::psf`]).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct PsfSpec {
    /// Lower depth of the slab, nm.
    pub depth_lo_nm: f64,
    /// Upper depth of the slab (excluded), nm.
    pub depth_hi_nm: f64,
    /// Outer edge of the central disc and inner edge of the first log bin, nm.
    pub r_min_nm: f64,
    /// Outer edge of the last bin, nm.
    pub r_max_nm: f64,
    /// Log bins between `r_min_nm` and `r_max_nm`.
    pub bins: usize,
    /// Forms to fit (`"double"`, `"triple"`); may be empty.
    #[serde(default = "default_psf_fits")]
    pub fits: Vec<PsfFitSpec>,
    /// How the energy scale of the fits is set.
    #[serde(default)]
    pub normalization: PsfNormalizationSpec,
}

fn default_exposure_bins() -> usize {
    200
}
fn default_exposure_quantiles() -> Vec<f64> {
    vec![0.05, 0.5, 0.95]
}
fn default_exposure_tail() -> f64 {
    1e-12
}

/// Beam profile of `[electron.tally.exposure]`.
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "kebab-case", deny_unknown_fields)]
pub enum ExposureBeamSpec {
    /// All electrons land on the axis.
    Point,
    /// Gaussian landing offset, `sigma_nm` per lateral axis.
    Gaussian {
        /// Standard deviation per axis, nm.
        sigma_nm: f64,
    },
    /// Uniform disc.
    UniformDisc {
        /// Radius, nm.
        radius_nm: f64,
    },
}

/// Shape of a volume of `[electron.tally.exposure]`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum ExposureShapeSpec {
    /// Cylinder along the depth axis (needs `radius_nm`).
    Cylinder,
    /// Box centred on the offset (needs `half_y_nm` and `half_z_nm`).
    Box,
}

/// One `[[electron.tally.exposure.volumes]]` entry.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ExposureVolumeSpec {
    /// Label in the outputs (unique).
    pub name: String,
    /// Shape.
    pub shape: ExposureShapeSpec,
    /// Cylinder radius, nm.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub radius_nm: Option<f64>,
    /// Box half width along `y`, nm.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub half_y_nm: Option<f64>,
    /// Box half width along `z`, nm.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub half_z_nm: Option<f64>,
    /// Lower depth, nm.
    pub depth_lo_nm: f64,
    /// Upper depth (excluded), nm.
    pub depth_hi_nm: f64,
    /// Lateral centre `y`, nm.
    #[serde(default)]
    pub offset_y_nm: f64,
    /// Lateral centre `z`, nm.
    #[serde(default)]
    pub offset_z_nm: f64,
}

/// `[electron.tally.exposure]`: the per-electron deposit in target volumes
/// and the compound-Poisson distribution of a finite exposure
/// ([`crate::tally::exposure`]).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ExposureSpec {
    /// Mean number of incident electrons.
    pub lambda: f64,
    /// Beam profile.
    pub beam: ExposureBeamSpec,
    /// Target volumes (a neighbour is another volume at its offset).
    pub volumes: Vec<ExposureVolumeSpec>,
    /// Histogram bins of the per-electron deposit.
    #[serde(default = "default_exposure_bins")]
    pub bins: usize,
    /// Upper edge of the histogram, eV. Default: the beam energy.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub x_max_ev: Option<f64>,
    /// Probabilities whose quantiles of the exposure energy are reported.
    #[serde(default = "default_exposure_quantiles")]
    pub quantiles: Vec<f64>,
    /// Thresholds `a`, eV, for `P(S < a)`.
    #[serde(default)]
    pub below_ev: Vec<f64>,
    /// Thresholds `b`, eV, for `P(S > b)`.
    #[serde(default)]
    pub above_ev: Vec<f64>,
    /// Poisson tail mass dropped from the convolution.
    #[serde(default = "default_exposure_tail")]
    pub tail_tolerance: f64,
}

fn default_split() -> f64 {
    SE_BSE_SPLIT_EV
}
fn default_energy_bins() -> usize {
    100
}
fn default_polar_max() -> f64 {
    90.0
}
fn default_polar_bins() -> usize {
    18
}

/// `[electron.tally]`.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ElectronTallySpec {
    /// SE/BSE split, eV.
    #[serde(default = "default_split")]
    pub se_bse_split_ev: f64,
    /// Upper edge of the escape-energy spectra, eV (from 0). Default: the
    /// beam energy.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub escape_energy_max_ev: Option<f64>,
    /// Escape-energy bins.
    #[serde(default = "default_energy_bins")]
    pub escape_energy_bins: usize,
    /// Upper edge of the escape polar-angle spectra, degrees from the
    /// outward normal (from 0, at most 180).
    #[serde(default = "default_polar_max")]
    pub escape_polar_max_deg: f64,
    /// Escape polar-angle bins.
    #[serde(default = "default_polar_bins")]
    pub escape_polar_bins: usize,
    /// Cartesian deposition grid.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cartesian: Option<CartesianSpec>,
    /// Cylindrical deposition grid.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cylindrical: Option<CylindricalSpec>,
    /// Radial profile of a depth slab and its PSF fits.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub psf: Option<PsfSpec>,
    /// Dose per layer, depth-dose profile and interface transmission.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub dose: Option<DoseSpec>,
    /// Exposure statistics of small volumes.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub exposure: Option<ExposureSpec>,
    /// Voxel energy-deposition grid, written as `damage_export.csv` (the
    /// ion `[tally.voxel]` table, same fields). The electron tally has no
    /// species axis, so the per-species defect columns are empty.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub voxel: Option<VoxelTallySpec>,
}

/// `[electron.tally.dose]`: dose in each layer per unit incident fluence
/// (always on once the table is present), optional depth-dose profile and
/// interface transmission.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct DoseSpec {
    /// Uniform depth bins per layer; omit for no depth-dose profile.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub depth_bins_per_layer: Option<usize>,
    /// Width of the refined depth bands next to each interface, nm.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub refine_width_nm: Option<f64>,
    /// Bins in each refined band (default 10 when a width is given).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub refine_bins: Option<usize>,
    /// Depth binned in a semi-infinite last layer, nm.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub substrate_depth_nm: Option<f64>,
    /// Count crossings of each interface, with energy spectra.
    #[serde(default)]
    pub transmission: bool,
}

impl Default for ElectronTallySpec {
    fn default() -> Self {
        Self {
            se_bse_split_ev: default_split(),
            escape_energy_max_ev: None,
            escape_energy_bins: default_energy_bins(),
            escape_polar_max_deg: default_polar_max(),
            escape_polar_bins: default_polar_bins(),
            cartesian: None,
            cylindrical: None,
            psf: None,
            dose: None,
            exposure: None,
            voxel: None,
        }
    }
}

/// `[run]` of an electron run.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ElectronRunSpec {
    /// Number of primary electrons (histories).
    pub histories: u64,
    /// Run seed.
    pub seed: u64,
    /// Worker threads (not echoed; never changes results).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub threads: Option<usize>,
}