Plasma computations
JenaAtomicCalculator.Plasma.AbstractPlasmaScheme — Type
abstract type Plasma.AbstractPlasmaScheme ... defines an abstract type to distinguish different kinds of plasma computations; see also:
+ struct AverageAtomScheme
... to perform an average-atom computation.
+ struct LineShiftScheme
... to compute the energy shifts and properties of atomic/ionic lines in some selected plasma model.
+ struct SahaBoltzmannScheme
... to compute thermodynamic properties of a Saha-Boltzmann LTE mixture.
+ struct SatelliteDiagnosticScheme
... to compute a dielectronic-satellite-to-parent-line intensity-ratio Te diagnostic.
+ struct CollisionalRadiativeScheme
... to compute the (relative) collisional-radiative population balance among a small set of
levels of one ion.
+ struct KineticChargeBalanceScheme
... the cross-charge-state sibling of CollisionalRadiativeScheme: a kinetic (rate-based, non-LTE)
population balance across several adjacent charge states, with PhotoEmission + ImpactExcitation
within each stage and ImpactIonization + PhotoRecombination + ThreeBodyRecombination between
adjacent stages. Each of the five legs independently selects an Empirical (tabulated/fitted) or
a structure-based (ab-initio/semi-empirical) treatment -- see Plasma.AbstractRateTreatment.
+ struct SuperConfigurationOpacityScheme
... to build one SuperConfigurations.Group per reference configuration, report its Boltzmann
population at a given plasma temperature, build a SuperConfigurations.TransitionArray for every
E1-connected pair with its oscillator-strength sum, and -- if opacityOmegas is given -- sum
every array's Gaussian onto that frequency grid into a photo-absorption cross section
kappa(omega). All three stages are built; see that struct's own docstring for what even that
still is not (a macroscopic opacity in cm^2/g).
+ struct SuperConfigurationIonizationScheme
... to compute the EQUILIBRIUM (LTE) population across several ionization stages of one species,
each stage described by its own SuperConfigurations.Group's rather than by diagonalized levels
-- the natural extension of SuperConfigurationOpacityScheme ACROSS charge states instead of
within one. See that struct's own docstring for the grand-canonical Saha-Boltzmann equations
and their self-consistent electron-density solve.
+ struct SuperConfigurationMixtureOpacityScheme
... to combine several SPECIES (each its own Nuclear.Model, own number fraction, and now possibly
several of its own ionization STAGES) into one coupled multi-species Saha-Boltzmann balance and
one PLANCK MEAN opacity at a shared LTE temperature -- the natural extension of
SuperConfigurationOpacityScheme ACROSS a composition AND of SuperConfigurationIonizationScheme
ACROSS species, both axes at once. OPTIONALLY (`boundFreeApprox`, 18-Oct-2026) also sums a
bound-free (photoionization) contribution between every pair of adjacent stages, reusing
`Empirical.photoionizationCrossSection`, and OPTIONALLY (`freeFreeIncluded`, 19-Oct-2026) also
sums a free-free (inverse-bremsstrahlung) contribution per stage, via
`Empirical.freeFreeAbsorptionCoefficient` -- once EITHER is on, the ROSSELAND mean, previously
withheld as ill-posed, becomes well-defined and is reported too. See that struct's own
docstring for the coupled balance, the two-stage mixing rule, both continuum additions, and the
Planck/Rosseland weight functions.JenaAtomicCalculator.Plasma.AbstractRateTreatment — Type
abstract type Plasma.AbstractRateTreatment ... distinguishes, for ONE leg (one process) of a Plasma.KineticChargeBalanceScheme, the QUALITY of both the atomic input (scaled/hydrogenic, or a real JAC-computed energy/rate) and the collision/radiative dynamics model (a literature-fitted formula, or JAC's own cross-section computation) used for that rate. Every leg (PhotoEmission, ImpactExcitation, ImpactIonization, PhotoRecombination, ThreeBodyRecombination) carries its own AbstractRateTreatment, so a single scheme can mix the three tiers freely across legs ("mixed use") – this is the one thing the whole scheme is built to make visible. The type is deliberately kept separate from Empirical.AbstractEmpiricalApproximation (it is NOT a subtype of it): the three tiers are different in kind, not flavours of the same thing.
+ Plasma.EmpiricalTreatment ... scaled/hydrogenic input AND a fitted formula; wraps one
Empirical.AbstractEmpiricalApproximation singleton; no SCF/CI anywhere.
+ Plasma.SemiEmpiricalTreatment ... a REAL, JAC-computed input (a cheap mean-field energy, Einstein-A or
binding energy) fed into the SAME fitted formula the EmpiricalTreatment
leg would use. Supported for all five legs: PhotoEmission
(Empirical.UsingJAC), ImpactExcitation (bridged through
Empirical.GivenEinsteinA), PhotoRecombination (Empirical.UsingJAC, via
the Einstein-Milne relation to a mean-field photoionization cross
section), and ImpactIonization/ThreeBodyRecombination
(Empirical.Lotz1967, fed a mean-field AL-Field binding energy via the
pSource keyword of Empirical.impactIonizationBindingEnergy rather than
a tabulated one). Plasma.validateKineticChargeBalanceSupport checks the
required approx for each leg and raises rather than guessing.
+ Plasma.StructureBasedTreatment ... real input AND JAC's own cross-section/rate computation end-to-end; the
only tier open to a GENERAL (non-classic) Plasma.ChargeStage. Carries the
one knob that differs between models, an ImpactIonization.AbstractModel,
read only by the ImpactIonization/ThreeBodyRecombination legs and ignored
by the other three.JenaAtomicCalculator.Plasma.AverageAtomOutcome — Type
struct Plasma.AverageAtomOutcome ... the complete result of one average-atom computation, as named fields rather than as string keys into a Dict.
**THE DIVISION OF THE FIELDS IS THE SCHEME'S OWN DIVISION.** The cell block is ALWAYS filled, because a
converged cell always has it; every optional property is `Union{Nothing,...}` and is `nothing` exactly when
its switch was not set. That distinction is the reason for the type: a string-keyed Dict cannot tell
"this was not computed" from "this came out zero", and a conductivity of zero and an absent conductivity
mean entirely different things to whoever reads the number afterwards.
+ temperature ::Float64 ... the temperature [a.u.] the cell was converged at.
+ massDensity ::Float64 ... the mass density [g/cm^3].
+ radiusWS ::Float64 ... the Wigner-Seitz cell radius [a.u.]; NOT the B-spline box, which is
several times larger and must be -- see SelfConsistent's own note.
+ iCell ::Int64 ... the grid index of the cell boundary, i.e. the last point with
r <= radiusWS. Every cell integral runs 1:iCell.
+ chemicalMu ::Float64 ... the chemical potential [a.u.], fixed by neutrality of the cell.
+ meanCharge ::Float64 ... Z*, the mean ionization, i.e. the free-electron count of the cell.
+ noBoundElectrons ::Float64 ... the bound-electron count; noBound + meanCharge = Z exactly.
+ radialDensity ::Array{Float64,1} ... the total electron density, carrying Z over the cell.
+ orbitals ::Dict{Subshell, Orbital} ... the converged bound orbitals.
+ couplingParameter ::Float64 ... the COUPLING PARAMETER Gamma = Z*^2/(R_WS kT): the ratio of the
typical Coulomb energy between neighbouring ions to their thermal
energy. Gamma << 1 is a weakly coupled (ideal) plasma, Gamma >> 1 a
strongly coupled one, Gamma ~ 1 the warm-dense regime this model is
for.
+ degeneracyParameter ::Float64 ... the DEGENERACY PARAMETER Theta = kT/E_F with E_F the free-electron
Fermi energy: Theta << 1 is a degenerate electron gas, Theta >> 1 a
classical one. **Gamma and Theta say WHERE in the (rho,T) plane a
number came from, so they are always reported and never optional** --
a result quoted without them can be misused in a regime the model
does not describe.
+ qValues ::Union{Nothing, Array{Float64,1}} ... momentum transfers of the form factor.
+ formFactors ::Union{Nothing, Array{Float64,1}} ... F(q), integrated over the cell.
+ piOmegas ::Union{Nothing, Array{Float64,1}} ... photon energies of the cross sections.
+ piCrossSections ::Union{Nothing, Any} ... bound-free cross sections per subshell.
+ scatteringFactor ::Union{Nothing, Array{Float64,1}} ... the imaginary scattering factor f_2.
+ massAttenuation ::Union{Nothing, Array{Float64,1}} ... mu/rho [cm^2/g].
+ condOmegas ::Union{Nothing, Array{Float64,1}} ... photon energies of the conductivity.
+ conductivity ::Union{Nothing, Array{Float64,1}} ... Re sigma(omega) [a.u.].
+ condLines ::Union{Nothing, Any} ... the individual box transitions and their
strengths, classified by kind.
+ condSumRules ::Union{Nothing, Any} ... the per-channel sum rules.
+ optical ::Union{Nothing, Any} ... eps(omega), n + ik, the absorption coefficient.
+ dcConductivity ::Union{Nothing, Any} ... sigma(0) and the collision rate, from the
scattering phase shifts.
+ meanOpacities ::Union{Nothing, Any} ... the Planck and Rosseland mean opacities.JenaAtomicCalculator.Plasma.AverageAtomOutcome — Method
Plasma.AverageAtomOutcome(temperature::Float64, massDensity::Float64, radiusWS::Float64, iCell::Int64, chemicalMu::Float64, meanCharge::Float64, noBoundElectrons::Float64, radialDensity::Array{Float64,1}, orbitals::Dict{Subshell, Orbital}) ... constructor for the CELL alone, with every optional property left as nothing; the coupling and degeneracy parameters are derived here rather than passed, since they follow from the cell:
Gamma = Z*^2 / (R_WS kT) ... coupling, the ion-sphere form
Theta = kT / E_F, E_F = (3 pi^2 n_e)^(2/3) / 2, n_e = Z* / (4pi/3 R_WS^3)
An `outcome::Plasma.AverageAtomOutcome` is returned.JenaAtomicCalculator.Plasma.AverageAtomScheme — Type
struct Plasma.AverageAtomScheme <: Plasma.AbstractPlasmaScheme ... a struct to perform an average-atom computation.
+ nMax ::Int64 ... maximum principal quantum number for the subshells of the AA model.
+ lMax ::Int64 ... maximum orbital quantum number for the subshells of the AA model.
+ scField ::AbstractScField ... self-consistent field of the AA model, e.g. Basics.AaDFSField().
+ calcPhotoionizationCs ::Bool ... True, if photoionization cross sections are to be calculated.
+ calcFormFactor ::Bool ... True, if the form factor need to be calculated.
+ calcScatteringFactor ::Bool ... True, if scattering factor need to be calculated.
+ piSubshells ::Array{Subshell,1} ... Bound subshells to be included into the photoionization cross sections.
+ omegas ::Array{Float64,1} ... energies for the photoionization & scattering factors [in a.u.].
+ qValues ::Array{Float64,1} ... q-values for calculating the form factor [in a.u.].
+ calcConductivity ::Bool ... True, if the Kubo-Greenwood conductivity and the optical
constants are to be calculated.
+ condOmegas ::Array{Float64,1} ... photon energies for the conductivity [in a.u.]; carry them
WELL PAST the deepest ionization threshold and log-spaced,
since the Kramers-Kronig integral runs to infinity.
+ condBroadening ::Float64 ... width [a.u.] with which the conductivity lines of the box
are folded into a spectrum; a model parameter, see
Plasma.computeConductivitySpectrum.
+ condCollisionRate ::Float64 ... electron-ion collision rate gamma [a.u.] of the Drude
free-electron term. Zero leaves that term out; a
POSITIVE value is used as given; a NEGATIVE value means
COMPUTE it from the average atom's own scattering phase
shifts through `Plasma.dcConductivity`, which is the only
setting that leaves nothing in the optical chain supplied
from outside (see that function for what it is worth).
+ calcMeanOpacities ::Bool ... True, if the Planck and Rosseland mean opacities are to be
formed from the conductivity spectrum. NEEDS
calcConductivity, and needs condOmegas to span roughly
0.1 to 30 kT, since that is where the two thermal weights
live; both are checked.JenaAtomicCalculator.Plasma.AverageAtomScheme — Method
Plasma.AverageAtomScheme(nMax::Int64, lMax::Int64, scField::AbstractScField, calcPhotoionizationCs::Bool, calcFormFactor::Bool, calcScatteringFactor::Bool, piSubshells::Array{Subshell,1}, omegas::AbstractArray{<:Real,1}, qValues::AbstractArray{<:Real,1}) ... the nine-argument constructor, kept so that every call written before the conductivity existed still works; it leaves the conductivity out. The two meshes are accepted as ANY real arrays and converted here, since a mesh written with whole numbers – qValues = [q for q = 1:10] – is an Array{Int64,1}: the struct's own constructor converts such a list silently, but a typed method of the same arity shadows it, so a narrower signature here would refuse the very calls this constructor exists to keep working. A scheme::AverageAtomScheme is returned.
JenaAtomicCalculator.Plasma.AverageAtomScheme — Method
Plasma.AverageAtomScheme(scheme::Plasma.AverageAtomScheme; nMax::Union{Nothing,Int64}=nothing, lMax::Union{Nothing,Int64}=nothing, scField::Union{Nothing,AbstractScField}=nothing, calcPhotoionizationCs::Union{Nothing,Bool}=nothing, calcFormFactor::Union{Nothing,Bool}=nothing, calcScatteringFactor::Union{Nothing,Bool}=nothing, piSubshells::Union{Nothing,Array{Subshell,1}}=nothing, omegas::Union{Nothing,AbstractArray{<:Real,1}}=nothing, qValues::Union{Nothing,AbstractArray{<:Real,1}}=nothing, calcConductivity::Union{Nothing,Bool}=nothing, condOmegas::Union{Nothing,AbstractArray{<:Real,1}}=nothing, condBroadening::Union{Nothing,Real}=nothing, condCollisionRate::Union{Nothing,Real}=nothing, calcMeanOpacities::Union{Nothing,Bool}=nothing)
... constructor for modifying the given Plasma.AverageAtomScheme by 'overwriting' the previously selected
parameters. Everything not named is carried over unchanged, so a scheme is built by naming only what
differs from the default -- which is what makes a thirteen-field scheme readable at the call site:
scheme = Plasma.AverageAtomScheme(Plasma.AverageAtomScheme();
nMax = 8, lMax = 5, scField = Basics.AaDFSField(),
calcConductivity = true, condOmegas = [ 10^x for x = -2.0:0.08:2.6 ],
condBroadening = 0.05, condCollisionRate = -1.0 )
**THE STRUCTURE IS NEVER OPTIONAL AND HAS NO FLAG.** A converged cell always yields the chemical
potential, the bound/free split, every subshell's energy and fractional occupation, the mean charge and
the radial density; the `calc...` switches add the OPTIONAL properties on top of that, each at its own
cost. So a scheme with every switch false is a legitimate and useful computation, not an empty one.
**EACH SWITCH NEEDS ITS OWN MESH, and that dependency is enforced rather than assumed:**
`calcFormFactor` needs `qValues`, `calcPhotoionizationCs` needs `omegas` (and reads `piSubshells`), and
`calcConductivity` needs `condOmegas`. A switch set without its mesh raises at construction time, where
the mistake is, rather than returning an empty array from deep inside `perform`.
**EVERY MESH AND MODEL PARAMETER TAKES WHOLE NUMBERS AS WELL AS DECIMALS**, so `qValues = [1, 2, 3]`
and `condCollisionRate = -1` are accepted exactly as `[1., 2., 3.]` and `-1.0` are; the conversion to
Float64 happens on the way into the struct and the stored values are identical.
A `averageAtomScheme::Plasma.AverageAtomScheme` is returned.JenaAtomicCalculator.Plasma.AverageAtomScheme — Method
Plasma.AverageAtomScheme() ... constructor for an 'default' instance of a Plasma.AverageAtomScheme. A averageAtomScheme::Plasma.AverageAtomScheme is returned.
JenaAtomicCalculator.Plasma.ChargeStage — Type
struct Plasma.ChargeStage ... one charge state ("ionization stage") entering a Plasma.KineticChargeBalanceScheme, carrying one or several reference configurations of a shared electron count and, for each of them, how many of its own lowest CI levels to retain. The CLASSIC form – exactly 2 configurations, 1 level each, built by the two-argument constructor below – is the only form a Plasma.EmpiricalTreatment or Plasma.SemiEmpiricalTreatment leg may touch, because Empirical's own rate formulas resolve a CONFIGURATION, not a level: asking one of them for a rate between two levels of the SAME configuration has no defined answer. A GENERAL stage (more configurations, or more than one level from a configuration) is open only to Plasma.StructureBasedTreatment, which computes from real levels throughout; Plasma.validateKineticChargeBalanceSupport raises, rather than guessing, if a general stage is paired with an Empirical/SemiEmpirical leg.
A SECOND constraint on a general stage is NOT checked by Plasma itself: a cross-stage leg (ImpactIonization,
PhotoRecombination, ThreeBodyRecombination) connects EVERY level of one stage to EVERY level of its
neighbour, and each such pair must be a genuine single-electron capture/ionization -- the same shells
occupied except for exactly one gained or lost. Re-deriving that check here would duplicate logic
ThreeBodyRecombination.capturedSubshell already gets right; an invalid pair is left to raise there instead,
which it does loudly and correctly (confirmed 22-Oct-2026: "found 2 subshells gained ... not exactly one").
Choosing a general stage's configurations so that every pair against its neighbour IS a valid single-electron
step is therefore the user's own responsibility, not a Plasma guarantee.
See Plasma.AbstractRateTreatment.
+ configs ::Array{Configuration,1} ... reference configurations of this stage, lowest total energy expected
first for the classic 2-configuration case (ground, then excited);
for a general stage, order does not matter -- levels are sorted by
computed energy once the Multiplet is built.
+ nLevels ::Array{Int64,1} ... for each entry of configs, how many of its own lowest CI levels to
retain (same length as configs); the classic constructor sets [1,1].JenaAtomicCalculator.Plasma.ChargeStage — Method
Plasma.ChargeStage(groundConfig::Configuration, excitedConfig::Configuration) ... the CLASSIC two-configuration, one-level-each constructor – the only form an Empirical or SemiEmpirical leg may be applied to (cf. Plasma.ChargeStage). A Plasma.ChargeStage is returned.
JenaAtomicCalculator.Plasma.ChargeStage — Method
Plasma.ChargeStage(configs::Array{Configuration,1}; nLevels::Union{Nothing,Array{Int64,1}}=nothing) ... a GENERAL stage constructor: one or several reference configurations, each contributing nLevels[i] of its own lowest CI levels (default: 1 each). Usable only with Plasma.StructureBasedTreatment (cf. Plasma.ChargeStage). A Plasma.ChargeStage is returned.
JenaAtomicCalculator.Plasma.CollisionalRadiativeScheme — Type
struct Plasma.CollisionalRadiativeScheme <: Plasma.AbstractPlasmaScheme ... a small, closed-form (non-iterative) collisional-radiative population balance for one ion: for a generated set of its levels, computes how its population is distributed among them (a set of fractions summing to 1). Not a full multi-hundred-level CR code – for N levels, the steady-state balance (dn_i/dt = 0) is an N x N linear system, solved directly, once per (Te, Ne) point. Answers "how is this ion's population distributed among its levels", not "how much of this ion is present" – the latter (the ionization balance across charge states) is a separate question, answered separately (e.g. by Plasma.SahaBoltzmannScheme) if absolute densities are wanted. The ion itself (element and charge state) is not a field of this scheme: it is set entirely by the enclosing Plasma.Computation's nuclearModel (the element) and refConfigs (whose electron count against nuclearModel.Z fixes the charge state), exactly as for every other scheme.
+ NoExcitations ::Int64
... how many electrons may be excited at once, relative to the ion's own ground configuration,
when building its level set (1 = singles only, 2 = up to doubles, etc.) -- controls how rich
a level set is generated.
+ upperShellNo ::Int64
... the highest principal quantum number n allowed for an excited electron when building that
level set -- controls how far up in energy the generated levels reach.
+ ieSettings ::ImpactExcitation.Settings
... controls the electron-collisional (upward, excitation) rates between levels; the reverse
(de-excitation) direction is obtained from these by detailed balance, not computed separately.
+ peSettings ::PhotoEmission.Settings
... controls the radiative decay (A-value) rates between levels.
+ aiSettings ::AutoIonization.Settings
... RESERVED, CURRENTLY UNUSED (verified 04-Aug-2026): this field is accepted and stored, but the
driver never reads it and NO autoionization is computed -- every generated level is treated as
purely bound (radiative + collisional only), as the @warn in Plasma.perform states. Setting it
therefore changes nothing today. It is kept because the competing autoionization (electron-
ejecting) decay is genuinely needed for any generated level that lies above the next charge
state's ionization threshold -- a real possibility once NoExcitations/upperShellNo reach far
enough up in energy, and the reason example-Je.jl branch b (boron-like Ne5+) cannot be trusted
for its inner-shell block, which sits ~720 eV above threshold.
+ levelsFilenames ::Array{String,1}
... candidate files (tried in order) that may contain a previously-generated, still-matching level
set; [] (the default) means always regenerate. A fresh file is auto-written (name printed to
screen) whenever no candidate matches, for adoption into a later run -- same manual-reuse
workflow as Plasma.SahaBoltzmannScheme.isotopeFilenames.
+ ratesFilenames ::Array{String,1}
... candidate files (tried in order) that may contain previously-computed, still-matching
ImpactExcitation collision data (pre-thermal-average, so any scheme.ieSettings.temperatures
list can reuse them); [] (the default) means always recompute. Same auto-write/manual-reuse
workflow as levelsFilenames.
+ cacheDirectory ::String
... subdirectory that freshly-generated levelsFilenames/ratesFilenames files are written into
(created if missing); "" (the default) writes into the current directory. Only governs where
FRESH files go -- candidates in levelsFilenames/ratesFilenames are looked up as given, so a
cache file from elsewhere can always be reused directly.JenaAtomicCalculator.Plasma.CollisionalRadiativeScheme — Method
Plasma.CollisionalRadiativeScheme(scheme::Plasma.CollisionalRadiativeScheme; NoExcitations::Union{Nothing,Int64}=nothing, upperShellNo::Union{Nothing,Int64}=nothing, ieSettings::Union{Nothing,ImpactExcitation.Settings}=nothing, peSettings::Union{Nothing,PhotoEmission.Settings}=nothing, aiSettings::Union{Nothing,AutoIonization.Settings}=nothing, levelsFilenames::Union{Nothing,Array{String,1}}=nothing, ratesFilenames::Union{Nothing,Array{String,1}}=nothing, cacheDirectory::Union{Nothing,String}=nothing)
... constructor for modifying the given Plasma.CollisionalRadiativeScheme by 'overwriting' the previously
selected parameters.
A `collisionalRadiativeScheme::Plasma.CollisionalRadiativeScheme` is returned.JenaAtomicCalculator.Plasma.CollisionalRadiativeScheme — Method
Plasma.CollisionalRadiativeScheme() ... constructor for an 'default' instance of a Plasma.CollisionalRadiativeScheme. A collisionalRadiativeScheme::Plasma.CollisionalRadiativeScheme is returned.
JenaAtomicCalculator.Plasma.Computation — Type
struct Computation ... defines a type for defining (simple) plasma computation for atoms and ions in a given set of reference configurations. It also support different atomic processes under plasma conditions. The plasma environment is typical described in terms of its temperature, density, etc.
+ scheme ::AbstractPlasmaScheme ... Scheme (kind) of plasma computation.
+ nuclearModel ::Nuclear.Model ... Model, charge and parameters of the nucleus.
+ grid ::Radial.Grid ... The radial grid to be used for the computation.
+ refConfigs ::Array{Configuration,1} ... A list of non-relativistic configurations.
+ asfSettings ::AsfSettings
... Provides the settings for the SCF process (under plasma conditions) and the associated CI calculations.
+ settings ::Plasma.Settings ... communicates the properties of the plasmaJenaAtomicCalculator.Plasma.Computation — Method
Plasma.Computation( wa::Bool)
grid = Radial.Grid(true)
nuclearM = Nuclear.Model(18., FermiNucleus())
...
refConfigs = [Configuration("[Ne] 3s^2 3p^5")]
Plasma.Computation(Plasma.Computation(), grid=grid, nuclearModel=nuclearM, refConfigs=refConfigs, asfSettings=... )
... These simple examples can be further improved by overwriting the corresponding parameters.
A `computation::Plasma.Computation` is returned.JenaAtomicCalculator.Plasma.Computation — Method
Plasma.Computation(comp::Plasma.Computation; scheme::Union{Nothing,Plasma.AbstractPlasmaScheme}=nothing, nuclearModel::Union{Nothing,Nuclear.Model}=nothing, grid::Union{Nothing,Radial.Grid}=nothing, refConfigs::Union{Nothing,Array{Configuration,1}}=nothing, asfSettings::Union{Nothing,AsfSettings}=nothing, settings::Union{Nothing,Plasma.Settings}=nothing, printout::Bool=false)
... constructor for modifying the given Plasma.Computation by 'overwriting' the previously selected parameters.
A `computation::Plasma.Computation` is returned.JenaAtomicCalculator.Plasma.Computation — Method
Plasma.Computation() ... constructor for an 'empty' instance::Plasma.Computation. A computation::Plasma.Computation is returned.
JenaAtomicCalculator.Plasma.EmpiricalTreatment — Type
struct Plasma.EmpiricalTreatment <: Plasma.AbstractRateTreatment ... selects one of Empirical's own tabulated/fitted approximations for one leg of a Plasma.KineticChargeBalanceScheme; no SCF or CI is performed for a stage whose every leg uses this treatment. The quantity computed is otherwise identical in kind (a plasma rate coefficient, or a spontaneous rate for PhotoEmission) to what Plasma.StructureBasedTreatment returns for the same leg – only the INPUT to that same rate equation differs, which is the comparison this scheme exists to make legible.
+ approx ::Empirical.AbstractEmpiricalApproximation ... e.g. Empirical.ScaledHydrogenic(), Empirical.VanRegemorter1962(),
Empirical.Lotz1967().JenaAtomicCalculator.Plasma.KineticChargeBalanceScheme — Type
struct Plasma.KineticChargeBalanceScheme <: Plasma.AbstractPlasmaScheme ... a kinetic (rate-based, non-LTE) population balance across SEVERAL adjacent charge states of one element – the cross-charge-state sibling to Plasma.CollisionalRadiativeScheme, which is confined by design to one fixed charge state. Every chargeStages[k] is connected to itself by PhotoEmission (radiative decay, excited -> ground) and ImpactExcitation (collisional excitation/de-excitation, both directions, by detailed balance from one computed/estimated rate), and to chargeStages[k+1] by ImpactIonization (up, ground -> ground) and by PhotoRecombination + ThreeBodyRecombination (down, ground -> ground, added into the same matrix entry). DielectronicRecombination is deliberately NOT included here (an explicit scope decision, not an oversight – its resonant capture-then-stabilize mechanism does not reduce to a single rate coefficient the way the other four processes do).
EACH of the five legs carries its OWN Plasma.AbstractRateTreatment (peTreatment, ieTreatment, eiiTreatment,
rrTreatment, tbrTreatment), so a run can mix all THREE tiers -- Empirical, SemiEmpirical, StructureBased --
across the five processes freely, in any combination ("mixed use"), and EACH chargeStages[k] independently
carries however many reference configurations/levels it needs (cf. Plasma.ChargeStage). A run in which every
leg is Plasma.EmpiricalTreatment never calls a mean-field/CI computation at all and completes in well under a
second; the moment ANY leg is Plasma.SemiEmpiricalTreatment or Plasma.StructureBasedTreatment, a reference
Multiplet is generated for EVERY stage -- not only the stage(s) that leg touches -- since this is cheap here
(one mean-field pass per stage) and a per-leg, per-stage decision of which levels to generate would add real
bookkeeping for little saved time. An Empirical leg still uses its own Configuration-level formula regardless,
so this costs extra computation, never wrong physics.
NOT every combination of (treatment tier, chargeStage shape) is supported, and this is INTENTIONAL rather
than an oversight: Plasma.EmpiricalTreatment and Plasma.SemiEmpiricalTreatment resolve rates at the
CONFIGURATION level, so they are usable only on a CLASSIC Plasma.ChargeStage (exactly 2 configurations, 1
level each, cf. Plasma.ChargeStage); a GENERAL (multi-configuration or multi-level) stage requires
Plasma.StructureBasedTreatment on every leg that touches it. Plasma.SemiEmpiricalTreatment is supported on
all five legs, each with its own required approx (see Plasma.SemiEmpiricalTreatment).
Plasma.validateKineticChargeBalanceSupport checks every leg against every
stage it touches BEFORE any Multiplet is generated, and RAISES -- naming the leg, the stage, and the nearest
supported alternative -- rather than silently guessing at an unsupported combination or returning a wrong
number (the error-over-guess pattern already used by corePolarization.doApply in module-PhotoEmission.jl).
+ chargeStages ::Array{Plasma.ChargeStage,1} ... the charge states, ordered from the LOWEST to the
HIGHEST charge (fewest to most electrons removed);
chargeStages[k] and chargeStages[k+1] must differ by
exactly one electron in their groundConfig.
+ electronTemperatures ::Array{Float64,1} ... electron temperatures [K] at which the balance is solved.
+ peTreatment ::Plasma.AbstractRateTreatment ... within-stage PhotoEmission.
+ ieTreatment ::Plasma.AbstractRateTreatment ... within-stage ImpactExcitation.
+ eiiTreatment ::Plasma.AbstractRateTreatment ... cross-stage ImpactIonization (up).
+ rrTreatment ::Plasma.AbstractRateTreatment ... cross-stage PhotoRecombination (down).
+ tbrTreatment ::Plasma.AbstractRateTreatment ... cross-stage ThreeBodyRecombination (down).JenaAtomicCalculator.Plasma.KineticChargeBalanceScheme — Method
Plasma.KineticChargeBalanceScheme(scheme::Plasma.KineticChargeBalanceScheme; chargeStages::Union{Nothing,Array{Plasma.ChargeStage,1}}=nothing, electronTemperatures::Union{Nothing,Array{Float64,1}}=nothing, peTreatment::Union{Nothing,Plasma.AbstractRateTreatment}=nothing, ieTreatment::Union{Nothing,Plasma.AbstractRateTreatment}=nothing, eiiTreatment::Union{Nothing,Plasma.AbstractRateTreatment}=nothing, rrTreatment::Union{Nothing,Plasma.AbstractRateTreatment}=nothing, tbrTreatment::Union{Nothing,Plasma.AbstractRateTreatment}=nothing)
... constructor for modifying the given Plasma.KineticChargeBalanceScheme by 'overwriting' the previously selected
parameters.
A `kineticChargeBalanceScheme::Plasma.KineticChargeBalanceScheme` is returned.JenaAtomicCalculator.Plasma.KineticChargeBalanceScheme — Method
Plasma.KineticChargeBalanceScheme() ... constructor for a default instance of a Plasma.KineticChargeBalanceScheme. A kineticChargeBalanceScheme::Plasma.KineticChargeBalanceScheme is returned.
JenaAtomicCalculator.Plasma.LineShiftScheme — Type
struct Plasma.LineShiftScheme <: Plasma.AbstractPlasmaScheme ... defines a type for the details and parameters of computing level energies with plasma interactions.
+ plasmaModel ::AbstractPlasmaModel ... Specify a particular plasma model, e.g. ion-sphere, Debye.
+ initialConfigs ::Array{Configuration,1} ... List of one or several configurations that define the initial-state multiplet.
+ finalConfigs ::Array{Configuration,1} ... List of one or several configurations that define the final-state multiplet.
+ settings ::AbstractLineShiftSettings ... Specify the process and settings for which line-shifts need to be computed.
## + NoBoundElectrons ::Int64 ... Effective number of bound electrons.JenaAtomicCalculator.Plasma.LineShiftScheme — Method
Plasma.LineShiftScheme() ... constructor for a standard instance of Plasma.LineShiftScheme. A lineShiftScheme::Plasma.LineShiftScheme is returned.
JenaAtomicCalculator.Plasma.PartialWaveData — Type
struct Plasma.PartialWaveData ... defines a type to collect for partial-waves (kappa) cross sections, rates, etc. at different energies
+ kappa ::Int64 ... kappa
+ pairs ::Vector{Tuple{Float64, Float64}}
... vector of pairs, for instance (energy, cs), to later combine data in a proper manner.JenaAtomicCalculator.Plasma.PartialWaveData — Method
Plasma.PartialWaveData() ... constructor for the default values of Plasma.PartialWaveData set A partialWaveData::Plasma.PartialWaveData is returned.
JenaAtomicCalculator.Plasma.SahaBoltzmannScheme — Type
struct Plasma.SahaBoltzmannScheme <: Plasma.AbstractPlasmaScheme ... a struct to thermodynamic properties of a Saha-Boltzmann LTE mixture..
+ plasmaModel ::Basics.AbstractPlasmaModel
... A plasma model that "restricts" the Saha-Boltzmann equilibrium densities by some additional parameters, for instance,
due to ionization-potential-depression (IPD) or others.
+ calcLTE ::Bool ... True, if the Saha-Boltzmann equilibrium densities should be calculated.
+ printIonLevels ::Bool ... True, for printing detailed information about all ionic levels.
+ qRange ::UnitRange{Int64} ... Range of charge states q for which ions are taken into account.
+ maxNoIonLevels ::Int64 ... (maximum) No of ionic levels for any charge state of the ions in the mixture.
+ NoExcitations ::Int64
... No of excitations (S, D, T) that are taken into account with regard to the reference (ground) configuration of the ions.
This number is taken as a second qualifier to characterize the quality of the ionic-level data. Usually, NoExcitations = 1,2.
+ upperShellNo ::Int64
... upper-most princicpal quantum number n for which orbitals are taken into account into the ionic-level computations;
this is often chosen upperShellNo= 4..10; if ionic-level data are given, this number decides which of the levels
are taken into account.
+ isotopicMixture ::Array{Basics.IsotopicFraction,1}
... List of (non-normlized) isotopic fractions that form the requested mixture; the fractions will first be renormalized
to 1 in course of the Saha-Boltzmann LTE computations.
+ isotopeFilenames ::Array{String,1}
... set of files names from which the ionic-level data can be read in for the different isotopes (Z,A) in the mixture.JenaAtomicCalculator.Plasma.SahaBoltzmannScheme — Method
Plasma.SahaBoltzmannScheme() ... constructor for an 'default' instance of a Plasma.SahaBoltzmannScheme. A sahaBoltzmannScheme::Plasma.SahaBoltzmannScheme is returned.
JenaAtomicCalculator.Plasma.SatelliteDiagnosticScheme — Type
struct Plasma.SatelliteDiagnosticScheme <: Plasma.AbstractPlasmaScheme ... dielectronic-satellite-to-parent-line intensity-ratio Te diagnostic for one recombining ion (computation.refConfigs). The core promotion fromShells–>toShells drives BOTH the parent line (electron-impact excited, via ieSettings) and the satellites (dielectronically captured into intoShells, via drSettings) – the same physical excitation, populated two different ways.
+ fromShells ::Array{Shell,1} ... Core shell(s) excited; shared by the DR and impact-excitation steps.
+ toShells ::Array{Shell,1} ... Core-excitation target shell(s); shared by the DR and impact-excitation steps.
+ intoShells ::Array{Shell,1}
... Captured Rydberg shell(s) for DR; an EXPLICIT list of individually-resolved shells (e.g. n'=3: 3s,3p,3d),
not a generated high-n range -- only spectrally-resolvable low-n' shells belong here. Same naming AND same
semantics as Basics.ForDielectronicRecombination.intoShells: every shell given here is treated TOGETHER in
one combined doubly-excited representation/CI, exactly as ForDielectronicRecombination already works. Cost
grows sharply with the number of shells combined (measured: 220-665s for a single n=3 shell of F-like Ne+;
combining all three n=3 shells together exceeded 41 minutes). If cost becomes prohibitive, use fewer shells
here, or issue several separate Plasma.Computation calls (one per shell or small subset) -- the scheme does
not make this scoping choice automatically.
+ decayShells ::Array{Shell,1} ... (Radiative) stabilization target shell(s) for DR, e.g. [Shell("2p")]. Same
role as Basics.ForDielectronicRecombination.decayShells.
+ drSettings ::DielectronicRecombination.Settings
... Reused as-is (not re-flattened): temperatures, pathwaySelection, calcRateAlpha, corrections,
augerOperator, multipoles, gauges all come from here.
+ ieSettings ::ImpactExcitation.Settings
... Reused as-is: temperatures, lineSelection, calcRateCoefficient, maxKappa, numElectronEnergies,
maxEnergyMultiplier, operator all come from here. printBefore is forced to false internally by
the driver regardless of what is set here (module-ImpactExcitation.jl displayLines() bug workaround).JenaAtomicCalculator.Plasma.SatelliteDiagnosticScheme — Method
Plasma.SatelliteDiagnosticScheme(scheme::Plasma.SatelliteDiagnosticScheme; fromShells::Union{Nothing,Array{Shell,1}}=nothing, toShells::Union{Nothing,Array{Shell,1}}=nothing, intoShells::Union{Nothing,Array{Shell,1}}=nothing, decayShells::Union{Nothing,Array{Shell,1}}=nothing, drSettings::Union{Nothing,DielectronicRecombination.Settings}=nothing, ieSettings::Union{Nothing,ImpactExcitation.Settings}=nothing)
... constructor for modifying the given Plasma.SatelliteDiagnosticScheme by 'overwriting' the previously
selected parameters.
A `satelliteDiagnosticScheme::Plasma.SatelliteDiagnosticScheme` is returned.JenaAtomicCalculator.Plasma.SatelliteDiagnosticScheme — Method
Plasma.SatelliteDiagnosticScheme() ... constructor for an 'default' instance of a Plasma.SatelliteDiagnosticScheme. A satelliteDiagnosticScheme::Plasma.SatelliteDiagnosticScheme is returned.
JenaAtomicCalculator.Plasma.SemiEmpiricalTreatment — Type
struct Plasma.SemiEmpiricalTreatment <: Plasma.AbstractRateTreatment ... selects the SAME fitted formula an Plasma.EmpiricalTreatment(approx) leg would use, but fed a REAL, JAC-computed input instead of a scaled/hydrogenic one – a cheap mean-field quantity, not a correlated (CI) one, which is what keeps this tier cheaper in structure than Plasma.StructureBasedTreatment while being more realistic in input than Plasma.EmpiricalTreatment. Usable only on a CLASSIC Plasma.ChargeStage (cf. Plasma.ChargeStage), exactly like Plasma.EmpiricalTreatment.
Supported for PhotoEmission and PhotoRecombination, where approx must be Empirical.UsingJAC() -- Empirical's
own mean-field estimator, used directly (PhotoRecombination's photoionizationCrossSection(.., UsingJAC())
feeds the Einstein-Milne relation exactly as ScaledHydrogenic's own Kramers formula does); for
ImpactExcitation, where approx must be Empirical.VanRegemorter1962() and the real Einstein-A is obtained by
calling Empirical.photoemissionEinsteinA(.., Empirical.UsingJAC()) and bridging the result in as
aSource=Empirical.GivenEinsteinA(..); and for ImpactIonization/ThreeBodyRecombination, where approx must be
Empirical.Lotz1967() -- the SAME Lotz/Saha formula EmpiricalTreatment(Lotz1967()) would use -- fed a
mean-field (AL-Field) binding energy via pSource=Empirical.UsingJAC() rather than a tabulated one, cf.
Empirical.impactIonizationBindingEnergy.
+ approx ::Empirical.AbstractEmpiricalApproximation ... the formula this tier's real input is fed into;
Empirical.UsingJAC() for PhotoEmission/
PhotoRecombination, Empirical.VanRegemorter1962()
for ImpactExcitation, Empirical.Lotz1967() for
ImpactIonization/ThreeBodyRecombination.JenaAtomicCalculator.Plasma.Settings — Type
struct Plasma.Settings ... defines a type for the details and parameters of computing photoionization lines.
+ temperature ::Float64
... Plasma temperature. Unit convention is scheme-dependent: Plasma.perform(scheme::AverageAtomScheme, ...)
expects temperature in [K] and converts it internally; Plasma.perform(scheme::SahaBoltzmannScheme, ...)
expects temperature already in atomic (Hartree) units, cf. example-Jc.jl. Watch this when re-using
the same Settings across different schemes.
+ density ::Float64 ... Plasma density in [g/cm^3].
+ useNumberDensity ::Bool
... true, if the density above is taken as (total ion) number density ni, and false otherwise.JenaAtomicCalculator.Plasma.Settings — Method
Plasma.Settings(set::Plasma.Settings; temperature::Union{Nothing,Float64}=nothing, density::Union{Nothing,Float64}=nothing, useNumberDensity::Union{Nothing,Bool}=nothing)
... constructor for modifying the given Plasma.Settings by 'overwriting' the previously selected parameters.
A `settings::Plasma.Settings` is returned.JenaAtomicCalculator.Plasma.Settings — Method
Plasma.Settings() ... constructor for the default values of plasma computations A settings::Plasma.Settings is returned.
JenaAtomicCalculator.Plasma.StructureBasedTreatment — Type
struct Plasma.StructureBasedTreatment <: Plasma.AbstractRateTreatment ... selects JAC's own ab-initio/semi-empirical structure computation for one leg of a Plasma.KineticChargeBalanceScheme. Despite the name, this is NOT one uniform level of rigor across the five processes: PhotoEmission and ImpactExcitation are intrinsically ab-initio (there is no other JAC route for them); ImpactIonization and ThreeBodyRecombination are semi-empirical, since eiiModel itself selects a BEB/BED/... cross-section model over REAL computed levels; PhotoRecombination is ab-initio, a genuine structure-based cross section. A scheme prints which is which (see Plasma.displayKineticChargeBalanceTreatments); this field exists only to carry the one knob that the EII/TBR legs still need.
+ eiiModel ::ImpactIonization.AbstractModel ... read only by the ImpactIonization and ThreeBodyRecombination legs;
ignored otherwise.JenaAtomicCalculator.Plasma.StructureBasedTreatment — Method
Plasma.StructureBasedTreatment() ... constructor with the default eiiModel = ImpactIonization.BEBmodel(). A structureBasedTreatment::Plasma.StructureBasedTreatment is returned.
JenaAtomicCalculator.Plasma.SuperConfigurationIonizationScheme — Type
struct Plasma.SuperConfigurationIonizationScheme <: Plasma.AbstractPlasmaScheme ... a type for the EQUILIBRIUM (LTE) population across several ionization stages of ONE species, each stage described by SuperConfigurations.Group's rather than by diagonalized levels – the natural extension of SuperConfigurationOpacityScheme ACROSS charge states instead of within one.
THE PHYSICS IS THE GRAND-CANONICAL REFORMULATION OF THE SAHA EQUATION, the SAME one
`Plasma.SahaBoltzmannScheme` already uses and the SAME equations example-Jc.jl independently
verified by hand: every (stage q, group g) pair carries a Boltzmann weight
`g.degeneracy * exp(-(mu_e*q + g.meanEnergy - Eref)/kT)` in ONE shared sum over every stage at
once, where `mu_e` is the electron chemical potential and `q` the stage's charge (nuclear charge
minus its own electron count). `mu_e` is tied to the electron density by the standard non-degenerate
ideal-electron-gas relation, and the two are found together by a SELF-CONSISTENT fixed-point
iteration on charge neutrality -- reimplemented here rather than calling `SahaBoltzmannScheme`'s own
code, which is NOT in the test suite and carries isotopic-mixture and ionization-potential-
depression machinery this scheme deliberately does not need.
REUSES, NOT REIMPLEMENTS, EVERY STAGE'S OWN STRUCTURE: one `SuperConfigurations.Group` per
configuration, exactly as `SuperConfigurationOpacityScheme`'s Stage 1 already builds them -- no
diagonalization, no new structure physics.
SCOPE, DELIBERATELY NARROW, the same choice `SuperConfigurations` itself made for the same reason:
ONE species (no isotopic mixture), vacuum ionization energies (no ionization-potential-depression
model), and every stage considered must carry AT LEAST ONE electron -- a fully stripped bare
nucleus needs no `Group` at all and is not handled here.
+ refConfigsPerStage ::Array{Array{Configuration,1},1} ... one list of reference configurations per
ionization stage, ORDERED from the
LEAST to the MOST ionized stage
considered.JenaAtomicCalculator.Plasma.SuperConfigurationIonizationScheme — Method
Plasma.SuperConfigurationIonizationScheme() ... constructor for a standard (empty) instance. A superConfigurationIonizationScheme::Plasma.SuperConfigurationIonizationScheme is returned.
JenaAtomicCalculator.Plasma.SuperConfigurationMixtureOpacityScheme — Type
struct Plasma.SuperConfigurationMixtureOpacityScheme <: Plasma.AbstractPlasmaScheme ... a type for a MIXTURE of species, each possibly spread over SEVERAL of its own ionization stages, combined at a SHARED LTE temperature computation.settings.temperature into one PLANCK MEAN opacity over opacityOmegas. This is C9's own named remainder, item C20 in the competition list: "opacity for a realistic mixture, not one species" – EXTENDED 18-Oct-2026 to also cover the stage axis SuperConfigurationIonizationScheme covers for one species alone, so a mixture no longer has to be given a single hand-picked charge state per species.
EACH SPECIES CARRIES ITS OWN `Nuclear.Model` AND OWN GRID PER STAGE, built automatically
(`Basics.recommendedGrid`) rather than shared from `computation` -- a mixture is, by definition, more
than one element (and, now, each element possibly more than one charge state), so
`computation.nuclearModel`/`computation.grid` (sized for ONE species at ONE stage) cannot be reused
without breaking Rule 12's box-matching requirement for whichever (species,stage) is not the one
`computation` was built for. `computation.nuclearModel`/`computation.grid` are therefore UNUSED by
this scheme, the same way `computation.refConfigs` is already unused by
`SuperConfigurationOpacityScheme`'s own `refConfigs` field.
THE IONIZATION BALANCE IS SOLVED FIRST, COUPLED ACROSS EVERY SPECIES AT ONCE -- the genuinely new
physics here, not a wiring exercise: `SuperConfigurationIonizationScheme`'s own charge-neutrality
equation assumes ONE species supplies every electron, which is wrong the moment a species is a
trace component of the mixture -- its own ionization balance then depends on an electron density
set mostly by everyone ELSE. The SAME grand-canonical fixed-point iteration is reused, with the
charge-neutrality sum lifted to range over every (species, stage) pair:
n_e = n_ion,total * SUM_species numberFractions[s] * SUM_stages_i charge[s,i] * p[s,i]
where `p[s,i]` is species `s`'s OWN Boltzmann population of stage `i`, normalized to 1 WITHIN that
species (`SUM_i p[s,i] = 1`) at the SHARED chemical potential `mu_e` every species sees -- each
species keeps its own, purely numerical energy reference for the exponentials (Eref_s), which never
needs to agree ACROSS species since it cancels out of that species' own normalization. A SINGLE-
STAGE species has `p[s,1] = 1` identically, whatever `mu_e` is -- which is exactly why the
backward-compatible constructor below reproduces the ORIGINAL (17-Oct-2026) scheme's numbers
unchanged: the balance above is trivial when there is only one state to belong to.
THE MIXING RULE builds on that balance in two stages: WITHIN a species, its own stages' Stage-3
`kappa_{s,i}(omega)` (each built with EXACTLY `SuperConfigurationOpacityScheme`'s own machinery) are
weighted by that stage's OWN population `p[s,i]`; ACROSS species, by `numberFractions`:
kappa_s(omega) = SUM_i p[s,i] * kappa_{s,i}(omega)
kappa_mix(omega) = SUM_s numberFractions[s] * kappa_s(omega)
THE PLANCK MEAN is the standard dimensionless-weight form, written in terms of `x = omega/kT`:
kappa_P = INTEGRAL kappa_mix(x) * w_P(x) dx, w_P(x) = (15/pi^4) * x^3/(e^x-1)
normalized so `INTEGRAL w_P(x) dx = 1` over `x in (0,infinity)` -- the standard check this scheme's
own test uses: a FREQUENCY-INDEPENDENT `kappa_mix` must return exactly that same constant as its
Planck mean, since a weighted average of a constant is that constant. The integral is evaluated by
the trapezoidal rule over `opacityOmegas` itself, so the grid must be wide and fine enough to
resolve `w_P`'s own peak near `x ~ 3-4` AND every species' own line widths -- not merely wide
enough for the lines alone, as a single-species `opacityOmegas` choice would be.
**THE ROSSELAND MEAN IS WITHHELD UNLESS `boundFreeApprox` IS GIVEN**, and this was a finding, not
an oversight: a Rosseland mean is a HARMONIC average, dominated by whichever frequencies are LEAST
opaque, and a `kappa(omega)` built from E1 lines ALONE -- no bound-free or free-free continuum --
leaves every frequency between lines a true gap with nothing sensible to divide into. Measured, not
assumed, 17-Oct-2026: sweeping the numerical floor `Plasma.rosselandMeanOpacity` needs just to avoid
dividing by machine-zero moved the returned value by MORE THAN ELEVEN ORDERS OF MAGNITUDE (0.049
down to 7.7e-13) on the SAME line-only spectrum -- proof the number had no content, set by an
implementation detail rather than physics. The PLANCK mean, an ARITHMETIC (kappa-weighted) average,
has no such gap-sensitivity and remains reported unconditionally.
**BOUND-FREE, 18-Oct-2026 (`boundFreeApprox`, optional, default `nothing` = off):** when given an
`Empirical.AbstractEmpiricalApproximation` (e.g. `Empirical.ScaledHydrogenic()`, the default choice
once turned on), `Plasma.perform` ALSO sums a photoionization contribution between every pair of
ADJACENT stages of a species, reusing the ALREADY-VALIDATED `Empirical.photoionizationCrossSection`
-- Kramers' (1923) formula scaled by the ionized shell's own binding energy and a bound-free Gaunt
factor, the SAME machinery `Cascade.BoundFreeOpacity` already relies on for exactly this purpose
elsewhere in JAC. No new ab initio machinery is needed: that function already takes a bare
`(initialConfig, finalConfig)` pair, which is exactly what `refConfigsPerSpeciesStages`' own
adjacent-stage configurations already are, so this is substantially a WIRING addition on top of
machinery this project has already audited (see [[project_empirical_module]]-equivalent history),
NOT a new physical capability built from scratch. For every GROUP `g` in stage `i` and GROUP `h` in
stage `i+1` whose configurations differ by exactly one electron in exactly one shell (checked via
`Basics.extractFromConfigurations(Basics.OccupationDifference(), ...)`, the SAME compatibility test
`Empirical.photoionizationCrossSection` itself applies), the cross section is weighted by `g`'s own
ABSOLUTE population within the species -- `stagePopulations[s][i] * (g's population WITHIN stage i)`
-- and summed; a pair whose configurations are not a genuine single-electron ionization channel is
simply SKIPPED, not an error, exactly as a same-parity pair is skipped (not an error) in the
bound-bound Stage 2 above. Reported SEPARATELY from the bound-bound spectrum (own ResultKeys), so a
user always sees bound-bound, bound-free, and their sum as three distinct, clearly labelled things
-- never silently merged. Once this exists, `Plasma.rosselandMeanOpacity` is called on the SUMMED
(bound-bound + bound-free) spectrum and reported.
**FREE-FREE (inverse bremsstrahlung), 19-Oct-2026 (`freeFreeIncluded`, optional `Bool`, default
`false`):** when `true`, `Plasma.perform` ALSO sums, for every (species,stage), the free-free
(inverse-bremsstrahlung) absorption coefficient of a free electron scattering off that stage's own
ion charge, `Empirical.freeFreeAbsorptionCoefficient` -- the classical Kramers cross section times
the quantum Gaunt-factor correction, read from Sutherland's (1998) thermally-averaged table and
derived, step for step, against the typeset equations of Karzas & Latter (1961); see that function's
own docstring for the full derivation and provenance. Unlike bound-free, this needs no PAIR of
adjacent stages -- a stage's own charge alone sets the Coulomb field a passing electron feels -- so
it is available even for a single-stage species, PROVIDED a real electron density exists, i.e.
`useNumberDensity`/`density` must be set exactly as bound-free's multi-stage case already requires;
`freeFreeIncluded = true` with no density raises, naming what is missing. A neutral stage (charge 0)
contributes exactly zero, by construction of the formula's own Z^2 factor, not as a special case.
Reported under its OWN new key, SuperConfigurationMixtureFreeFreeOpacity, never merged into the
bound-free number; the TOTAL spectrum/Planck/Rosseland keys now mean "bound-bound plus whichever of
bound-free/free-free are switched on", and are present whenever EITHER is active.
**RESONANCES (autoionizing lines), 20-Oct-2026 (`resonanceContinuumGrid`, optional
`Union{Nothing,Radial.Grid}`, default `nothing` = off):** every stage's own excited configurations
already include some that lie ABOVE the adjacent, more-ionized stage's ground energy --
`Plasma.classifyResonantGroups` flags these RESONANT -- and are reached from that stage's own ground
configuration by an ORDINARY bound-bound E1 transition, exactly like any other line this scheme
already builds. What makes such a line different is its DECAY: besides radiating, it can
AUTOIONIZE into the adjacent stage's continuum, which gives it a finite lifetime and hence a
LORENTZIAN (not delta-function) contribution to its width, on top of the GAUSSIAN statistical
spread (`TransitionArray.variance`) every line already carries. The two combine into a Voigt
profile, `Plasma.voigtLineProfile` -- the Faddeeva-function closed form, verified (not assumed)
against a direct numerical convolution of the two component profiles to `1e-12` relative, against
its own normalization integral to `1e-10`, and against both single-component limits
(`gammaFWHM -> 0` reduces to `Plasma.gaussianLineProfile`; `sigma -> 0` reduces to a pure
Lorentzian), before being written into this scheme.
The width itself is `Plasma.resonanceAutoionizationWidth` -- a REPRESENTATIVE-LEVEL width, reusing
JAC's own, already-validated `AutoIonization` process UNCHANGED (no new decay-rate formula), applied
to the SAME ground-to-resonance `TransitionArray` this scheme's own Stage 2 already builds for that
pair. Each such line is therefore corrected IN PLACE, from the Gaussian its own Stage 2/3 would
otherwise give it to the Voigt profile its finite lifetime actually implies -- the correction is
`gfEff * (voigtLineProfile(...) - gaussianLineProfile(...))`, added directly into that stage's own
`kappa(omega)` before it is weighted into the species and mixture totals, so every other line (every
line with no open autoionization channel) is completely unaffected and the whole treatment is OFF,
byte-identically, whenever `resonanceContinuumGrid` is `nothing`. No new `ResultKeys` category is
needed for the bound-bound spectrum itself -- it simply contains better-shaped lines where they
apply -- but the resonances actually corrected are reported separately for inspection, under
`SuperConfigurationMixtureResonanceCorrections`.
+ nuclearModels ::Array{Nuclear.Model,1} ... one nuclear model per species.
+ refConfigsPerSpeciesStages ::Array{Array{Array{Configuration,1},1},1}
... one species' own `refConfigsPerStage` -- EXACTLY `SuperConfigurationIonizationScheme`'s own field
shape, one `Array{Configuration,1}` per ionization stage of that species -- matching
`nuclearModels` and `numberFractions` by index. A species with only ONE stage (the common case
before the coupled balance below existed) is simply a length-1 outer array; the backward-
compatible constructor below builds exactly that from the OLD one-stage-per-species call shape.
+ numberFractions ::Array{Float64,1} ... each species' number
fraction of the mixture; expected to
sum to 1, checked, not enforced silently.
+ opacityOmegas ::Array{Float64,1} ... the SHARED photon-energy
grid [a.u.] every species' Stage-3
spectrum and the Planck mean are built on.
+ boundFreeApprox ::Union{Nothing,Empirical.AbstractEmpiricalApproximation}
... `nothing` (default) turns the bound-free contribution OFF, reproducing every pre-18-Oct-2026
result unchanged; `Empirical.ScaledHydrogenic()` turns it ON. See above for what it adds.
+ freeFreeIncluded ::Bool
... `false` (default) turns the free-free contribution OFF; `true` turns it ON. See above for what
it adds. Unlike `boundFreeApprox` there is only ONE trusted free-free formula available, so this
is a plain switch rather than a choice among `Empirical.AbstractEmpiricalApproximation`s.
+ resonanceContinuumGrid ::Union{Nothing,Radial.Grid}
... `nothing` (default) turns the RESONANCE (autoionizing-line) treatment OFF, reproducing every
pre-20-Oct-2026 result unchanged. A `Radial.Grid` turns it ON and is the grid
`AutoIonization.computeLines` uses for the ejected electron's continuum orbital -- NOT auto-
derived (Rule 12: `Basics.recommendedGrid` is sized for BOUND orbitals only), so the CALLER must
supply one already checked adequate for the ejected electron's kinetic energy in every channel
the mixture opens. **ONE GRID SERVES EVERY SPECIES, STAGE AND RESONANT GROUP** -- a known
simplification, stated rather than hidden: a mixture whose channels span a wide range of
ejected-electron energies may need a wider or finer grid than any single channel alone would,
and this field offers no per-channel adjustment. See `Plasma.resonanceAutoionizationWidth`'s own
docstring for the full Rule-12 discussion this field's caller must satisfy.
+ resonanceAugerSettings ::AutoIonization.Settings
... the settings passed to every `AutoIonization` call the resonance treatment makes; unused when
`resonanceContinuumGrid` is `nothing`. Default `AutoIonization.Settings()`.JenaAtomicCalculator.Plasma.SuperConfigurationMixtureOpacityScheme — Method
Plasma.SuperConfigurationMixtureOpacityScheme(nuclearModels::Array{Nuclear.Model,1}, refConfigsPerSpecies::Array{Array{Configuration,1},1}, numberFractions::Array{Float64,1}, opacityOmegas::Array{Float64,1}) ... BACKWARD-COMPATIBLE constructor for the ORIGINAL, single-stage-per-species call shape (17-Oct-2026): each species' flat Array{Configuration,1} is wrapped into a length-1 outer array and boundFreeApprox/freeFreeIncluded are set to nothing/false, so every pre-existing call site keeps compiling and – since a single-stage species has a TRIVIAL ionization balance (stagePopulations = [1.0] whatever the temperature or density, there being only one state to belong to) AND both continuum contributions are off by default – keeps returning EXACTLY the result it always did, unaffected by the coupled multi-species balance or either continuum addition the general constructor now also allows. A scheme::SuperConfigurationMixtureOpacityScheme is returned.
JenaAtomicCalculator.Plasma.SuperConfigurationMixtureOpacityScheme — Method
Plasma.SuperConfigurationMixtureOpacityScheme(nuclearModels::Array{Nuclear.Model,1}, refConfigsPerSpeciesStages::Array{Array{Array{Configuration,1},1},1}, numberFractions::Array{Float64,1}, opacityOmegas::Array{Float64,1}, boundFreeApprox::Empirical.AbstractEmpiricalApproximation) ... BACKWARD-COMPATIBLE constructor for the 18-Oct-2026 bound-free-only 5-argument call shape (the one TestFrames.testModule_SuperConfigurationMixtureOpacity's own check (8) uses): freeFreeIncluded is set to false, so this call shape keeps compiling and free-free stays off unless explicitly requested through the full 6-argument form. A scheme::SuperConfigurationMixtureOpacityScheme is returned.
JenaAtomicCalculator.Plasma.SuperConfigurationMixtureOpacityScheme — Method
Plasma.SuperConfigurationMixtureOpacityScheme(nuclearModels::Array{Nuclear.Model,1}, refConfigsPerSpeciesStages::Array{Array{Array{Configuration,1},1},1}, numberFractions::Array{Float64,1}, opacityOmegas::Array{Float64,1}, boundFreeApprox::Union{Nothing,Empirical.AbstractEmpiricalApproximation}, freeFreeIncluded::Bool, resonanceContinuumGrid::Radial.Grid) ... CONVENIENCE constructor for turning the 20-Oct-2026 resonance treatment ON with the default AutoIonization.Settings(); equivalent to the full 8-argument struct constructor with resonanceAugerSettings = AutoIonization.Settings(). A scheme::SuperConfigurationMixtureOpacityScheme is returned.
JenaAtomicCalculator.Plasma.SuperConfigurationMixtureOpacityScheme — Method
Plasma.SuperConfigurationMixtureOpacityScheme(nuclearModels::Array{Nuclear.Model,1}, refConfigsPerSpeciesStages::Array{Array{Array{Configuration,1},1},1}, numberFractions::Array{Float64,1}, opacityOmegas::Array{Float64,1}, boundFreeApprox::Union{Nothing,Empirical.AbstractEmpiricalApproximation}, freeFreeIncluded::Bool) ... BACKWARD-COMPATIBLE constructor for the 19-Oct-2026 full 6-argument call shape (the one TestFrames.testModule_SuperConfigurationMixtureOpacity's own check (9), free-free, uses): this shape USED TO BE the struct's own plain positional constructor, before resonanceContinuumGrid/ resonanceAugerSettings were added 20-Oct-2026 and pushed it to 8 fields; this overload keeps it compiling, with the resonance treatment OFF (nothing, AutoIonization.Settings()). A scheme::SuperConfigurationMixtureOpacityScheme is returned.
JenaAtomicCalculator.Plasma.SuperConfigurationMixtureOpacityScheme — Method
Plasma.SuperConfigurationMixtureOpacityScheme(nuclearModels::Array{Nuclear.Model,1}, refConfigsPerSpeciesStages::Array{Array{Array{Configuration,1},1},1}, numberFractions::Array{Float64,1}, opacityOmegas::Array{Float64,1}) ... BACKWARD-COMPATIBLE constructor for the 18-Oct-2026 species+stage call shape WITHOUT a 5th argument (example-Jh.jl branch b's own call shape): boundFreeApprox/freeFreeIncluded are set to nothing/false, so every such call site keeps compiling and both continuum contributions stay off unless explicitly requested through the full 6-argument form. A scheme::SuperConfigurationMixtureOpacityScheme is returned.
JenaAtomicCalculator.Plasma.SuperConfigurationMixtureOpacityScheme — Method
Plasma.SuperConfigurationMixtureOpacityScheme() ... constructor for a standard (empty) instance. A superConfigurationMixtureOpacityScheme::Plasma.SuperConfigurationMixtureOpacityScheme is returned.
JenaAtomicCalculator.Plasma.SuperConfigurationOpacityScheme — Type
struct Plasma.SuperConfigurationOpacityScheme <: Plasma.AbstractPlasmaScheme ... a type for a superconfiguration-based plasma computation: ONE Gaussian SuperConfigurations.Group per reference configuration (a shared orbital set is built once, from ALL of refConfigs together), the Boltzmann population each group carries at the plasma temperature computation.settings.temperature, ONE SuperConfigurations.TransitionArray for every PAIR of refConfigs connected by a single-electron E1 transition (opposite parity), and – if opacityOmegas is non-empty – the SUM of every array's own Gaussian line profile on that frequency grid: a per-absorber photo-absorption cross section kappa(omega), in atomic units (a0^2).
STAGE 3 OF 3. Stage 1 was the population weighting alone; Stage 2 added the per-array transition
moment (mean energy, width, oscillator-strength sum `gf`) that Stage 1 lacked. This stage folds
every array's own Gaussian -- whose shape was CALIBRATED, not assumed, against a direct
diagonalization (skewness +0.28, excess kurtosis +1.11 on a real case; see
`SuperConfigurations.TransitionArray`'s own docstring) -- onto one shared frequency grid, weighted
by its lower configuration's population, into the single summed spectrum the scheme is named for.
`opacityOmegas` left empty (the default) skips this stage exactly as before; Stages 1 and 2 do not
need it. WHAT THIS STILL IS NOT: a macroscopic opacity in cm^2/g -- that needs an ion number density
and mass this scheme is not given, a multiplication the caller supplies.
+ refConfigs ::Array{Configuration,1} ... the configurations whose `SuperConfigurations.Group`
this scheme builds, one group per configuration.
+ opacityOmegas ::Array{Float64,1} ... photon energies [a.u.] at which to sum the Stage-3
spectrum; empty (the default) skips Stage 3.JenaAtomicCalculator.Plasma.SuperConfigurationOpacityScheme — Method
Plasma.SuperConfigurationOpacityScheme(refConfigs::Array{Configuration,1}) ... constructor with opacityOmegas defaulted to empty, i.e. Stages 1 and 2 only – every existing caller from before Stage 3 was added keeps working unchanged. A superConfigurationOpacityScheme::Plasma.SuperConfigurationOpacityScheme is returned.
JenaAtomicCalculator.Plasma.SuperConfigurationOpacityScheme — Method
Plasma.SuperConfigurationOpacityScheme() ... constructor for a standard (empty) instance. A superConfigurationOpacityScheme::Plasma.SuperConfigurationOpacityScheme is returned.
JenaAtomicCalculator.Basics.perform — Method
Basics.perform(comp::Plasma.Computation; output::Bool=false) ... to set-up and perform a plasma computation that starts from a given set of reference configurations and supports both an atomic-average SCF procedure and the computation of various plasma properties and processes. The method only dispatches on comp.scheme and hands the work to Plasma.perform(comp.scheme, comp; output=output), so what it returns is what that scheme's method returns: with output = false nothing, and with output = true a results::Dict{String,Any} whose keys give access to the individual steps. The results of all individual steps are printed to screen.
JenaAtomicCalculator.Plasma.isClassicChargeStage — Method
Plasma.isClassicChargeStage(stage::Plasma.ChargeStage) ... tests whether stage is in the CLASSIC form (exactly 2 configurations, 1 level each) that an Empirical or SemiEmpirical leg may be applied to (cf. Plasma.ChargeStage). A Bool is returned.
Average-atom computations
JenaAtomicCalculator.Plasma.computeElectronNumberDensity — Method
Plasma.computeElectronNumberDensity(grid::Radial.Grid, orbitals::Dict{Subshell, Orbital}, chemMu::Float64, temp::Float64) ... computes the electron number density ne from the one-particle energies of the electrons, the chemical potential chemMu [a.u.] and the temperature [a.u.]. A triple of three Array{Float64,1}'s ( totalNe, posNe, negNe ) which refer to the total n_e (r) and the contributions of the positive and negative part of the spectrum, respectively, all with regard to the given grid.
JenaAtomicCalculator.Plasma.computeFormFactors — Method
Plasma.computeFormFactors(qValues::Array{Float64,1}, orbitals::Dict{Subshell, Orbital}, chemMu::Float64, temp::Float64, grid::Radial.Grid; radiusCell::Float64=0.) ... computes the (standard) form factor F(q) for the electron density as given by the AA orbitals. A list of formFactors::Array{Float64,1} is returned that directly refers to the given q-values.
**THE INTEGRAL STOPS AT THE CELL**, given `radiusCell`. A form factor is the transform of ONE atom's
electron density, and in this model that atom is the Wigner-Seitz cell; the average-atom orbitals are
now normalised over a B-spline box several times wider than the cell, so integrating to the end of the
grid adds the neighbouring cells' electrons to this atom. Measured 08-Oct-2026 on boron at 2.463 g/cm^3:
F(1) came out 2.716 over the whole box against 4.210 over the cell, the oscillating `sin(qr)/qr` outside
the cell cancelling part of what belongs inside it. `radiusCell = 0.` keeps the whole grid, which is
correct only where the box IS the cell.JenaAtomicCalculator.Plasma.computeMeanCharge — Method
Plasma.computeMeanCharge(nm::Nuclear.Model, orbitals::Dict{Subshell, Orbital}, chemMu::Float64, temp::Float64) ... computes the mean charge of an average-atom ion from a given set of orbitals, i.e. the number of electrons that are NOT bound to it, Z* = sum_(eps>0) (2j+1) f(eps,mu,T); a meanCharge::Float64 is returned.
**IT USED TO RETURN `Z - sum_(eps>0) occ f`, WHICH IS THE COMPLEMENT -- the number of BOUND electrons --
under the name of the mean charge.** Corrected 08-Oct-2026: for aluminium at solid density and 10 eV it
printed 9.986 where the mean charge is 3.014, so the error was not small but exactly the complement, and
at neutrality the two are indistinguishable by eye only when Z/2 electrons happen to be free.
This form sums over whatever orbitals it is handed, so it is as complete as that set is.
`Plasma.perform(::AverageAtomScheme, ...)` does NOT use it: it takes the mean charge from
`SelfConsistent.solveAverageAtomSpectra`, which counts the FULL per-kappa spectrum of the cell -- about
seventy-eight states per kappa against the half-dozen a subshell list carries -- and whose count satisfies
neutrality exactly. The two agree only where the subshell list happens to hold the whole continuum.JenaAtomicCalculator.Plasma.computePhotoionizationData — Method
Plasma.computePhotoionizationData(piSubshells::Array{Subshell,1}, orbitals::Dict{Subshell, Orbital}, chemMu::Float64, temp::Float64, grid::Radial.Grid, pot::Radial.Potential, omegas::Array{Float64,1}) ... computes the bound-free photoionization cross section sigma_bf(omega) of each of the given bound subshells in the converged average-atom potential, for every photon energy in omegas [a.u.]; a Dict{Subshell, Array{Float64,1}} of cross sections [a.u.] is returned, one entry per subshell and one value per omega.
**THIS IS EQ. (23) OF JOHNSON & NILSEN, HEDP 31 (2019) 92**, `sigma_bf = (8 pi^2/3) alpha omega |D|^2` with
the radial dipole matrix element `D = int P_eps,l(r) r P_b(r) dr` of Eq. (24). The continuum electron takes
the energy `eps = omega + eps_b` left over after the binding energy, so a photon below threshold returns zero.
**THE FRACTIONAL OCCUPATION IS APPLIED HERE AND IS NOT A DETAIL.** In a plasma the bound subshell is only
partly filled, and Johnson multiplies the cross section by the fractional occupation -- occ/2 for the K shell,
which is just the Fermi-Dirac factor f(eps_b) itself. Their Fig. 7 shows that factor accounting for a 95 %
reduction of the opacity between 20 and 500 eV while the cross section proper contributes 18 %, so a
sigma_bf computed without it is not approximately right but wrong by more than an order of magnitude.
**THE ANGULAR FACTOR IS THE s -> p ONE.** The 8 pi^2/3 of Eq. (23) already carries the angular algebra of a
K-shell (l = 0 -> l = 1) transition, which is what the paper computes and what this reproduces. For a
subshell with l > 0 the two channels l-1 and l+1 would each need their own weight, so such a subshell is
REFUSED here rather than silently given the K-shell factor. The two relativistic partial waves p_1/2 and
p_3/2 are combined with their statistical weights, which returns the single non-relativistic l = 1 channel
in the limit where they coincide.JenaAtomicCalculator.Plasma.computeScatteringFactors — Method
Plasma.computeScatteringFactors(omegas::Array{Float64,1}, piData::Dict{Subshell, Array{Float64,1}}, nm::Nuclear.Model) ... computes the imaginary part f2 of the atomic scattering factor and the x-ray mass attenuation coefficient mu/rho from the bound-free cross sections; a Tuple (f2::Array{Float64,1}, muOverRho::Array{Float64,1}) is returned, with f2 dimensionless and mu/rho in cm^2/g.
**EQS. (21) AND (27) OF JOHNSON & NILSEN (2019)**: `f_2 = sigma_bf / (2 r_0 lambda)` relates the imaginary
scattering factor to the cross section through the optical theorem, and `mu/rho = (N_A/A) sigma_bf` is the
mass attenuation coefficient that the x-ray intensity falls off with, `I = I_0 exp(-mu z)`. Both are summed
over the subshells present in piData, since each contributes additively to the absorption.JenaAtomicCalculator.Plasma.determineWignerSeitzRadius — Method
Plasma.determineWignerSeitzRadius(rho::Float64, nm::Nuclear.Model) ... determines the Wigner-Seitz radius R^(WS) from the plasma density rho [g/cm^3] ne and the nuclear charge Z.
JenaAtomicCalculator.Plasma.displayElectronNumberDensity — Method
Plasma.displayElectronNumberDensity(grid::Radial.Grid, orbitals::Dict{Subshell, Orbital}, chemMu::Float64, temp::Float64, radiusWS::Float64) ... displays the electron number density 4pi r^2 ne from the one-particle energies of the electrons, the chemical potential chemMu [a.u.] and the temperature [a.u.]. It tabulates the radial grid, total density as well as the contributions from orbital with negative and positive binding energies separately for a fixed stepsize in r/a_o. Nothing is returned from this procedure
JenaAtomicCalculator.Plasma.displayPhotoionizationCrossSections — Method
Plasma.displayPhotoionizationCrossSections(omegas::Array{Float64,1}, piData::Dict{Subshell, Array{Float64,1}}) ... displays the bound-free photoionization cross sections of every subshell in piData, in barn and as a function of the photon energy; nothing is returned.
JenaAtomicCalculator.Plasma.finiteNorm — Method
Plasma.finiteNorm(a::Radial.Orbital, radiusWS::Float64, grid::Radial.Grid) ... computes the (finite norm) integral of two radial orbital functions.
norm = int_0^radiusWS dr [P_a^2 + Q_a^2]JenaAtomicCalculator.Plasma.perform — Method
Plasma.perform(scheme::Plasma.AverageAtomScheme, computation::Plasma.Computation; output::Bool=true) ... to perform an average-atom plasma computation for an atoms with nuclear charge Z which generates a self-consistent set of orbitals. For output=true, dictionary is returned from which the relevant results can be can easily accessed by proper keys.
Average-atom optical properties
JenaAtomicCalculator.Plasma.ConductivityLine — Type
struct Plasma.ConductivityLine ... one dipole-allowed transition of the average atom, together with the conductivity it carries.
+ omega ::Float64 ... transition energy eps_b - eps_a > 0 [Hartree].
+ sigma ::Float64 ... the INTEGRATED conductivity of this transition [a.u.], i.e. its contribution
to `int sigma(omega) d omega` and not a value of `sigma` at a point.
+ electrons ::Float64 ... the number of electrons it carries in the conductivity sum rule,
`(2 Omega/pi) sigma`.
+ kind ::Symbol ... `:boundBound`, `:boundFree` or `:freeFree`, by the signs of the two energies.
+ kappaA ::Int64 ... kappa of the lower state.
+ kappaB ::Int64 ... kappa of the upper state.
+ energyA ::Float64 ... eps_a [Hartree].
+ energyB ::Float64 ... eps_b [Hartree].JenaAtomicCalculator.Plasma.computeConductivityLines — Method
Plasma.computeConductivityLines(scfResult::NamedTuple, temp::Float64, radiusWS::Float64, grid::Radial.Grid, primitives::Bsplines.Primitives; fMin::Float64=1.0e-8, sigmaMin::Float64=1.0e-14, useFreeSpectra::Bool=false) ... computes every dipole-allowed transition between the box states of a converged average atom and the conductivity it carries; an Array{Plasma.ConductivityLine,1} is returned, sorted by omega.
This is the average-atom Kubo-Greenwood formula of Johnson, Guet & Bertsch, JQSRT 99, 327 (2006), Eq.
(13), evaluated in the B-spline box. Their Eqs. (14), (16) and (17) are the free-free, bound-bound and
bound-free parts of the same sum; here they are not separated, because in a box they are the same object
-- a list of transitions between box states -- and only the SIGNS of the two energies say which name a
transition goes by. **THAT IS THE SIMPLIFICATION THE BOX BUYS.** Johnson's free-free and bound-free
terms carry an integral over the continuum energy with energy-normalised continuum functions; in a box
the energy normalisation cancels the level spacing and the integral becomes a plain sum over box states,
exactly as it does for the density.
Each transition contributes `sigma_ab = (pi/3 Omega) (f_a - f_b) omega_ab |<kappa_a||C^(1)||kappa_b>|^2
R_ab^2`, with `R_ab = int (P_a P_b + Q_a Q_b) r dr` the length-form radial integral and `f` the Fermi
factor. The value stored is the INTEGRATED strength of the line, i.e. its contribution to
`int sigma d omega`; `Plasma.computeConductivitySpectrum` folds the lines into a spectrum.
**THE BOX WALL SCATTERS, SO THE FREE-FREE PART NEEDS THE SAME SUBTRACTION THE DENSITY NEEDS.** A free
particle has no free-free absorption at all: between two exact free waves normalised on the energy scale
the dipole matrix element is a delta function in the energy, so it vanishes for any omega > 0, and
Johnson's free-free l-sum converges because a high-l continuum pair barely feels the potential. A BOX
state is not a free wave -- the wall supplies the momentum -- so free-free transitions between box states
are non-zero however high l goes, and the sum rule then grows without limit: measured 11-Oct-2026 on
aluminium at 0.27 g/cm^3, N_ff came out 3.13 at lMax = 3 and 6.82 at lMax = 5. Called with
`useFreeSpectra = true` this routine returns the same list for the FREE (V = 0) box, and the difference of
the two is the physical free-free conductivity; `Plasma.computeConductivitySumRules` and
`Plasma.computeConductivitySpectrum` both take the two lists and subtract.
**THE RELATIVISTIC ANGULAR FACTOR REPLACES JOHNSON'S `l_>`, AND REDUCES TO IT.** Johnson's model is
non-relativistic -- his Eq. (1) is the Schroedinger equation -- so his line strength is `l_> R^2`. Summed
over the two spin-orbit partners of each l, JAC's `AngularMomentum.CL_reduced_me` gives exactly `2 l_>`
(checked for l = 0...4), and the factor of two is the spin that his prefactor carries separately. So the
form above is his wherever fine structure does not matter, and better where it does.
Validated 11-Oct-2026 against their Table 2, aluminium at 0.27 g/cm^3 and T = 5 eV: the four
bound-bound lines come out at -0.24 %, -0.14 %, -0.42 % and +3.4 % (3s -> 3p, the smallest omega and the
one most sensitive to the 3s and 3p energies), and the sum rule gives N_bb = 0.504 against their 0.493.JenaAtomicCalculator.Plasma.computeConductivitySpectrum — Method
Plasma.computeConductivitySpectrum(lines::Array{Plasma.ConductivityLine,1}, omegas::Array{Float64,1}, broadening::Float64; freeLines::Array{Plasma.ConductivityLine,1}=ConductivityLine[], kinds::Array{Symbol,1}=[:boundBound, :boundFree, :freeFree]) ... folds the conductivity lines into a spectrum on the given photon energies; a sigmas::Array{Float64,1} of the real part of the conductivity [a.u.] is returned.
Every transition of the box is a delta line, and a spectrum needs a width. Each line is folded with a
normalised Lorentzian of half-width `broadening`, `L(w) = broadening/(pi ((w-w_ab)^2 + broadening^2))`,
which preserves `int sigma dw` exactly and so leaves the sum rules of
`Plasma.computeConductivitySumRules` untouched. Johnson, Guet & Bertsch (2006) do the same for their
bound-bound lines, with the width taken to be the electron-ion collision rate.
**THE WIDTH IS A MODEL AND NOT A RESULT**, which is the one thing to keep in view when reading a
spectrum from this routine. A broadening much smaller than the box level spacing shows the comb of box
states rather than a continuum; one much larger washes out real structure, such as the opening of an
ionization edge. The box spacing of the continuum near an energy eps is about `pi^2 n/R^2` with
`n = R sqrt(2 eps)/pi`, so a sensible choice is a few times that.
`freeLines`, if given, are folded in the same way and SUBTRACTED, which removes the box-wall artifact
from the free-free part; see `Plasma.computeConductivityLines`.JenaAtomicCalculator.Plasma.computeConductivitySumRules — Method
Plasma.computeConductivitySumRules(lines::Array{Plasma.ConductivityLine,1}, nFree::Float64, radiusWS::Float64; freeLines::Array{Plasma.ConductivityLine,1}=ConductivityLine[]) ... evaluates the conductivity sum rule of Johnson, Guet & Bertsch (2006), Eq. (15), separately for the three kinds of transition; a NamedTuple (nBoundBound, nBoundFree, nFreeFree, nTotal, nFree, gamma) is returned.
`int sigma(omega) d omega = pi N_free / (2 Omega)` in atomic units, so each transition carries
`(2 Omega/pi) sigma_ab` electrons and the three partial sums are the effective electron numbers that
Johnson quotes -- `N_bb = 0.493` for aluminium at 0.27 g/cm^3 and 5 eV.
**THE SUM RULE IS WHAT FIXES THE ONE FREE PARAMETER OF THE MODEL.** The free-free conductivity diverges
as `1/omega^2` towards zero frequency, because the radial matrix element between two nearly degenerate
continuum states grows without bound; in reality a finite lifetime cuts it off. Johnson mocks that up
with a Drude factor `omega^2/(gamma^2 + omega^2)` and chooses `gamma` so that the FREE-FREE part of the
sum rule returns the number of free electrons. `gamma` is then the mean electron-ion collision rate, and
the returned value is that choice: `gamma` such that `sum_ff sigma_ab omega_ab^2/(gamma^2+omega_ab^2)`
equals `pi n_free/(2 Omega)`. For their aluminium case `gamma = 0.0466 a.u. = 1.27 eV`.JenaAtomicCalculator.Plasma.computeMeanOpacities — Method
Plasma.computeMeanOpacities(omegas::Array{Float64,1}, sigmas::Array{Float64,1}, temp::Float64, massDensity::Float64) ... forms the Planck and Rosseland mean opacities of the plasma from its conductivity spectrum; a NamedTuple (planck, rosseland, kappa, weightPlanck, weightRosseland, xValues) is returned, the two means in cm^2/g and kappa the spectral mass absorption coefficient they are formed from.
**THE TWO MEANS ARE DIFFERENT FUNCTIONALS AND NOT TWO WEIGHTINGS OF ONE, which is the whole physics.**
With `x = omega/kT`,
kappa_P = (15/pi^4) int kappa(x) x^3 / (e^x - 1) dx ... ARITHMETIC
1/kappa_R = (15/4 pi^4) int [1/kappa(x)] x^4 e^x / (e^x - 1)^2 dx ... HARMONIC
The Planck mean is dominated by the frequencies where the plasma absorbs MOST and is the one to use
when the radiation escapes; the Rosseland mean is dominated by the WINDOWS where it absorbs least,
because radiation leaks through them, and is the one to use when the plasma is optically thick. So
`rosseland <= planck` always, a harmonic mean never exceeding its arithmetic counterpart, and the two
can differ by orders of magnitude rather than by a factor.
**AN ARITHMETIC SUM CARRYING THE ROSSELAND WEIGHT IS NOT A ROSSELAND MEAN**, and that error has been
made in this project before -- `simulateRosselandOpacities` formed `sum_i w_i kappa_i` while calling the
result Rosseland. The normalisations above are therefore checked rather than trusted: a CONSTANT
`kappa` must return that same constant from BOTH means, since both weights integrate to one, and that
identity is asserted by the suite.
**WHY THIS BELONGS TO THE AVERAGE ATOM AND NOT TO A LINE LIST.** A correct Rosseland mean of bound-bound
lines ALONE is identically ZERO: an empty frequency bin means `kappa = 0` there, and one perfectly
transparent window short-circuits a harmonic mean. An average atom has no empty bins -- the free-free
and bound-free channels absorb at every frequency -- so here the harmonic mean is finite and meaningful,
which it cannot be made to be for a line list without an added continuum.
**NO FURTHER STIMULATED-EMISSION FACTOR IS APPLIED, and this is the one convention to check before
comparing with another code.** An opacity built from a bare cross section needs the factor
`(1 - e^{-x})`; the Kubo-Greenwood conductivity does NOT, because its own `(f_a - f_b)` already IS
absorption minus stimulated emission. Applying both is a classic double correction and would depress
the means by up to that factor at small x.
The absorption coefficient comes from `Plasma.computeOpticalProperties` (its `absorption` field,
`2 omega k/c` in inverse Bohr radii) and is divided by the mass density to give cm^2/g. Scattering is
NOT included: a Rosseland mean for a hot, thin plasma should carry at least the Thomson term, and this
routine deliberately leaves it out rather than guessing a value -- so the number is an ABSORPTION mean.JenaAtomicCalculator.Plasma.computeOpticalProperties — Method
Plasma.computeOpticalProperties(omegas::Array{Float64,1}, sigmas::Array{Float64,1}) ... turns the real part of the conductivity into the optical constants of the plasma; a NamedTuple (sigmaImag, epsReal, epsImag, refIndex, extinction, absorption) of Array{Float64,1} is returned, each on the given photon energies.
The imaginary part of the conductivity follows from the real part by the Kramers-Kronig relation,
`Im sigma(w) = -(2w/pi) P int_0^inf Re sigma(w') dw'/(w'^2 - w^2)`, and then, in atomic units and
following Johnson, Guet & Bertsch (2006), Section 4.1,
Re eps = 1 - 4 pi Im sigma / w, Im eps = 4 pi Re sigma / w, n + i k = sqrt(eps),
with the refractive index and the extinction coefficient
`n = sqrt((|eps| + Re eps)/2)`, `k = sqrt((|eps| - Re eps)/2)`, and the absorption coefficient
`alpha = 2 w k / c` [1/a_o].
**THE PRINCIPAL VALUE IS TAKEN BY SUBTRACTION AND IS THEREFORE EXACT RATHER THAN REGULARISED.**
`P int_0^inf dw'/(w'^2-w^2)` vanishes identically, so subtracting `Re sigma(w)` from the numerator
leaves an integrand with no pole and changes nothing; at `w' = w` the integrand is the derivative
`sigma'(w)/(2w)`, which is taken from the neighbouring points.
**AND THE ANSWER IS ONLY AS GOOD AS THE RANGE OF `omegas`.** The dispersion integral runs to infinity,
so a grid that stops below the K edge of the element silently omits the bound-free strength above it and
the refractive index comes out wrong at every frequency, not only near the edge. Carry `omegas` well
past the deepest ionization threshold, and log-spaced, since the integrand spans decades.JenaAtomicCalculator.Plasma.dcConductivity — Method
Plasma.dcConductivity(scfResult::NamedTuple, temp::Float64, radiusWS::Float64, grid::Radial.Grid; lMax::Int64=8, energyMin::Float64=0.001, energyMax::Float64=2.5, noEnergies::Int64=48) ... computes the DC electrical conductivity of the average atom from its own scattering phase shifts, with no adjustable parameter; a NamedTuple (sigma0, gamma, crossSections, energies) is returned, sigma0 in a.u. and gamma the collision rate the same sum rule assigns to it.
**WHY NOT FROM THE FREE-FREE CONDUCTIVITY, which is where one would look first.** A single-site model has
no relaxation time: one scattering centre cannot give a finite DC conductivity, so the small-frequency
divergence of its free-free Kubo-Greenwood sum -- and the l-sum that grows with it -- is the physics and
not a defect to be removed. A finite `sigma(0)` needs the DENSITY of scatterers, which enters here as
`n_ion = 1/Omega` through the relaxation time and nowhere else. Johnson, Guet & Bertsch (2006) reach
their own `sigma(0)` the same way, cross-checking it against the Ziman formula.
In the relaxation-time approximation, with one ion per cell and `v = k` in atomic units,
tau(k) = 1 / ( n_ion k sigma_tr(k) )
sigma(0) = (1/3 pi^2) int dk k^4 tau(k) (-df/d eps)|_{eps = k^2/2}
and the prefactor is fixed rather than fitted: for a constant `tau` the integral reduces to
`sigma(0) = n_e tau` exactly, which is how it was checked.
Validated against Johnson, Guet & Bertsch (2006) for aluminium at 0.27 g/cm^3 and T = 5 eV: this gives
`sigma(0) = 0.02763 a.u.` against their 0.0262, i.e. 5.5 % high, and the collision rate it implies is
0.0486 a.u. against their 0.0466. Converged to 0.1 % in `lMax` (6 -> 8), to 0.01 % in the mesh (24 -> 48
points) and to 0.02 % in the lower energy cut (0.005 -> 0.001 Ha). **The agreement is the same few per
cent the Drude form reached while being GIVEN their collision rate; what has changed is that nothing is
given.**JenaAtomicCalculator.Plasma.displayConductivitySumRules — Method
Plasma.displayConductivitySumRules(sumRules::NamedTuple, lines::Array{Plasma.ConductivityLine,1}) ... displays the three partial sum rules, the collision rate taken from them and the strongest transitions of each kind; nothing is returned.
JenaAtomicCalculator.Plasma.displayOpticalProperties — Method
Plasma.displayOpticalProperties(omegas::Array{Float64,1}, sigmas::Array{Float64,1}, optical::NamedTuple) ... displays the conductivity and the optical constants of the plasma against the photon energy; nothing is returned.
JenaAtomicCalculator.Plasma.drudeConductivity — Method
Plasma.drudeConductivity(nFree::Float64, radiusWS::Float64, gamma::Float64, omegas::Array{Float64,1}) ... returns the free-electron (Drude) conductivity sigma(w) = sigma(0) gamma^2/(gamma^2 + w^2) of the cell on the given photon energies; a sigmas::Array{Float64,1} [a.u.] is returned.
**THIS IS A MODEL WITH ONE PARAMETER, AND IT IS HERE BECAUSE THE BOX CANNOT DO THE JOB.** The free-free
conductivity of a plasma carries the whole free-electron oscillator strength, and it carries it at photon
energies of order the electron-ion collision rate -- below the level spacing of any affordable box, and
in a region where the free-free subtraction of `Plasma.computeConductivitySpectrum` changes sign. So the
free-electron response is supplied here in closed form instead of computed.
Its AMPLITUDE is not free: the conductivity sum rule `int sigma dw = pi N_free/(2 Omega)` gives
`sigma(0) = N_free/(Omega gamma)` with no adjustable factor left. Only `gamma` is a choice -- and since
11-Oct-2026 it need not be a choice at all: `Plasma.dcConductivity` computes it from the average atom's
own scattering phase shifts, so the whole optical chain can be run with nothing supplied from outside. Johnson, Guet & Bertsch
(2006) obtain
`gamma = 0.0466 a.u. = 1.27 eV` for aluminium at 0.27 g/cm^3 and 5 eV by imposing that same sum rule on
their (divergent) free-free integral, and quote `sigma(0) = 0.0262 a.u. = 0.121 (mOhm m)^-1` against
0.125 from the Ziman formula. The closed form above gives 0.0286 at their gamma -- 9 % high, the
difference being that their value comes from the damped Kubo-Greenwood integrand and not from a pure
Drude shape.JenaAtomicCalculator.Plasma.transportCrossSection — Method
Plasma.transportCrossSection(scfResult::NamedTuple, energy::Float64, grid::Radial.Grid; lMax::Int64=8) ... returns the momentum-transfer (transport) cross section an electron of the given kinetic energy sees in the converged average-atom potential; a value::Float64 [a.u.^2] is returned, or 0 where the continuum orbital cannot be formed.
`sigma_tr(k) = (4 pi/k^2) sum_l (l+1) sin^2(delta_{l+1} - delta_l)`, the standard phase-shift form, with
the phases taken from `Continuum.generateOrbitalLocalPotential` in the self-consistent potential.
**ONLY THE DIFFERENCE OF NEIGHBOURING PHASES ENTERS, AND THAT IS WHAT MAKES THIS WELL POSED.** A phase
shift is defined modulo pi and the routines that compute one do wrap: on aluminium at 0.27 g/cm^3 and
5 eV, delta_0 runs -1.447 at 0.2 Ha and +1.310 at 0.35 Ha, a jump of very nearly pi. Because `sin^2` is
pi-periodic the cross section does not notice, so no unwrapping is needed and a constant offset in the
phase convention cannot matter. Contrast the free-free dipole amplitude, where the box boundary enters
the integrand itself; that is the difference between this route to the DC conductivity and the one that
failed.Super-configuration opacities
JenaAtomicCalculator.Plasma.displayOpacitySpectrum — Method
Plasma.displayOpacitySpectrum(stream::IO, omegas::Array{Float64,1}, kappa::Array{Float64,1}) ... prints the Stage-3 summed photo-absorption cross section kappa(omega) [a0^2 per absorber, NOT YET a macroscopic opacity – see Plasma.SuperConfigurationOpacityScheme's own docstring] at every omegas entry. Nothing is returned.
JenaAtomicCalculator.Plasma.displayResults — Method
Plasma.displayResults(stream::IO, groups::Array, weights::Array{Float64,1}, Z::Float64) ... prints, for each group (each a SuperConfigurations.Group, typed loosely here for the SAME include-order reason superConfigurationsModule() exists above), its configuration, mean energy, width (sqrt variance), degeneracy, and Boltzmann population fraction weights[i]/Z. Nothing is returned.
JenaAtomicCalculator.Plasma.displayTransitionArrays — Method
Plasma.displayTransitionArrays(stream::IO, arrays::Array, gfValues::Array{Float64,1}, gfEffValues::Array{Float64,1}) ... prints, for each SuperConfigurations.TransitionArray found among scheme.refConfigs (typed loosely here for the SAME include-order reason superConfigurationsModule() exists above), the initial and final configuration, the mean transition energy, its width (sqrt variance), the array's OWN total oscillator-strength sum gf = (2/3) * meanEnergy * totalStrength, and that same gf weighted by the initial configuration's Boltzmann population fraction – the quantity that actually enters a plasma opacity sum. Nothing is returned.
JenaAtomicCalculator.Plasma.gaussianLineProfile — Method
Plasma.gaussianLineProfile(omega::Float64, mean::Float64, sigma::Float64) ... the NORMALIZED Gaussian line-shape value at omega for a line centered at mean with standard deviation sigma, i.e. integral d(omega) of this function over all omega is exactly 1, so that multiplying it by a total strength and integrating recovers that strength exactly. A value::Float64 is returned.
JenaAtomicCalculator.Plasma.perform — Method
Plasma.perform(scheme::Plasma.SuperConfigurationOpacityScheme, computation::Plasma.Computation; output::Bool=true) ... to build one SuperConfigurations.Group per configuration in scheme.refConfigs, on a SHARED orbital set obtained from SelfConsistent.performSCF over all of refConfigs together, to report each group's Boltzmann population fraction at computation.settings.temperature, to build a SuperConfigurations.TransitionArray for every PAIR of refConfigs connected by a single-electron E1 transition (opposite parity) with its oscillator-strength sum gf (STAGE 2), and – STAGE 3, only if scheme.opacityOmegas is non-empty – to sum every array's own Gaussian line profile, weighted by gf and the lower configuration's population, onto that frequency grid into a single kappa(omega). See Plasma.SuperConfigurationOpacityScheme's own docstring for what this still is not (a macroscopic opacity). For output=true, a dictionary is returned under the keys "superconfiguration groups" (Array{SuperConfigurations.Group,1}), "superconfiguration populations" (the matching Boltzmann population fractions, Array{Float64,1}, summing to 1), "superconfiguration transition arrays" (Array{SuperConfigurations.TransitionArray,1}, one per E1-connected pair), "superconfiguration transition gf" (each array's own gf, Array{Float64,1}), "superconfiguration opacity contributions" (that gf weighted by the lower configuration's population, Array{Float64,1}), and, only when scheme.opacityOmegas is non-empty, "superconfiguration opacity spectrum" (kappa(omega) on that grid, Array{Float64,1}).
JenaAtomicCalculator.Plasma.superConfigurationsModule — Method
Plasma.superConfigurationsModule() ... resolves the sibling SuperConfigurations module at RUNTIME and returns it as a mod::Module.
WHY BY REFLECTION RATHER THAN BY `using`: this file deliberately does not `using ..SuperConfigurations` at
module top level, unlike most sibling `-inc-` files. `SuperConfigurations` is included in
`JenaAtomicCalculator.jl` AFTER `module-Plasma.jl`, because it depends on `BasicsAZ.meanEnergyInClosedForm` and
`BasicsAZ` is deliberately included near the very end -- its own docstring says it "contains methods from the
Basics module but with reference to many other modules". Moving either module earlier to permit a direct
`using` would risk an include order nothing has audited. This lookup runs only when `perform` is actually
CALLED, by which point every module has long since been included, so no include order has to change.Super-configuration ionization balance
JenaAtomicCalculator.Plasma.displayIonizationBalance — Method
Plasma.displayIonizationBalance(stream::IO, charges::Array{Int64,1}, groupsPerStage::Array, stagePopulations::Array{Float64,1}, electronDensity::Float64) ... prints, for every ionization stage, its charge, the configuration of its lowest-meanEnergy group, how many groups it carries, and its own population fraction (summed over every group in that stage); then the converged electron number density. Nothing is returned.
JenaAtomicCalculator.Plasma.perform — Method
Plasma.perform(scheme::Plasma.SuperConfigurationIonizationScheme, computation::Plasma.Computation; output::Bool=true) ... to build one SuperConfigurations.Group per configuration in EVERY stage of scheme.refConfigsPerStage (one SHARED orbital set PER STAGE, since different stages have different electron counts and cannot share orbitals the way configurations WITHIN one stage do), and to solve the grand-canonical Saha-Boltzmann equilibrium self-consistently for the electron density at computation.settings.temperature [Hartree] and computation.settings.density [a.u., the TOTAL ION number density; computation.settings.useNumberDensity must be true]. See this scheme's own docstring for the equations and their scope. For output=true, a dictionary is returned under the keys "superconfiguration ionization groups" (Array{Array{SuperConfigurations.Group,1},1}, one inner array per stage), "superconfiguration ionization charges" (Array{Int64,1}, matching), "superconfiguration ionization stage populations" (Array{Float64,1}, summing to 1), "superconfiguration ionization group populations" (Array{Array{Float64,1},1}, matching the groups, summing to 1 OVER ALL stages together), and "superconfiguration ionization electron density" (Float64, the converged value).
Super-configuration mixture opacities
JenaAtomicCalculator.Plasma.boundFreeOpacityContribution — Method
Plasma.boundFreeOpacityContribution(stages::Array{Array{Configuration,1},1}, popsPerStage::Array{Array{Float64,1},1}, stagePopulations::Array{Float64,1}, omegas::Array{Float64,1}, approx::Empirical.AbstractEmpiricalApproximation) ... sums the bound-free (photoionization) contribution to kappa(omega), for ONE species, over every pair of groups in every pair of ADJACENT stages whose configurations differ by exactly one electron in exactly one shell – checked by Basics.extractFromConfigurations(Basics.OccupationDifference(),...), the SAME compatibility test Empirical.photoionizationCrossSection applies internally. A pair that is not a genuine single-electron ionization channel is simply SKIPPED, not an error, the same way a same-parity pair is skipped (not an error) for the bound-bound Stage 2 in Plasma.perform(::SuperConfigurationOpacityScheme,...). Each valid channel's cross section – from Empirical.photoionizationCrossSection, Kramers' (1923) formula scaled by the ionized shell's own binding energy and a bound-free Gaunt factor – is weighted by the INITIAL group's own ABSOLUTE population within the species, stagePopulations[i] * popsPerStage[i][g]; the FINAL state's own population plays no role, since a photoionization event is driven by the absorber, not by how occupied the state it is ejected into happens to be. A (kappaBF::Array{Float64,1}, channels::Array{Tuple{Configuration,Configuration,Float64,Array{Float64,1}},1}) tuple is returned – channels holding (initialConf, finalConf, population, crossSection(omegas)) for every channel actually used, for display.
JenaAtomicCalculator.Plasma.classifyResonantGroups — Method
Plasma.classifyResonantGroups(groupsPerStage::Array) ... classifies every SuperConfigurations.Group (typed loosely here for the SAME include-order reason superConfigurationsModule() exists for, see module-Plasma-inc-superconfiguration-opacity.jl) in every stage but the LAST as BOUND or RESONANT (autoionizing), by comparing its own meanEnergy against the GROUND energy of the adjacent, one-electron-more-ionized stage – minimum(g.meanEnergy for g in groupsPerStage[i+1]), the SAME stage-to-stage pairing Plasma.boundFreeOpacityContribution already uses for its own configuration-level connectivity test. A group whose mean energy EXCEEDS that threshold has, on average, enough energy to autoionize into the adjacent stage's ground level and is flagged true; one below it is an ordinary bound excited configuration and is flagged false. The LAST stage has no stage above it to compare against and is returned all-false, by convention rather than by any physics claim. Classification ALONE: no width, no line profile, and nothing here is wired into any kappa – an Array{Array{Bool,1},1} is returned, matching groupsPerStage's own shape.
**ONE CAVEAT STATED RATHER THAN HIDDEN**, since it bears directly on whether the comparison means
anything: `Plasma.perform(::SuperConfigurationMixtureOpacityScheme,...)`'s own Stage 0 builds each
stage's groups from an INDEPENDENT SCF, on that stage's OWN grid and orbitals. The comparison here
assumes the two stages' absolute energies already sit on a mutually consistent scale -- true for a
shared nuclear model and adequately converged orbitals (Rule 12), but NOT independently checked by
this function.JenaAtomicCalculator.Plasma.displayMixtureBalance — Method
Plasma.displayMixtureBalance(stream::IO, charges::Array{Array{Int64,1},1}, stagePopulations::Array{Array{Float64,1},1}, numberFractions::Array{Float64,1}, electronDensity::Float64) ... prints, for every species, its own stages' charges and population fractions (summing to 1 WITHIN that species), then the ONE electron density shared by the whole mixture. Nothing is returned.
JenaAtomicCalculator.Plasma.displayMixtureBoundFreeChannels — Method
Plasma.displayMixtureBoundFreeChannels(stream::IO, channels::Array{Tuple{Configuration,Configuration,Float64,Array{Float64,1}},1}) ... prints, for every bound-free channel Plasma.boundFreeOpacityContribution found, its initial and final configuration, the initial group's own absolute population, and the PEAK cross section (the maximum of crossSection(omegas) over the grid it was evaluated on – not the full spectrum, which is in the opacity table that follows). Nothing is returned.
JenaAtomicCalculator.Plasma.displayMixtureFreeFreeStages — Method
Plasma.displayMixtureFreeFreeStages(stream::IO, stages::Array{Tuple{Int64,Int64,Float64,Array{Float64,1}},1}) ... prints, for every (species,stage) Plasma.freeFreeOpacityContribution actually used (charge > 0), its species index, ion charge, absolute population, and PEAK free-free absorption coefficient (the maximum of kappaFF(omegas) over the grid it was evaluated on – not the full spectrum, which is in the opacity table that follows). Nothing is returned.
JenaAtomicCalculator.Plasma.displayMixtureResonanceCorrections — Method
Plasma.displayMixtureResonanceCorrections(stream::IO, records::Array{Tuple{Int64,Int64,Int64,Float64,Float64,Float64},1}) ... prints, for every resonant line Plasma.perform(::SuperConfigurationMixtureOpacityScheme,...) actually corrected from a Gaussian to a Voigt profile, its species, stage and group index, its mean energy, its population-weighted gfEff, and its autoionization width (eV). A resonant group with NO open autoionization channel is never corrected (its line stays the Gaussian Stage 2/3 already gave it) and so never appears here – see Plasma.resonanceAutoionizationWidth's own docstring for why that is zero, not an error. Nothing is returned.
JenaAtomicCalculator.Plasma.displayMixtureSpectrum — Method
Plasma.displayMixtureSpectrum(stream::IO, omegas::Array{Float64,1}, kappaMix::Array{Float64,1}, kappaP::Float64) ... prints the mixture's own summed BOUND-BOUND per-absorber cross section kappaMix(omega) at every omegas entry, followed by its Planck mean opacity kappaP. Used UNCHANGED whenever scheme.boundFreeApprox === nothing (the default); see Plasma.displayMixtureSpectrumBreakdown for the richer, three-column table used once bound-free is turned on. The Rosseland mean is DELIBERATELY not printed here – see Plasma.rosselandMeanOpacity's own docstring for why it is not yet a trustworthy number for a line-only spectrum. Nothing is returned.
JenaAtomicCalculator.Plasma.displayMixtureSpectrumBreakdown — Method
Plasma.displayMixtureSpectrumBreakdown(stream::IO, omegas::Array{Float64,1}, kappaBB::Array{Float64,1}, kappaBF::Union{Nothing,Array{Float64,1}}, kappaFF::Union{Nothing,Array{Float64,1}}, kappaTotal::Array{Float64,1}, kappaPbb::Float64, kappaPtotal::Float64, kappaR::Float64) ... prints the mixture's BOUND-BOUND, and whichever of BOUND-FREE/FREE-FREE are active (kappaBF/ kappaFF not nothing), and TOTAL per-absorber cross sections SIDE BY SIDE at every omegas entry, each column clearly labelled so no contribution is ever read as one undifferentiated number, followed by the Planck mean of the bound-bound-only spectrum (kappaPbb, UNCHANGED in meaning from Plasma.displayMixtureSpectrum's own number), the Planck mean of the TOTAL spectrum (kappaPtotal), and the Rosseland mean of the TOTAL spectrum (kappaR – MUCH LESS floor-sensitive now that a continuum contribution supplies a smooth, physically decaying tail in place of a Gaussian line's literal float64 underflow, but NOT UNCONDITIONALLY floor-free: measured, not assumed, 18-Oct-2026 for bound-free alone, a floor sweep on a real case stayed CONSTANT across 9 orders of magnitude of floor choice – kappaMax*1e-6 down to kappaMax*1e-15 all agreed to 6 figures on a moderate opacityOmegas grid – but widening that SAME grid further past threshold moved the 1e-6 point away from the (still-stable) 1e-9-to-1e-15 plateau, since a power-law tail can still underflow a FIXED multiplicative floor given enough span. Plasma.rosselandMeanOpacity's hardcoded 1e-12 sat inside the stable plateau in both tests run, but this is a measured observation on those cases, not a proof for every grid). Ends with an EXPLICIT reminder naming whichever of bound-free/free-free is still nothing, so neither mean is mistaken for a complete continuum opacity unless BOTH are active. Nothing is returned.
JenaAtomicCalculator.Plasma.displayResonanceTransitionArrays — Method
Plasma.displayResonanceTransitionArrays(stream::IO, arrays::Array, groupIndices::Array{Tuple{Int64,Int64},1}, gfValues::Array{Float64,1}) ... prints, for every SuperConfigurations.TransitionArray Plasma.resonanceTransitionArrays built, the stage and group index it belongs to, the initial (ground) and final (resonant) configuration, the mean transition energy, its width (sqrt variance), and the array's own total oscillator-strength sum gf – the SAME gf = (2/3) * meanEnergy * totalStrength SuperConfigurationOpacityScheme's own Stage 2 uses. Nothing is returned.
JenaAtomicCalculator.Plasma.displayResonanceWidths — Method
Plasma.displayResonanceWidths(stream::IO, groupIndices::Array{Tuple{Int64,Int64},1}, widths::Array{Float64,1}) ... prints, for every resonant group Plasma.resonanceAutoionizationWidths computed a width for, its stage and group index, the autoionization width (Hartree and eV), and – where the width is zero – a note that no channel was open rather than leaving a silent zero to be misread as a vanishingly narrow resonance. Nothing is returned.
JenaAtomicCalculator.Plasma.displayResonantClassification — Method
Plasma.displayResonantClassification(stream::IO, groupsPerStage::Array, flags::Array{Array{Bool,1},1}) ... prints, for every stage but the last, each of its groups' configuration and mean energy, the adjacent higher stage's own threshold energy, and whether Plasma.classifyResonantGroups flagged it bound or resonant. Nothing is returned.
JenaAtomicCalculator.Plasma.freeFreeOpacityContribution — Method
Plasma.freeFreeOpacityContribution(chargesPerStage::Array{Int64,1}, stagePopulations::Array{Float64,1}, omegas::Array{Float64,1}, ne::Float64, kT::Float64) ... sums the free-free (inverse-bremsstrahlung) contribution to kappa(omega), for ONE species, over every one of its OWN stages. Unlike Plasma.boundFreeOpacityContribution this needs no PAIR of adjacent stages: a stage's own ion charge alone sets the Coulomb field a passing free electron feels, so each stage contributes independently through Empirical.freeFreeAbsorptionCoefficient(omegas, chargesPerStage[i], ne, kT), weighted by that stage's own ABSOLUTE population within the species, stagePopulations[i]. A neutral stage (charge 0) contributes exactly zero, through that function's own Z^2 factor, not as a special case here. A kappaFF::Array{Float64,1} is returned, matching omegas in length.
JenaAtomicCalculator.Plasma.perform — Method
Plasma.perform(scheme::Plasma.SuperConfigurationMixtureOpacityScheme, computation::Plasma.Computation; output::Bool=true) ... STAGE 0: for every species and every one of its OWN stages in scheme.refConfigsPerSpeciesStages, builds one SuperConfigurations.Group per configuration, each on that (species,stage)'s own automatically-sized grid. STAGE 1: solves the COUPLED multi-species grand-canonical Saha-Boltzmann balance (see this scheme's own docstring for the equation) for the ONE electron density shared by the whole mixture at computation.settings.temperature [Hartree] and computation.settings.density [a.u., the TOTAL ION number density of the WHOLE mixture; needs computation.settings.useNumberDensity true] – giving each species its OWN stage populations, summing to 1 within that species. SKIPPED ENTIRELY, with every stage population set to 1 directly, when NO species has more than one stage (the balance is then trivial by construction) – which is exactly why the backward-compatible, single-stage-per-species constructor needs no density settings at all, same as the ORIGINAL (17-Oct-2026) scheme never did. A MIXTURE WITH ANY MULTI-STAGE SPECIES, however, DOES need a valid computation.settings.density/useNumberDensity, and raises if given none. STAGE 2/3: runs Plasma.perform(::SuperConfigurationOpacityScheme, ...) UNCHANGED for every (species,stage) pair, population-weights each stage's own kappa WITHIN its species by that stage's balance population, then weights ACROSS species by numberFractions into kappaMix, and reduces that to its Planck mean opacity. The Rosseland mean is DELIBERATELY NOT computed – see Plasma.rosselandMeanOpacity's own docstring. computation.nuclearModel/computation.grid/ computation.refConfigs are UNUSED; only computation.asfSettings and computation.settings are shared across every (species,stage). A MEASURED, ACCEPTED COST of composing two already-separate schemes this way: every (species,stage)'s SCF and grid are built TWICE – once here for its Group (Stage 0) and again inside SuperConfigurationOpacityScheme's own perform call (Stage 2/3) – rather than changing THAT scheme's interface to accept externally-built orbitals, which would be a separate module's change.
STAGE 2.5, ONLY WHEN `scheme.boundFreeApprox !== nothing` (18-Oct-2026): for every species with more
than one stage, `Plasma.boundFreeOpacityContribution` sums a bound-free (photoionization) contribution
between every pair of ADJACENT stages, reusing the within-stage populations `SuperConfigurationOpacityScheme`
already returned in Stage 2/3 -- no extra SCF, no extra grid.
STAGE 2.6, ONLY WHEN `scheme.freeFreeIncluded` (19-Oct-2026): for every species, EVERY one of its
stages (no adjacency needed -- a stage's own ion charge alone sets the free-free cross section),
`Plasma.freeFreeOpacityContribution` sums the free-free (inverse-bremsstrahlung) contribution,
weighted the same way. This needs a real electron density: `scheme.freeFreeIncluded` with no
density given (STAGE 1 skipped) raises, naming what is missing.
STAGE 4/5, ONLY WHEN `scheme.resonanceContinuumGrid !== nothing` (20-Oct-2026): for every species with
more than one stage, `Plasma.classifyResonantGroups` + `Plasma.resonanceTransitionArrays` (built from
STAGE 0's OWN groups/orbitals/grid, no extra SCF) find every ground-to-resonance E1 line of every
stage, `Plasma.resonanceAutoionizationWidth` gives each an autoionization width, and -- for every one
with an OPEN channel -- that line is corrected, IN PLACE inside THIS stage's own `kappaStage` (before
it is weighted into `kappaSpecies`/`kappaMix`), from the Gaussian `SuperConfigurationOpacityScheme`'s
own Stage 2/3 already gave it to the Voigt profile `Plasma.voigtLineProfile` implies, via
`gfEff * (voigt - gaussian)`. A resonant group with NO open channel, or whose own ground-to-resonance
pair shares its parity (no E1 array at all), is left as the Gaussian it already had. This changes
`kappaMix`, `kappaP` and every other BOUND-BOUND-ONLY number WHENEVER a resonant line is actually
corrected -- unlike bound-free/free-free, it is not a separately-added contribution, so there is no
new `kappaMixTotal` term for it; the lines actually corrected are reported separately (see below) for
inspection, not because they are excluded from the totals.
The bound-bound-only `ResultKeys` (`SuperConfigurationMixtureOpacitySpectrum`, `...PlanckOpacity`)
keep their EXACT, UNCHANGED pre-18-Oct meaning regardless of either switch; the bound-free spectrum
and the free-free spectrum are each reported under their OWN key (present only when their own switch
is on); and the TOTAL spectrum, its Planck mean, and its Rosseland mean (MUCH LESS floor-sensitive
than bound-bound alone once EITHER continuum contribution supplies a floor -- see
`Plasma.displayMixtureSpectrumBreakdown`'s own docstring for the measured, not-unconditional extent
of that improvement) sum bound-bound plus WHICHEVER of bound-free/free-free are active, and are
present whenever EITHER is. No contribution is ever merged into another's own key; see
`Plasma.displayMixtureSpectrumBreakdown`. When NEITHER switch is on (the default), both new stages
are skipped entirely and every printout/result is BYTE-IDENTICAL to the pre-18-Oct scheme.
For output=true, a dictionary is returned under the keys "superconfiguration mixture species
opacities" (`Array{Array{Float64,1},1}`, one BOUND-BOUND spectrum per species), "superconfiguration
mixture opacity spectrum" (`kappaMix`, BOUND-BOUND ONLY, `Array{Float64,1}`), "superconfiguration
mixture planck opacity" (`Float64`, of that bound-bound-only spectrum), "superconfiguration mixture
charges" (`Array{Array{Int64,1},1}`, one array per species), "superconfiguration mixture stage
populations" (`Array{Array{Float64,1},1}`, matching, summing to 1 WITHIN each species), and
"superconfiguration mixture electron density" (`Float64`, the ONE value shared by the whole mixture)
-- ALWAYS present -- plus, ONLY when `scheme.boundFreeApprox !== nothing`: "superconfiguration mixture
bound-free opacity" (`Array{Float64,1}`) -- plus, ONLY when `scheme.freeFreeIncluded`:
"superconfiguration mixture free-free opacity" (`Array{Float64,1}`) -- plus, WHENEVER EITHER is
active: "superconfiguration mixture total opacity spectrum" (bound-bound plus whichever of
bound-free/free-free are on, `Array{Float64,1}`), "superconfiguration mixture total planck opacity"
(`Float64`), and "superconfiguration mixture rosseland opacity" (`Float64`, of that same TOTAL
spectrum) -- plus, ONLY when `scheme.resonanceContinuumGrid !== nothing`: "superconfiguration mixture
resonance corrections" (`Array{Tuple{Int64,Int64,Int64,Float64,Float64,Float64},1}`, one entry per
resonant line actually corrected: species, stage, group index, mean energy [a.u.], `gfEff`, and
autoionization width [eV]).JenaAtomicCalculator.Plasma.planckMeanOpacity — Method
Plasma.planckMeanOpacity(xGrid::Array{Float64,1}, kappa::Array{Float64,1}) ... the Planck mean of kappa over xGrid (x = omega/kT), INTEGRAL kappa(x)*planckWeight(x) dx, evaluated by the trapezoidal rule over the GIVEN grid – the caller's own opacityOmegas choice, not a refined quadrature, so the grid must already resolve both planckWeight's own peak (x ~ 3-4) and every line in kappa. A value::Float64 is returned.
JenaAtomicCalculator.Plasma.planckWeight — Method
Plasma.planckWeight(x::Float64) ... the normalized Planck mean-opacity weight function at x = omega/kT: (15/pi^4) * x^3/(e^x-1), INTEGRAL over x in (0,infinity) of this function is exactly 1 (verified numerically to 1e-10 over x in [0,60] before this formula was written into the code, not assumed from memory – see this module's own docstring for why that check matters here). A value::Float64 is returned.
JenaAtomicCalculator.Plasma.resonanceAutoionizationWidth — Method
Plasma.resonanceAutoionizationWidth(confResonant::Configuration, finalConfigs::Array{Configuration,1}, nm::Nuclear.Model, grid::Radial.Grid, settings::AsfSettings, augerSettings::AutoIonization.Settings) ... the REPRESENTATIVE-LEVEL autoionization width of one resonant group's configuration, reusing JAC's own, already-validated AutoIonization process UNCHANGED, through the SAME top-level call every other JAC process uses – Atomic.Computation(initialConfigs=[confResonant], finalConfigs=finalConfigs, processSettings=augerSettings) followed by Basics.perform – the same pattern Plasma.SatelliteDiagnosticScheme already uses for its own DR/impact-excitation steps, and the SAME electron-count direction that module's own comment warns about: confResonant must carry ONE electron MORE than every configuration in finalConfigs, or every channel comes back empty (NOT an error – see below).
**"REPRESENTATIVE" MEANS ONE LEVEL, NOT A GROUP AVERAGE** -- the choice made explicitly over two more
elaborate alternatives (a degeneracy-scaled estimate, or a true trace-based group average with no
existing building block and no reference checked), because it needs NO new formula. `confResonant` is
fully diagonalized here (ordinary CI -- exactly what `SuperConfigurations.Group` itself avoids doing,
affordable here only because this function runs on ONE flagged group, not a whole stage), its LOWEST
level is taken as the representative, and `AutoIonization.Line.totalRate` is summed over every channel
that level has into `finalConfigs` -- the SAME aggregation `AutoIonization.displayLifetimes` itself
uses for a level's own total width, already in Hartree (rate and energy share units since hbar=1, so
no conversion is needed before combining it with a `TransitionArray`'s own Hartree-valued variance in
a later Voigt profile).
**THE GRID IS THE CALLER'S RESPONSIBILITY, AND THIS MATTERS (Rule 12).** `AutoIonization.computeLines`
needs a CONTINUUM orbital for the ejected electron, and `Basics.recommendedGrid` -- the grid every
OTHER function in this file uses -- is explicitly documented as sized for BOUND orbitals only and
gives NO warning when it is too small for a continuum one. `grid` here is therefore NOT auto-derived;
pass one already checked adequate for the ejected electron's kinetic energy (halve `hp` until the
width stops moving, per Rule 12), not simply a stage's own bound-orbital grid. Likewise, the ambient
continuum-method defaults (`"method: continuum, ..."`, `"method: normalization, ..."`) are left
UNTOUCHED here -- set by the caller beforehand, exactly as any other direct `AutoIonization` call
already requires.
A `(width::Float64, line::Union{Nothing,AutoIonization.Line})` tuple is returned: `width` in Hartree,
zero when no channel is open (a parity- or angular-momentum-forbidden case, or `confResonant`'s own
lowest level sitting below every open threshold -- NOT an error, the same convention every
pair-connectivity check elsewhere in this file already uses), and `line` one representative
`AutoIonization.Line` for display, or `nothing` when width is zero.JenaAtomicCalculator.Plasma.resonanceAutoionizationWidths — Method
Plasma.resonanceAutoionizationWidths(groupsPerStage::Array, flags::Array{Array{Bool,1},1}, stagesConfigs::Array{Array{Configuration,1},1}, nm::Nuclear.Model, continuumGrid::Radial.Grid, settings::AsfSettings, augerSettings::AutoIonization.Settings) ... calls Plasma.resonanceAutoionizationWidth for every group Plasma.classifyResonantGroups flagged RESONANT in every stage but the last, decaying into the adjacent, one-electron-more-ionized stage's own reference configurations (stagesConfigs[i+1]) – the SAME stage-to-stage pairing used throughout this file. A stage's own GROUND group is never passed here even if flagged (see Plasma.resonanceTransitionArrays's own docstring for why an array from a group to itself is not meaningful; the same reasoning rules out a self-width here). continuumGrid is the ONE grid used for EVERY call – see resonanceAutoionizationWidth's own docstring for why this is not auto-derived and must already be checked adequate for the channel energies actually involved.
Returns `(widths::Array{Float64,1}, lines::Array, groupIndices::Array{Tuple{Int64,Int64},1})`,
aligned entry-by-entry: `widths[k]`/`lines[k]` belong to the resonant group at stage
`groupIndices[k][1]`, index `groupIndices[k][2]` -- the SAME `groupIndices` convention
`Plasma.resonanceTransitionArrays` returns, so the two can be zipped together by a later Voigt-profile
step.JenaAtomicCalculator.Plasma.resonanceTransitionArrays — Method
Plasma.resonanceTransitionArrays(groupsPerStage::Array, flags::Array{Array{Bool,1},1}, orbitalsPerStage::Array, nm::Nuclear.Model, gridPerStage::Array, settings::AsfSettings) ... for every stage but the last, builds a SuperConfigurations.TransitionArray (typed loosely here for the SAME include-order reason superConfigurationsModule() exists for, see module-Plasma-inc-superconfiguration-opacity.jl) from that stage's OWN ground group – the group of LOWEST meanEnergy, the configuration a plasma actually populates – to every OTHER group Plasma.classifyResonantGroups flagged RESONANT. Ground and resonance are the SAME electron count, built from the SAME stage SCF, so no cross-stage energy-scale assumption enters here the way it does in classifyResonantGroups itself.
**THIS IS A BOUND-BOUND E1 ARRAY, EXACTLY `SuperConfigurationOpacityScheme`'s OWN STAGE 2** -- a
photoionization resonance is REACHED by ordinary photoabsorption from the ground configuration into a
doubly-excited state embedded in the continuum, and only DECAYS via a separate channel (autoionization
into the adjacent, more-ionized stage) that this function does not touch. So what is built here is the
resonance's own absorption strength (its `gf`, exactly as Stage 2 already defines it), not yet its
width or line shape -- see `Plasma.classifyResonantGroups`'s own docstring for what step is still
missing before either exists. A ground-to-resonance pair of the SAME parity is not a genuine E1 array
and is SKIPPED, not an error, the same convention `SuperConfigurationOpacityScheme.perform`'s own
Stage 2 already uses; so is a stage whose own GROUND group was itself flagged resonant, since an array
from a group to itself is not meaningful.
Returns `(arrays::Array, groupIndices::Array{Tuple{Int64,Int64},1})`: `arrays[k]` is the
TransitionArray built for the resonant group at stage `groupIndices[k][1]`, index `groupIndices[k][2]`
within that stage's own `groupsPerStage` entry -- a flagged group skipped for either reason above has
NO entry in either array.JenaAtomicCalculator.Plasma.rosselandMeanOpacity — Method
Plasma.rosselandMeanOpacity(xGrid::Array{Float64,1}, kappa::Array{Float64,1}) ... the Rosseland mean of kappa over xGrid (x = omega/kT), the HARMONIC mean 1 / INTEGRAL( rosselandWeight(x)/kappa(x) dx ), evaluated by the trapezoidal rule over the GIVEN grid.
**NOT CALLED BY `Plasma.perform(::SuperConfigurationMixtureOpacityScheme, ...)`, AND NAMED HERE
RATHER THAN SILENTLY SHIPPED, because it was MEASURED, not assumed, to have no stable value for a
LINE-ONLY spectrum.** A Rosseland mean is a harmonic average, dominated by whichever frequencies
are LEAST opaque -- and a `kappa(omega)` built only from Gaussian E1 lines (no bound-free, no
free-free continuum) never reaches a true zero between lines, only an exponentially small one, so
the function needs a FLOOR below which `kappa` is treated as the model's own zero rather than
divided into. Tried on a real two-configuration case, 17-Oct-2026: the returned value moved by
**more than eleven orders of magnitude** as the floor was swept from `1e-3` to `1e-15` of the peak
(0.049 down to 7.7e-13) -- proof that the number this function returns is set by an ARBITRARY
internal threshold, not by the physics of the lines. A quantity that moves eleven orders of
magnitude with an implementation detail has no content worth reporting. Kept here, floored at
`max(kappa)*1e-12` purely so the function itself does not divide by zero or overflow, as a
BUILDING BLOCK for the day a continuum opacity exists to fill the gaps a line-only model cannot --
at that point the harmonic mean becomes well-posed again, because the continuum (not an arbitrary
floor) sets what "least opaque" means. Until then, `Plasma.planckMeanOpacity` -- an ARITHMETIC,
kappa-weighted average with no reciprocal and therefore no gap-sensitivity -- is the only mean
opacity this scheme reports. A value::Float64 is returned.JenaAtomicCalculator.Plasma.rosselandWeight — Method
Plasma.rosselandWeight(x::Float64) ... the normalized Rosseland mean-opacity weight function at x = omega/kT: (15/(4*pi^4)) * x^4*e^x/(e^x-1)^2, INTEGRAL over x in (0,infinity) of this function is exactly 1 (verified the same way as Plasma.planckWeight). A value::Float64 is returned.
JenaAtomicCalculator.Plasma.voigtLineProfile — Method
Plasma.voigtLineProfile(omega::Float64, mean::Float64, sigma::Float64, gammaFWHM::Float64) ... the NORMALIZED Voigt line-shape value at omega for a line centered at mean, with GAUSSIAN standard deviation sigma (the statistical spread Plasma.gaussianLineProfile already uses) and a LORENTZIAN component of FULL WIDTH AT HALF MAXIMUM gammaFWHM – the natural-linewidth convention, i.e. gammaFWHM is the quantity Plasma.resonanceAutoionizationWidth already returns (a total decay rate, in Hartree, which under hbar=1 IS the FWHM of the line it produces). integral d(omega) of this function over all omega is exactly 1, like Plasma.gaussianLineProfile's own normalization.
Evaluated through the Faddeeva function, `w(z) = erfcx(-i*z)` with `z = (omega-mean + i*gammaFWHM/2) /
(sigma*sqrt(2))`, so that `Plasma.voigtLineProfile(omega,mean,sigma,gammaFWHM) = Re[w(z)] /
(sigma*sqrt(2*pi))` -- the standard closed form, **VERIFIED, NOT ASSUMED, before being written into
this scheme**: against a direct numerical convolution of a normalized Gaussian and a normalized
Lorentzian (QuadGK, `rtol=1e-12`) over six widely spread `(omega-mean, sigma, gammaFWHM)` cases,
relative agreement at or below `1e-6` in every case (most at `1e-15`-`1e-16`); against its own
normalization integral over `(-Inf,Inf)`, to `1e-8`; and against both single-component limits --
`gammaFWHM -> 0` reduces to `Plasma.gaussianLineProfile` (`rtol=1e-5`) and `sigma -> 0` reduces to the
plain Lorentzian `(gammaFWHM/(2*pi)) / ((omega-mean)^2+(gammaFWHM/2)^2)` (`rtol=1e-3`, limited by how
close to zero a finite test value can be pushed, not by the formula). The two DEGENERATE limits
(`gammaFWHM <= 0` or `sigma <= 0`) are handled EXACTLY, not through the Faddeeva function, so that
`Plasma.resonanceAutoionizationWidth` returning zero (no channel open) gives a correction of
EXACTLY zero against `Plasma.gaussianLineProfile`, never a tiny numerical residual. A value::Float64
is returned.Kinetic charge-balance populations
JenaAtomicCalculator.Plasma.computeKineticChargeBalance — Method
Plasma.computeKineticChargeBalance(scheme::Plasma.KineticChargeBalanceScheme, nm::Nuclear.Model, grid::Radial.Grid, asf::AsfSettings, Ne::Float64, output::Bool) ... the body of Plasma.perform(scheme::Plasma.KineticChargeBalanceScheme, ...), factored out only so that the global "nuclear: charge" default can be set and reliably restored around it via a try/finally in the caller.
JenaAtomicCalculator.Plasma.displayKineticChargeBalanceResults — Method
Plasma.displayKineticChargeBalanceResults(stream::IO, scheme::Plasma.KineticChargeBalanceScheme, Ne::Float64, popVectors::Dict, levelCounts::Array{Int64,1}) ... prints a table of the relative populations (Coulomb/Babushkin) of every (stage, local level) slot, one row per (slot, temperature) pair, following JAC's usual table style. A neat table is printed but nothing is returned otherwise.
JenaAtomicCalculator.Plasma.displayKineticChargeBalanceTreatments — Method
Plasma.displayKineticChargeBalanceTreatments(stream::IO, scheme::Plasma.KineticChargeBalanceScheme) ... prints, once per leg, which Plasma.AbstractRateTreatment was used – the user-facing provenance table that lets a reader recognize, at a glance, at which (empirical, semi-empirical or structure-based) tier each process was treated, without having to read the scheme's fields back out of the code that built it.
JenaAtomicCalculator.Plasma.generateChargeStageMultiplet — Method
Plasma.generateChargeStageMultiplet(stage::Plasma.ChargeStage, nm::Nuclear.Model, grid::Radial.Grid, asfSettings::AsfSettings) ... generates the reference Multiplet of one charge stage: one shared mean-field orbital basis for stage.configs, followed by Hamiltonian.performCIwithFrozenOrbitals for each configuration separately, retaining its own stage.nLevels[i] lowest CI levels (clipped if that configuration has fewer), and a single energy sort across the combined set – the same generation policy as Plasma.generateCollisionalRadiativeLevels, applied once per configuration. A named tuple (multiplet::Multiplet=, configIndex::Array{Int64,1}=) is returned, where configIndex[j] gives the index into stage.configs that multiplet.levels[j] was generated from (levels sorted by energy, lowest first, so for a CLASSIC stage multiplet.levels[1] is always the ground level).
JenaAtomicCalculator.Plasma.perform — Method
Plasma.perform(scheme::Plasma.KineticChargeBalanceScheme, computation::Plasma.Computation; output::Bool=true) ... to compute the kinetic (rate-based, non-LTE) population balance across scheme.chargeStages. For output=true, a dictionary is returned from which the relevant results can be accessed by proper keys.
JenaAtomicCalculator.Plasma.structureBasedRrRateCoefficient — Method
Plasma.structureBasedRrRateCoefficient(groundLevel::Level, higherLevel::Level, nm::Nuclear.Model, grid::Radial.Grid, Te::Float64) ... computes the structure-based photorecombination plasma rate coefficient alpha^(RR)(T_e; higherLevel -> groundLevel) by a Gauss-Legendre Maxwellian average of JAC's own PhotoRecombination.computeLines cross section, mirroring Cascade.simulateRrRateCoefficients but as a plain-argument local helper (that function is coupled to Cascade.Simulation's own types and is not reused here, to keep this task to one module). Te is given in Kelvin. A named tuple (Coulomb::Float64, Babushkin::Float64) [cm^3/s] is returned.
JenaAtomicCalculator.Plasma.validateKineticChargeBalanceSupport — Method
Plasma.validateKineticChargeBalanceSupport(scheme::Plasma.KineticChargeBalanceScheme) ... checks every leg of scheme against the chargeStages it touches and raises – listing every violation found, each naming the leg, the stage(s) involved, and the nearest supported alternative – if an unsupported (treatment tier, stage shape) combination is requested. Called BEFORE any Multiplet is generated (cf. Plasma.KineticChargeBalanceScheme), so an unsupported request fails fast and cheaply rather than part-way through real computation. Nothing is returned if every leg/stage combination is supported; an error is raised otherwise.
Collisional-radiative level populations
JenaAtomicCalculator.Plasma.collisionalRadiativeLevelFingerprint — Method
Plasma.collisionalRadiativeLevelFingerprint(scheme::Plasma.CollisionalRadiativeScheme, computation::Plasma.Computation) ... builds a small Dict{String,Any} of PLAIN, comparable values (Float64/Int64/String only, never whole structs) that together identify the physics inputs of Plasma.generateCollisionalRadiativeLevels for the given scheme/computation: element, charge state, reference configuration(s), NoExcitations, upperShellNo, the grid's own recipe scalars (rnt, h, hp, NoPoints – NOT its large r/rp/wr arrays, which would risk truncated/misleading string comparisons), and asfSettings (safe to stringify whole, since none of its own fields are large arrays, unlike Radial.Grid). Used both when writing a level-cache file (stored alongside the data) and when validating a candidate cache file for reuse – an EXACT match on every key is required, not a sufficiency/>=-style check.
JenaAtomicCalculator.Plasma.collisionalRadiativeRatesFingerprint — Method
Plasma.collisionalRadiativeRatesFingerprint(scheme::Plasma.CollisionalRadiativeScheme, levelFingerprint::Dict{String,Any}) ... extends the given levelFingerprint with the ImpactExcitation-specific settings that also determine the raw collision data (maxKappa, maxEnergyMultiplier, numElectronEnergies, operator) – copying in the level fingerprint keeps the rates-cache file self-contained, so validating it does not require separately cross-checking a level-cache file. Deliberately does NOT include ieSettings.temperatures: the cached data (ImpactExcitation's raw, pre-thermal-average lines) is temperature-independent by construction, so any temperature list can be evaluated from it afterward at negligible cost.
JenaAtomicCalculator.Plasma.displayCollisionalRadiativeResults — Method
Plasma.displayCollisionalRadiativeResults(stream::IO, repMultiplet::Multiplet, temperatures::Array{Float64,1}, Ne::Float64, popVectors::Dict) ... prints a table of the relative level populations (Coulomb/Babushkin), one row per (level, temperature) pair, following JAC's usual table style (2-line header, truncated scientific notation, energies/temperatures in the usual units). A neat table is printed but nothing is returned otherwise.
JenaAtomicCalculator.Plasma.estimateCollisionalRadiativeCost — Method
Plasma.estimateCollisionalRadiativeCost(scheme::Plasma.CollisionalRadiativeScheme, computation::Plasma.Computation; referencePair::Tuple{Int64,Int64}=(1,2))
... estimates, WITHOUT running ImpactExcitation for every level pair, whether a Plasma.
CollisionalRadiativeScheme computation is tractable. Generates the real level set (mean-field basis
+ per-configuration CI, always cheap) to get the real level count N, times ONE representative
ImpactExcitation pair (referencePair, by energy-sorted index) at the scheme's own scheme.ieSettings,
and extrapolates the total collisional-rate cost via N(N-1)/2 pair-count scaling -- the dominant
cost for any level set beyond a handful of levels (found 02-Aug-2026: a 45-level/990-pair He-like
carbon case extrapolated to ~7h; a 1879-level/1.76M-pair Ar3+ case -- single excitations from ALL
shells of a 3s^2 3p^3 reference configuration, including the closed 1s/2s/2p core -- extrapolated
to ~17000h, genuinely intractable rather than merely slow). This is a ROUGH order-of-magnitude
estimate, not a precise prediction: per-pair cost varies with channel count and CSF-basis size, and
only one representative pair is timed here. Meant to be checked BEFORE attempting a full run, not
as a replacement for one. A named tuple (levels, pairs, levelGenerationTime, referencePairTime,
estimatedTotalIETime) is returned; a human-readable summary is always printed.
+ scheme ::Plasma.CollisionalRadiativeScheme
... the scheme (NoExcitations, upperShellNo, ieSettings) whose cost is to be estimated.
+ computation ::Plasma.Computation ... provides nuclearModel, grid, refConfigs, asfSettings.
+ referencePair ::Tuple{Int64,Int64} ... which (by-energy-sorted) level indices to time; default (1,2).JenaAtomicCalculator.Plasma.generateCollisionalRadiativeLevels — Method
Plasma.generateCollisionalRadiativeLevels(scheme::Plasma.CollisionalRadiativeScheme, computation::Plasma.Computation) ... generates the (small) level set for computation.refConfigs, following the same generation policy as Plasma.generateIonLevelData (single excitations from all shells of refConfigs; double & higher excitations, if scheme.NoExcitations > 1, from the same shells – refConfigs is given explicitly by the caller here, so no Plasma.determineValenceShells electron-count heuristic is needed or used). All configurations share ONE mean-field orbital basis, and every level is then extracted via Hamiltonian.performCIwithFrozenOrbitals against that shared basis – this is what keeps the levels properly reconciled for the later PhotoEmission/ImpactExcitation calls (no separate SCF per config). A Multiplet, sorted by energy with levels re-indexed 1..N (Basics.sortByEnergy), is returned.
JenaAtomicCalculator.Plasma.perform — Method
Plasma.perform(scheme::Plasma.CollisionalRadiativeScheme, computation::Plasma.Computation; output::Bool=true) ... to compute the (relative) collisional-radiative population balance among the levels generated for one ion (computation.refConfigs). For output=true, a dictionary is returned from which the relevant results can be accessed by proper keys.
JenaAtomicCalculator.Plasma.readEvaluateCollisionalRadiativeLevels — Method
Plasma.readEvaluateCollisionalRadiativeLevels(scheme::Plasma.CollisionalRadiativeScheme, computation::Plasma.Computation) ... tries each file in scheme.levelsFilenames, in order, and returns the cached Multiplet from the first one whose stored fingerprint EXACTLY matches collisionalRadiativeLevelFingerprint(scheme, computation) – not a sufficiency/>=-style check, unlike Plasma.readEvaluateIonLevelData, since most of the relevant parameters here (grid, asfSettings, ...) have no natural "richer implies superset" ordering. missing is returned if no candidate matches (or scheme.levelsFilenames is empty), so the caller can fall back to a fresh Plasma.generateCollisionalRadiativeLevels call.
JenaAtomicCalculator.Plasma.readEvaluateCollisionalRadiativeRates — Method
Plasma.readEvaluateCollisionalRadiativeRates(scheme::Plasma.CollisionalRadiativeScheme, computation::Plasma.Computation, levelFingerprint::Dict{String,Any}) ... tries each file in scheme.ratesFilenames, in order, and returns the cached raw ImpactExcitation lines from the first one whose stored fingerprint EXACTLY matches collisionalRadiativeRatesFingerprint(scheme, levelFingerprint). missing is returned if no candidate matches (or scheme.ratesFilenames is empty), so the caller can fall back to a fresh ImpactExcitation.computeLines call.
JenaAtomicCalculator.Plasma.solveCollisionalRadiativeBalance — Method
Plasma.solveCollisionalRadiativeBalance(matrixA::Array{Float64,2}) ... solves the steady-state collisional-radiative balance dn_i/dt = 0 for the given N x N rate matrix (matrixA[i,j] = total rate FROM level i TO level j for i != j; matrixA[i,i] = -(total loss rate out of level i)). Since the rows of matrixA sum to zero by construction (population conservation), this system is singular; exactly one of the N balance equations is redundant and is replaced by the normalization constraint sum(n) = 1 to obtain a well-posed, uniquely solvable system. The equation that gets sacrificed is the GROUND STATE's (index 1, the lowest level, since repMultiplet is sorted ascending in energy) – see the discussion below. A relative-population vector (summing to 1) is returned.
JenaAtomicCalculator.Plasma.writeCollisionalRadiativeLevels — Method
Plasma.writeCollisionalRadiativeLevels(scheme::Plasma.CollisionalRadiativeScheme, computation::Plasma.Computation, repMultiplet::Multiplet) ... writes repMultiplet, together with its collisionalRadiativeLevelFingerprint(scheme, computation), to a new, auto-named, never-overwritten file inside scheme.cacheDirectory (created if missing; "" writes into the current directory). The filename is printed so it can be adopted into a later run's scheme.levelsFilenames.
JenaAtomicCalculator.Plasma.writeCollisionalRadiativeRates — Method
Plasma.writeCollisionalRadiativeRates(scheme::Plasma.CollisionalRadiativeScheme, computation::Plasma.Computation, levelFingerprint::Dict{String,Any}, ieLines::Array{ImpactExcitation.Line,1}) ... writes ieLines (ImpactExcitation's raw, pre-thermal-average lines), together with its collisionalRadiativeRatesFingerprint(scheme, levelFingerprint), to a new, auto-named, never-overwritten file inside scheme.cacheDirectory. The filename is printed so it can be adopted into a later run's scheme.ratesFilenames.
Line-shift computations
JenaAtomicCalculator.Plasma.displayResults — Method
Plasma.displayResults(stream::IO, multiplet::Multiplet, pMultiplet::Multiplet, plasmaModel::Basics.AbstractPlasmaModel) ... to display the energies, M_ms and F-parameters, etc. for the selected levels. A neat table is printed but nothing is returned otherwise.
JenaAtomicCalculator.Plasma.perform — Method
Plasma.perform(scheme::Plasma.LineShiftScheme, computation::Plasma.Computation; output::Bool=true) ... to perform a Saha-Boltzmann equilibrium computation for a given ion mixture. For output=true, a dictionary is returned from which the relevant results can be can easily accessed by proper keys.
JenaAtomicCalculator.Plasma.performCI — Method
Plasma.performCI(basis::Basis, nm::Nuclear.Model, grid::Radial.Grid, settings::AsfSettings, plasmaModel::Basics.AbstractPlasmaModel; printout::Bool=false) ... computes and diagonalizes the CI matrix for all CSF in the given basis under the given plasma model, mirroring Hamiltonian.performCI but replacing the field-free Hamiltonian.setupMatrix by the plasma-screened Basics.compute(JP, basis, nm, grid, settings, plasmaModel). For plasmaModel = Basics.NoPlasmaModel(), this delegates directly to Hamiltonian.performCI, so that the field-free computation of the standard processes is never touched by the plasma-specific code path. A multiplet::Multiplet is returned.
Saha-Boltzmann computations of ionic mixtures
JenaAtomicCalculator.Plasma.IonicClass — Type
struct Plasma.IonicClass ... a struct to comprise the (necessary) information about a single ionic charge state in Saha-Boltzmann computations.
+ q ::Int64 ... charge state q of the ions.
+ groundEnergy ::Float64 ... ground level energy of the ion.
+ ionLevels ::Array{Plasma.IonicLevel,1} ... ionic levels of this charge stateJenaAtomicCalculator.Plasma.IonicLevel — Type
struct Plasma.IonicLevel ... a struct to comprise the (necessary) information about a single ionic level in Saha-Boltzmann computations.
+ energy ::Float64 ... total energy E (Z, A, q) of the ionic level.
+ g ::Float64 ... degeneracy g (Z, A, q) of the ionic level.
+ nDensity ::Float64 ... number density of ions I(Z, A, q) in this level.
+ uppermostShell ::Shell ... uppermost shell in the underlying configuration.JenaAtomicCalculator.Plasma.IsotopeClass — Type
struct Plasma.IsotopeClass ... a struct to comprise the (necessary) information about a single isotopic fraction in Saha-Boltzmann computations.
+ isotopicDensity ::Float64 ... (number) density n (Z,A) of all ions of this isotope class.
+ Lambda ::Float64 ... thermal length Lambda of the given isotope.
+ dominantEnergy ::Float64
... energy of the "dominant" ion level of this isotope; this depends on energy and help improve convergence
+ isotopicFraction ::Basics.IsotopicFraction ... isotopic fraction in the Saha-Boltzmann mixture.
+ ionClasses ::Array{Plasma.IonicClass,1} ... list of all ions of the isotope I(Z,A).JenaAtomicCalculator.Plasma.computeElectronChemicalPotential — Method
Plasma.computeElectronChemicalPotential(temp::Float64, ne::Float64) ... computes the electron chemical potential for the given electron (number) density; a chemMu::Float64 is returned.
JenaAtomicCalculator.Plasma.computeElectronNumberDensity — Method
Plasma.computeElectronNumberDensity(temp::Float64, isoClasses::Array{IsotopeClass,1}) ... computes the electron (number) density n_e (T) from the density of all ionic levels, charge states and isotopic mixture at temperature T; an nDensity::Float64 is returned.
JenaAtomicCalculator.Plasma.computeIonLevelNumberDensity — Method
Plasma.computeIonLevelNumberDensity(temp::Float64, q::Int64, ionLevel::IonicLevel, pfIsoClass::Float64, isoDensity::Float64, chemMuE::Float64, dominantEnergy::Float64) ... computes the (number) density of an individual ionLevel of ions of charge state q at temperature T, the electron chemical potential chemMuE and for a given partion function of the associated IsotopeClass pfIonClass; an nDensity::Float64 is returned.
JenaAtomicCalculator.Plasma.computeIonLevelNumberDensityTotal — Method
Plasma.computeIonLevelNumberDensityTotal(isoClass::IsotopeClass) ... computes the total (number) density of all charge states and individual ionLevel's just by summation. an nDensity::Float64 is returned.
JenaAtomicCalculator.Plasma.computeIsotopicPartitionFunction — Method
Plasma.computeIsotopicPartitionFunction(temp::Float64, isoClass::IsotopeClass, chemMuE::Float64, dominantEnergy::Float64) ... computes the (unnormalized) partition function of the given isotopic class in terms of a summation over all charge states and ionic levels of these class. A pf::Float64 is returned.
JenaAtomicCalculator.Plasma.computeIsotopicPartitionFunctionBound — Method
Plasma.computeIsotopicPartitionFunctionBound(temp::Float64, isoClass::IsotopeClass, chemMuE::Float64, dominantEnergy::Float64, groundE::Dict{Int64,Float64}, deltaIp::Dict{Int64,Float64}, qMax::Int64) ... the IPD-aware sibling of Plasma.computeIsotopicPartitionFunction, needed once an ionization- potential-depression model removes levels from the ensemble (item 97): sums over only the levels that pass the SAME bound/unbound test Plasma.solveSahaBoltzmannEquilibrium applies before computing each level's own number density – level.energy == 0. || ionClass.q == qMax || level.energy + deltaIp[ionClass.q] < groundE[ionClass.q+1]. A level the IPD model removes must also be removed from the normalizing sum every surviving level's population is divided by, or the population it carried is destroyed rather than transferred to the next charge state – the half of item 97 that flipping deltaIp's sign alone does not fix. A pf::Float64 is returned.
JenaAtomicCalculator.Plasma.computeMeanIsotopeChargeState — Method
Plasma.computeMeanIsotopeChargeState(isoClass::IsotopeClass) ... computes the (mean) charge states <q> of all ions of the given isotope; a qbar::Float64 is returned.
JenaAtomicCalculator.Plasma.determineInitialIonDensitiesPropterties — Method
Plasma.determineInitialIonDensitiesPropterties(scheme::Plasma.SahaBoltzmannScheme, temp::Float64, ionDensity::Float64, isoClass::IsotopeClass) ... determines the initial level densities and all temperature-dependent properties which are not yet defined for solving the Saha-Boltzmann equations. The procedure assumes however that the ionic level information has been provided before. A list of isoClasses::Array{Plasma.IsotopeClass,1} is returned.
JenaAtomicCalculator.Plasma.determineIonicClasses — Method
Plasma.determineIonicClasses(scheme::Plasma.SahaBoltzmannScheme, temp::Float64, isoFraction::Basics.IsotopicFraction) ... determines all relevant ionic classes of the given isotope with fraction x at temperature temp which (sufficiently) contribute to the ionic mixture. The procedure selects the relevant charge states but does neither determine the number nor the properties of the ionic levels of these ion classes. These levels need to be later initialized by either explicit computations or reading them from a file. A list of ionClasses::Array{Plasma.IonicClass,1} is returned.
JenaAtomicCalculator.Plasma.determineIpShifts — Method
Plasma.determineIpShifts(pm::Basics.AbstractPlasmaModel, temp::Float64, ni::Float64, isoClass::IsotopeClass) ... determines the ground-state energie as well as the shifts Delta I_p (q –> q+1) for all charge states q = 0 ... qmax of the ions defined by isotopeClass. The procedure assumes that the plasma model pm brings in the current plasma parameters. In some models, the ion number density ni is required as well. Two dictionaries groundE[q]::Dict{Int64,Float64}, deltaIp[q]::Dict{Int64,Float64} are returned with all the energies (shifts) in [Hartree].
JenaAtomicCalculator.Plasma.determineIsotopeClasses — Method
Plasma.determineIsotopeClasses(scheme::Plasma.SahaBoltzmannScheme, temp::Float64) ... determines which isotope classes which need to be considered for the given Saha-Boltzmann mixture; it first normalizes all isotopic fractions to 1 and then selects the relevant charge states in the mixture due to the given temperature and the number of charge states involved the self-consistent treatment of the mixture. However, this procedure does neither determine the number nor the detailed properties of the ionic levels of these ion classes. These ionic levels and all further properties are first left out (empty) for later specification. A list of isoClasses::Array{Plasma.IsotopicClass,1}
JenaAtomicCalculator.Plasma.determineReferenceConfiguration — Method
Plasma.determineReferenceConfiguration(ne::Int64) ... determines the reference configuration for an ion with ne electrons. A refConfig::Configuration is returned.
JenaAtomicCalculator.Plasma.determineValenceShells — Method
Plasma.determineValenceShells(ne::Int64) ... determines the valance shells for an ion with ne electrons. A shellList::Array{Shell,1} is returned.
JenaAtomicCalculator.Plasma.displayIsotopeClasses — Method
Plasma.displayIsotopeClasses(stream::IO, isoClasses::Array{IsotopeClass,1}) ... list all basic information about the ionic mixture, i.e. the isotopic fractions, the thermal length, the isotopic density as well as the number of charge states and ionic levels involved into the computations. A neat table is printed but nothing is returned otherwise.
JenaAtomicCalculator.Plasma.displaySahaBoltzmannEquilibrium — Method
Plasma.displaySahaBoltzmannEquilibrium(stream::IO, isoClasses::Array{IsotopeClass,1}, pm::Basics.AbstractPlasmaModel; printLevelDensities::Bool=true) ... list some basic information about the ionic mixture, along with the charge states and the ionic densities; it also prints the ionic level number densities if this is required. A neat table is printed but nothing is returned otherwise.
JenaAtomicCalculator.Plasma.displayThermodynamicProperties — Method
Plasma.displayThermodynamicProperties(stream::IO, temp::Float64, totalIonDensity::Float64, isoClasses::Array{IsotopeClass,1}) ... evaluates, converts units and displays the thermodynamic properties of the ionic mixture, based on the given isotopic-class data. A neat table is printed but nothing is returned otherwise.
JenaAtomicCalculator.Plasma.freeEnergyDensity — Method
Plasma.freeEnergyDensity(temp::Float64, totalIonDensity::Float64, isoClasses::Array{IsotopeClass,1}) ... computes the internal energy density u(T) of an isotopic mixture at temperature T; a u::Float64 is returned.
JenaAtomicCalculator.Plasma.generateIonLevelData — Method
Plasma.generateIonLevelData(scheme::Plasma.SahaBoltzmannScheme, isoClass::IsotopeClass, q::Int64, grid::Radial.Grid) ... generates the ionic-level data for the given isotope class and charge state q of the ionic mixture. These ionic-level data are generated for the requested number in scheme.NoIonLevels and excitations in scheme.NoExcitations of levels. The procedure presently assumes that the electron shells in the reference configuration are filled in standard order with the Z-q electrons. A special treatment of the reference configuration need to be introduced if this is not the case. The energy levels are generated by including scheme.NoExcitations excitations w.r.t. the reference configuration, and all levels with an excitation energy < maxEn are taken into account, up to scheme.NoIonLevels. An ionLevels::Array{IonicLevels,1} is returned where all ionic-level data are properly places but all (number) densities are still set to 0.
JenaAtomicCalculator.Plasma.internalEnergyDensity — Method
Plasma.internalEnergyDensity(temp::Float64, totalIonDensity::Float64, isoClasses::Array{IsotopeClass,1}) ... computes the internal energy density u(T) of an isotopic mixture at temperature T; a u::Float64 is returned.
JenaAtomicCalculator.Plasma.perform — Method
Plasma.perform(scheme::Plasma.SahaBoltzmannScheme, computation::Plasma.Computation; output::Bool=true) ... to perform a Saha-Boltzmann equilibrium computation for a given ion mixture. For output=true, a dictionary is returned from which the relevant results can be can easily accessed by proper keys.
JenaAtomicCalculator.Plasma.pressure — Method
Plasma.pressure(temp::Float64, totalIonDensity::Float64, isoClasses::Array{IsotopeClass,1}) ... computes the pressure of an isotopic mixture at temperature T; a pressure::Float64 is returned.
JenaAtomicCalculator.Plasma.readEvaluateIonLevelData — Method
Plasma.readEvaluateIonLevelData(scheme::Plasma.SahaBoltzmannScheme, isoClass::IsotopeClass, grid::Radial.Grid) ... reads in or evaluates the ionic-level data for the given isotope class of the ionic mixture. This steps basically generates/provides all atomic level data upon which Saha-Boltzmann ionic mixture is based on. To generate these data it analyses of whether ion-level data are provided by one of the files in scheme.isotopeFilenames::{String,1}; if this is the case, it further analyzes of whether the provided data fullfill the requested number scheme.NoIonLevels and excitations scheme.NoExcitations of levels for each charge state of the isotope. If no suitable ion-level data are found for an isotope (Z,A) in isoClasses, the routine generates a (new) set of ion-level data for the current computation. In addition, a (new) file with name NewIonLevelsZxxxAyyyy.... is written to disk and can be utilized in any subsequent computation. It is typically assumed that these file are renamed with the proper physical settings for their generation in mind.
A newIsoClass::IsotopeClass is returned where all ionic-level data are properly places
but all (number) densities are still set to 0. All other fields remain unchanged.JenaAtomicCalculator.Plasma.readEvaluateIonLevelData — Method
Plasma.readEvaluateIonLevelData(filename::String, isoClass::IsotopeClass, NoExcitations::Int64, upperShellNo::Int64) ... reads in, if available, the ionic-level data for the given isotope class from filename. The ionic-level data are accepted for return, if (1) they belong to isotope (Z,A) in isoClasses and if they fullfill (2) upperShellNo <= filename:upperShellNo, (3) NoExcitations <= filename:NoExcitations. If proper data are found, an updated newIsoClass::IsotopeClass returned and missing otherwise.
JenaAtomicCalculator.Plasma.restrictIonLevelData — Method
Plasma.restrictIonLevelData(scheme::Plasma.SahaBoltzmannScheme, isoClass::IsotopeClass) ... restricts the compiled ion-level-data tp those levels that need to be included into the Saha-Boltzmann equilibrium iteration. a newIsoClass::IsotopeClass is returned.
JenaAtomicCalculator.Plasma.solveSahaBoltzmannEquilibrium — Method
Plasma.solveSahaBoltzmannEquilibrium(temp::Float64, isoClasses::Array{IsotopeClass,1}, pm::Basics.AbstractPlasmaModel) ... solves the Saha-Boltzmann equations for a given ionic mixture and temperature; it iterates the ion-level number densities until no relevant changes occur. A newIsoClasses::Array{IsotopeClass,1} with the proper number densities is returned.
JenaAtomicCalculator.Plasma.thermalLength — Method
Plasma.thermalLength(temp::Float64, isoFraction::Basics.IsotopicFraction) ... returns the thermal length Lambda(T, M) for a particle with mass M at temperature T. A length Lambda::Float64 in {a_o] is returned.
JenaAtomicCalculator.Plasma.updateIpdPlasmaModel — Method
Plasma.updateIpdPlasmaModel(pm::Basics.AbstractPlasmaModel, temp::Float64, ne::Float64, isotopeClasses::Array{IsotopeClass,1}) ... updates the (parameters) of the plasma model pm due to the given temperature temp, electron density ne and the level population of the mixture. A new plasma model npm::type(pm) is returned.
JenaAtomicCalculator.Plasma.writeIonLevelData — Method
Plasma.writeIonLevelData(filename::String, isoClass::IsotopeClass, NoExcitations::Int64, upperShellNo::Int64) ... writes-out the ionic-level data for the given isotope class to filename. Nothing is returned.
Plasma: satellite diagnostics
JenaAtomicCalculator.Plasma.displaySatelliteDiagnosticResults — Method
Plasma.displaySatelliteDiagnosticResults(stream::IO, temperatures::Array{Float64,1}, satelliteAlpha::Dict{Float64,EmProperty}, parentAlpha::Dict{Float64,Float64}, branchingFraction::EmProperty, ratios::Dict{Float64,EmProperty}) ... prints a table of the satellite/parent rate coefficients and the combined R(Te) ratio. A neat table is printed but nothing is returned otherwise.
JenaAtomicCalculator.Plasma.perform — Method
Plasma.perform(scheme::Plasma.SatelliteDiagnosticScheme, computation::Plasma.Computation; output::Bool=true) ... to compute the dielectronic-satellite-to-parent-line intensity-ratio Te diagnostic R(Te) for one recombining ion. For output=true, a dictionary is returned from which the relevant results can be accessed by proper keys.
JenaAtomicCalculator.Plasma.reconcileTemperatures — Method
Plasma.reconcileTemperatures(drTemps::Array{Float64,1}, ieTemps::Array{Float64,1}) ... reconciles the two independent temperature grids of scheme.drSettings and scheme.ieSettings into a single, shared grid [K] for the R(Te) ratio. If one is empty, the other is used. If both are non-empty and differ, the longer one is used and a warning is printed to the summary/log stream. If both are empty, an error is raised. An Array{Float64,1} is returned.
Super-configurations: unresolved-level statistics
JenaAtomicCalculator.SuperConfigurations.Group — Type
struct SuperConfigurations.Group ... the Gaussian (two-moment) statistical description of one configuration's UNRESOLVED level spectrum: its mean energy, variance, and total (2J+1)-weighted degeneracy (the statistical weight the group represents), computed without diagonalizing its CI matrix. See this module's own docstring for exactly how meanEnergy and variance are obtained, and what each still costs.
+ conf ::Configuration ... the configuration this group describes.
+ meanEnergy ::Float64 ... (2J+1)-weighted mean energy, in Hartree.
+ variance ::Float64 ... (2J+1)-weighted variance of the level energies, in Hartree^2.
+ degeneracy ::Float64 ... total (2J+1)-weighted statistical weight, SUM_csf (2*J_csf+1).JenaAtomicCalculator.SuperConfigurations.SuperGroup — Type
struct SuperConfigurations.SuperGroup ... the Gaussian (two-moment) statistical description of a GENUINE superconfiguration: several Group's, each already an unresolved configuration, POOLED into one wider statistical bin – competition item C9's own name for this module, completed 17-Oct-2026. The mean, variance and degeneracy are the STANDARD combined-sample (pooled) moments: the between-configuration spread is folded into the variance via the law of total variance, exactly as SuperConfigurations.Group folds the within-configuration spread into ITS OWN variance one level down. See SuperConfigurations.buildSuperGroup for the formula and for the ONE assumption it carries, named rather than hidden: NO configuration-interaction MIXING between the bin's own configurations is included, only within each one individually (the same scope Group itself already has). The MEAN is exact regardless – a trace argument, not an approximation – while the VARIANCE is, in principle, only a LOWER BOUND where configurations genuinely mix; measured on a realistic strongly-mixing pair against full CI, that bound came out tight (5 significant figures), not substantially low (see buildSuperGroup's own docstring for what an earlier, bug-corrupted measurement claimed instead, and why it was wrong).
+ confs ::Array{Configuration,1} ... the configurations pooled into this bin.
+ meanEnergy ::Float64 ... the pooled (degeneracy-weighted) mean energy, in Hartree.
+ variance ::Float64 ... the pooled variance (within-configuration spread,
degeneracy-weighted, PLUS the between-configuration
spread of the individual means around the pooled
mean), in Hartree^2.
+ degeneracy ::Float64 ... the total (2J+1)-weighted statistical weight, SUM over
every configuration in the bin.JenaAtomicCalculator.SuperConfigurations.TransitionArray — Type
struct SuperConfigurations.TransitionArray ... the Gaussian (two-moment) statistical description of the UNRESOLVED electric-dipole (E1) transition array between two configurations' level spectra: the line-strength-weighted mean transition energy, its variance, and the array's total line strength, computed without diagonalizing either configuration's CI matrix. See SuperConfigurations.buildTransitionArray for exactly how these are obtained, and this module's own docstring for why they are EXACT rather than a closed form.
WHETHER A GAUSSIAN IS A GOOD MODEL FOR THE TRUE DISTRIBUTION -- not just whether these two moments
are computed correctly -- was CALIBRATED, not assumed, 17-Oct-2026, on Co2+ [Ar] 3d^7 -> 3d^6 4p
(3420 individual CSF-pair lines, exact eigenbasis via direct diagonalization, used only for this
one-time check and nowhere in the production path): skewness +0.28, excess kurtosis +1.11 against
the Gaussian's 0 and 0, with no single line carrying more than 2.2 % of the total strength (the top
five together 8.4 %). So at this CSF count a Gaussian is a reasonable, mildly heavy-tailed and
mildly asymmetric approximation, not an exact one, and NOT an artefact of a few outlier lines
dominating the sum. This is ONE measurement on ONE array, not a theorem -- re-check before trusting
it at a very different size or shell structure, in particular before building Stage 3 (a single
summed opacity spectrum) on top of it.
+ confFinal ::Configuration ... the configuration the transition ends in.
+ confInitial ::Configuration ... the configuration the transition starts from.
+ meanEnergy ::Float64 ... line-strength-weighted mean of (E_final - E_initial), in Hartree;
POSITIVE for an allowed absorption transition to a higher complex.
+ variance ::Float64 ... line-strength-weighted variance of the transition energy, in
Hartree^2.
+ totalStrength ::Float64 ... the array's total E1 line strength, SUM over every CSF pair of
|<confFinal CSF || D^(1) || confInitial CSF>|^2, in atomic units.JenaAtomicCalculator.SuperConfigurations.buildBasisAndCsfs — Method
SuperConfigurations.buildBasisAndCsfs(conf::Configuration, orbitals::Dict{Subshell,Orbital}; subshellList::Union{Nothing,Array{Subshell,1}}=nothing) ... a private helper that builds the SAME relativistic-CSF basis Basics.determineMeanEnergy builds, so that varianceFromCsfMatrix and BasicsAZ.meanEnergyInClosedForm describe EXACTLY the same set of states. If subshellList is given, conf's CSFs are built on THAT list instead of generating one from conf alone – the one case this is needed is buildTransitionArray, where two DIFFERENT configurations' CSFs must be indexed against their COMBINED subshell list before a transition operator can connect them. A (basis::Basis, csfList::Array{CsfR,1}) tuple is returned.
JenaAtomicCalculator.SuperConfigurations.buildDipoleMatrix — Method
SuperConfigurations.buildDipoleMatrix(csfListFinal::Array{CsfR,1}, basisFinal::Basis, csfListInitial::Array{CsfR,1}, basisInitial::Basis, subshellList::Array{Subshell,1}, grid::Radial.Grid) ... a private helper that fills the CSF-pair electric-dipole (E1) REDUCED matrix element <csfListFinal[s] || D^(1) || csfListInitial[r]> for every pair, the two-configuration analogue of buildHamiltonianMatrix for a rank-1 operator instead of the rank-0 Hamiltonian. Reuses the SAME InteractionStrength.eMultipole(1, ...) radial integral MultipoleMoment.emmStaticAmplitude pairs with coeff.T (GRASP-dressed, Rule 18) – NOT InteractionStrength.MabEmission, which is the retarded photon-emission operator and needs a transition energy this module does not yet have. The residual sqrt(2J_f+1) factor Rule 18 places AFTER the CSF loop is applied HERE PER ROW, using that row's OWN csf.J, since csfListFinal spans several J blocks at once rather than one level's fixed J – the direct generalization of varianceFromCsfMatrix's per-CSF wr weight to a rank-1 operator. eMultipole is MEMOIZED by orbital pair here too, the SAME fix and the SAME reason as oneParticleIntegralCached (priority item 79) – the number of distinct orbital pairs is bounded by the two configurations' active shells, not by nF x nI. A matrix::Array{Float64,2} of size (length(csfListFinal), length(csfListInitial)) is returned.
JenaAtomicCalculator.SuperConfigurations.buildGroup — Method
SuperConfigurations.buildGroup(conf::Configuration, orbitals::Dict{Subshell,Orbital}, nm::Nuclear.Model, grid::Radial.Grid, settings::AsfSettings) ... to build the Gaussian statistical description of conf: the mean energy from BasicsAZ.meanEnergyInClosedForm (closed form, no CSF touched) and the variance from SuperConfigurations.varianceFromCsfMatrix (exact, CSF-pair-level, not yet closed form – see this module's own docstring for why). A group::SuperConfigurations.Group is returned.
JenaAtomicCalculator.SuperConfigurations.buildHamiltonianMatrix — Method
SuperConfigurations.buildHamiltonianMatrix(csfList::Array{CsfR,1}, basis::Basis, nm::Nuclear.Model, grid::Radial.Grid, settings::AsfSettings) ... a private helper that fills the FULL CSF-pair Hamiltonian matrix of basis – zero between different J^P blocks, exactly as varianceFromCsfMatrix's own loop skips them – needed here because buildTransitionArray contracts this matrix with the transition operator rather than only reading its trace. Uses matrixElementCached, NOT Hamiltonian.matrixElement directly, so the one-particle radial integral is memoized by orbital pair across every CSF pair in this build (priority item 79; see oneParticleIntegralCached's own docstring for the measurement). A matrix::Array{Float64,2} is returned.
JenaAtomicCalculator.SuperConfigurations.buildSuperGroup — Method
SuperConfigurations.buildSuperGroup(confs::Array{Configuration,1}, orbitals::Dict{Subshell,Orbital}, nm::Nuclear.Model, grid::Radial.Grid, settings::AsfSettings) ... to build the pooled Gaussian description of a GENUINE superconfiguration: build one SuperConfigurations.Group per configuration in confs (reusing buildGroup exactly, no new CSF-level computation), then combine them with the STANDARD combined-sample (pooled) moment formulas – the same ones the Bauche-Arnoult/STA literature itself uses at this level of theory:
G = SUM_i g_i -- total degeneracy
M = SUM_i g_i * mean_i / G -- pooled mean
V = SUM_i g_i * ( var_i + (mean_i - M)^2 ) / G -- pooled variance
THE MEAN `M` IS EXACT, PROVABLY, NOT JUST USUALLY. Configuration-interaction mixing between
`confs[i]` and `confs[j]` would add OFF-DIAGONAL blocks to the full combined Hamiltonian, and an
off-diagonal block never contributes to a trace -- so Tr(H_full) = Tr(H_AA) + Tr(H_BB) + ... holds
with NO approximation, whatever the mixing, and `M` built from the separate `Group`s' own means is
exactly the mean a full multi-configuration diagonalization would give.
THE VARIANCE `V` IS NOT EXACT WHERE CONFIGURATIONS GENUINELY MIX, IN PRINCIPLE: Tr(H_full^2) picks
up an off-diagonal cross term the pooled formula has no way to see, and that term is exactly the
mixing `SuperGroup` omits -- `V` is therefore a LOWER BOUND on the true variance, never an
overestimate. HOW LARGE THAT CROSS TERM ACTUALLY IS was measured, not guessed, on a realistic
strongly-mixing pair, Co2+ `[Ar] 3d^7` + `[Ar] 3d^6 4s` (near-degenerate nd^n/nd^(n-1)(n+1)s mixing,
a textbook case), against `Hamiltonian.performCI` on the two configurations TOGETHER (the SAME
validation route `TestFrames.testModule_SuperConfigurations` already uses for one configuration).
RE-MEASURED 17-Oct-2026 after the catastrophic-cancellation fix to `varianceFromCsfMatrix` (see this
module's own top docstring): the FIRST measurement, taken through the unfixed formula, reported the
pooled width 19.5 % too narrow (0.115 Hartree against 0.143 Hartree) -- that number was itself an
artifact of the bug, not a property of CI mixing, because each `Group`'s own variance feeding the
pool was already corrupted before pooling began. Through the FIXED formula, the pooled width is
0.142711 Hartree against a true (full-CI) 0.142714 Hartree -- agreement to 5 significant figures,
not a 19.5 % shortfall. For THIS pair, in other words, the omitted cross term turns out to be
negligible despite the strong level mixing, because Tr(H_AB*H_BA) can be small even when individual
off-diagonal matrix elements are not. The lower-bound property above still holds in general and the
cross term is not zero by any argument -- only ever measured small here -- so a new pair should
still be checked rather than assumed, but do not re-use the retracted 19.5 % figure for anything.
A superGroup::SuperConfigurations.SuperGroup is returned.JenaAtomicCalculator.SuperConfigurations.buildTransitionArray — Method
SuperConfigurations.buildTransitionArray(confFinal::Configuration, confInitial::Configuration, orbitals::Dict{Subshell,Orbital}, nm::Nuclear.Model, grid::Radial.Grid, settings::AsfSettings) ... to build the Gaussian statistical description of the UNRESOLVED E1 transition array from confInitial to confFinal: the line-strength-weighted mean energy, variance and total line strength, EXACT at CSF-pair level, with no diagonalization of either configuration's Hamiltonian and no closed-form Bauche-Arnoult moment formula. The two configurations' CSFs are built on their COMBINED subshell list (Basics.merge), exactly as every two-configuration transition amplitude elsewhere in JAC already does, so the dipole operator can connect them.
THE ALGEBRA, so it can be checked rather than trusted. Let H1, H2 be the ordinary CSF-pair
Hamiltonian matrices of confInitial, confFinal (each block-diagonal in J, parity, with EXACT
eigenvalues equal to that configuration's true level energies), and D the CSF-pair E1 REDUCED matrix
element (Rule 18: already Wigner-Eckart-normalized, so |D_sr|^2 IS the standard line strength between
the levels D's CSF indices expand into -- no extra statistical weight is needed anywhere below).
Inserting the completeness relation of each configuration's OWN exact eigenvectors on either side of
D, with NO approximation:
S_total = Tr(D^T D) -- the array's total line strength
mean = [Tr(H2 D D^T) - Tr(H1 D^T D)] / S_total -- strength-weighted <E_final-E_initial>
var = [Tr(H2^2 D D^T) - 2 Tr(H1 D^T H2 D) + Tr(H1^2 D^T D)] / S_total - mean^2
See `TestFrames.testModule_SuperConfigurations` for the brute-force check -- diagonalizing H1, H2
directly and summing over the resulting level pairs -- that these traces reproduce the double sum
rather than being a tidy-looking guess.
H1 AND H2 ARE SHIFTED BY A REPRESENTATIVE CONSTANT BEFORE EITHER IS SQUARED, for the same reason as
`varianceFromCsfMatrix`: found 17-Oct-2026 on Dy3+ `[Xe] 4f^9` -> `[Xe] 4f^8 5d` (absolute energies
~ -12160 Hartree) that `Tr(H2^2 D D^T)` and its two partners each reach ~3.7e11 while the combination
that survives is of order 1 -- 9 of Float64's ~16 significant digits lost in that one subtraction,
leaving only 5-6 reliable digits in the printed variance, measured by comparing against the shifted
form below (agreement to 3.7e-8 absolute, i.e. about 6 digits, exactly as the lost-digit count
predicts). Writing `a = Tr(H1)/n1`, `b = Tr(H2)/n2` and `H1' = H1-a*I`, `H2' = H2-b*I`, the identity
`Tr((H+c*I)*A) = Tr(H*A) + c*Tr(A)` propagates through every trace above and the shift cancels
EXACTLY out of `varE` (algebra kept in the module's own validation script, not reproduced here);
`meanE` picks up the leftover constant `(b-a)`, which is itself an ordinary, unproblematic number.
The shifted matrices carry only the physically small energies, so no large intermediate ever forms.
A transitionArray::SuperConfigurations.TransitionArray is returned.JenaAtomicCalculator.SuperConfigurations.matrixElementCached — Method
SuperConfigurations.matrixElementCached(basis::Basis, r::Int64, s::Int64, nm::Nuclear.Model, grid::Radial.Grid, settings::AsfSettings, potential::Radial.Potential, cache::InteractionStrength.XLCache, grantCache::Dict{Tuple{Subshell,Subshell},Float64}) ... a private helper, EXACTLY Hamiltonian.matrixElement's own logic – the two-particle XL_Coulomb/XL_Breit terms already reuse cache across every CSF pair and are unchanged here – with its one-particle term routed through oneParticleIntegralCached instead of calling RadialIntegrals.GrantIab fresh every time. Kept as a LOCAL copy rather than a change to Hamiltonian.matrixElement itself, since that function is shared by the whole RAS/CI machinery and extending it is a larger, separate decision this module does not make for it – the fix here stays inside this module's own file. A value::Float64 is returned.
JenaAtomicCalculator.SuperConfigurations.oneParticleIntegralCached — Method
SuperConfigurations.oneParticleIntegralCached(a::Subshell, b::Subshell, orbitals::Dict{Subshell,Orbital}, nm::Nuclear.Model, grid::Radial.Grid, settings::AsfSettings, potential::Radial.Potential, cache::Dict{Tuple{Subshell,Subshell},Float64}) ... a private helper returning the SAME one-particle quantity Hamiltonian.matrixElement's own inner loop computes per coefficient – RadialIntegrals.GrantIab plus the QED local term when settings.qedModel asks for one – but MEMOIZED by the orbital-pair key (a,b). THIS IS THE FIX FOR PRIORITY ITEM 79. Measured 17-Oct-2026 on Co2+ 3d^7/3d^6 4p: across 400 sampled same-block CSF pairs, the SAME orbital pair recurred about 12 TIMES, because every CSF pair's one-particle coefficients can only ever name orbitals from the small, SHARED active set, while the number of CSF PAIRS grows as the square of the CSF count – so the redundancy grows with the configuration, not a constant. GrantIab alone was 82 % of the sampled cost (measured ~199 microseconds per call against ~12.5 for the angular coefficients feeding it), so caching IT specifically, by orbital pair rather than by CSF pair, is what changes the ORDER of the cost – unlike skipping zero-coupling CSF pairs, which the EOL solver's own register entry already found plateaus at a constant factor rather than vanishing. A value::Float64 is returned.
JenaAtomicCalculator.SuperConfigurations.varianceFromCsfMatrix — Method
SuperConfigurations.varianceFromCsfMatrix(conf::Configuration, orbitals::Dict{Subshell,Orbital}, nm::Nuclear.Model, grid::Radial.Grid, settings::AsfSettings, meanEnergy::Float64) ... to determine the (2J+1)-weighted variance of a configuration's level energies from the full CSF-pair Hamiltonian matrix, via Tr((H - meanEnergy*I)^2), WITHOUT diagonalizing it. THIS IS NOT YET THE CLOSED FORM this module's own docstring names as future work: it still touches every CSF PAIR (O(n^2) matrix elements), only the O(n^3) diagonalization is avoided. Pairs of CSFs in different J^P blocks are skipped outright rather than relied on to return zero, since the Hamiltonian's own J/parity selection rule makes them exactly zero by construction.
THE MEAN IS SUBTRACTED PER ELEMENT, BEFORE SQUARING -- NOT, as an earlier version did,
`Tr(H^2) - meanEnergy^2` AFTER the fact. Found 17-Oct-2026 on Dy3+ `[Xe] 4f^9` (meanEnergy ~
-12160 Hartree): `Tr(H^2)/den` and `meanEnergy^2` both carry 9 integer digits, Float64 keeps about
16 significant digits total, and their difference -- the true variance, of order 1 Hartree^2 --
needs 7-8 of those digits just to survive the subtraction. It did not: the result came out
NEGATIVE, -0.71 Hartree^2, a value no variance can honestly be. Subtracting `meanEnergy` from
the DIAGONAL of H before squaring (`Tr((H-meanEnergy*I)^2)`, algebraically IDENTICAL to the old
formula -- only `delta_rs`-weighted terms change) keeps every summand at the PHYSICAL scale of an
energy deviation from the mean, never forming the ~1.5e8 intermediate the cancellation fed on.
Verified byte-for-byte unchanged on every light-ion case already validated (where the old formula
was never wrong, only ever one accident away from being so). A value::Float64 (in Hartree^2) is
returned.