API: infrastructure
The modules JAC is built on: grids and orbitals, the nuclear model, the self-consistent field, the many-electron basis, and the tabulated data behind them. They are published in full because a user writing a script reaches for them directly – Nuclear.Model, Radial.Grid, AsfSettings – even though they carry no example files of their own (Rule 16 of CLAUDE.md).
Atomic states and bases
JenaAtomicCalculator.AtomicState.AbstractGreenApproach — Type
abstract type AtomicState.AbstractGreenApproach ... defines an abstract and a number of singleton types for approximating a many-electron Green function expansion for calculating second-order processes.
+ struct SingleCSFwithoutCI
... to approximate the many-electron multiplets (gMultiplet) for every chosen level symmetry by dealing with each CSF
independently, and without any configuration interaction. This is a fast but also very rough approximation.
+ struct CoreSpaceCI
... to approximate the many-electron multiplets (gMultiplet) by taking the electron-electron interaction between the
bound-state orbitals into account.
+ struct DampedSpaceCI
... to approximate the many-electron multiplets (gMultiplet) by taking the electron-electron interaction for all, the
bound and free-electron, orbitals into account but by including a damping factor e^{tau*r}, tau > 0 into the
electron densities rho_ab (r) --> rho_ab (r) * e^{tau*r}JenaAtomicCalculator.AtomicState.AbstractRasShellPolicy — Type
abstract type AtomicState.AbstractRasShellPolicy ... defines an abstract and a number of concrete types to decide WHICH new shells the next RAS layer introduces, given what the expansion already has (coreShells, fromShells, every earlier layer's own newShells). AtomicState.AbstractRasStoppingPolicy decides WHETHER another layer runs; this family decides WHAT it would contain if it did – a separate question, asked first. Like the stopping hierarchy, this one is deliberately small and meant to grow by adding a struct and one AtomicState.proposeNextShells method, never by changing the driver or an existing policy.
JenaAtomicCalculator.AtomicState.AbstractRasStoppingPolicy — Type
abstract type AtomicState.AbstractRasStoppingPolicy ... defines an abstract and a number of concrete types to decide whether another RAS layer should be PROPOSED, given the record of every layer run so far. A policy is read-only advice: it answers one question (stop, or go on) and says WHY, and it cannot abort a layer that is already running. The hierarchy is intentionally small and is meant to grow – a new stopping rule is a new struct plus one AtomicState.evaluateStoppingPolicy method, never a change to the driver that calls it, and never a change to any existing policy.
JenaAtomicCalculator.AtomicState.AbstractRepresentationType — Type
abstract type AtomicState.AbstractRepresentationType ... defines an abstract type and a number of data types to work with and distinguish different atomic representations; see also:
+ struct MeanFieldBasis ... to represent (and generate) a mean-field basis and, especially, a set of
(mean-field) orbitals.
+ struct MeanFieldMultiplet ... to represent (and generate) a mean-field multiplet, based on (mean-field) orbitals.
+ struct OneElectronSpectrum ... to represent (and generate) a one-electron spectrum for the mean-field
potential of refConfigs.
+ struct CiExpansion ... to represent (and generate) a configuration-interaction representation.
+ struct RasExpansion ... to represent (and generate) a restricted active-space representation.
+ struct GreenExpansion ... to represent (and generate) an approximate (many-electron) Green functions.JenaAtomicCalculator.AtomicState.CiExpansion — Method
AtomicState.CiExpansion() ... constructor for an 'empty' instance of a variable::AtomicState.CiExpansion, i.e. one with no orbitals, no excitations beyond the reference configurations and the default settings. It is also what AtomicState.Representation() is built from, so the zero-argument form of a representation depends on this one existing. A ciExpansion::AtomicState.CiExpansion is returned.
JenaAtomicCalculator.AtomicState.CiExpansion — Type
struct AtomicState.CiExpansion <: AbstractRepresentationType ... a struct to represent (and generate) a configuration-interaction representation.
+ applyOrbitals ::Dict{Subshell, Orbital}
+ excitations ::AtomicState.RasStep ... Excitations beyond refConfigs.
+ settings ::AtomicState.CiSettings ... Settings for the given CI expansionJenaAtomicCalculator.AtomicState.CiSettings — Method
AtomicState.CiSettings(settings::AtomicState.CiSettings; eeInteractionCI::Union{Nothing,AbstractEeInteraction}=nothing, levelSelectionCI::Union{Nothing,LevelSelection}=nothing)
... constructor for modifying the given CiSettings by 'overwriting' the explicitly selected parameters.
A `ciSettings::AtomicState.CiSettings` is returned.JenaAtomicCalculator.AtomicState.CiSettings — Method
AtomicState.CiSettings() ... constructor for setting the default values. A ciSettings::AtomicState.CiSettings is returned.
JenaAtomicCalculator.AtomicState.CiSettings — Type
struct AtomicState.CiSettings ... a struct for defining the settings for a configuration-interaction (CI) expansion.
+ eeInteractionCI ::AbstractEeInteraction ... Specifies the treatment of the e-e interaction.
+ levelSelectionCI ::LevelSelection ... Specifies the selected levels, if any.JenaAtomicCalculator.AtomicState.CombinedPolicy — Type
struct AtomicState.CombinedPolicy <: AtomicState.AbstractRasStoppingPolicy ... stops as soon as ANY of policies says to stop (a logical OR), and is the actual seam that keeps the hierarchy expandable: a brand-new policy type needs no change here, it simply becomes one more entry in somebody's list. A convergence rule alone, trusted without a cost ceiling and a hard layer count behind it, is exactly the silent over-trust this item must not build – so a CombinedPolicy such as CombinedPolicy([IncrementBelow(1.0e-4), CostCeiling(5000, 1800.), FixedLayerCount(6)]) is the recommended way to use this hierarchy, rather than any one policy alone.
+ policies ::Array{AtomicState.AbstractRasStoppingPolicy,1} ... the sub-policies, tested in order.JenaAtomicCalculator.AtomicState.CostCeiling — Type
struct AtomicState.CostCeiling <: AtomicState.AbstractRasStoppingPolicy ... refuses to propose a further layer once the LAST layer that actually ran already met or exceeded the given cost, in CSF count or wall time. This is a safety valve, not a convergence judgement, and it is deliberately phrased against the last MEASURED layer rather than a predicted next one, since the existing tryRun cost estimator is known to be off by 3-4x (reference_ras_practical_recipe) and no clean per-CSF cost law fits any case measured so far (reference_ras_cost_scaling).
+ maxCsf ::Int64 ... the CSF count a layer may not meet or exceed.
+ maxWallTime ::Float64 ... the wall time (seconds) a layer may not meet or exceed.JenaAtomicCalculator.AtomicState.FixedLayerCount — Type
struct AtomicState.FixedLayerCount <: AtomicState.AbstractRasStoppingPolicy ... stops once exactly n layers have run. This is the escape hatch that makes the automatic driver a strict superset of today's hand-built one: wrapping a fully-specified, hand-written layer list in FixedLayerCount(length(layers)) reproduces exactly the existing behaviour.
+ n ::Int64 ... the number of layers to run, reference layer included.JenaAtomicCalculator.AtomicState.GreenChannel — Method
AtomicState.GreenChannel() ... constructor for an empty instance of AtomicState.GreenChannel. A greenChannel::AtomicState.GreenChannel is returned.
JenaAtomicCalculator.AtomicState.GreenChannel — Type
struct AtomicState.GreenChannel ... defines a type for a single symmetry channel of an (approximate) Green (function) expansion.
+ symmetry ::LevelSymmetry ... Level symmetry of this part of the representation.
+ gMultiplet ::Multiplet ... Multiplet of (scattering) levels of this symmetry.JenaAtomicCalculator.AtomicState.GreenExpansion — Method
AtomicState.GreenExpansion() ... constructor for an empty instance of AtomicState.GreenExpansion. A greenExpansion::AtomicState.GreenExpansion is returned.
JenaAtomicCalculator.AtomicState.GreenExpansion — Type
struct AtomicState.GreenExpansion <: AbstractRepresentationType ... defines a type to keep an (approximate) Green (function) expansion that is associated with a given set of reference configurations.
+ approach ::AtomicState.AbstractGreenApproach ... Approach used to approximate the representation.
+ excitationScheme ::Basics.AbstractExcitationScheme ... Applied excitation scheme w.r.t. refConfigs.
+ levelSymmetries ::Array{LevelSymmetry,1} ... Total symmetries J^P to be included into Green expansion.
+ NoElectrons ::Int64 ... Number of electrons.
+ settings ::AtomicState.GreenSettings ... settings for the Green (function) expansion.JenaAtomicCalculator.AtomicState.GreenSettings — Method
AtomicState.GreenSettings(settings::AtomicState.GreenSettings; nMax::Union{Nothing,Int64}=nothing, lValues::Union{Nothing,Array{Int64,1}}=nothing, dampingTau::Union{Nothing,Float64}=nothing, printBefore::Union{Nothing,Bool}=nothing, levelSelection::Union{Nothing,LevelSelection}=nothing, scField::Union{Nothing,AbstractScField}=nothing)
... the standard JAC keyword copy-constructor.
A `greenSettings::AtomicState.GreenSettings` is returned.JenaAtomicCalculator.AtomicState.GreenSettings — Method
AtomicState.GreenSettings(nMax::Int64, lValues::Array{Int64,1}, dampingTau::Float64, printBefore::Bool, levelSelection::LevelSelection) ... backward-compatible five-argument constructor; the self-consistent field defaults to Basics.DFSField(), which is what generate(GreenExpansion, ...) used unconditionally before scField existed. Supply the sixth argument (or use the keyword constructor) whenever the Green space must match the potential of a surrounding computation – see the note in the struct docstring. A greenSettings::AtomicState.GreenSettings is returned.
JenaAtomicCalculator.AtomicState.GreenSettings — Method
AtomicState.GreenSettings() ... constructor for an empty instance of AtomicState.GreenSettings. A greenSettings::AtomicState.GreenSettings is returned.
JenaAtomicCalculator.AtomicState.GreenSettings — Type
struct AtomicState.GreenSettings ... defines a type for defining the details and parameters of the approximate Green (function) expansion.
+ nMax ::Int64 ... maximum principal quantum numbers of (single-electron)
excitations that are to be included into the representation.
+ lValues ::Array{Int64,1} ... List of (non-relativistic) orbital angular momenta for which
(single-electron) excitations are to be included.
+ dampingTau ::Float64 ... factor tau (> 0.) that is used to 'damp' the one- and two-electron
interactions strength: exp( - tau * r)
+ printBefore ::Bool ... True if a short overview is to be printed before.
+ levelSelection ::LevelSelection ... Specifies the selected levels, if any.
+ scField ::AbstractScField
... the self-consistent field in which the Green space is generated.
WHY THIS FIELD EXISTS (added 07-Aug-2026). A Green expansion is used as the INTERMEDIATE spectrum of a
second-order calculation, and gauge invariance there requires the intermediate states to be eigenstates
of the SAME one-body Hamiltonian as the initial and final states. Until now `generate(GreenExpansion,...)`
hardcoded `AsfSettings()` for the reference SCF and `Basics.DFSField(1.0)` for the mean potential, so a
user had NO way to match it to their own computation -- and a mismatch breaks gauge invariance
systematically without preventing either gauge from converging on its own, i.e. invisibly. Measured on
H 2s -> 1s two-photon decay, moving from a mismatched to a matched potential took the length gauge from
35 % error to 5.5 %.JenaAtomicCalculator.AtomicState.IncrementBelow — Method
AtomicState.IncrementBelow(tolerance::Float64; consecutive::Int64=2) ... constructor taking the tolerance positionally and consecutive as a keyword, defaulted to the safe value of 2. An policy::AtomicState.IncrementBelow is returned.
JenaAtomicCalculator.AtomicState.IncrementBelow — Type
struct AtomicState.IncrementBelow <: AtomicState.AbstractRasStoppingPolicy ... stops once consecutive layer increments IN A ROW fall below tolerance. A single small increment proves nothing on its own – reference_ras_practical_recipe measured a case where ONE frozen-looking increment understated the true remaining error by a factor of 100 – so this policy refuses to trust one data point; consecutive is 2 by default and should not be lowered to 1 without reading why.
+ tolerance ::Float64 ... the absolute increment (in Hartree) a layer must fall below.
+ consecutive ::Int64 ... how many layers in a row must fall below `tolerance` before stopping.JenaAtomicCalculator.AtomicState.IncrementRatioBelow — Type
struct AtomicState.IncrementRatioBelow <: AtomicState.AbstractRasStoppingPolicy ... stops once the newest layer increment's magnitude falls below fraction times the PREVIOUS layer's, i.e. a decaying-ladder test. Useful across different elements/ions without re-tuning an absolute tolerance per case, since Rule 21's own warning is that the increment is not an error bar in absolute terms – but its rate of decay is at least comparable between elements without rescaling.
+ fraction ::Float64 ... the ratio |increment_n| / |increment_(n-1)| must fall below.JenaAtomicCalculator.AtomicState.MeanFieldBasis — Method
AtomicState.MeanFieldBasis() ... constructor for an 'empty' instance of a variable::AtomicState.MeanFieldBasis, i.e. a mean-field basis built with the default MeanFieldSettings(). It completes the set of zero-argument forms of the representation types, so that each of them can be written down before its settings are chosen. A basis::AtomicState.MeanFieldBasis is returned.
JenaAtomicCalculator.AtomicState.MeanFieldBasis — Type
struct AtomicState.MeanFieldBasis <: AbstractRepresentationType ... a struct to represent (and generate) a mean-field orbital basis.
+ settings ::AtomicState.MeanFieldSettings ... Settings for the given mean-field orbital basisJenaAtomicCalculator.AtomicState.MeanFieldMultiplet — Method
AtomicState.MeanFieldMultiplet() ... constructor for an 'empty' instance of a variable::AtomicState.MeanFieldMultiplet, i.e. a mean-field multiplet built with the default MeanFieldSettings(). It completes the set of zero-argument forms of the representation types, so that each of them can be written down before its settings are chosen. A multiplet::AtomicState.MeanFieldMultiplet is returned.
JenaAtomicCalculator.AtomicState.MeanFieldMultiplet — Type
struct AtomicState.MeanFieldMultiplet <: AbstractRepresentationType ... a struct to represent (and generate) a mean-field orbital basis and multiplet.
+ settings ::AtomicState.MeanFieldSettings ... Settings for the given mean-field orbital basis and multiplet.JenaAtomicCalculator.AtomicState.MeanFieldSettings — Method
AtomicState.MeanFieldSettings(scField::AbstractScField) ... constructor from a field alone, keeping gridStopper = true. It exists so that the one-argument form every existing caller uses goes on meaning what it meant; a settings::MeanFieldSettings is returned.
JenaAtomicCalculator.AtomicState.MeanFieldSettings — Method
AtomicState.MeanFieldSettings(settings::AtomicState.MeanFieldSettings; scField::Union{Nothing,AbstractScField}=nothing, gridStopper::Union{Nothing,Bool}=nothing) ... the standard JAC keyword copy-constructor; a settings::MeanFieldSettings is returned.
JenaAtomicCalculator.AtomicState.MeanFieldSettings — Method
AtomicState.MeanFieldSettings() ... constructor for setting the default values. A meanFieldSettings::AtomicState.MeanFieldSettings is returned.
JenaAtomicCalculator.AtomicState.MeanFieldSettings — Type
struct AtomicState.MeanFieldSettings ... a struct for defining the settings for a mean-field basis (orbital) representation.
+ scField ::AbstractScField
... Specify the (mean) self-consistent field as DFSField() or HSField(); note that not all AbstractScField's
allowed here.
+ gridStopper ::Bool
... False to let `Bsplines.checkGridRepresentation` WARN instead of raising, so that deliberately
box-confined high-n orbitals can be generated. **Added 15-Oct-2026, and it was a real gap rather
than a convenience:** this struct carried `scField` alone, so the whole
`Representation`/`MeanFieldMultiplet` route could not express a PSEUDO-CONTINUUM intermediate set
at all -- and that is what kept `example-Dh.jl` branch (b) on a bound-only sum for months, giving
10.104 /s where the exact two-photon rate is 8.22906. The recipe that converges it (n_max ~ 100,
the grid guard relaxed, the box held fixed) had to be driven through an `Atomic.Computation`
instead. The default is TRUE, i.e. the guard raises as before, so no existing caller changes;
set it false only where the high-n states are MEANT to be box-confined stand-ins for the
continuum, and say so at the call site.JenaAtomicCalculator.AtomicState.OneElectronSettings — Method
AtomicState.OneElectronSettings(settings::AtomicState.OneElectronSettings; nMax::Union{Nothing,Int64}=nothing, lValues::Union{Nothing,Array{Int64,1}}=nothing, levelSelectionMean::Union{Nothing,LevelSelection}=nothing)
... constructor for modifying the given OneElectronSettings by 'overwriting' the explicitly selected parameters.
A `oneElectronSettings::AtomicState.OneElectronSettings` is returned.JenaAtomicCalculator.AtomicState.OneElectronSettings — Method
AtomicState.OneElectronSettings() ... constructor for setting the default values. A oneElectronSettings::AtomicState.OneElectronSettings is returned.
JenaAtomicCalculator.AtomicState.OneElectronSettings — Type
struct AtomicState.OneElectronSettings ... a struct for defining the settings for a one-electron spectrum.
+ nMax ::Int64 ... maximum principal quantum number.
+ lValues ::Array{Int64,1} ... l-values (partial waves) for which orbitals are to be generated.
+ levelSelectionMean ::LevelSelection ... Level(s) of the mean-field to generate the underlying atomic potentialJenaAtomicCalculator.AtomicState.OneElectronSpectrum — Method
AtomicState.OneElectronSpectrum() ... constructor for an 'empty' instance of a variable::AtomicState.OneElectronSpectrum, i.e. a one-electron spectrum built with the default OneElectronSettings(). It completes the set of zero-argument forms of the representation types, so that each of them can be written down before its settings are chosen. A spectrum::AtomicState.OneElectronSpectrum is returned.
JenaAtomicCalculator.AtomicState.OneElectronSpectrum — Type
struct AtomicState.OneElectronSpectrum <: AbstractRepresentationType ... a struct to represent (and generate) a one-electron spectrum for the mean-field potential of given levels from a set of reference configurations.
+ settings ::AtomicState.OneElectronSettings ... Settings for the given OneElectronSpectrumJenaAtomicCalculator.AtomicState.RasAutoSettings — Method
AtomicState.RasAutoSettings(stoppingPolicy::AtomicState.AbstractRasStoppingPolicy, shellPolicy::AtomicState.AbstractRasShellPolicy; layerTemplate::AtomicState.RasLayer=AtomicState.RasLayer(Shell[]), maxLayers::Int64=10) ... constructor taking the two policies positionally and the template/ceiling as keywords with safe defaults. A settings::AtomicState.RasAutoSettings is returned.
JenaAtomicCalculator.AtomicState.RasAutoSettings — Type
struct AtomicState.RasAutoSettings ... bundles the choices an automatic RAS ladder needs: WHICH shells to propose next, WHETHER to propose another layer at all, and a hard ceiling that applies no matter what either policy says.
+ stoppingPolicy ::AtomicState.AbstractRasStoppingPolicy ... decides whether another layer runs.
+ shellPolicy ::AtomicState.AbstractRasShellPolicy ... decides what it would contain if it did.
+ layerTemplate ::AtomicState.RasLayer ... the `se`/`de`/`treatment` to reuse for
every auto-proposed layer; its own `newShells` field is ignored, since the shell policy fills that in.
+ maxLayers ::Int64 ... a hard ceiling that ALWAYS applies,
independent of `stoppingPolicy`, so an automatic ladder can never run unbounded even if a
AtomicState.CombinedPolicy forgets a count-based term.JenaAtomicCalculator.AtomicState.RasCompleteShellPolicy — Type
struct AtomicState.RasCompleteShellPolicy <: AtomicState.AbstractRasShellPolicy ... proposes every l = 0, ..., n-1 of the next unused principal quantum number n – GRASP's own default layering convention, and the one every RAS example in this codebase has used by hand so far.
JenaAtomicCalculator.AtomicState.RasExpansion — Method
AtomicState.RasExpansion(symmetries::Array{LevelSymmetry,1}, NoElectrons::Int64, coreShells::Array{Shell,1}, fromShells::Array{Shell,1}, layers::Array{AtomicState.RasLayer,1}, settings::AtomicState.RasSettings) ... constructor for a variable::AtomicState.RasExpansion from a simplified, non-cumulative list of AtomicState.RasLayer's; internally translated into the equivalent Array{AtomicState.RasStep,1}. For each layer, only the newly-introduced shells need to be given: coreShells (always frozen, never excited from) and fromShells (the reference valence shells that single/double excitations originate from) stay the same for every layer; seTo/deTo accumulate fromShells plus every newShells seen so far (including the current layer). fromShells are optimized together with the FIRST layer's new shells (their one and only chance to vary, exactly as for a plain reference SCF), then frozen from the second layer onward, alongside every earlier layer's own newShells (never the current layer's). A rasExpansion::AtomicState.RasExpansion is returned.
JenaAtomicCalculator.AtomicState.RasExpansion — Method
AtomicState.RasExpansion() ... constructor for an 'empty' instance of the a variable::AtomicState.RasExpansion A rasExpansion::AtomicState.RasExpansion is returned.
JenaAtomicCalculator.AtomicState.RasExpansion — Type
struct AtomicState.RasExpansion <: AbstractRepresentationType ... a struct to represent (and generate) a restricted active-space representation.
+ symmetries ::Array{LevelSymmetry,1} ... Symmetries of the levels/CSF in the many-electron basis.
+ NoElectrons ::Int64 ... Number of electrons.
+ steps ::Array{AtomicState.RasStep,1} ... List of SCF steps that are to be done in this model
computation.
+ settings ::AtomicState.RasSettings ... Settings for the given RAS computationJenaAtomicCalculator.AtomicState.RasLayer — Method
AtomicState.RasLayer(newShells::Array{Shell,1}; se::Bool=true, de::Bool=true, treatment::Basics.AbstractQTreatment=Basics.Variational()) ... constructor for a variable::AtomicState.RasLayer with the given new shells and, by default, both single and double excitations enabled. A rasLayer::AtomicState.RasLayer is returned.
JenaAtomicCalculator.AtomicState.RasLayer — Type
struct AtomicState.RasLayer ... a struct to specify a single layer of a multi-layer restricted active-space computation in a simplified, non-cumulative form: only the shells that are NEW at this layer need to be given; the frozen and active shell sets of the equivalent AtomicState.RasStep are derived automatically layer by layer, see AtomicState.RasExpansion(..., layers::Array{RasLayer,1}, ...).
+ newShells ::Array{Shell,1} ... Shells introduced (as virtual/correlation shells) at this layer.
+ se ::Bool ... Include single excitations from the reference into all active
shells (up to and including this layer) if true.
+ de ::Bool ... Include double excitations from the reference into all active
shells (up to and including this layer) if true.
+ treatment ::Basics.AbstractQTreatment ... how this layer's configurations are treated; see
AtomicState.RasStep. Variational() by default, so a layered
expansion written before 11-Sep-2026 is unaffected.JenaAtomicCalculator.AtomicState.RasLayerVerdict — Type
struct AtomicState.RasLayerVerdict ... what one completed RAS layer is worth, in numbers a stopping or shell policy can read, modelled on SelfConsistent.ScfVerdict: advice about what has already happened, never a gate on it. It is built by the driver AFTER a layer has run and is never consulted while that layer is still being computed.
+ istep ::Int64 ... which layer this is; 1 is the reference layer, which carries no increment.
+ newShells ::Array{Shell,1} ... the shells this layer introduced, for the printed record.
+ csfCount ::Int64 ... size of this layer's CI space -- the cheap, reliable cost signal
(reference_ras_cost_scaling found no clean per-CSF law, so this stays a raw count rather than a derived cost).
+ wallTime ::Float64 ... seconds this layer took to run.
+ energy ::Float64 ... the lowest target-level energy at this layer.
+ increment ::Float64 ... `energy` minus the PREVIOUS layer's energy; `NaN` for the reference layer,
which has no previous layer to compare against. This is Rule 21's own quantity -- the one a policy must
look at, never the total.
+ scfVerdict ::Union{Nothing,SelfConsistent.ScfVerdict} ... this layer's own SCF verdict, so a policy that
wants the doubling-test drift, not only the increment, can read it; `nothing` for a layer treated to second
order, since that layer's orbitals are never optimized and no SCF verdict exists for it.
+ shapedBasis ::Union{Nothing,Basis} ... the refined, separate Q-space `Basis` a `RasStep.shapedTo`
layer built -- its own CSF space (the reference plus that layer's shaped excitation alone), with every
OTHER subshell's orbital the literal SAME object `priorMultiplet` already used, and the new shell(s)
tagged `Basics.CoreValenceCorrelationShape` and SCF-refined on this small space. `nothing` for every
ordinary layer. `energy` and `increment` above are NOT about this space -- they stay the ladder's own
P-progression, unchanged by a shaped layer, which is why this field exists separately rather than
folding Q's energy into them.
+ shapedPartition ::Union{Nothing,Hamiltonian.ShapeCrossingPartition} ... the second-order P/Q coupling
this shape-crossing layer is actually FOR -- `Hamiltonian.secondOrderShapeCrossingCorrection` applied
between `priorMultiplet` (P) and `shapedBasis`'s own multiplet (Q), biorthogonalized first. `nothing`
for every ordinary layer, and whenever `shapedBasis` is `nothing`.JenaAtomicCalculator.AtomicState.RasLimitedAngularMomentumPolicy — Type
struct AtomicState.RasLimitedAngularMomentumPolicy <: AtomicState.AbstractRasShellPolicy ... caps how far the active space reaches in l, INDEPENDENTLY of how far n climbs – the remedy for AtomicState.RasCompleteShellPolicy being "rather extreme" once n exceeds about 5 (at n=6 it would propose 6s,6p,6d,6f,6g,6h in one layer, mostly high-l partial waves far from anything the reference occupies, and reference_ras_practical_recipe measured that a layer of high-n, already-occupied-symmetry orbitals is both the hardest to converge and the least rewarding).
For the next unused `n`, this policy proposes only `l = 0, ..., min(n-1, lMaxRef + extraL)`, where
`lMaxRef` is the largest `l` occupied by `coreShells` or `fromShells`. So with `extraL = 2` on a
`3d^2` reference (`lMaxRef = 2`), layer `n=6` proposes only `6s,6p,6d,6f` -- `6g` and `6h` are never
opened, however high `n` goes, because they sit beyond `lMaxRef+extraL = 4`. The ladder keeps
climbing in `n` without ever again reaching for a new, likely-unrewarding high-`l` partial wave.
+ extraL ::Int64 ... how many `l`-values beyond the reference's own maximum may ever be opened.JenaAtomicCalculator.AtomicState.RasSettings — Method
AtomicState.RasSettings(set::AtomicState.RasSettings; levelsScf::Union{Nothing,Array{Int64,1}}=nothing, scfRoute::Union{Nothing,Basics.AbstractScfRoute}=nothing, accuracyScf::Union{Nothing,Float64}=nothing, eeInteractionCI::Union{Nothing,AbstractEeInteraction}=nothing, levelSelectionCI::Union{Nothing,LevelSelection}=nothing, freezing::Union{Nothing,Symbol}=nothing, maxIterationsScf::Union{Nothing,Int64}=nothing)
... constructor for modifying the given AtomicState.RasSettings by 'overwriting' the previously selected parameters; a
settings::AtomicState.RasSettings is returned.
IT ALSO REFUSES `maxIterationsScf` BY NAME, and that is the point of having it. `AsfSettings` retired the same field
into the routes and refuses the keyword with a message naming the replacement, so a caller is told what to write;
`RasSettings` carried it on as its SECOND POSITIONAL argument, so the one quantity had two spellings and only one of
them announced itself. A user who learned the new convention from the `AsfSettings` message and wrote it into a
`RasSettings` call got a `MethodError` about positional arguments instead -- which is what this refusal replaces.JenaAtomicCalculator.AtomicState.RasSettings — Method
AtomicState.RasSettings(levelsScf::Array{Int64,1}, scfRoute::Basics.AbstractScfRoute, accuracyScf::Float64, eeInteractionCI::AbstractEeInteraction, levelSelectionCI::LevelSelection) ... the five-argument form every caller written before 06-Oct-2026 uses; it keeps the freezing policy that was the only one available then, so no existing computation changes.
JenaAtomicCalculator.AtomicState.RasSettings — Method
AtomicState.RasSettings() ... constructor for setting the default values. A rasSettings::AtomicState.RasSettings is returned.
JenaAtomicCalculator.AtomicState.RasSettings — Type
struct AtomicState.RasSettings ... a struct for defining the settings for a restricted active-space computations.
+ levelsScf ::Array{Int64,1} ... Levels on which the optimization is carried out, BY INDEX.
Read only when `levelSelectionCI` is INACTIVE; when both are given, `levelSelectionCI` wins and the RAS
driver says so. Until 01-Sep-2026 this field was declared, documented and printed but NEVER READ (priority
item 22), so a user who wrote `RasSettings([1], ...)` to optimize a layer on the ground level alone
silently got an EOL functional over every level `levelSelectionCI` had selected -- thirteen of them in one
measured case -- while the printout confirmed the wrong belief.
PREFER `levelSelectionCI` with `configurations=`: selecting an EOL target by INDEX is unstable, because
the indices refer to the energy-sorted multiplet and a correlation configuration sinking below the
reference silently changes which levels are optimized.
+ scfRoute ::Basics.AbstractScfRoute ... the SCF route by which each RAS step is solved, carrying its own
iteration budget and whatever else that solver needs. **This replaced `maxIterationsScf::Int64` on 04-Oct-2026 and the
change is not cosmetic.** The old field was converted, one line deep in the driver, into
`Basics.RotationRoute(maxIterationsScf)` -- so a RAS ladder could name ONLY the rotation route and ONLY its iteration
count, while `RotationRoute` also carries `nVirtual` and `stepping`, `FockRoute` carries `unscaledOffDiagonal`, and the
route hierarchy exists precisely so that a computation may be repeated on a more expensive route when a cheaper one does
not converge. Four of the six things a route can say were unreachable from a RAS computation. Naming the route here makes
all of them reachable and gives the quantity ONE spelling, the same as `AsfSettings.scfRoute`.
+ accuracyScf ::Float64 ... convergence criterion for the SCF field. This stays a settings field
rather than moving into the route, exactly as in `AsfSettings`, and the split is deliberate: an iteration BUDGET is a
property of the solver -- a mean field converges in a handful of iterations where the rotation route needs thousands --
whereas a convergence TOLERANCE is a property of the answer the caller wants, and is the same question whichever solver
is asked.
+ eeInteractionCI ::AbstractEeInteraction ... logical flag to include Breit interactions.
+ levelSelectionCI ::LevelSelection ... Specifies the selected levels, if any; also the EOL target
of every step when active, and then takes precedence over `levelsScf`.
+ freezing ::Symbol ... WHICH ORBITALS A LAYER MAY STILL MOVE, one of
`:previousLayersFrozen` (the default), `:coreFrozen` or `:allFree`; an unrecognized symbol RAISES. These are
Rule 21's three freezing policies, and naming the policy is what makes a layer increment comparable between
runs -- so it belongs in the settings that are printed with the computation rather than in a script.
* `:previousLayersFrozen` ... every shell an earlier layer optimized is held, and only the shells this layer
introduces are varied. GRASP's default, and the safe one: the layer's space contains the previous layer's,
and with the earlier orbitals held it cannot help but descend.
* `:coreFrozen` ... only the `coreShells` of the expansion are held; everything else is released, so the
valence shells may relax against the correlation this layer adds.
* `:allFree` ... nothing is held. The richest policy and the most expensive.
**THE RELEASED POLICIES RUN IN TWO PHASES, and that is what makes them trustworthy.** A layer first WARMS its
new shells with the earlier ones frozen, and only then RELEASES them, starting the optimized-level solver from
the warm orbitals through `ManyElectron.StartFromPrevious`. Because the warming phase leaves a set that COVERS
the basis, the average-level pre-pass is then skipped, and so does not re-derive the inherited orbitals for the
configuration AVERAGE rather than for the level energy. (That skip follows from the COVERAGE and not from
`StartFromPrevious` alone; a handed-in set that leaves subshells uncovered would leave them hydrogenic, so
`SelfConsistent.averageLevelPrePass` pre-passes those alone with the handed-in ones frozen.)
Without that two-step entry a released layer begins far ABOVE the layer it sits on: measured on 43Ca+ [Ar] 4s
with 3s -> 5s,6s singles, 36.1 mHa above, which is more than the whole correlation effect being measured, and
the resulting layer increment had a BUDGET-DEPENDENT SIGN (+11.2, +5.9, +1.0 mHa at budgets 20, 60, 120).
Repaired, the same layer gives -0.013, -0.053, -0.063 mHa -- monotone, correctly signed, and saturating.
**WHAT THE RELEASE IS WORTH, measured on three ions with the same two-layer structure and `freezing` as the
only variable** -- a reference layer, then ONE correlation layer with singles and doubles, every box checked
adequate and every correlation orbital contracted into the valence region, so no grid confound:
ion reference CSFs frozen incr. allFree incr. deeper doubling test cost
Ca+ [Ar] 4s 5 -0.0234 mHa -0.0604 mHa +158 % 29.5 % / 7.3 % ~2.0x
C II 1s^2 2s^2 2p 41 -77.1587 mHa -80.4217 mHa +4.2 % 0.0001%/ 0.31% 1.65x
Ti III [Ar] 3d^2 2264 -150.8840 mHa -161.8682 mHa +7.3 % 0.025 % / 0.25% 1.83x
The release is deeper on every case above -- but **READ THE NEXT PARAGRAPH BEFORE CHOOSING IT, because that
advantage is almost entirely the release buying back something the REFERENCE layer was forbidden to do, and
it is far better not to forbid it.**
**WHERE THE CORE IS ALLOWED TO RELAX MATTERS MORE THAN THIS POLICY DOES, and earlier is better.** Isolated
07-Oct-2026 on Ti III [Ar] 3d^2 + 4s4p4d(SD), one code path, adaptive stop, `coreShells` the only variable:
layer 1 step 1 :previousLayersFrozen :allFree policy gap
core FROZEN -852.160048 -852.310901 (305 s) -852.321827 (526 s) 10.93 mHa
core FREE -852.176877 -852.327971 (321 s) -852.328019 (544 s) 0.048 mHa
Letting the core relax at the REFERENCE layer is worth **16.8 mHa** on step 1, and the best total improves by
**6.2 mHa** -- so no later freezing policy recovers what a frozen core costs: the best frozen-core run still
ends 6.2 mHa ABOVE the worst core-free one. And once the core has relaxed there, **this policy is worth
0.048 mHa, a factor 228 less than it appeared**, at which point `:previousLayersFrozen` is the right choice
because it is 1.7x faster.
**SO `:allFree` IS A REMEDY FOR A FROZEN-CORE REFERENCE, NOT A GENERAL IMPROVEMENT.** Declare `coreShells`
only when cost forces it; if it is forced, `:allFree` wins back about 11 mHa of the ~17 mHa given away.
The same ordering holds on C II, less sharply: the gap falls from 3.26 mHa to 0.61 mHa when its 1s is
released, a 1s having little to relax. It costs 1.65x to 1.83x rather than
the 2x two phases suggest, because the warm-up leaves the release a good start. Cross-checked under both
`stepping = :curvature` and `:newton`, so it is a property of the handover and not of the solver.
**AND A CLAIM MADE ON THE Ca+ CASE ALONE IS WITHDRAWN HERE:** that the released policy SATURATES in the
iteration budget while the frozen one does not. That is true only of Ca+. On both open-shell ions BOTH
policies converge and the FROZEN one converges better. **The argument for the release is its DEPTH, not its
convergence.**
**WHAT MAKES A LAYER HARD TO CONVERGE IS THE LAYER'S OWN SHELL STRUCTURE, not the ion's.** Ca+'s layer adds
5s and 6s -- high-n orbitals of the SAME symmetry as the occupied 4s, diffuse and nearly degenerate with it;
C II adds 3s,3p,3d and Ti III adds 4s,4p,4d, compact orbitals mostly in l channels the reference does not
occupy. Measured, the drift of the increment when the budget doubles: 0.0069 mHa for Ca+ against 0.0001 mHa
for C II, i.e. 69x more drift on a 3000x smaller increment. A layer of high-n orbitals in an
already-occupied symmetry is the hard case AND earns little; a layer opening new l channels is the easy case
AND earns the real correlation energy. Budget accordingly, and test it by DOUBLING the budget and comparing
the layer INCREMENT -- under about 10 % the layer is converged. That test replaces the "about twelve
iterations" rule of thumb, which is strongly Z-dependent (45:1 at Z = 92 against 7:1 at Z = 8) and so cannot
be carried between elements.JenaAtomicCalculator.AtomicState.RasSpectrumOrderedShellPolicy — Type
struct AtomicState.RasSpectrumOrderedShellPolicy <: AtomicState.AbstractRasShellPolicy ... for medium and heavy elements, where neither AtomicState.RasCompleteShellPolicy nor AtomicState.RasLimitedAngularMomentumPolicy is reliable, because both assume shells group cleanly by n – which stops holding once a real atomic potential, rather than a bare hydrogenic one, is involved. For a 3d^3 4s^2-type reference, the next worthwhile correlation orbitals are not "finish n=4, then start n=5" but something that may read 5s, 4p, 4d, 4f, ...: shells from DIFFERENT principal quantum numbers interleaved by where they actually sit, because screening and 3d/4s mixing move 4p, 4d, 4f and 5s out of their light-atom, hydrogenic order.
This policy answers the question numerically rather than combinatorially, reusing
AtomicState.OneElectronSpectrum -- generated once by the driver into `candidateOrbitals`, see
AtomicState.needsEnergySpectrum -- rather than inventing new orbital generation: for every partial
wave `l` present in `candidateOrbitals`, it finds the lowest-`n` shell of that `l` not already in the
ladder, ranks those one-candidate-per-`l` shells by their ACTUAL one-electron energy, and proposes
the `count` cheapest.
THIS IS THE ONE PLACE THIS HIERARCHY DOES SOMETHING GRASP'S OWN WORKFLOW NEVER HAS TO, AND IT IS
WORTH KNOWING WHY. GRASP's correlation virtuals are generated per `kappa` and referred to only by
their sequential index within that `kappa` -- "the 3rd d_5/2 virtual" -- never by a principal
quantum number, because once an orbital is correlated and polarized, the node-counting convention
that even DEFINES `n` for a hydrogenic function stops applying cleanly, so GRASP never has to decide
whether that 3rd virtual "is" 4d or 5d. JAC's RAS API cannot take that way out: `RasLayer.newShells`,
every `se/deFrom/To` list, `frozenShells` and this very policy's own candidates are all referred to
by name, because that is how a user reads and writes a RAS ladder. So where GRASP can simply ask its
spectrum for the next cheapest orbital of a given `kappa` and never decide what to call it, this
policy keeps names attached to a measured energy ordering that may cross `n`.
A diffuse, box-truncated state can rank artificially low in energy (Rule 12's territory), so this
policy inherits a risk the other two never face, since they never consult a computed energy at all --
its first real use on any one case is a judgement call for a human, not an automatic pass/fail.
+ count ::Int64 ... how many new shells to propose per layer.
+ spectrumSettings ::AtomicState.OneElectronSettings ... the candidate pool (nMax, lValues) the
driver generates, once, via the existing `Basics.generate(::AtomicState.OneElectronSpectrum, rep)`.JenaAtomicCalculator.AtomicState.RasStep — Method
AtomicState.RasStep(rasStep::AtomicState.RasStep; seFrom::Array{Shell,1}=Shell[], seTo::Array{Shell,1}=Shell[], deFrom::Array{Shell,1}=Shell[], deTo::Array{Shell,1}=Shell[], teFrom::Array{Shell,1}=Shell[], teTo::Array{Shell,1}=Shell[], qeFrom::Array{Shell,1}=Shell[], qeTo::Array{Shell,1}=Shell[], shapedTo::Array{Shell,1}=Shell[], frozen::Array{Shell,1}=Shell[], constraints::Array{String,1}=String[], treatment::Union{Nothing,Basics.AbstractQTreatment}=nothing, scfRoute::Union{Nothing,Basics.AbstractScfRoute}=nothing)
seFrom::Array{Shell,1}=Shell[], seTo::Array{Shell,1}=Shell[],
deFrom::Array{Shell,1}=Shell[], deTo::Array{Shell,1}=Shell[],
teFrom::Array{Shell,1}=Shell[], teTo::Array{Shell,1}=Shell[],
qeFrom::Array{Shell,1}=Shell[], qeTo::Array{Shell,1}=Shell[],
shapedTo::Array{Shell,1}=Shell[],
frozen::Array{Shell,1}=Shell[], constraints::Array{String,1}=String[],
treatment::Union{Nothing,Basics.AbstractQTreatment}=nothing,
scfRoute::Union{Nothing,Basics.AbstractScfRoute}=nothing
... constructor for modifying the given rasStep by specifying all excitations, frozen shells and
constraints optionally.
NOTE THAT `scfRoute` CANNOT BE CLEARED BACK TO `nothing` THROUGH THIS CONSTRUCTOR, since `nothing` is also how the
keyword says "leave this field alone" -- which is the price of the keyword-copy pattern and is the same for every other
field here. Build a fresh `RasStep()` to drop an override.
A `rasStep::AtomicState.RasStep` is returned.JenaAtomicCalculator.AtomicState.RasStep — Method
AtomicState.RasStep() ... constructor for an 'empty' instance of a variable::AtomicState.RasStep A rasStep::AtomicState.RasStep is returned.
JenaAtomicCalculator.AtomicState.RasStep — Type
struct AtomicState.RasStep ... specifies an individual step of a (relativistic) restricted active space computation for a set of levels. This struct comprises all information to generate the orbital basis and to perform the associated SCF and multiplet computations for a selected number of levels.
+ seFrom ::Array{Shell,1} ... Single-excitations from shells [sh_1, sh_2, ...]
+ seTo ::Array{Shell,1} ... Single-excitations to shells [sh_1, sh_2, ...]
+ deFrom ::Array{Shell,1} ... Double-excitations from shells [sh_1, sh_2, ...]
+ deTo ::Array{Shell,1} ... Double-excitations to shells [sh_1, sh_2, ...]
+ teFrom ::Array{Shell,1} ... Triple-excitations from shells [sh_1, sh_2, ...]
+ teTo ::Array{Shell,1} ... Triple-excitations to shells [sh_1, sh_2, ...]
+ qeFrom ::Array{Shell,1} ... Quadrupole-excitations from shells [sh_1, sh_2, ...]
+ qeTo ::Array{Shell,1} ... Quadrupole-excitations to shells [sh_1, sh_2, ...]
+ shapedTo ::Array{Shell,1} ... Which of this step's OWN *To shells get a separate,
independently-contracted `Basics.CoreValenceCorrelationShape` orbital rather than the ordinary
`Basics.SCFShape` -- see that type's own docstring. Empty (the default) leaves every shell this step
generates as `SCFShape`, exactly as before this field existed. When set: any OTHER shell this step's
own *To lists name (a core-valence DOUBLE needs the full valence+new-shell list to generate at all,
exactly as an ordinary second-order step already requires) must be in `frozenShells`, since this
step's own SCF re-optimizes only what is unfrozen and nothing may vary except the shaped shell(s);
and its `treatment` must not be `Basics.Variational()`: the refined, shaped orbital this step produces
is kept as a separate P/Q junction (`AtomicState.RasLayerVerdict.shapedBasis`) rather than merged into
the ladder's own running multiplet, since ordinary Slater-Condon CI assumes every subshell of a kappa
is mutually orthonormal, which a shaped realization of an existing label deliberately is not.
+ frozenShells ::Array{Shell,1} ... List of shells that are kept 'frozen' in this step.
+ constraints ::Array{String,1} ... List of Strings to define 'constraints/restrictions'
to the generated CSF basis.
+ scfRoute ::Union{Nothing,Basics.AbstractScfRoute} ... an SCF route for THIS step alone, or `nothing` to inherit
the ladder's `RasSettings.scfRoute`. `nothing` is the default and is what nearly every ladder wants. The override exists
because a ladder's steps are not alike: measured, a REFERENCE layer is converged by about twelve iterations while a
CORRELATION layer never converges at all -- it descends indefinitely with increments that grow -- so one budget for the
whole ladder cannot express both, and spending the correlation layer's budget on the reference one buys nothing. This
mirrors `treatment`, which is likewise a per-step policy rather than a ladder-wide one.
+ treatment ::Basics.AbstractQTreatment ... how the configurations this step generates are to be treated:
Basics.Variational() puts every one of them into the CI, which is
what a step has always done and remains the default, while
Basics.SecondOrder(promoteAbove, discardBelow) ranks each one by
the fraction of the wave function it carries and promotes, folds
in perturbatively or discards it accordingly.JenaAtomicCalculator.AtomicState.RasStoppingVerdict — Type
struct AtomicState.RasStoppingVerdict ... what a stopping policy concluded about whether a RAS ladder should propose another layer, in the same advisory spirit as SelfConsistent.ScfVerdict: it is read by the driver and PRINTED, never used to silently decide anything a human cannot see.
+ stop ::Bool ... whether the policy says to stop proposing further layers.
+ reason ::String ... one sentence naming WHY, printed verbatim; empty when `stop` is false.JenaAtomicCalculator.AtomicState.Representation — Method
AtomicState.Representation(wa::Bool) ... to return a default representation::AtomicState.Representation, which the keyword copy-constructor above then modifies; the argument wa is not read. The examples below show the typical use.
Example for the generation of a mean-field basis:
name = "Oxygen 1s^2 2s^2 2p^4 ground configuration"
grid = Radial.Grid(true)
nuclearM = Nuclear.Model(8.)
refConfigs = [Configuration("[He] 2s^2 2p^4")]
mfSettings = MeanFieldSettings()
Representation(name, nuclearM, grid, refConfigs, MeanFieldBasis(mfSettings) )AtomicState.Representation( ... example for the computation of a configuration-interaction (CI) expansion)
name = "Oxygen 1s^2 2s^2 2p^4 ground configuration"
grid = Radial.Grid(true)
nuclearM = Nuclear.Model(8.)
refConfigs = [Configuration("[He] 2s^2 2p^4")]
orbitals = wb[ResultKeys.MeanFieldBasis].orbitals # get a proper set of orbitals
ciSettings = CiSettings(true, false, Int64[], false, LevelSymmetry[] )
from = [Shell("2s")]
to = [Shell("2s"), Shell("2p")]
excitations = RasStep(RasStep(), seFrom=from, seTo=to, deFrom=from, deTo=to, frozen=[Shell("1s")])
Representation(name, nuclearM, grid, refConfigs, CiExpansion(orbitals, excitations, ciSettings) )AtomicState.Representation( ... example for the computation of a restricted-active-space (RAS) expansion)
name = "Beryllium 1s^2 2s^2 ^1S_0 ground state"
refConfigs = [Configuration("[He] 2s^2")]
rasSettings = RasSettings([1], Basics.RotationRoute(24), 1.0e-6, CoulombInteraction(), LevelSelection() )
from = [Shell("2s")]
frozen = [Shell("1s")]
to = [Shell("2s"), Shell("2p")]
step1 = RasStep(RasStep(), seFrom=from, seTo=deepcopy(to), deFrom=from, deTo=deepcopy(to),
frozen=deepcopy(frozen))
append!(frozen, [Shell("2s"), Shell("2p")])
append!(to, [Shell("3s"), Shell("3p"), Shell("3d")])
step2 = RasStep(step1; seTo=deepcopy(to), deTo=deepcopy(to), frozen=deepcopy(frozen))
append!(frozen, [Shell("3s"), Shell("3p"), Shell("3d")])
append!(to, [Shell("4s"), Shell("4p"), Shell("4d"), Shell("4f")])
step3 = RasStep(step2, seTo=deepcopy(to), deTo=deepcopy(to), frozen=deepcopy(frozen))
Representation(name, Nuclear.Model(4.), Radial.Grid(true), refConfigs,
RasExpansion(LevelSymmetry(0, Basics.plus), 4, [step1, step2, step3], rasSettings) )AtomicState.Representation( ... example for the computation of Green(function) expansion)
name = "Lithium 1s^2 2s ground configuration"
refConfigs = [Configuration("[He] 2s")]
levelSymmetries = [LevelSymmetry(1//2, Basics.plus), LevelSymmetry(3//2, Basics.plus)]
greenSettings = GreenSettings(5, [0, 1, 2], 0.01, true, false, Int64[])
Representation(name, Nuclear.Model(8.), Radial.Grid(true), refConfigs,
GreenExpansion( AtomicState.DampedSpaceCI(), Basics.DeExciteSingleElectron(),
levelSymmetries, 3, greenSettings) )
Either example is adapted by overwriting the parameters that matter for the case at hand.JenaAtomicCalculator.AtomicState.Representation — Method
AtomicState.Representation(name::String, nuclearModel::Nuclear.Model, grid::Radial.Grid, refConfigs::Array{Configuration,1}, repType::AbstractRepresentationType; orbitalSource::Basics.AbstractOrbitalSource=Basics.SeparateOrbitals()) ... the five-argument constructor, which is how a representation has always been written down and goes on meaning exactly what it meant: the generator runs its own SCF on refConfigs. The sixth field is reached by the keyword, so that a caller who holds an orbital set already – the one case where a second-order amplitude is valid at all – can hand it over without the positional form. A rep::AtomicState.Representation is returned.
orbitals = res[ResultKeys.MeanFieldMultiplet].levels[1].basis.orbitals
rep = Representation(name, nm, grid, [Configuration("1s"), Configuration("2s"), Configuration("2p")],
MeanFieldMultiplet(MeanFieldSettings()); orbitalSource = Basics.GivenOrbitals(orbitals) )JenaAtomicCalculator.AtomicState.Representation — Method
AtomicState.Representation(name::String, nuclearModel::Nuclear.Model, refConfigs::Array{Configuration,1}, repType::AbstractRepresentationType; printout::Bool=true, orbitalSource::Basics.AbstractOrbitalSource=Basics.SeparateOrbitals()) ... constructor for which NO grid is given, so that the radial box is derived from the REFERENCE configurations by Basics.recommendedGrid; a rep::AtomicState.Representation is returned.
THE REFERENCE CONFIGURATIONS ARE THE RIGHT THING TO SIZE THE BOX FROM, and the alternative -- handing
the estimate every configuration the expansion will contain -- is actively wrong. The estimate reads a
shell by its (n,l) and cannot see the ROLE it plays: a spectroscopic 3s, occupied in a real 1s^2 2s 3s
state, is diffuse and is bound by its own ionization potential, whereas a CORRELATION 3s added to
1s^2 2s^2 is never occupied, describes the short-range correlation hole, and contracts onto the valence
region. Same quantum numbers, extent differing by an order of magnitude. Fed the correlation layers of
a beryllium RAS expansion, the estimate returns 66 a.u. where the reference alone asks 20.5, and a box
that large starves the fixed B-spline basis precisely on the high-n orbitals the layers introduce.
MEASURED on a three-layer beryllium expansion (reference, +2p, +3s3p3d) with a full EOL optimisation per
layer, one grid per run:
box sized from rbox final energy dE(layer 3 - layer 2)
refConfigs 20.9 -14.61925410 -0.000135
all shells 66.7 -14.61911933 -0.001730
Radial.Grid(true) 614 -14.61805822 +0.001205
The reference-sized box gives the LOWEST energy, which at fixed layer structure is the variational
criterion that decides this. The uncorrelated first layer is box-independent to eight digits across
that whole range, so nothing is being traded away. And the layer-to-layer differences are not
comparable across grids at all -- the last column changes sign, and a correlation layer that RAISES the
energy is not physics -- so a layer difference should never be quoted without stating the grid.
The correlation orbitals are still checked, not merely assumed to fit: Bsplines.checkOrbitalBox runs on
the converged orbitals of every layer and reports if any of them reaches the wall.
+ name ::String ... name of the representation.
+ nuclearModel ::Nuclear.Model ... nuclear model.
+ refConfigs ::Array{Configuration,1} ... reference configurations, which set the box.
+ repType ::AbstractRepresentationType ... the expansion to be generated.JenaAtomicCalculator.AtomicState.Representation — Method
AtomicState.Representation() ... constructor for an 'empty' instance of the a variable::AtomicState.Representation A representation::AtomicState.Representation is returned.
JenaAtomicCalculator.AtomicState.Representation — Type
struct AtomicState.Representation ... a struct for defining an atomic state representation. Such representations often refer to approximate wave function approximations of one or several levels but may concern also a mean-field basis (for some multiplet of some given configurations) or Green functions, etc.
+ name ::String ... to assign a name to the given model.
+ 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} ... List of references configurations, at least 1.
+ repType ::AbstractRepresentationType ... Specifies the particular representation.
+ orbitalSource ::Basics.AbstractOrbitalSource
... says WHICH one-electron orbital set the representation is generated on. `SeparateOrbitals()` is the default and is what JAC has
always done: the generator runs its own SCF on `refConfigs`. `GivenOrbitals(orbitals)` instead hands the generator a set the
CALLER already holds, and every multiplet of the representation is then a CI on it, built by
`Hamiltonian.performCIwithFrozenOrbitals` with no further orbital optimization.
WHY IT IS HERE AS WELL AS ON `Atomic.Computation` (added 05-Nov-2026). An explicit SECOND-ORDER amplitude is valid only
on ONE orthonormal set, because `ManyElectron.matrixElement_HminusE` drops the overlap term `-E <r|s>`, which vanishes
identically only then. `Atomic.Computation` has carried `orbitalSource` since 02-Nov-2026, so the PROCESS half of such a
computation could be put on one set -- but its Green space is a `Representation`, which could not be, and a caller who
wanted both halves consistent had to leave the `generate` route and call `Hamiltonian.performCIwithFrozenOrbitals` by
hand. That is what every second-order harness in `tools/` and both second-order branches of `examples/example-Dj.jl`
did. Both halves are now reachable through the ordinary route.
ONLY `SeparateOrbitals()` AND `GivenOrbitals(...)` MEAN ANYTHING HERE. A representation has no initial/final pair, so
`InitialStateOrbitals()` and `FinalStateOrbitals()` have nothing to refer to, and `Basics.generate` raises on them
rather than quietly picking one of the two. Not every representation can honour a given set either -- one whose whole
purpose is to OPTIMIZE orbitals cannot -- and those generators raise as well; see `Basics.generate` for which do what.JenaAtomicCalculator.AtomicState.collectLadderShells — Method
AtomicState.collectLadderShells(coreShells::Array{Shell,1}, fromShells::Array{Shell,1}, layersSoFar::Array{RasLayer,1}) ... gathers every shell that the RAS ladder has already used – the core, the reference valence, and the new shells of each layer built so far – so that a shell policy can exclude them from what it proposes next. A shells::Array{Shell,1} is returned, with duplicates removed and the order of first appearance kept. This is plumbing shared by every concrete shell policy rather than something a caller builds or inspects, and it is therefore not exported; a shell present anywhere in the ladder is never proposed a second time by any policy.
JenaAtomicCalculator.AtomicState.evaluateStoppingPolicy — Method
AtomicState.evaluateStoppingPolicy(policy::AtomicState.CombinedPolicy, history::Array{AtomicState.RasLayerVerdict,1}) ... tests every sub-policy in order and stops on the first one that does, carrying its reason forward. A verdict::AtomicState.RasStoppingVerdict is returned.
JenaAtomicCalculator.AtomicState.evaluateStoppingPolicy — Method
AtomicState.evaluateStoppingPolicy(policy::AtomicState.CostCeiling, history::Array{AtomicState.RasLayerVerdict,1}) ... stops once the last layer's own csfCount or wallTime meets or exceeds the ceiling. A verdict::AtomicState.RasStoppingVerdict is returned.
JenaAtomicCalculator.AtomicState.evaluateStoppingPolicy — Method
AtomicState.evaluateStoppingPolicy(policy::AtomicState.FixedLayerCount, history::Array{AtomicState.RasLayerVerdict,1}) ... stops once length(history) >= policy.n. A verdict::AtomicState.RasStoppingVerdict is returned.
JenaAtomicCalculator.AtomicState.evaluateStoppingPolicy — Method
AtomicState.evaluateStoppingPolicy(policy::AtomicState.IncrementBelow, history::Array{AtomicState.RasLayerVerdict,1}) ... stops once the last policy.consecutive layers all have abs(increment) < policy.tolerance. A verdict::AtomicState.RasStoppingVerdict is returned.
JenaAtomicCalculator.AtomicState.evaluateStoppingPolicy — Method
AtomicState.evaluateStoppingPolicy(policy::AtomicState.IncrementRatioBelow, history::Array{AtomicState.RasLayerVerdict,1}) ... stops once abs(history[end].increment) / abs(history[end-1].increment) < policy.fraction. A verdict::AtomicState.RasStoppingVerdict is returned.
JenaAtomicCalculator.AtomicState.evaluateStoppingPolicy — Function
AtomicState.evaluateStoppingPolicy(policy::AtomicState.AbstractRasStoppingPolicy, history::Array{AtomicState.RasLayerVerdict,1}) ... asks policy whether the ladder recorded in history (oldest first, one entry per layer already run) should stop here. A verdict::AtomicState.RasStoppingVerdict is returned; see the concrete policies for what each one actually tests.
JenaAtomicCalculator.AtomicState.needsEnergySpectrum — Method
AtomicState.needsEnergySpectrum(policy::AtomicState.AbstractRasShellPolicy) ... whether policy needs a precomputed, named one-electron spectrum to propose shells. Defaults to false, so a new, purely combinatorial policy needs no change here; a new policy that DOES read energies overrides this method, the same one-method-to-add discipline as the rest of this hierarchy. A value::Bool is returned.
JenaAtomicCalculator.AtomicState.needsEnergySpectrum — Method
AtomicState.needsEnergySpectrum(policy::AtomicState.RasSpectrumOrderedShellPolicy) ... always true – this policy cannot propose anything without the generated candidate spectrum. A value::Bool is returned.
JenaAtomicCalculator.AtomicState.proposeNextShells — Method
AtomicState.proposeNextShells(policy::AtomicState.RasCompleteShellPolicy, coreShells::Array{Shell,1}, fromShells::Array{Shell,1}, layersSoFar::Array{AtomicState.RasLayer,1}, candidateOrbitals::Dict{Subshell,Orbital}) ... proposes the complete next principal shell, n = 1 + maximum(n of every shell already in the ladder). candidateOrbitals is ignored. An Array{Shell,1} is returned.
JenaAtomicCalculator.AtomicState.proposeNextShells — Method
AtomicState.proposeNextShells(policy::AtomicState.RasLimitedAngularMomentumPolicy, coreShells::Array{Shell,1}, fromShells::Array{Shell,1}, layersSoFar::Array{AtomicState.RasLayer,1}, candidateOrbitals::Dict{Subshell,Orbital}) ... proposes the next unused n's shells with l capped at lMaxRef + policy.extraL, as described in the struct's own docstring. candidateOrbitals is ignored. An Array{Shell,1} is returned.
JenaAtomicCalculator.AtomicState.proposeNextShells — Method
AtomicState.proposeNextShells(policy::AtomicState.RasSpectrumOrderedShellPolicy, coreShells::Array{Shell,1}, fromShells::Array{Shell,1}, layersSoFar::Array{AtomicState.RasLayer,1}, candidateOrbitals::Dict{Subshell,Orbital}) ... ranks the lowest-n unused shell of every partial wave present in candidateOrbitals by its actual one-electron energy there, and proposes the policy.count cheapest, as described in the struct's own docstring. An Array{Shell,1} is returned, shorter than policy.count once the candidate pool itself is exhausted, and empty once nothing more can be proposed from it.
JenaAtomicCalculator.AtomicState.proposeNextShells — Function
AtomicState.proposeNextShells(policy::AtomicState.AbstractRasShellPolicy, coreShells::Array{Shell,1}, fromShells::Array{Shell,1}, layersSoFar::Array{AtomicState.RasLayer,1}, candidateOrbitals::Dict{Subshell,Orbital}) ... asks policy which shells the NEXT layer should introduce; candidateOrbitals is the empty dict for a policy that does not need one (see AtomicState.needsEnergySpectrum). An Array{Shell,1} is returned, which may be empty if the policy has nothing left to propose – an empty proposal is read by the driver as "stop", independent of whatever the stopping policy says, since there is nothing left to run.
JenaAtomicCalculator.AtomicState.sizeRasStep — Method
AtomicState.sizeRasStep(refConfigs::Array{Configuration,1}, symmetries::Array{LevelSymmetry,1}, step::AtomicState.RasStep; printout::Bool=true) ... counts what a RAS step would cost BEFORE any of it is run, so that a layer can be judged against the machine it is meant to run on. Only the CSF expansion is built – no orbitals, no SCF, no angular coefficients – so this is seconds even for a layer that would take hours. A NamedTuple (nCsf, nSub, lMax, blocks, sumN2, maxN2, blockShare) is returned.
WHAT IT REPORTS, AND WHY NOT MORE. Everything here is either an exact COUNT or a RATIO of two counts, and
that restraint is deliberate. Everything an EOL/RAS layer builds per CSF PAIR lives inside one symmetry
block, so the pair work is `sum_b n_b^2` over the blocks and NOT `nCsf^2`; with the stores of all blocks
resident, as they are today, that sum is what is paid, while a route holding ONE block at a time would pay
`max_b n_b^2` instead. Both are counted here, and `blockShare = max_b n_b^2 / sum_b n_b^2` is what such a
route would save -- 31 % on a Ti III layer of 25 085 CSFs, measured 14-Sep-2026.
**A RATIO IS QUOTED WHERE AN ABSOLUTE FIGURE IS NOT, BECAUSE THE UNKNOWN CONSTANT CANCELS IN IT.** Four peak-RSS
anchors on Ti III layers with 3p opened -- 887 CSFs at 1.647 GB, 3 167 at 2.149, 11 298 at 12.784, 25 085 at
29.73 -- are fitted by NO law in the CSF count alone: the space-dependent cost per CSF runs 1.7e-4, 2.1e-4,
1.0e-3, 1.1e-3 GB, a fivefold jump between the second and third and then flat, because those four are not four
sizes of one thing but layers that add 4p, then 4d, then 4f. Two successive fitted laws disagreed by 24x in
slope for exactly that reason. So the anchors are printed as MEASUREMENTS to interpolate between, and this
routine does not pretend to a law it does not have.
THE TWO DESIGN LEVERS IT IS MEANT TO INFORM, both measured rather than argued:
- the angular coefficient count per CSF is set mainly by l, at roughly 2.7x per step -- about 55 entries per
CSF for p, 130-172 for d, 340-389 for f -- and grows with the subshell count as well, so `lMax` and `nSub`
are reported beside the CSF count;
- CONCENTRATING the open electrons beats splitting them: 3d^5 gives 37 CSFs and 6 363 entries against
3p^3 3d^2 with 141 and 33 545, a factor 5.3 for the same five open-shell electrons.
AND THE J DISTRIBUTION IS NOT A LEVER, though it looks like one in the table below: it follows from the
configurations and the angular coupling and is not chosen. The only control there is which symmetries are
asked for at all, which drops whole blocks.JenaAtomicCalculator.AtomicState.tryRun — Method
AtomicState.tryRun(rep::AtomicState.Representation; nSample::Int64=2000, printout::Bool=true) ... a TRY RUN of a RAS ladder: for every step it reports what the production job would cost in memory and in time, WITHOUT running any of it, so that a ladder can be discussed and decided before a machine is committed to it. An Array{NamedTuple,1}, one entry per step, is returned.
WHY IT TAKES THE REPRESENTATION AND NOT A SETTINGS FLAG. It is handed THE VERY OBJECT that `generate`
would be handed, so the estimate cannot describe a different calculation from the production run -- which
is the one advantage a `tryRun` field in `AsfSettings` would have had, obtained here without any of its
costs. A flag there would have to make `performSCF` return something other than a `Multiplet` (a fake one,
or `nothing`, or a union every caller must then handle); `AsfSettings` is threaded through every module,
so a stray `true` left in a copy-constructor would silently produce no physics everywhere and look like a
convergence failure; and "estimate instead of compute" is a verb, not a property of the Hamiltonian. With
a separate entry point there is no flag to default, and the production path is untouched.
HOW THE NUMBERS ARE OBTAINED -- COUNTED WHERE POSSIBLE, SAMPLED WHERE NOT. The CSF expansion of each step
is generated (cheap: no orbitals, no SCF) and its symmetry blocks are counted exactly. Everything an
EOL/RAS step builds per CSF PAIR lives inside one block, so the pair work is `sum_b n_b^2` and NOT
`nCsf^2`; with the stores of all blocks resident, as they are today, that sum is what is paid, while a
route holding one block at a time would pay `max_b n_b^2`. Those are exact. The only unmeasured quantity
is the cost of ONE pair, and that is SAMPLED: `nSample` pairs are drawn at RANDOM from each block and
their angular coefficients actually computed, on this system's own shells and occupations.
RANDOM PAIRS, NOT A CONTIGUOUS SUB-BLOCK, AND THE DIFFERENCE MATTERS. Cost per pair FALLS as a block grows
-- measured 14-Sep-2026, 61.5 coefficients per pair at 3d^2 against 29.1 at 3d^5 -- because most pairs of
a large block are far apart in excitation and carry nothing at all (61 % were empty in one measured
block). A contiguous subset over-samples the near-diagonal pairs and would over-predict; a random draw
samples the true distribution, so the mean is unbiased. The scatter over the sample is reported beside the
estimate, since 60 % of draws returning zero makes a small sample noisy.
WHAT IS SOLID AND WHAT IS NOT. The per-ITERATION figures rest on exact counts times a measured per-pair
cost, and are the trustworthy part. The TOTAL needs the iteration count, which is genuinely
unpredictable -- so `maxIterationsScf` from the ladder's own settings is printed as the multiplier it is,
and the total is given as "up to", not as a forecast.
AND THE ITERATION BUDGET IS PRINTED AS A DIAL, because for a large open-shell system it may be the only
one left to turn. The cost is linear in it, and the rotation route descends MONOTONICALLY, so a run
stopped early returns a variational UPPER BOUND on the energy: the orbitals are less converged, not
wrong. Trading convergence for feasibility is therefore a legitimate choice, and the row exists so that
the choice can be made on numbers -- "60 iterations is 22 h but 15 is 5 h" -- rather than discovered
after a job has been queued.Default settings and units
JenaAtomicCalculator.Defaults.convertUnits — Method
Defaults.convertUnits(sa::String, wa::Float64) ... converts one value from one format/unit into another one; the keystring sa selects the conversion from the list below, and the return value is given with it.
("cross section: from atomic to predefined unit", value::Float64)or("cross section: from atomic", value::Float64)... to convert an cross section value from atomic to the predefined cross section unit; a Float64 is returned.("cross section: from barn to atomic unit", value::Float64)... to convert an cross section value from barn atomic section unit; a Float64 is returned.("cross section: from atomic to barn", value::Float64)or("cross section: from atomic to Mbarn", value::Float64)or("cross section: from atomic to cm^2", value::Float64)... to convert an energy value from atomic to the speficied cross section unit; a Float64 is returned.("cross section: from predefined to atomic unit", value::Float64)or("cross section: to atomic", value::Float64)... to convert a cross section value from the predefined to the atomic cross section unit; a Float64 is returned.("Einstein B: from atomic", value::Float64)... to convert a Einstein B coefficient from atomic to the speficied energy units; a Float64 is returned.("density: from [g/cm^3] to atomic", value::Float64)... to convert a mass density from [g/cm^3] to atomic units [u/a_o^3]; a Float64 is returned.("energy-diff. cross section: from atomic to predefined unit", value::Float64)or("energy-diff. cross section: from atomic", value::Float64)... to convert an energy-diff. cross section value from atomic to the predefined energy-diff. cross section unit; a Float64 is returned.("energy: from atomic to eV", value::Float64)or("energy: from atomic to Kayser", value::Float64)or("energy: from atomic to Hz", value::Float64)or("energy: from atomic to Angstrom", value::Float64)or("energy: from atomic to Ws", value::Float64)... to convert an energy value from atomic to the speficied energy unit; a Float64 is returned.("energy: from predefined to atomic unit", value::Float64)or("energy: to atomic", value::Float64)... to convert an energy value from the predefined to the atomic energy unit; a Float64 is returned.("energy: from eV to atomic", value::Float64)... to convert an energy value from eV to the atomic energy unit; a Float64 is returned.("energy: from wavelength [nm] to atomic", value::Float64)... to convert a wavelength [nm] to the atomic energy unit; a Float64 is returned.("intensity: from W/cm^2 to atomic", value::Float64)... to convert the intensity [in W/cm^2] to the atomic intensity unit; a Float64 is returned.("kinetic energy to wave number: atomic units", value::Float64)... to convert a kinetic energy value (in a.u.) into a wave number k (a.u.); a Float64 is returned.("kinetic energy to wavelength: atomic units", value::Float64)... to convert a kinetic energy value (in a.u.) into a wavelength (a.u.); a Float64 is returned.("length: from fm to atomic", value::Float64)... to convert a length value (in fm) into a.u.; a Float64 is returned.("length: from atomic to fm", value::Float64)or("length: from atomic to cm", value::Float64)... to convert a length value (in Bohr's a.u.) to the speficied length unit; a Float64 is returned.("moment: from nuclear magneton to atomic", value::Float64)... to convert a value in mu_nuc into a.u.; a Float64 is returned.("moment: from nuclear magneton x fm^2 to atomic", value::Float64)... to convert a value in [mu_nuc x fm^2] into a.u.; a Float64 is returned.("rate: from atomic to predefined unit", value::Float64)or ("rate: from atomic", value::Float64) ... to convert a rate value from atomic to the predefined rate unit; a Float64 is returned.("rate: from atomic to 1/s", value::Float64)... to convert an rate value from atomic to the speficied rate unit; a Float64 is returned.("rate: from predefined to atomic unit", value::Float64)or `("rate: to atomic", value::Float64)'... to convert a rate value from the predefined to the atomic rate unit; a Float64 is returned.
("strength: from atomic to predefined unit", value::Float64)or ("strength: from atomic", value::Float64) ... to convert a (resonance) strength value from atomic to the predefined rate unit; a Float64 is returned.("time: from atomic to predefined unit", value::Float64)or ("time: from atomic", value::Float64) ... to convert an time value from atomic to the predefined time unit; a Float64 is returned.("time: from atomic to sec", value::Float64)or("time: from atomic to fs", value::Float64)' or("time: from atomic to as", value::Float64)` ... to convert a time value from atomic to the speficied time unit; a Float64 is returned.("time: from predefined to atomic unit", value::Float64)or `("time: to atomic", value::Float64)' ... to convert a time value from the predefined to the atomic time unit; a Float64 is returned.("temperature: from Kelvin to (Hartree) units", value::Float64)... to convert a temperature in Kelvin into atomic (Hartree) units; a Float64 is returned.("temperature: from atomic to Kelvin", value::Float64)... to convert an atomic (energy) unit into Kelvin; 1 Hartree = 315774.64 K; a Float64 is returned.("wave number to total electron energy: atomic units", value::Float64)... to convert a wavenumber (a.u.) into the total electron energy, including the rest energy; a Float64 is returned.("wave number to kinetic energy: atomic units", value::Float64)... to convert a wavenumber (a.u.) into the kinetic energy; a Float64 is returned.
JenaAtomicCalculator.Defaults.convertUnits — Method
Defaults.convertUnits(sa::String, values::Array{Float64,1}) ... to apply the same conversion as Defaults.convertUnits(sa::String, wa::Float64), and for the same keystrings, to a whole list of values at once; a newValues::Array{Float64,1} of the same length is returned.
JenaAtomicCalculator.Defaults.getDefaults — Method
Defaults.getDefaults(sa::String, n_max::Int64) ... to give an ordered list of shells or subshells up to the (maximum) principal number n_max; the keystring sa selects which of the two, as below.
("ordered shell list: non-relativistic", n_max::Int64)... to give an ordered list of non-relativistic shells::Array{Shell,1} up to the (maximum) principal number n_max.("ordered subshell list: relativistic", n_max::Int64)... to give an ordered list of relativistic subshells::Array{Subshell,1} up to the (maximum) principal number n_max. An Array{Shell,1} or an Array{Subshell,1}, depending on the keystring, is returned.
JenaAtomicCalculator.Defaults.getDefaults — Method
Defaults.getDefaults(sa::String) ... gives/supplies different information about the (present) framework of the computation or about some given data; cf. Defaults.setDefaults().
("alpha")or("fine-structure constant alpha")... to get the (current) value::Float64 of the fine-structure constant alpha.("electron mass: kg")or("electron mass: amu")... to get the (current) value::Float64 of the electron mass in the specified unit.("framework")... to give the (current) setting::String of the overall framework.("electron rest energy")or("mc^2")... to get the electron rest energy.("electron g-factor")... to give the electron g-factor g_s = 2.00232.("nuclear: charge")or("nuclear: model")... to get the nuclear charge or model, if it has been set before.("unit: energy")or("unit: cross section")or("unit: rate")or("unit: strength")or("unit: time")... to get the corresponding (user-defined) unit::String for the current computations.("standard grid")... to get the (current standard) grid::Array{Float64,1} to which all radial orbital functions usually refer.("speed of light: c")... to get the speed of light in atomic units.("mass: muon")... to get the muon mass in atomic units, i.e. in units of the electron mass.("summary flag/stream")... to get the logical flag and stream for printing a summary file; a tupel (flag, iostream) is returned.
JenaAtomicCalculator.Defaults.selectWignerMethod — Method
Defaults.selectWignerMethod(name::Symbol) ... to switch how the Wigner symbols are evaluated, from the short name used by the setDefaults keystrings: :exact, :floating or :gsl. The choice itself is DISPATCHED on a singleton type inside AngularMomentum; this routine only turns a keystring into that type. Nothing is returned.
JenaAtomicCalculator.Defaults.setDefaults — Method
Defaults.setDefaults(sa::String, nm::Any) ... sets a global default that carries an arbitrary object; nothing is returned. The single keystring is "nuclear: model", whose value is a Nuclear.Model used where none is given explicitly. The argument is typed Any rather than Nuclear.Model only because this module is compiled before that type exists; it is not an invitation to store something else. An unrecognised keystring raises and names itself.
JenaAtomicCalculator.Defaults.setDefaults — Method
Defaults.setDefaults(sa::String, Znuc::Float64, wa::Array{Float64,1}) ... to (re-) define the lambda-C damped overlap integrals of the lowest kappa-orbitals [ wa1s1/2, wa2p1/2, wa2p3/2, wa3d3/2, wa3d5/2 ] for the (new) nuclear charge Znuc; the keystring is sa = "QED: damped-hydrogenic". Nothing is returned.
JenaAtomicCalculator.Defaults.setDefaults — Method
Defaults.setDefaults(sa::String, Z::Float64) ... sets a global default that carries a single real number; nothing is returned.
+ `"nuclear: charge"` ... the nuclear charge used where none is given explicitly.
+ `"fine structure constant: alpha"` ... alpha, and with it its inverse, which is kept consistent here rather
than recomputed at each use. **Changing alpha changes every relativistic quantity in the package**, so this
is a setting for a deliberate study of the alpha-dependence -- see the AlphaVariation module -- and not one
to be varied casually.
An unrecognised keystring raises and names itself.JenaAtomicCalculator.Defaults.setDefaults — Method
Defaults.setDefaults(sa::String, scField::Basics.AbstractScField) ... to (re-) define the potential that is applied for the generation of the continuum orbitals; the keystring is sa = "continuum: SCF potential". Nothing is returned; the default is set internally.
JenaAtomicCalculator.Defaults.setDefaults — Method
Defaults.setDefaults(sa::String, grid::Radial.Grid; printout::Bool=true) ... to (pre-) define internally the standard radial grid which is used to represent most orbitals; the keystring is sa = "standard grid". Nothing is returned; the default is set internally.
JenaAtomicCalculator.Defaults.setDefaults — Method
Defaults.setDefaults(sa::String, sb::String) ... sets the string-valued global default named by the keystring sa to sb; nothing is returned.
Two families of keystring are handled here and nowhere else, and they behave differently:
+ the UNIT settings -- `"unit: energy"`, `"unit: cross section"`, `"unit: rate"`, `"unit: strength"` and
`"unit: time"` -- are VALIDATED against the list of units the corresponding conversion can perform, and an
unsupported value raises at once rather than at the first conversion.
+ the STREAM settings -- `"print data: open"/"close"`, `"print data-X: ..."`, `"print data-Y: ..."`,
`"print summary: open"/"append"/"close"` and `"print test: open"/"close"` -- open or close a file whose
name is sb, and the "close" forms ignore sb.
An unrecognised keystring raises and names itself. See the keystring catalogue above `setDefaults(sa::String)`
for the complete list across all methods of this family.JenaAtomicCalculator.Defaults.setDefaults — Method
Defaults.setDefaults(sa::String, subshells::Array{Subshell,1}; printout::Bool=true) ... to (pre-) define internally the standard relativistic subshell list on which the standard order of orbitals is based; the keystring is sa = "relativistic subshell list". Nothing is returned; the default is set internally.
JenaAtomicCalculator.Defaults.setDefaults — Method
Defaults.setDefaults(sa::String) ... (re-) defines some 'standard' settings which are common to all the computations with the JAC module, and which can be 'overwritten' by the user. — An improper setting of some variable may lead to an error message, if recognized immediately. The following defaults apply if not specified otherwise by the user: the framework is 'relativistic', energies are given in eV and cross sections in barn. Note that, internally, atomic units are used throughout for all the computations within the program. nothing is returned if not indicated otherwise.
+ ("framework: relativistic") or ("framework: non-relativistic")
... to define a relativistic or non-relativistic framework for all subsequent computations.
("method: continuum, spherical Bessel")or("method: continuum, pure sine")or("method: continuum, asymptotic Coulomb")or("method: continuum, nonrelativistic Coulomb")or("method: continuum, Galerkin")... to define a a method for the generation of the continuum orbitals as (pure) spherical Bessel, pure sine, asymptotic Coulomb, nonrelativistic Coulomb orbital or by means of the B-spline-Galerkin method.("method: normalization, pure sine")or("method: normalization, pure Coulomb")or("method: normalization, Ong-Russek")... to define a method for the normalization of the continuum orbitals as asymptotically (pure) sine or Coulomb functions, or following the procedure by Ong & Russek (1978).("method: Wigner symbols, exact")or("method: Wigner symbols, floating-point")or("method: Wigner symbols, GSL")... to (pre-) define HOW the Wigner 3-j, 6-j and 9-j symbols are evaluated. All three agree to about one part in 1e15, so this is a choice of cost and not of physics:floating-pointevaluates in Float64, is 4.2x faster on a mid-size cascade with BIT-IDENTICAL results, and is the DEFAULT;exactevaluates in Rational{BigInt} and is what JAC used until 25-Aug-2026; andGSLis faster again but differs in the ninth digit, which would put approved reference data in question. SeeAngularMomentum.AbstractWignerMethod.("nuclear: charge", Z::Float64)or("nuclear: model", nm::Any")... to define the nuclear charge or nuclear model for the pedestrian approach to atomic computations.("fine structure constant: alpha", value::Float64)... to (re-) define the fine-structure constant alpha used throughout JAC, together with its reciprocal (the speed of light in atomic units); needed for alpha-variation (q-factor) computations, which re-run the SCF/CI machinery at a slightly shifted alpha. Defaults.FINESTRUCTURECONSTANT and Defaults.INVERSEFINESTRUCTURE_CONSTANT are updated together so they never go out of sync.
("unit: energy", "eV")or("unit: energy", "Kayser")or("unit: energy", "Hartree")or("unit: energy", "Hz")or("unit: energy", "Hz")... to (pre-) define the energy units for all further printouts and communications with the JAC module.("unit: cross section", "a.u.")or("unit: cross section", "barn")or("unit: cross section", "Mbarn")... to (pre-) define the unit for the printout of cross sections.("unit: rate", "a.u.")or("unit: rate", "1/s")... to (pre-) define the unit for the printout of rates.("unit: strength", "a.u.")or("unit: strength", "barn eV")or("unit: strength", "cm^2 eV")... to (pre-) define the unit for the printout of resonance strengths. The keystring is"unit: strength"; until 07-Nov-2026 this block offered"unit: resonance strength", which the code has never accepted.("unit: time", "a.u.")or("unit: time", "sec")or("unit: time", "fs")or("unit: time", "as")... to (pre-) define the unit for the printout and communications of times with the JAC module.
JenaAtomicCalculator.Defaults.setStandardSubshellList — Method
Defaults.setStandardSubshellList(subshells::Array{Subshell,1}; printout::Bool=true) ... sets the standard relativistic subshell list, which fixes the ORDER in which the subshells of a CSF are named when one is printed. Nothing is returned.
THIS IS FOR DISPLAY ONLY, and it is internal. It is set in many places but read in exactly two, both of
which produce output: `Base.string(csf::CsfR)` and `Basics.display(stream, orbitals, grid)`. No
computation consults it -- every process module works from its own local subshell list, obtained from
`Basics.generate(OrderedSubshellList(), basisA, basisB)` and passed explicitly to whatever needs it.
IT IS NOT A USER SETTING, which is why it was demoted out of `Defaults.setDefaults` on 12-Aug-2026
(the string key still delegates here, so existing scripts keep working). The correspondence to a CSF is
POSITIONAL -- `csf.occupation[i]` belongs to `subshells[i]` -- and nothing validates the list against
the CSFs it will label. A list that does not match therefore mislabels every printed CSF silently. The
value is derived data with no physical content, so there is nothing a user answers by overriding it.JenaAtomicCalculator.Defaults.warn — Method
Defaults.warn(wa::AbstractWarning, sa::String) ... records the warning text sa under the action wa; nothing is returned. The only action taken here is AddWarning(); the actions that print or reset the collected warnings take no text and are handled by Defaults.warn(wa::AbstractWarning).
**A warning is RECORDED ONCE AND COUNTED EVERY TIME.** A condition met by five hundred lines produces one
entry saying so, not five hundred entries, and the count is shown when the warnings are printed. The
bookkeeping is done under a lock, so this may be called from a threaded line loop; the lock is uncontended in
the ordinary single-threaded case and costs nothing against the work that produced the warning.JenaAtomicCalculator.Defaults.warn — Method
Defaults.warn(wa::AbstractWarning) ... deals with warnings that occur during a run and session; it handles the global array GBL_WARNINGS. Adding a warning carries its text and is done by Defaults.warn(wa::AbstractWarning, sa::String) instead.
(PrintWarnings)... to print all warnings that are currently kept in the global array GBL_WARNINGS.(ResetWarnings)... to reset the global array GBL_WARNINGS. Nothing is returned; the warning is appended to the global list.
Distributions
JenaAtomicCalculator.Distribution.AbstractElectronDistribution — Type
abstract type Distribution.AbstractElectronDistribution ... defines an abstract and a number of singleton types to deal with different electron distributions in a plasma.
+ ElectronBiMaxwell ... to apply a non-relativistic Bi-Maxwellian electron distribution.
+ ElectronFermiDirac ... to apply a non-relativistic electron distribution in a degenerate plasma.
+ ElectronMaxwell ... to apply a non-relativistic Maxwell-Boltzmann electron distribution.JenaAtomicCalculator.Distribution.AbstractLineProfile — Type
abstract type Distribution.AbstractLineProfile ... defines an abstract and a number of singleton types to deal with different line profiles, for instance, in a plasma.
+ GaussianProfile ... assumes a Gaussian line profile L^Gaussian (omega)
+ LorentzianProfile ... assumes a Lorentzian line profile L^Lorentzian (omega)JenaAtomicCalculator.Distribution.AbstractPhotonDistribution — Type
abstract type Distribution.AbstractPhotonDistribution ... defines an abstract and a number of singleton types to deal with different electron and photon-flux distributions in a plasma.
+ PhotonBremsstrahlungThin ... to apply a free-free bremsstrahlung photon distribution in hot, optically-thin plasma.
+ PhotonBremsstrahlungThick ... to apply a free-free bremsstrahlung photon distribution in hot, optically-thick plasma.
+ PhotonDilute ... to apply a dilute photon distribution.
+ PhotonPlanck ... to apply Planck's black-body photon distribution.
+ PhotonPowerLaw ... to apply a power-law photon distribution.
+ PhotonVacuumField ... to apply a vacuum (zero-intensity) photon distribution.JenaAtomicCalculator.Distribution.ElectronBiMaxwell — Type
struct ElectronBiMaxwell <: Distribution.AbstractElectronDistribution ... to apply a bi-Maxwellian electron distribution to photoexcitation, photonionization and recombination processes.
+ Tpar ::Float64 ... parallel temperature
+ Tperp ::Float64 ... perpendicular temperatureJenaAtomicCalculator.Distribution.ElectronFermiDirac — Type
struct ElectronFermiDirac <: Distribution.AbstractElectronDistribution ... to apply a Fermi-Dirac electron distribution in plasma simulations to excitation and recombination processes.
+ T ::Float64 ... temperature
+ muChem ::Float64 ... chemical potential mu.JenaAtomicCalculator.Distribution.ElectronMaxwell — Type
struct ElectronMaxwell <: Distribution.AbstractElectronDistribution ... to apply a Maxwell-Boltzmann electron distribution in plasma simulations to excitation and recombination processes.
+ T ::Float64 ... temperatureJenaAtomicCalculator.Distribution.PhotonBremsstrahlungThick — Type
struct PhotonBremsstrahlungThick <: Distribution.AbstractPhotonDistribution ... to apply a free-free bremsstrahlungs photon spectrum of a hot, optically-thick plasma to photoexcitation, photonionization and recombination processes.
+ T ::Float64 ... temperatureJenaAtomicCalculator.Distribution.PhotonBremsstrahlungThin — Type
struct PhotonBremsstrahlungThin <: Distribution.AbstractPhotonDistribution ... to apply a free-free bremsstrahlungs photon spectrum of a hot, optically-thin plasma to photoexcitation, photonionization and recombination processes.
+ T ::Float64 ... temperatureJenaAtomicCalculator.Distribution.PhotonDilute — Type
struct PhotonDilute <: Distribution.AbstractPhotonDistribution ... to apply a dilute photon spectrum to photoexcitation, photonionization and recombination processes.
+ T ::Float64 ... temperature
+ w ::Float64 ... geometric dilution factorJenaAtomicCalculator.Distribution.PhotonPlanck — Type
struct PhotonPlanck <: Distribution.AbstractPlasmaDistribution ... to apply Planck's black-body photon spectrum to photoexcitation, photonionization and recombination processes.
+ T ::Float64 ... temperatureJenaAtomicCalculator.Distribution.PhotonPowerLaw — Type
struct PhotonPowerLaw <: Distribution.AbstractPhotonDistribution ... to apply a dilute photon spectrum n(omega; T) = A * (omega/omega0)^(-p) / ( exp(omega/dist.T) - 1.0 ) to photoexcitation, photonionization and recombination processes. The constants A, omega0 can be combined but for the price that the units are less obvious.
+ T ::Float64 ... temperature
+ A ::Float64 ... Constant amplitude [a0^-3 Hz^-1]
+ p ::Float64 ... decay parameter; 1 < p < 2 ... high-energy dominated; p > 2 ... low-energy dominated.
+ omegaMin ::Float64 ... minimum omega for which the power law applies.
+ omegaMax ::Float64 ... maximum omega for which the power law applies.JenaAtomicCalculator.Distribution.PhotonVacuumField — Type
struct PhotonVacuumField <: Distribution.AbstractPhotonDistribution ... to apply a vacuum (zero-intensity) photon spectrum to photoexcitation, photonionization and recombination processes. This vacuum field is suitable to extract spontaneous rates and rate coefficients.
+ T ::Float64 ... temperatureJenaAtomicCalculator.Distribution.electronEnergyDistribution — Method
Distribution.electronEnergyDistribution(dist::Distribution.ElectronFermiDirac, energy::Float64) ... to provide the Fermi-Dirac electron energy distribution at the given energy, i.e. the spin-degenerate free-electron density of states sqrt(2 E)/pi^2 times the Fermi occupation of that energy. A value::Float64 is returned, with the dimension of a number density per unit energy.
THIS IS AN ABSOLUTE DENSITY AND NOT A PROBABILITY, which is the one thing to know before using it: it
integrates to the electron number density n, whereas the two ElectronMaxwell methods of the same names
integrate to ONE. The two families are therefore not interchangeable, and the relation between them is
f_FD -> f_Maxwell * n in the non-degenerate limit, which `TestFrames.testModule_Distribution` asserts.
A caller wanting a rate coefficient <sigma v> from a degenerate distribution must divide by n itself.
The prefactor was 2^(3/2)/pi^2 until 08-Nov-2026, i.e. twice this, and so counted the two spin states
once too often. Four independent checks agreed on the factor and none of them on the old value: the
Jacobian against this module's own velocity form, the textbook density of states
(2m)^(3/2) sqrt(E) / (2 pi^2 hbar^3), the T -> 0 density (2 mu)^(3/2)/(3 pi^2), and the non-degenerate
limit above. Nothing in JAC constructs an ElectronFermiDirac, so no published number moves.JenaAtomicCalculator.Distribution.electronEnergyDistribution — Method
Distribution.electronEnergyDistribution(dist::Distribution.ElectronMaxwell, energy::Float64) ... to provide the Maxwell-Boltzmann electron energy distribution of given temperature at electron energy. A value::Float64 is returned.
JenaAtomicCalculator.Distribution.electronVelocityDistribution — Method
Distribution.electronVelocityDistribution(dist::Distribution.ElectronFermiDirac, velocity::Float64) ... to provide the Fermi-Dirac velocity distribution of given temperature at electron velocity, with regard to d^3 v, i.e. 2/(2 pi)^3 times the Fermi occupation of the state of that speed. A value::Float64 is returned.
LIKE ITS ENERGY PARTNER THIS IS AN ABSOLUTE DENSITY, not a probability: integrated over d^3 v it gives the
electron number density n, while the two ElectronMaxwell methods integrate to ONE. Taken through the
Jacobian f_E(E) dE = f_v(v) 4 pi v^2 dv at E = v^2/2 it yields sqrt(2 E)/pi^2 per unit energy, which is the
spin-degenerate free-electron density of states, and that agreement with electronEnergyDistribution above
was established on 08-Nov-2026 by correcting THAT method, which had carried twice this weight.JenaAtomicCalculator.Distribution.electronVelocityDistribution — Method
Distribution.electronVelocityDistribution(dist::Distribution.ElectronMaxwell, velocity::Float64) ... to provide the Maxwell-Boltzmann electron velocity distribution of given temperature at electron velocity. A value::Float64 is returned.
JenaAtomicCalculator.Distribution.isNormalizedToOne — Method
Distribution.isNormalizedToOne(dist::Distribution.AbstractElectronDistribution) ... states whether the distribution's own electronEnergyDistribution and electronVelocityDistribution integrate to ONE, i.e. whether it is a probability density, as against an ABSOLUTE number density integrating to the electron density n. A value::Bool is returned.
WHY THIS IS A TRAIT AND NOT A REMARK IN A DOCSTRING. The two families of this module answer differently --
`ElectronMaxwell` integrates to one, `ElectronFermiDirac` to n -- and a caller that forms a rate coefficient
`<sigma v> = int sigma(E) v(E) f(E) dE` is correct only for the first. A careful note had already been written at both
methods and could not protect anything, because the caller is dispatched on the ABSTRACT type and cannot read a
docstring; the same reasoning Rule 18 of the coding conventions gives for carrying an operator's kind in its type.
**THE ABSTRACT FALLBACK RAISES BY DESIGN.** A new electron distribution must declare which it is, and a type that
forgets to gets an error naming itself rather than being silently treated as a probability density.JenaAtomicCalculator.Distribution.isNormalizedToOne — Method
Distribution.isNormalizedToOne(dist::Distribution.ElectronFermiDirac) ... a Fermi-Dirac distribution as implemented here is an ABSOLUTE density – the spin-degenerate density of states times the Fermi occupation – and integrates to the electron density n rather than to one; false is returned.
JenaAtomicCalculator.Distribution.isNormalizedToOne — Method
Distribution.isNormalizedToOne(dist::Distribution.ElectronMaxwell) ... a Maxwell-Boltzmann distribution is a probability density; true is returned. Both of its methods integrate to one, which TestFrames.testModule_Distribution asserts directly.
JenaAtomicCalculator.Distribution.photonNumberDensity — Method
Distribution.photonNumberDensity(dist::Distribution.PhotonDilute, omega::Float64) ... to provide the photon number density of a diluite Planckian black-body field of given temperature at frequency omega. A value::Float64 is returned.
JenaAtomicCalculator.Distribution.photonNumberDensity — Method
Distribution.photonNumberDensity(dist::Distribution.PhotonPlanck, omega::Float64) ... to provide the photon number density of a Planckian black-body field of given temperature at frequency omega. A value::Float64 is returned.
JenaAtomicCalculator.Distribution.photonNumberDensity — Method
Distribution.photonNumberDensity(dist::Distribution.PhotonPowerLaw, omega::Float64) ... to provide the photon number density of a dilute photon field of given temperature at frequency omega. A value::Float64 is returned.
JenaAtomicCalculator.Distribution.photonNumberDensity — Method
Distribution.photonNumberDensity(dist::Distribution.PhotonVacuumField, omega::Float64) ... to provide the photon number density of a vacuum photon field , i.e. a zero field. A value::Float64 is returned.
Hamiltonian matrices
JenaAtomicCalculator.Hamiltonian.QPartition — Type
struct Hamiltonian.QPartition ... records how the Q space of one step was divided, and whether the division was justified. Returned beside the multiplet by Hamiltonian.performCIwithSecondOrderQ so that a caller can act on the numbers rather than on the printed report.
+ promoted ::Array{Configuration,1} ... configurations put INTO the CI and diagonalized exactly.
+ folded ::Array{Configuration,1} ... configurations folded in through second order only.
+ discarded ::Array{Configuration,1} ... configurations dropped entirely.
+ weights ::Array{Tuple{Configuration,Float64},1} ... |c|^2 of every configuration of the Q space, the
MAXIMUM over the target levels (a configuration that matters
to any one level must enter the basis they all share),
sorted descending. A LIST and not a Dict because the order
is the point: a caller reads this to see WHICH configurations
carry the weight, and a Dict would throw that away.
+ deltaE ::Array{Float64,1} ... second-order contribution of the folded part, per level.
+ sumC2Folded ::Array{Float64,1} ... Sum |c|^2 over the folded part, per level. THE GATE.
+ isJustified ::Bool ... whether that sum stayed below `promoteAbove` for every
level, i.e. whether the folded remainder really is a weak
perturbation. False means the energies are not to be used.
+ unsound ::Array{Tuple{Configuration,Float64},1} ... configurations carrying an INTRUDER level: one that
came out of the enlarged CI below the reference level while
holding almost none of the reference, with that eigenvalue.
Empty is the normal case. A non-empty list means the CI has
been handed a state that displaces the reference rather than
corrects it -- see the guard in `Hamiltonian.secondOrderBlock`.JenaAtomicCalculator.Hamiltonian.ShapeCrossingPartition — Type
struct Hamiltonian.ShapeCrossingPartition ... what one shape-crossing second-order junction (AtomicState.RasStep.shapedTo) is worth, returned by Hamiltonian.secondOrderShapeCrossingCorrection.
+ targetLevels ::Array{Int64,1} ... which levels of P (by index into the ladder's own priorMultiplet)
this correction was computed for -- those carrying weight >= 0.5 on the reference configurations, the
SAME rule `Hamiltonian.secondOrderBlock` uses, for the same reason: P carries the whole accumulated
ladder, most of whose levels are correlation states nobody asked for.
+ deltaE ::Array{Float64,1} ... the second-order energy shift for each of `targetLevels`, in the
SAME order.
+ newQIndices ::Array{Int64,1} ... which CSFs of Q's OWN basis are genuinely NEW -- not already
present (by non-relativistic configuration key) in P -- and therefore the ones actually summed over.
Q's basis always re-includes `refConfigs` and typically re-includes much of what P already built
(`Basics.generateBasis` was written for a P-like space, not a bare "new excitations only" one), and
coupling P against one of THOSE would be a near-diagonal, not a genuine off-diagonal, term.
+ coupling ::Array{Float64,2} ... the `<P level i|H-E|Q CSF s>` coupling, P's levels (rows) against
`newQIndices` (columns, in the SAME order), for a caller who wants more than the target levels alone.JenaAtomicCalculator.Hamiltonian.configurationKey — Method
Hamiltonian.configurationKey(conf::Configuration) ... builds a canonical String for the given (non-relativistic) configuration – the occupied shells in a fixed order – so that configurations which compare equal give the same key, and so that the key can be sorted and printed. A key::String is returned.
JenaAtomicCalculator.Hamiltonian.diagonalizeCiMatrix — Method
Hamiltonian.diagonalizeCiMatrix(matrix::Array{Float64,2}, levelSelectionCI::LevelSelection) ... diagonalizes a single symmetry-block CI matrix, automatically choosing between a full and a partial (LAPACK syevr-based, via Basics.diagonalize's range keyword) diagonalization. Partial diagonalization is used only when levelSelectionCI selects a bounded set of global level INDICES (never symmetries – those already keep only whole, fully-wanted blocks via Basics.selectSymmetry, so there is no partial- eigenpair opportunity within a kept block) and the matrix is at least CIPARTIALDIAGMINDIM large. When used, only the lowest min(n, maximum(levelSelectionCI.indices)) eigenpairs are requested – this is always sufficient and safe: the GLOBAL (energy-sorted, merged-across-blocks) rank of any level can never be smaller than its own LOCAL (within-block) rank, so if a level's global index is <= maximum(indices), its local index must be too; the true global top-maximum(indices) levels are therefore guaranteed to survive in the collected per-block partial spectra before the final merge-and-sort in performCI/performCIKinkAware. An eigen::Basics.Eigen is returned.
JenaAtomicCalculator.Hamiltonian.displayQPartition — Method
Hamiltonian.displayQPartition(stream::IO, partition::Hamiltonian.QPartition, treatment::Basics.SecondOrder, nCsfUsed::Int64) ... reports how the Q space was divided and, where the fold-in was not justified, NAMES the configurations that would have to be promoted to make it so. Nothing is returned.
JenaAtomicCalculator.Hamiltonian.foldNearDegenerateQCluster — Method
Hamiltonian.foldNearDegenerateQCluster(ePLevel::Float64, hqqCluster::Array{Float64,1}, couplingCluster::Array{Float64,1}) ... folds a P target level together with a cluster of Q-CSFs whose Epstein-Nesbet denominator with it is too small for ordinary non-degenerate perturbation theory to be trusted (see secondOrderShapeCrossingCorrection's own classification, priority item 5's dense-Q half). Builds the small (1+n) x (1+n) matrix with ePLevel and hqqCluster on the diagonal and couplingCluster in the first row/column – Q-Q off-diagonals are zero, since no such matrix element is ever computed by the caller – diagonalizes it, and returns the shift of the eigenvalue closest to ePLevel, relative to ePLevel itself. Validated against a hand-built toy case before being wired in: reduces to the ordinary -coupling^2/dd sum to machine precision in the well-separated limit, matches the closed-form 2x2 degenerate-PT result for a single flagged CSF, and matches a direct external diagonalization for a multi-CSF cluster. A shift::Float64 is returned.
JenaAtomicCalculator.Hamiltonian.foldQGroup! — Method
Hamiltonian.foldQGroup!(hNN::Array{Float64,2}, newIdx::Array{Int64,1}, hDiag::Array{Float64,1}, basis::Basis, qIndices::Array{Int64,1}, nm::Nuclear.Model, grid::Radial.Grid, settings::AsfSettings, potential::Radial.Potential, cache::InteractionStrength.XLCache, perturbation::Basics.BlockDiagonalizedPerturbation) ... the Basics.BlockDiagonalizedPerturbation method: qIndices' own CSF block is built and diagonalized FIRST (Hamiltonian.matrixElement to build it, Hamiltonian.diagonalizeCiMatrix to diagonalize it – the same two primitives Hamiltonian.secondOrderBlock already uses elsewhere), then the coupling vector to every retained CSF of newIdx is transformed into this configuration's OWN eigenbasis, and the SAME Gaigalas-Eq.-(37)-style fold is applied summed over its eigenstates – their eigenvalues in place of each bare CSF's diagonal element – rather than over its bare CSFs one at a time. This captures correlation WITHIN qIndices that the diagonal method cannot see. Mutates hNN in place. Nothing is returned.
JenaAtomicCalculator.Hamiltonian.foldQGroup! — Method
Hamiltonian.foldQGroup!(hNN::Array{Float64,2}, newIdx::Array{Int64,1}, hDiag::Array{Float64,1}, basis::Basis, qIndices::Array{Int64,1}, nm::Nuclear.Model, grid::Radial.Grid, settings::AsfSettings, potential::Radial.Potential, cache::InteractionStrength.XLCache, perturbation::Basics.DiagonalCSFPerturbation) ... folds ONE Q-space configuration's CSFs (qIndices) into hNN, the growing CI matrix of the retained (P + promoted) basis – the body of Hamiltonian.secondOrderBlock's own fold loop, taken out so that HOW a folded configuration's own internal coupling is treated can be dispatched on perturbation; see Basics.AbstractQSpacePerturbation. This method is Basics.DiagonalCSFPerturbation's: every CSF of qIndices is folded as its own, isolated intermediate state, using its own diagonal Hamiltonian element as the Epstein-Nesbet denominator – exactly what this loop has always done. Mutates hNN in place. Nothing is returned.
JenaAtomicCalculator.Hamiltonian.groupCsfsByConfiguration — Method
Hamiltonian.groupCsfsByConfiguration(basis::Basis, indices::Array{Int64,1}) ... groups the given CSF indices of the basis by their NON-RELATIVISTIC configuration. Grouping is by the nl-configuration and not by the relativistic one on purpose: the jj partners of one nl shell then stay together, so a threshold can never keep 3p_^2 3p while dropping 3p_ 3p^2 and leave the expansion unbalanced in the spin-orbit splitting.
THE GROUPING IS BY A CANONICAL STRING AND NOT BY THE Configuration ITSELF. The original reason was a defect:
`Configuration` satisfied `==` while `hash` fell back to object identity, so a `Dict` keyed by one put 426
CSFs into 425 groups -- one per CSF -- with no error anywhere. THAT DEFECT IS FIXED (12-Sep-2026; see
`Base.hash(conf::Basics.Configuration, h::UInt)` in `module-Basics-inc-first.jl`) and a Dict keyed by a
Configuration is now sound. The String key is kept because it is also SORTABLE and READABLE, which is what
the reports below need, not because it must be. A tuple
`(groups, confOf)::Tuple{Dict{String,Array{Int64,1}}, Dict{String,Configuration}}` is returned, the second
map holding one representative Configuration per key for reporting.JenaAtomicCalculator.Hamiltonian.matrixElement — Method
Hamiltonian.matrixElement(basis::Basis, r::Int64, s::Int64, nm::Nuclear.Model, grid::Radial.Grid, settings::AsfSettings, potential::Radial.Potential, cache::InteractionStrength.XLCache) ... computes the single Hamiltonian matrix element between the CSF with indices r and s of the given basis, under the electron-electron interaction and QED model named by the settings. This is the body of the inner loop of Hamiltonian.setupMatrix, taken out so that a caller which needs only a BLOCK of the matrix – the P rows against one configuration of Q, say – can have it without allocating the whole symmetry block. A value::Float64 is returned.
JenaAtomicCalculator.Hamiltonian.performCI — Method
Hamiltonian.performCI(basis::Basis, nm::Nuclear.Model, grid::Radial.Grid, settings::AsfSettings; printout::Bool=false, writeSummary::Bool=true) ... Computes and diagonalizes the Hamiltonian matrix for all CSF in the given basis. It also assigns the mixing coefficients to the individual levels. The individual contributions from the Breit or diagonal interaction as well as from QED to this matrix are controlled by the settings. A multiplet::Multiplet is returned. With writeSummary=false, the level table is not written to the summary file even when a summary file is open; this is needed by callers that invoke performCI inside a per-configuration loop (Cascade, Plasma) and would otherwise append one table per configuration to the .sum file.
JenaAtomicCalculator.Hamiltonian.performCIKinkAware — Method
Hamiltonian.performCIKinkAware(basis::Basis, nm::Nuclear.Model, grid::Radial.Grid, settings::AsfSettings; printout::Bool=false) ... computes and diagonalizes the same CI Hamiltonian matrix as performCI, but via setupMatrixKinkAware (kink-aware two-electron Slater integral) instead of setupMatrix. Isolated from performCI; reached from SelfConsistent.performSCF when settings.scField = Basics.ALField(), and directly from SelfConsistent.solveOptimizedLevelField (EOLField), so that the FINAL reported level energies reflect the same kink-aware integral used during SCF orbital optimization, not just the SCF's own internal energy tracking. A multiplet::Multiplet is returned.
JenaAtomicCalculator.Hamiltonian.performCIwithFrozenOrbitals — Method
Hamiltonian.performCIwithFrozenOrbitals(configs::Array{Configuration,1}, frozenOrbitals::Dict{Subshell, Orbital}, nuclearModel::Nuclear.Model, grid::Radial.Grid, settings::AsfSettings; printout::Bool=true) ... to generate, from the given frozen orbitals, the CI multiplet for the given configurations: the CSF basis is set up for these configurations and the frozen orbitals, and is then diagonalized by Hamiltonian.performCI without any further orbital optimization. The e-e interaction that enters the CI matrix is whatever settings.eeInteractionCI specifies – CoulombInteraction() (the AsfSettings() default), CoulombBreit(), ..., or DiagonalCoulomb() for the cheap, single-CSF-level approximation this function was once hard-wired to. A multiplet::Multiplet, sorted by energy, is returned.
JenaAtomicCalculator.Hamiltonian.performCIwithSecondOrderQ — Method
Hamiltonian.performCIwithSecondOrderQ(basis::Basis, pBasis::Basis, refConfigs::Array{Configuration,1}, nm::Nuclear.Model, grid::Radial.Grid, settings::AsfSettings, treatment::Basics.SecondOrder; printout::Bool=true) ... performs the CI of the given basis, symmetry block by symmetry block, with the Q space of each treated by the thresholds of the treatment; see Hamiltonian.secondOrderBlock for what happens inside one block. The levels of every block are merged and sorted by energy, exactly as Hamiltonian.performCI does, so that the multiplet returned here is indistinguishable from one that routine would give.
P IS `pBasis`, THE SPACE THE PREVIOUS STEP BUILT, and Q is what this basis adds beyond it. A perturbative
step is therefore always a LEAF: it reports what the excluded excitations are still worth and is never
inherited by a later variational step, so a promotion is internal to it -- some Q configurations simply
treated better -- and needs no carrying forward.
AND Q IS FINITE. It is the set of CSFs the CURRENT ORBITAL SET can build but the previous step excluded,
not the complete second-order sum over an infinite virtual space. A correction from here says what this
orbital set is still missing through the excitations left out; it does not say what a larger orbital set
would add. That is why a new layer ENLARGES Q rather than shrinking it, and why the sequence of these
corrections across layers is a convergence measure for the variational space.
A tuple `(multiplet::Multiplet, partitions::Array{Hamiltonian.QPartition,1})` is returned, one partition
per symmetry block, in the order the blocks were computed.JenaAtomicCalculator.Hamiltonian.projectHamiltonian — Method
Hamiltonian.projectHamiltonian(subshell::Subshell, matrix::Array{Float64,2}, matrixB::Array{Float64,2}, bVectors::Dict{Subshell, Vector{Float64}}) ... projects the (single-electron DHF) Hamiltonian matrix of subshell with regard to the B-vectors of the same symmetry. This projection is necessary to ensure orthogonality among the various orbitals. A (nsL+nsS) x (nsL+nsS) matrix::Array{Float64,2} is returned.
JenaAtomicCalculator.Hamiltonian.rankQspace — Method
Hamiltonian.rankQspace(basis::Basis, pIndices::Array{Int64,1}, qGroups::Dict{String,Array{Int64,1}}, energies::Array{Float64,1}, vectors::Array{Float64,2}, nm::Nuclear.Model, grid::Radial.Grid, settings::AsfSettings, cache::InteractionStrength.XLCache, targetLevels::Array{Int64,1}) ... computes, for every configuration of the Q space, the fraction of the atomic state function it carries and the second-order energy it would contribute. The P space must already have been diagonalized, its energies and eigenvectors being passed in; the Q space is visited ONE CONFIGURATION AT A TIME and its CSFs are never held, so the memory is set by the P space and by the largest single configuration, not by |Q|.
For each Q-CSF `q` and each P level `i` the weight is `|c|^2 = (<Psi_i|V|q> / D)^2` with the Epstein-Nesbet
denominator `D = <q|H|q> - E_i`: the Q-CSF's OWN diagonal element against the CI eigenvalue, so that no
configuration-average energy is needed and no H0/V partitioning has to be declared. The weight of a
configuration is the MAXIMUM over the TARGET levels named by `targetLevels`, since one basis must serve
them all -- but only them: a correlation level of P that nobody asked for must not enlarge the basis.
A tuple `(weights, deltaE, c2)::Tuple{Dict{String,Float64}, Dict{String,Array{Float64,1}},
Dict{String,Array{Float64,1}}}` is returned, keyed as `Hamiltonian.groupCsfsByConfiguration` keys its groups
and holding per configuration the level-maximum weight, the per-level second-order energy and the per-level
weight.JenaAtomicCalculator.Hamiltonian.secondOrderBlock — Method
Hamiltonian.secondOrderBlock(sym::LevelSymmetry, basis::Basis, pBasis::Basis, refConfigs::Array{Configuration,1}, nm::Nuclear.Model, grid::Radial.Grid, settings::AsfSettings, treatment::Basics.SecondOrder; printout::Bool=true) ... performs the CI of ONE symmetry block of the given basis with its Q space treated by the thresholds of the treatment, and is the body of Hamiltonian.performCIwithSecondOrderQ. Every configuration whose weight exceeds promoteAbove enters the CI and is diagonalized exactly, those below discardBelow are dropped, and the remainder is folded in through the second-order effective Hamiltonian. The P space is taken to be the CSFs belonging to the reference configurations.
THE STEP REFUSES TO STAY SILENT WHEN ITS OWN PRECONDITION FAILS. `Sum |c|^2` over the folded part says
whether that part really is a weak perturbation; where it is not, the computation still returns -- the
multiplet is a legitimate CI in the space actually used -- but `isJustified` is false, a warning is printed,
and the configurations that would have to be promoted are NAMED, in descending order with their running
sum, so that a second attempt succeeds by reading the output rather than by guessing a threshold.
A tuple `(levels::Array{Level,1}, partition::Hamiltonian.QPartition)` is returned.JenaAtomicCalculator.Hamiltonian.secondOrderShapeCrossingCorrection — Method
Hamiltonian.secondOrderShapeCrossingCorrection(pMp::Multiplet, qMp::Multiplet, refConfigs::Array{Configuration,1}, grid::Radial.Grid, nm::Nuclear.Model, settings::AsfSettings) ... the shape-crossing counterpart of Hamiltonian.secondOrderBlock, for a Q space built by a AtomicState.RasStep.shapedTo layer (BasicsAZ.retagShapedSubshells/generateOrbitalsForShapedBasis – its own, separately SCF-refined Basis, never merged into P). P and Q are biorthogonalized via BiOrthogonal.computeTransformation(BiOrthogonal.ShapeCrossingJunction(), pMp, qMp, grid), and every P-Q coupling then goes through ManyElectron.matrixElement_HminusE on the RESULTING biorthonormal bases, summed over P's own CI mixing coefficients – never a bare, unweighted CSF-pair value, which Phase 0's toy validation (work/clIII-corevalence/phase0-toy/validate2.jl; see the module docstring of BiOrthogonal.jl) showed is not a well-defined quantity on its own.
ONLY Q'S GENUINELY NEW CSFs ENTER THE SUM -- those whose non-relativistic configuration is NOT already
present in P. `Basics.generateBasis` (used to build Q in `BasicsAZ.runRasStep!`) was written for a
P-LIKE space and always re-includes `refConfigs`, and typically much of P's own valence-correlation
excitation set besides (it has no "new excitations only" mode); treating Q's WHOLE CSF space, or its
own full diagonalization, as "the Q space" therefore couples P against configurations P ALREADY HAS.
For such a pair the biorthogonal overlap after transformation is exactly 1 (same spectators, same
shape, no reshaping at that label), so the coupling is really a DIAGONAL-like term, equal to roughly
the CSF's own total energy (`ManyElectron.matrixElement_HminusE` carries no `-E<r|s>` term -- see its
own docstring -- which is harmless only where the overlap is exactly 0, as it is for a genuinely new
CSF). Measured while building this function: including P's own CSFs on the Q side gave a "correction"
of +5.7e7 Ha; restricting to the genuinely new CSFs, as this function now does, is what removes it.
For each of Q's new CSFs `s` the Epstein-Nesbet denominator is ITS OWN diagonal Hamiltonian element,
computed on Q's OWN, untransformed, internally-orthonormal basis (a single-basis quantity, exactly
`Hamiltonian.rankQspace`'s own per-CSF Epstein-Nesbet formula) -- NOT on the biorthogonal-transformed
one, since the transform is not norm-preserving in general (`BiOrthogonal.jl`'s own module docstring)
and the denominator needs Q's true, physical self-energy. The second-order shift for target P level
`i` is `- sum_s |<Psi_Pi|H-E|s>|^2 / (h_ss - E_Pi)`, the same sign convention as `Hamiltonian.rankQspace`
and `Hamiltonian.foldQGroup!` -- a state lying ABOVE the reference (`h_ss > E_Pi`, the normal case)
LOWERS it, as a correlation correction must.
ONLY THE TARGET LEVELS OF P ARE CORRECTED -- those carrying weight >= 0.5 on `refConfigs`, the SAME
rule `Hamiltonian.secondOrderBlock` uses and for the same reason.
THE DENOMINATOR GUARD IS A HARD EXCLUSION AT `abs(dd) < 1.0e-10` (literal degeneracy, UNCHANGED) PLUS
A QUASI-DEGENERATE FOLD, added 05-Nov-2026 -- filed as priority item 5, 04-Nov-2026, after a dense Q
space (Ti III 3d^2 -> 4d, 5371 genuinely-new CSFs against 9 target levels) gave a correction swinging
-386 to -537 mHa, LARGER than the whole NIST term span, with no warning printed anywhere. For each
target level, every surviving Q-CSF `s` is classified by `abs(coupling[i,s]/dd)`: non-degenerate PT is
trusted (`ratioThreshold`, default 0.4, below which a Taylor expansion in the coupling is a fair
description) and stays in the ordinary `-coupling^2/dd` sum; above it, the CSF is FLAGGED and its
whole flagged cluster for that level is folded instead -- `foldNearDegenerateQCluster` diagonalizes
the small matrix of the target level plus its flagged Q-CSFs (Q-Q off-diagonals zero, since this
function never computes them) and takes the eigenvalue closest to the unperturbed level as the
correction, which stays bounded as `dd -> 0` where the ordinary sum diverges.
THE FOLD IS VALIDATED AND HARMLESS, BUT DOES NOT REPAIR THE TI III CASE IT WAS BUILT FOR -- state this
plainly rather than letting the mechanism's correctness stand in for the fix having worked. Measured
05-Nov-2026: on the real Ti III 3d^2 run, `abs(coupling[i,s]/dd)` never exceeds `ratioThreshold` for a
SINGLE one of the 9x5371 pairs, so nothing is ever flagged, the `@warn` below never fires, and the
nine `deltaE` values are UNCHANGED from before this fold existed (-386.2 to -537.4 mHa, still larger
than the whole NIST term span). The diagnosis behind this fold -- a few outlier near-degenerate
denominators -- was WRONG for this case: the blowup is a DENSE ACCUMULATION of many only-moderately-
small denominators across those 5371 CSFs, none individually near-degenerate enough to trip a ratio
test, which is a different failure mode that a per-term classifier cannot catch by construction. The
dense-Q half of item 5 is UNFIXED and is held on the challenges list (see `src/` `CLAUDE.md`'s working
lists) rather than carried here as an open priority item; this fold stays in `src/` because it is
correct, toy-validated (see the helper's own docstring) and a byte-identical no-op everywhere tested
(Cl III's sparse p^3 Q space, branch g: nothing is ever flagged there either, and the five dated
`deltaE` values reproduce exactly), so it is ready for whatever genuinely isolated near-degeneracy
turns up in a future case -- it is simply not that case.
P MAY CARRY MORE SUBSHELLS THAN Q -- priority item 5's second half, also closed 04-Nov-2026. A prior
RAS layer can deepen P's own ladder beyond the fixed subshell set Q's own `shapedTo` step touches
(branch h's n3+n4 ladder is exactly this). Q's subshells are now remapped by (n,kappa) SEARCH and
then RE-EXPANDED onto P's (possibly longer) subshell list via `ManyElectron.Basis(basis, subshells)`,
the already-existing zero-padding re-expansion constructor, rather than requiring the two lists to
match length-for-length and position-for-position. This is exact, not approximate: every CSF of Q
genuinely has zero electrons on the extra slots, and `ManyElectron.matrixElement_HminusE`'s angular
coefficients are driven by CSF OCCUPATION, never by subshell-list length, so a slot no CSF occupies
is never looked up. A no-op (bit-identical) when P and Q already agree, as on branch g.
A `Hamiltonian.ShapeCrossingPartition` is returned.JenaAtomicCalculator.Hamiltonian.setupMatrix — Method
Hamiltonian.setupMatrix(sym::LevelSymmetry, basis::Basis, nm::Nuclear.Model, grid::Radial.Grid, settings::AsfSettings, cache::InteractionStrength.XLCache; printout::Bool=false) ... Set-up (computes) the Hamiltonian matrix for all CSF with symmetry sym in the given basis. The individual contributions from the Breit or diagonal interaction as well as from QED to this matrix are controlled by the settings. A matrix::Arrays{Float64,2} is returned.
JenaAtomicCalculator.Hamiltonian.setupMatrixKinkAware — Method
Hamiltonian.setupMatrixKinkAware(sym::LevelSymmetry, basis::Basis, nm::Nuclear.Model, grid::Radial.Grid, settings::AsfSettings, cache::InteractionStrength.XLCache; printout::Bool=false) ... sets up the same Hamiltonian matrix as setupMatrix, but using InteractionStrength.XLCoulombKinkAware (kink-aware) instead of InteractionStrength.XLCoulomb for the Coulomb two-electron contributions. The Breit contribution (XL_Breit) and the QED contribution are left untouched – this bug is specific to the Coulomb Slater integral's quadrature, not to those other terms. Isolated from setupMatrix; only used by performCIKinkAware. A matrix::Arrays{Float64,2} is returned.
Many-electron bases and levels
JenaAtomicCalculator.ManyElectron.AbstractQedModel — Type
abstract type ManyElectron.AbstractQedModel ... defines an abstract and a number of singleton types for dealing with QED estimates in the many-electron computations.
+ struct QedPetersburg
... to estimate the QED corrections due to the model Hamiltonian by Shabaev and coworkers (2013).
+ struct QedSydney
... to estimate the QED corrections by means of the radiative potential by Flambaum and Ginges (2004),
completed with Kozioł's Rci-Q per-shell A(Z,n) re-fit for the s-orbital electric self-energy term
(arXiv:2512.01515). Empirically verified sign-correct and Z-stable for 1s over Z=30-100 (see
example-Ae.jl); the magnitude ratio to QedPetersburg's self-energy declines smoothly from ~0.9
(Z=30) to ~0.4 (Z=100) -- an expected, understood residual gap between two independent approximate
models, not an instability. p/d/f orbitals still use Flambaum-Ginges' original, less accurate,
generic fit (not yet re-derived from Rci-Q's tables) -- treat results for those orbitals, and for
Z<20 (outside Rci-Q's stated fit range), with more caution than 1s in the verified range.
+ struct NoneQed
... No QED estimates are included into the computations.JenaAtomicCalculator.ManyElectron.AbstractStartOrbitals — Type
abstract type ManyElectron.AbstractStartOrbitals ... defines an abstract and a number of singleton types to determine the orbitals from which the SCF computations start.
+ struct StartFromHydrogenic ... to start the SCF procedure from hydrogenic orbitals.
+ struct StartFromThomasFermi ... to start the SCF procedure from orbitals in a Thomas-Fermi potential.
+ struct StartFromPrevious ... to start the SCF procedure from previously calculated orbitals.
StartFromHydrogenic ignores the other electrons entirely, so for a many-electron atom its outer
orbitals start far too tightly bound. StartFromThomasFermi screens the nucleus with a statistical
model of the electron cloud before any orbital exists, which costs nothing and starts the iteration
much closer to the answer; see Basics.ThomasFermiField.JenaAtomicCalculator.ManyElectron.AsfSettings — Method
ManyElectron.AsfSettings(settings::AsfSettings; generateScf::Union{Nothing,Bool}=nothing, eeInteraction::Union{Nothing,AbstractEeInteraction}=nothing, scField::Union{Nothing,AbstractScField}=nothing, startScfFrom::Union{Nothing,AbstractStartOrbitals}=nothing, scfRoute::Union{Nothing,Basics.AbstractScfRoute}=nothing, accuracyScf::Union{Nothing,Float64}=nothing, shellSequenceScf::Union{Nothing,Array{Subshell,1}}=nothing, frozenSubshells::Union{Nothing,Array{Subshell,1}}=nothing, gridAccuracy::Union{Nothing,Float64}=nothing, gridStopper::Union{Nothing,Bool}=nothing, eeInteractionCI::Union{Nothing,AbstractEeInteraction}=nothing, qedModel::Union{Nothing,AbstractQedModel}=nothing, jjLS::Union{Nothing,LSjjSettings}=nothing, levelSelectionCI::Union{Nothing,LevelSelection}=nothing, printout::Bool=false, maxIterationsScf::Union{Nothing,Int64}=nothing)
... constructor for re-defining a settings::AsfSettings.
A `asfSettings::ManyElectron.AsfSettings` is returned.JenaAtomicCalculator.ManyElectron.AsfSettings — Method
ManyElectron.AsfSettings() ... constructor for setting the default values. A asfSettings::ManyElectron.AsfSettings is returned.
JenaAtomicCalculator.ManyElectron.AsfSettings — Type
struct ManyElectron.AsfSettings ... a struct for defining the settings for the atomic state functions, i.e. the self-consistent-field (SCF) and CI computations
+ generateScf ::Bool ... True, if a SCF need to be generated, and false otherwise
(frozen orbitals).
+ eeInteraction ::AbstractEeInteraction ... Specify the e-e interaction to be included into the SCF
computations.
+ scField ::AbstractScField ... Specify the self-consistent field, for instance,
Basics.ALField(), etc.
+ startScfFrom ::AbstractStartOrbitals ... Specify the orbitals to start the SCF computations
+ scfRoute ::AbstractScfRoute ... Specify HOW the orbitals of the given scField are found, and with
what iteration budget; cf. Basics.AbstractScfRoute. The routes form a
hierarchy by cost, so that a computation which does not converge on a
fast route can be repeated on a dependable one.
+ accuracyScf ::Float64 ... convergence criterion for the SCF field.
+ shellSequenceScf ::Array{Subshell,1} ... Sequence of subshells to be optimized.
+ frozenSubshells ::Array{Subshell,1} ... Sequence of subshells to be kept frozen.
+ gridAccuracy ::Float64 ... accuracy to which the radial grid must represent every
subshell in the pure (point-nucleus) Dirac spectrum;
cf. Bsplines.checkGridRepresentation.
+ gridStopper ::Bool ... True, if a grid that fails gridAccuracy shall raise an
error, and false if it shall only warn.
+ eeInteractionCI ::AbstractEeInteraction ... Specify the e-e interaction to be included into the
CI computations.
+ qedModel ::AbstractQedModel ... model for estimating QED corrections {NoneQed(),
QedPetersburg(), QedSydney()}.
+ jjLS ::LSjjSettings ... settings to control a jj-LS transformation of atomic
level, if requested.
+ levelSelectionCI ::LevelSelection ... Specifies the selected levels, if any.JenaAtomicCalculator.ManyElectron.Basis — Method
ManyElectron.Basis(basis::Basis, subshells::Array{Subshell,1}) ... constructor to re-expand a given basis with regard to an extended subshell list; this expansion does not change the CSF basis but makes sure that the occupation and other quantum numbers are properly expanded. An error message is issued if the sequence of the subshells does not allow such a simple re-expansion. A newBasis::Basis is returned.
JenaAtomicCalculator.ManyElectron.Basis — Method
ManyElectron.Basis(sa::String, cslFilename::String, rwfFilename::String) ... to construct an instance::Basis from the Grasp92/Grasp2013 .csl and .rwf files. A basis::ManyElectron.Basis is returned.
JenaAtomicCalculator.ManyElectron.Basis — Method
ManyElectron.Basis() ... constructor for an 'empty' instance::Basis with isDefined == false. A basis::ManyElectron.Basis is returned.
JenaAtomicCalculator.ManyElectron.Basis — Type
struct ManyElectron.Basis ... defines a type for a relativistic atomic basis, including the (full) specification of the configuration space and radial orbitals.
+ isDefined ::Bool ... Determines whether this atomic basis 'points' to some a well-defined basis
or to an empty instance, otherwise.
+ NoElectrons ::Int64 ... No. of electrons.
+ subshells ::Array{Subshell,1} ... Explicitly given subshell list for this basis.
+ csfs ::Array{CsfR,1} ... List of CSF.
+ coreSubshells ::Array{Subshell,1} ... List of (one-electron) core orbitals.
+ orbitals ::AbstractDict{Subshell, Orbital} ... Dictionary of (one-electron) orbitals -- widened
from the concrete Dict 08-Nov-2026 so that a caller with a
genuinely large orbital set (PhotoIonizationPseudostates'
pooled pseudostate ladders, priority item 14) can supply an
AbstractDict that materializes an Orbital on getindex rather
than holding every one resident at once; every existing
caller still passes a plain Dict, which remains a valid
AbstractDict, so nothing about an ordinary Basis changes.JenaAtomicCalculator.ManyElectron.CsfR — Method
ManyElectron.CsfR(J::AngularJ64, parity::Parity) ... simple constructor for given J and parity, and where standardOrbitals is set to false. A csfR::ManyElectron.CsfR is returned.
JenaAtomicCalculator.ManyElectron.CsfR — Method
ManyElectron.CsfR(sa::String) ... simple constructor for given closed-shell occupation (such as "[Ne]"), and where standardOrbitals is set to true. A csfR::ManyElectron.CsfR is returned.
JenaAtomicCalculator.ManyElectron.CsfR — Type
struct ManyElectron.CsfR ... defines a type for a relativistic configuration state function (CSF) in terms of its orbitals (sequence of orbitals), their occupation as well as the angular momenta, seniority and the coupling of the corresponding antisymmetric subshell states.
+ useStandardSubshells ::Bool ... Determines whether the subshell list has to be obtained from some outer structure
given by the subshells field below.
+ J ::AngularJ64 ... Total angular momentum J.
+ parity ::Parity ... Total parity.
+ occupation ::Array{Int64,1} ... occupation of the orbitals with regard to the specified orbital list.
+ seniorityNr ::Array{Int64,1} ... list of seniority or Nr values of the antisymmetric subshell states
+ subshellJ ::Array{AngularJ64,1} ... list of J-values of the antisymmetric subshell states.
+ subshellX ::Array{AngularJ64,1} ... intermediate X-values in the coupling of the antisymmetric subshell states.
+ subshells ::Array{Subshell,1} ... Explicitly given subshell list if useStandardSubshells == false.JenaAtomicCalculator.ManyElectron.LSjjSettings — Method
ManyElectron.LSjjSettings(makeIt::Bool) ... constructor for the default values of jj-LS transformations. A lSjjSettings::ManyElectron.LSjjSettings is returned.
JenaAtomicCalculator.ManyElectron.LSjjSettings — Type
struct ManyElectron.LSjjSettings ... defines a type for the details and parameters for performing jj-LS expansions.
+ makeIt ::Bool ... True, if the jj-LS expansion is to be made and false otherwise.
+ minWeight ::Float64 ... minimum weight with which a (relativistic) CSF must contribute
to (at least one) level.
+ printWeight ::Float64 ... minimum weight of a nonrelativistic CSF to be printed out in the
final expansion.
+ levelSelection ::LevelSelection ... Specifies the selected levels, if any.JenaAtomicCalculator.ManyElectron.Level — Method
ManyElectron.Level(J::AngularJ64, parity::Parity, energy::Float64, relativeOcc::Float64) ... constructor an atomic level without a state representation: hasStateRep == false. A level::ManyElectron.Level is returned.
JenaAtomicCalculator.ManyElectron.Level — Method
ManyElectron.Level(level::Level, subshells::Array{Subshell,1}) ... constructor to re-expand a given level with regard to an extended subshell list; this expansion does not change the CSF basis nor the mixing coeffients but makes sure that the occupation and other quantum numbers are properly expanded. An error message is issued if the sequence of the subshells does not allow such a simple re-expansion. A newLevel::Level is returned.
JenaAtomicCalculator.ManyElectron.Level — Method
ManyElectron.Level() ... constructor an empty level without useful data. A level::ManyElectron.Level is returned.
JenaAtomicCalculator.ManyElectron.Level — Type
struct ManyElectron.Level ... defines a type for an atomic level in terms of its quantum number, energy and with regard to a relativistic basis.
+ J ::AngularJ64 ... Total angular momentum J.
+ M ::AngularM64 ... Total projection M, only defined if a particular sublevel is referred to.
+ parity ::Parity ... Parity of the level.
+ index ::Int64 ... Index of this level in its original multiplet, or 0.
+ energy ::Float64 ... energy
+ relativeOcc ::Float64 ... Relative occupation of this level, if involved in the evolution of a cascade.
+ hasStateRep ::Bool ... Determines whether this level 'point' to a physical representation of an state
(i.e. an basis and corresponding mixing coefficient vector), or just to empty instances,
otherwise.
+ basis ::Basis ... relativistic atomic basis
+ mc ::Vector{Float64} ... Vector of mixing coefficients w.r.t basis.JenaAtomicCalculator.ManyElectron.Multiplet — Method
ManyElectron.Multiplet(sa::String, cslFilename::String, rwfFilename::String, mixFilename::String) ... to construct an instance::Multiplet from the Grasp92/Ratip2012 .csl, .rwf and .mix files. Some consistency checks are made and the method terminates with an error message if the files don't fit together.
A `multiplet::ManyElectron.Multiplet` is returned.JenaAtomicCalculator.ManyElectron.Multiplet — Method
ManyElectron.Multiplet(multiplet::Multiplet, subshells::Array{Subshell,1}) ... constructor to re-expand a given Multiplet with regard to an extended subshell list; this expansion does not change the CSF basis nor the mixing coeffients but makes sure that the occupation and other quantum numbers are properly expanded. An error message is issued if the sequence of the subshells does not allow such a simple re-expansion. A newMultiplet::Multiplet is returned.
JenaAtomicCalculator.ManyElectron.Multiplet — Method
`ManyElectron.Multiplet()` ... constructor for providing an 'empty' instance of this struct.
A `multiplet::ManyElectron.Multiplet` is returned.JenaAtomicCalculator.ManyElectron.Multiplet — Type
struct ManyElectron.Multiplet ... defines a type for an ordered list of atomic levels; has only the default constructor.
+ name ::String ... A name associated to the multiplet.
+ levels ::Array{Level,1} ... A list of levels (pointers).JenaAtomicCalculator.ManyElectron.NoneQed — Type
... no QED estimates are included into the computations.
JenaAtomicCalculator.ManyElectron.QedPetersburg — Type
... to estimate the QED corrections from the model Hamiltonian of Shabaev and coworkers (2013).
JenaAtomicCalculator.ManyElectron.QedSydney — Type
... to estimate the QED corrections from the radiative potential of Flambaum and Ginges (2004), completed with Kozioł's Rci-Q per-shell A(Z,n) re-fit of the s-orbital electric self-energy.
JenaAtomicCalculator.ManyElectron.StartFromHydrogenic — Type
... to start the SCF procedure from hydrogenic orbitals; this ignores the other electrons entirely, so the outer orbitals of a many-electron atom start far too tightly bound.
JenaAtomicCalculator.ManyElectron.StartFromPrevious — Type
struct ManyElectron.StartFromPrevious <: ManyElectron.AbstractStartOrbitals ... to start from a set of previously calculated orbitals.
+ orbitals ::Dict{Subshell, Orbital} ... set of previously-calculated orbitals.JenaAtomicCalculator.ManyElectron.StartFromThomasFermi — Type
... to start the SCF procedure from orbitals in a Thomas-Fermi potential, which screens the nucleus with a statistical model of the electron cloud before any orbital exists; see Basics.ThomasFermiField.
Base.:(==) — Method
Base.:(==)(seta::AsfSettings, setb::AsfSettings) ... compares (recursively) two instances of AsfSettings and return true if all subfields are equal, and false otherwise A value::Bool is returned.
Base.:(==) — Method
Base.:(==)(csfa::CsfR, csfb::CsfR) ... compares (recursively) two relativistic CSFs and return true if all subfields are equal, and false otherwise A value::Bool is returned.
JenaAtomicCalculator.ManyElectron.CsfRGrasp92 — Method
ManyElectron.CsfRGrasp92(subshells::Array{Subshell,1}, coreSubshells::Array{Subshell,1}, sa::String, sb::String, sc::String) ... to construct a CsfR from 3 Grasp-Strings and the given list of subshells and core subshells. A csf::ManyElectron.CsfR is returned.
JenaAtomicCalculator.ManyElectron.CsfRTransformToStandardSubshells — Method
ManyElectron.CsfRTransformToStandardSubshells(csf::CsfR, subshells::Array{Subshell,1}) ... constructor to re-define a CSF with regard to the given list of subshells. It incorporates 'empty' subshell state and their coupling (if necessary) but does not support a re-arrangement of the subshell order. This constructor is used to 'combine' individual CsfR into a common list (such as in a Basis) and, thus, use StandardSubshells = true is set. This method terminates with an error message if the given subshell list requires a re-coupling of the CSF. A csf::ManyElectron.CsfR is returned.
JenaAtomicCalculator.ManyElectron.parseA — Method
ManyElectron.parseA(x::AbstractString) ... helper function for ManyElectron.CsfRGrasp92 Either nothing for an empty string, a value::Int64 for one or two characters, or an Expr holding a rational for three, is returned.
Nuclear models
JenaAtomicCalculator.Nuclear.AbstractNuclearModel — Type
abstract type Nuclear.AbstractNuclearModel ... defines an abstract type to distinguish the shapes of the nuclear charge distribution:
+ struct PointNucleus ... a point-like nucleus, rho(r) = Z delta(r).
+ struct UniformNucleus ... a homogeneously charged sphere of radius R.
+ struct FermiNucleus ... a two-parameter Fermi distribution,
rho(r) = rho_0 / (1 + exp((r-c)/a)), with the skin thickness a fixed by
Nuclear.fermiA and c determined from the requested rms radius.
+ struct ThreeParameterFermiNucleus
... a three-parameter Fermi distribution,
rho(r) = rho_0 (1 + w r^2/c^2) / (1 + exp((r-c)/a)); see below.
Until 12-Aug-2026 the model was carried as a String and compared with ==, which made every new
distribution another branch and left the accepted spellings inconsistent ("Fermi", but "point" and
"uniform"). Dispatching on the type instead follows Basics.AbstractScField and its singletons, and
makes a further distribution one new subtype plus one new method of Nuclear.nuclearPotential.JenaAtomicCalculator.Nuclear.DeformedFermiNucleus — Method
Nuclear.DeformedFermiNucleus(beta2::Float64) ... constructor for a purely quadrupole-deformed Fermi nucleus with beta4 = w = 0 and a = Nuclear.fermiA.
Nuclear.DeformedFermiNucleus(; beta2=nothing, axisRatio=nothing, beta4=0., w=0., a=Nuclear.fermiA) ... constructor that accepts EITHER the deformation beta2 OR the axis ratio cpar/cperp, but not both.
JenaAtomicCalculator.Nuclear.DeformedFermiNucleus — Method
Nuclear.DeformedFermiNucleus(; beta2::Union{Nothing,Float64}=nothing, axisRatio::Union{Nothing,Float64}=nothing, beta4::Float64=0., w::Float64=0., a::Float64=Nuclear.fermiA) ... keyword constructor for a quadrupole-deformed Fermi charge distribution. Give EITHER beta2 OR axisRatio, never both and never neither – they describe the same deformation and are converted into one another by Nuclear.axisRatio, so supplying both invites an inconsistent pair; either mistake raises here rather than later. beta4 adds a hexadecapole term, w the three-parameter Fermi correction, and a the surface thickness. A model::Nuclear.DeformedFermiNucleus is returned.
JenaAtomicCalculator.Nuclear.DeformedFermiNucleus — Type
struct Nuclear.DeformedFermiNucleus <: Nuclear.AbstractNuclearModel ... an axially-deformed Fermi distribution, in which the half-density radius depends on the polar angle,
rho(r,theta) = rho_0 (1 + w r^2/c^2) / (1 + exp((r - c(theta))/a)),
c(theta) = c_0 N [1 + beta2 Y_20(theta) + beta4 Y_40(theta)].
With Y_20(0) = +0.63078 at the pole and Y_20(pi/2) = -0.31539 at the equator, the two semi-axes are
c_par = c_0 N (1 + 0.63078 beta2) and c_perp = c_0 N (1 - 0.31539 beta2), so that
beta2 > 0 is PROLATE (cigar, axis ratio c_par/c_perp > 1),
beta2 < 0 is OBLATE (pancake, axis ratio < 1),
and the axis ratio is available directly through Nuclear.axisRatio / Nuclear.deformationFromAxisRatio;
the keyword constructor below accepts either parametrisation.
N IS A VOLUME NORMALISATION, N = <(1 + beta2 Y_20 + beta4 Y_40)^3>^(-1/3), without which the nucleus
would silently GROW as it deforms: the bare form gives V/V_0 = 1.022 at beta2 = 0.3, an effect as
large as the deformation signal itself. Nuclear matter is nearly incompressible, so deformation at
constant volume is the physical case.
+ beta2 ::Float64 ... quadrupole deformation; 0 recovers Nuclear.ThreeParameterFermiNucleus.
+ beta4 ::Float64 ... hexadecapole deformation.
+ w ::Float64 ... the three-parameter weight, so this model generalises both Fermi models.
+ a ::Float64 ... skin-thickness parameter [fm].
WHAT A DEFORMED NUCLEUS DOES TO AN ATOM, and what it does not. JAC is a central-field theory
throughout: Nuclear.nuclearPotential returns a radial Z(r), and the angular algebra everywhere
assumes it. This model therefore contributes its MONOPOLE part, the average of rho over the polar
angle, which is what a spherically-symmetric electron density samples. That part carries the whole
effect deformation has on the mean-square radius, and hence on the FIELD SHIFT:
<r^2> = <r^2>_sph [1 + (5/4pi) beta2^2 + ...],
good to 0.2% at beta2 = 0.3 once the volume is held fixed. The lambda = 2 component that is dropped
is NOT lost physics: it is the electric quadrupole interaction, which JAC already carries separately
through nm.Q in the hyperfine structure. THESE TWO MUST NOT BOTH BE COUNTED for the same effect.
NOTE FOR ANYONE FITTING beta2 TO AN ISOTOPE SHIFT: the enhancement above is EVEN in beta2, so a
field shift is nearly blind to the sign. beta2 = +0.3 and -0.3 differ by 0.6% in <r^2>, the sign
entering only at order beta2^3. Prolate and oblate are distinguished by the spectroscopic
quadrupole moment, not by an isotope shift.JenaAtomicCalculator.Nuclear.FermiNucleus — Type
... a two-parameter Fermi distribution, rho(r) = rho_0 / (1 + exp((r-c)/a)), with the skin thickness a fixed by Nuclear.fermiA and the half-density radius c determined from the requested rms radius.
JenaAtomicCalculator.Nuclear.Isomer — Method
Nuclear.Isomer(isomer::Nuclear.Isomer; spinI::Union{Nothing,AngularJ64}=nothing, parity::Union{Nothing,Parity}=nothing, energy::Union{Nothing,Float64}=nothing, mu::Union{Nothing,Float64}=nothing, Q::Union{Nothing,Float64}=nothing, Omega::Union{Nothing,Float64}=nothing, multipoleM::Union{Nothing,Array{EmMultipole,1}}=nothing, elementM::Union{Nothing,Array{Float64,1}}=nothing)
... constructor for re-defining an isomer::Nuclear.Isomer, i.e. the standard JAC keyword copy-constructor.
Its absence is why every application script builds an Isomer from positional arguments, and why every one
of them is now wrong against the eight-field struct.
A `isomer::Nuclear.Isomer` is returned.JenaAtomicCalculator.Nuclear.Isomer — Method
Nuclear.Isomer() ... constructor for an empty instance of Nuclear.Isomer.
Note (06-Aug-2026): multipoleM and elementM are both left EMPTY. They previously read `[E1]` and
`Float64[]`, i.e. of unequal length, which breaks the pairing the two fields are supposed to express and
would give an out-of-bounds the moment anything iterated them together. An empty isomer has no known
nuclear transition, which is the honest default.
A `isomer::Nuclear.Isomer` is returned.JenaAtomicCalculator.Nuclear.Isomer — Type
struct Nuclear.Isomer ... defines a type for modeling isomeric levels that are involved in hyperfine-induced transitions and structure. It assumes that the nuclear charge, model and mass, radius is defined by an associated nm::Nuclear.Model.
+ spinI ::AngularJ64 ... nuclear spin I >= 0 of the isomeric nuclear level, could be the ground level.
+ parity ::Parity ... parity of the isomeric nuclear level
+ energy ::Float64 ... nuclear excitation energy of the isomeric level; 0. if nuclear ground level [in user-specified units]
+ mu ::Float64 ... magnetic dipole moment [Bohr magnetons].
+ Q ::Float64 ... electric quadrupole moment.
+ Omega ::Float64 ... magnetic octupole moment [Bohr magnetons x fm^2].
+ multipoleM ::Array{EmMultipole,1}
... multipoles of the <Ia || M^(multipole) || Ib > nuclear matrix elements.
+ elementM ::Array{Float64,1}
... (real) values of the <Ia || M^(multipole) || Ib > nuclear matrix elements in [a.u.], one for each entry
of multipoleM and IN THE SAME ORDER; the two arrays must therefore have equal length.
These last two fields carry the NUCLEAR transition data: they are what makes a hyperfine-induced nuclear
transition possible at all, and what mixes two nuclear levels of the same F. Use
Nuclear.reducedTransitionAmplitude to obtain elementM from a reduced transition probability B(multipole),
rather than converting by hand -- that conversion carries a Weisskopf unit and a convention factor, and
has already been got wrong once in an application script.JenaAtomicCalculator.Nuclear.Model — Method
Nuclear.Model(nm::Nuclear.Model; Z::Union{Nothing,Float64}=nothing, model::Union{Nothing,AbstractNuclearModel}=nothing, mass::Union{Nothing,Float64}=nothing, radius::Union{Nothing,Float64}=nothing, spinI::Union{Nothing,AngularJ64}=nothing, mu::Union{Nothing,Float64}=nothing, Q::Union{Nothing,Float64}=nothing, Omega::Union{Nothing,Float64}=nothing)
... constructor for re-defining a nuclear model nm::Nuclear.Model.
A `model::Nuclear.Model` is returned.JenaAtomicCalculator.Nuclear.Model — Method
Nuclear.Model(Z::Real, model::Nuclear.AbstractNuclearModel) ... to specify a nucleus with charge Z and the given model – PointNucleus(), UniformNucleus() or FermiNucleus() – and where the nuclear spin and nuclear moments are all set to zero. A model::Nuclear.Model is returned.
JenaAtomicCalculator.Nuclear.Model — Method
Nuclear.Model(Z::Real, M::Float64) ... to specify a Fermi-type nucleus with charge Z and mass M, and where the nuclear spin and nuclear moments are all set to zero. A model::Nuclear.Model is returned.
JenaAtomicCalculator.Nuclear.Model — Method
Nuclear.Model(Z::Real) ... to specify a Fermi-type nucleus with charge Z, and where the nuclear spin and nuclear moments are all set to zero. A model::Nuclear.Model is returned.
JenaAtomicCalculator.Nuclear.Model — Type
struct Nuclear.Model ... defines a type for the nuclear model, i.e. for its form and parameters.
+ Z ::Float64 ... nuclear charge
+ model ::AbstractNuclearModel
... shape of the nuclear charge distribution: PointNucleus(),
UniformNucleus() or FermiNucleus(). This was a String until
12-Aug-2026, with the spellings "Fermi", "point" and "uniform" -- a
capitalisation the docstring itself got wrong, so that
Nuclear.Model(Z, "Point") raised for anyone following the manual.
A wrong model is now a MethodError at the call site instead.
+ mass ::Float64 ... atomic mass
+ radius ::Float64 ... (root-mean square) radius of a uniform or Fermi-distributed nucleus
+ spinI ::AngularJ64 ... nuclear spin I, must be >= 0
+ mu ::Float64 ... magnetic dipole moment [nuclear magnetons]
+ Q ::Float64 ... electric quadrupole moment [barn]
+ Omega ::Float64 ... magnetic octupole moment [nuclear magnetons x barn]JenaAtomicCalculator.Nuclear.PointNucleus — Type
... a point-like nucleus, rho(r) = Z delta(r); the potential is the bare Coulomb -Z/r at every grid point.
JenaAtomicCalculator.Nuclear.ThreeParameterFermiNucleus — Method
Nuclear.ThreeParameterFermiNucleus(w::Float64) ... constructor for a three-parameter Fermi nucleus with the shape parameter w and the skin thickness left at JAC's standard Nuclear.fermiA.
JenaAtomicCalculator.Nuclear.ThreeParameterFermiNucleus — Type
struct Nuclear.ThreeParameterFermiNucleus <: Nuclear.AbstractNuclearModel ... a three-parameter Fermi distribution of the nuclear charge,
rho(r) = rho_0 (1 + w r^2/c^2) / (1 + exp((r-c)/a)),
which relaxes the flat interior that the two-parameter form imposes by construction. Here w > 0
describes a central bump and w < 0 a CENTRAL DEPRESSION. Two quite different mechanisms produce
the latter: in medium-mass nuclei it is a shell effect (the 34Si bubble), whereas in the superheavy
region it is driven by the Coulomb repulsion pushing protons outward, which makes it robust rather
than model-dependent. This is the form tabulated by the elastic electron-scattering compilations
(de Vries, de Jager and de Vries, At. Data Nucl. Data Tables 36 (1987) 495) and used in the analysis
of muonic atoms, where the muon orbits largely INSIDE the nucleus and hence samples the shape of the
charge distribution rather than only its second moment.
+ w ::Float64 ... dimensionless shape parameter; w = 0 recovers Nuclear.FermiNucleus exactly.
+ a ::Float64 ... skin-thickness parameter [fm]. Unlike the two-parameter model, which always
uses the fixed Nuclear.fermiA, this is a field: the published parameter sets
come as triples (w, c, a) with a different a for every nucleus, so a fixed a
would make the model impossible to compare against any tabulated nucleus.
The one-argument constructor defaults it to Nuclear.fermiA.
NOTE on the parametrisation itself: for w < 0 the profile 1 + w r^2/c^2 turns negative beyond
r = c/sqrt(|w|). For the tabulated magnitudes (|w| <~ 0.1) that lies beyond 3c, where the Fermi
factor has already fallen to ~exp(-2c/a), so the contribution is numerically irrelevant. It is a
property of the three-parameter form, however, and not an oversight here.JenaAtomicCalculator.Nuclear.UniformNucleus — Type
... a homogeneously charged sphere of radius R = Model.radius [in fm]; the potential is harmonic inside, -Z/(2R) (3 - r^2/R^2), and Coulombic -Z/r outside.
JenaAtomicCalculator.Nuclear.axisRatio — Method
Nuclear.axisRatio(beta2::Float64) ... returns the ratio cparallel/cperpendicular of the two semi-axes of an axially-deformed nucleus with quadrupole deformation beta2; > 1 for a prolate and < 1 for an oblate shape. The relation
q = (1 + 0.63078 beta2) / (1 - 0.31539 beta2)
follows from the values of Y_20 at the pole and the equator, and is exact for the half-density
surface of Nuclear.DeformedFermiNucleus (up to the common volume factor N, which cancels in a ratio).JenaAtomicCalculator.Nuclear.computeDeformedFermiC — Method
Nuclear.computeDeformedFermiC(R::Float64, a::Float64, model::Nuclear.DeformedFermiNucleus) ... computes the half-density radius parameter c [fm] of a deformed Fermi nucleus with the given rms radius R, skin thickness a and deformation. Bisects, for the reasons given at Nuclear.computeThreeParameterFermiC. A value::Float64 is returned.
JenaAtomicCalculator.Nuclear.computeFermiBParameter — Method
Nuclear.computeFermiBParameter(R::Float64) ... computes a value::Float64 for the fermi_b parameter for a fermi-distributed nuclear with root-mean square radius R. A value::Float64 is returned.
JenaAtomicCalculator.Nuclear.computeThreeParameterFermiC — Method
Nuclear.computeThreeParameterFermiC(R::Float64, a::Float64, w::Float64) ... computes a value::Float64 for the half-density radius c [fm] of a three-parameter Fermi nucleus with root-mean-square radius R, skin thickness a and shape parameter w.
This BISECTS rather than iterating the fixed-point step used by Nuclear.computeFermiBParameter. That
step, b <- b - (fermiRrms(b) - R) with unit damping, converges at a rate set by d(fermiRrms)/db, and
that derivative vanishes as R approaches the smallest radius the form can represent -- which is why
it stalls on helium (see the comment in computeFermiBParameter). Bisection cannot stall: it either
converges or reports an unreachable R, which is the distinction that matters to the caller.
The bracket is grown outwards from c0 = sqrt(5/3) R -- the sharp-sphere relation R = sqrt(3/5) c --
rather than being fixed in advance, because threeParameterFermiRrms is monotone in c ONLY while
c stays comfortably above a. That was measured, not assumed: for a = 0.523 fm the closed form is
smooth and increasing for c >~ 2.5 fm, and for smaller c it is non-monotone and eventually singular,
since |w| a^2/c^2 then reaches O(1). cFloor below marks that boundary. Every physically meaningful
nucleus has c ~ 1.2 R with R >~ 2 fm and so sits far above it.
A value::Float64 is returned.JenaAtomicCalculator.Nuclear.deformationFromAxisRatio — Method
Nuclear.deformationFromAxisRatio(q::Float64) ... the inverse of Nuclear.axisRatio: returns the beta2 that produces the given ratio of semi-axes,
beta2 = (q - 1) / (0.63078 + 0.31539 q).
NOTE that this is the small-to-moderate deformation convention of the Y_20 expansion, not the
eccentricity of a true ellipsoid; the two agree for small beta2 and drift apart well before q = 2.JenaAtomicCalculator.Nuclear.deformedFermiNucleus — Method
Nuclear.deformedFermiNucleus(Rrms::Float64, Z::Float64, model::Nuclear.DeformedFermiNucleus, grid::Radial.Grid) ... computes the effective, radial-dependent charge Z(r) of the MONOPOLE part of an axially-deformed Fermi distribution with rms radius Rrms and nuclear charge Z; V_nuc = - Z(r)/r, and a potential::Radial.Potential is returned.
The angular average is taken first,
rho_0(r) = (1/2) Int_{-1}^{+1} dcos(theta) rho(r,theta),
after which the structure is identical to Nuclear.threeParameterFermiNucleus: the same split of the
Coulomb integral into an inner and an outer part, with the same quadrature tolerances. The cost is
the number of theta nodes, ~24; that is affordable because the Fermi potential was measured at 0.08%
of an Ar Auger run when the Nuclear module was profiled on 12-Aug-2026.
See the docstring of Nuclear.DeformedFermiNucleus for why only the monopole enters, and for the
warning against double-counting the quadrupole interaction that nm.Q already carries.JenaAtomicCalculator.Nuclear.deformedFermiRrms — Method
Nuclear.deformedFermiRrms(c::Float64, a::Float64, model::Nuclear.DeformedFermiNucleus; noTheta::Int64=24) ... returns the root-mean-square radius [fm] of the deformed Fermi distribution with half-density radius parameter c, skin thickness a and the deformation of the given model.
There is no closed form here -- the angular dependence sits inside the exponential -- so the two
radial moments are taken by quadrature and averaged over cos(theta) on a Gauss-Legendre grid, reusing
Radial.GridGL rather than a private rule. For beta2 = beta4 = 0 this reduces to
Nuclear.threeParameterFermiRrms, which is used as a regression test.JenaAtomicCalculator.Nuclear.deformedShape — Method
Nuclear.deformedShape(x::Float64, model::Nuclear.DeformedFermiNucleus) ... returns the angular factor [1 + beta2 Y20 + beta4 Y40] of the half-density radius at x = cos(theta), INCLUDING the volume normalisation N = <(1 + beta2 Y20 + beta4 Y40)^3>^(-1/3). Without N the nucleus grows as it deforms (V/V_0 = 1.022 already at beta2 = 0.3), which would show up as a spurious change of size in every quantity that follows.
JenaAtomicCalculator.Nuclear.deformedVolumeFactor — Method
Nuclear.deformedVolumeFactor(model::Nuclear.DeformedFermiNucleus) ... returns N = <(1 + beta2 Y20 + beta4 Y40)^3>^(-1/3), the factor that keeps the volume enclosed by the half-density surface independent of the deformation; a value::Float64 is returned.
JenaAtomicCalculator.Nuclear.fermiDistributedNucleus — Method
Nuclear.fermiDistributedNucleus(Rrms::Float64, Z::Float64, grid::Radial.Grid) ... computes the effective, radial-dependent charge Z(r) for a Fermi-distributed nucleus with rms radius R and nuclear charge Z. The full nuclear potential is then given by V_nuc = - Z(r)/r; a potential::Radial.Potential is returned.
JenaAtomicCalculator.Nuclear.fermiRrms — Method
Nuclear.fermiRrms(b::Float64) ... provides a value::Float64 for the root-mean-squared radius of a fermi-distributed charge density for given fermia and fermib parameters. A value::Float64 is returned.
JenaAtomicCalculator.Nuclear.innerBreakPoints — Method
Nuclear.innerBreakPoints(r::Float64) ... returns the integration limits and break points for the INNER part of the nuclear Coulomb integral, which runs from the origin out to r; a tuple::Tuple{Vararg{Float64}} is returned, always in increasing order.
The break point at 1.0e-3 a.u. is there to resolve the nuclear surface, and it is CLAMPED into the interval rather than being
dropped, so that the tuple always has the same length and the quadrature is not recompiled for each of several tuple types. A
clamped break point yields a zero-width segment, which contributes exactly nothing.
Passing it unconditionally makes the segment list non-monotonic for every grid point with r < 1.0e-3, so that quadgk integrates
out to 1.0e-3 -- straight across the surface -- and back again. That is right in exact arithmetic but ruinous in floating point:
for a heavy nucleus the intermediate segment is about 1.6e9 times the integral being asked for, so the result is formed by
cancelling two numbers nine orders of magnitude apart. Measured at the innermost grid point, that cost up to 1.7 s for a SINGLE
point and returned a relative error of 1.2e-5 where the call asks for 1.0e-8.JenaAtomicCalculator.Nuclear.name — Method
Nuclear.name(model::Nuclear.AbstractNuclearModel) ... returns a short name::String of the given nuclear model, for printout.
JenaAtomicCalculator.Nuclear.nuclearPotential — Method
Nuclear.nuclearPotential(nm::Nuclear.Model, grid::Radial.Grid) ... computes the effective, radial-dependent charge Z(r) for a nucleus with radius R and nuclear charge Z. The full nuclear potential is then given by V_nuc = - Z(r)/r; a potential::Radial.Potential is returned.
JenaAtomicCalculator.Nuclear.nuclearPotentialDH — Method
Nuclear.nuclearPotentialDH(nm::Nuclear.Model, grid::Radial.Grid, lambda::Float64) ... computes the effective, radial-dependent charge Z(r) for a nucleus with radius R, nuclear charge Z and for a Debye-Hueckel screening exp(-lambda r). The full Debye-Hueckel nuclear potential is then given by V_nuc = - Z(r)/r; a potential::Radial.Potential is returned.
JenaAtomicCalculator.Nuclear.outerBreakPoints — Method
Nuclear.outerBreakPoints(r::Float64) ... returns the integration limits and break points for the OUTER part of the nuclear Coulomb integral, which runs from r out to the practical infinity of 1.0e+3 a.u.; a tuple::Tuple{Vararg{Float64}} is returned, always in increasing order.
As for Nuclear.innerBreakPoints, the break points at 1.0 and 1.0e+1 a.u. are CLAMPED into the interval, so that the segment list
never runs backwards and the tuple keeps a fixed length; a clamped break point gives a zero-width segment. A grid point beyond the
outer limit yields an empty interval rather than a negatively oriented one.JenaAtomicCalculator.Nuclear.pointNucleus — Method
Nuclear.pointNucleus(Z::Float64, grid::Radial.Grid) ... computes the effective, radial-dependent charge Z(r) for a point-like nucleus with nuclear charge Z. The full nuclear potential is then given by V_nuc = - Z(r)/r; a potential::Radial.Potential is returned.
JenaAtomicCalculator.Nuclear.reducedTransitionAmplitude — Method
Nuclear.reducedTransitionAmplitude(mp::EmMultipole, B::Float64, A::Int64, spinI::AngularJ64; inWeisskopfUnits::Bool=true) ... to convert a reduced nuclear transition probability B(mp) into the reduced nuclear matrix element <If || M^(mp) || Ii> that Nuclear.Isomer.elementM expects, in atomic units; spinI is the spin of the INITIAL (decaying) nuclear state. A value::Float64 is returned. If inWeisskopfUnits, B is taken in Weisskopf units and converted with Nuclear.weisskopfUnit; otherwise B is taken as already in atomic units.
THE CONVENTION, corrected 06-Aug-2026, and it is worth reading before changing anything here. The
reduced transition probability is DEFINED as
B(sigma L; I_i -> I_f) = |<I_f || M^(sigma L) || I_i>|^2 / (2 I_i + 1)
so the reduced matrix element is simply sqrt( (2 I_i + 1) * B ), which is what is implemented.
THIS IS NOT WHAT THE MANUSCRIPT SAYS. examples/papers/b26.pra-hyperfine-induced.tex gives, for the 235U
E3 case, <I_g || W^(E3) || I_e> = sqrt( 8 pi / 7 * B(E3) ), i.e. sqrt( 8 pi/(2L+1) * B ), and that form
was implemented here first. It is wrong for this purpose, and not merely by a constant: since B already
carries the 1/(2 I_i + 1), the manuscript's W has the initial-state degeneracy folded into it and is
therefore NOT a reduced matrix element. Two things then break.
* elementM is contracted with a 6-j symbol in Hfs.computeInteractionAmplitudeM, where nothing but a
true reduced matrix element is admissible.
* the radiation field factor in HyperfineInduced.amplitude acquired a spurious (2 I_i + 1) dependence
to compensate -- and a field factor cannot depend on the spin of the emitting state, since it
describes the photon, not the nucleus. That is what exposed the error.
The manuscript needs a corresponding correction; it is marked in cyan in the -claude.tex copy.
UNITS. The returned matrix element is in JAC's own moment convention, i.e. magnetic multipoles carry
mu_N = 5.446170e-4/2 a.u. ("moment: from nuclear magneton to atomic"), the SAME convention as
Nuclear.Isomer.mu and hence as the diagonal hyperfine matrix elements. It is deliberately NOT converted
to the Gaussian convention mu_B = alpha/2 that the multipole RADIATION formula needs: that factor of
alpha belongs to the 1/c of the magnetic multipole radiation operator and is applied in
HyperfineInduced.amplitude, not to the nuclear moment itself.
Doing this by hand has already gone wrong: an HFS-induced uranium calculation computed
`sqrt(8/7. * 5.38e-27)` -- without the pi, and from a B value that differs from the one in the text.JenaAtomicCalculator.Nuclear.rrmsRadius — Method
Nuclear.rrmsRadius(A::Float64) ... provides a value::Float64 for the root-mean-squared radius R [fm] of a uniformly-distributed charge density of a nucleus with mass number A. Renamed from Nuclear.Rrms on 12-Aug-2026 to follow JAC's camelCase rule for function names. A value::Float64 is returned.
JenaAtomicCalculator.Nuclear.threeParameterFermiNucleus — Method
Nuclear.threeParameterFermiNucleus(Rrms::Float64, Z::Float64, model::Nuclear.ThreeParameterFermiNucleus, grid::Radial.Grid) ... computes the effective, radial-dependent charge Z(r) for a nucleus whose charge density follows the three-parameter Fermi form rho(r) = rho0 (1 + w r^2/c^2) / (1 + exp((r-c)/a)) with rms radius Rrms and nuclear charge Z. The full nuclear potential is then given by Vnuc = - Z(r)/r; a potential::Radial.Potential is returned.
The structure follows Nuclear.fermiDistributedNucleus exactly -- the same split of the Coulomb
integral into an inner and an outer part, the same quadrature tolerances -- with both integrands and
the normalisation carrying the extra weight (1 + w r^2/c^2). For w = 0 the two therefore agree to
the quadrature tolerance, which is checked as a regression test.JenaAtomicCalculator.Nuclear.threeParameterFermiRrms — Method
Nuclear.threeParameterFermiRrms(c::Float64, a::Float64, w::Float64) ... provides a value::Float64 for the root-mean-square radius [fm] of the three-parameter Fermi charge density rho(r) = rho_0 (1 + w r^2/c^2) / (1 + exp((r-c)/a)), in closed form.
The moments of the Fermi factor are analytic,
M_n = Int_0^Inf r^n / (1 + exp((r-c)/a)) dr = - n! a^(n+1) Li_(n+1)(-exp(c/a)),
and Math.polylogExp(x, s) is exactly Li_s(-exp(x)) (it wraps GSL's complete Fermi-Dirac integral).
With the weight 1 + w r^2/c^2 folded in,
<r^2> = [M_4 + (w/c^2) M_6] / [M_2 + (w/c^2) M_4],
which is the expression below. For w = 0 it collapses identically to 12 a^2 L_5 / L_3, i.e. to
Nuclear.fermiRrms, and that is used as a regression test of this whole model.
A value::Float64 is returned.JenaAtomicCalculator.Nuclear.uniformNucleus — Method
Nuclear.uniformNucleus(R::Float64, Z::Float64, grid::Radial.Grid) ... computes the effective, radial-dependent charge Z(r) for a uniformly-distributed nucleus with radius R [in fm] and nuclear charge Z. The full nuclear potential is then given by V_nuc = - Z(r)/r outside the nucleus; a potential::Radial.Potential is returned.
JenaAtomicCalculator.Nuclear.weisskopfUnit — Method
Nuclear.weisskopfUnit(mp::EmMultipole, A::Int64) ... to return one Weisskopf unit for the multipole mp and mass number A, in ATOMIC units, i.e. the single-particle estimate against which reduced nuclear transition probabilities B(mp) are conventionally quoted. A value::Float64 is returned.
With R = 1.2 A^(1/3) fm,
B_W(EL) = 1/(4 pi) * [3/(L+3)]^2 * R^(2L) [e^2 fm^(2L)]
B_W(ML) = 10/pi * [3/(L+3)]^2 * R^(2L-2) [mu_N^2 fm^(2L-2)]
so that B_W(M1) = 1.79 mu_N^2, independent of A, as it must be. The result is converted into atomic units
here, so that a caller never has to mix fm with a_0 or nuclear magnetons with atomic ones -- which is
precisely where the factors have gone missing before.Periodic table data
JenaAtomicCalculator.PeriodicTable.AbstractEnergyData — Type
abstract type PeriodicTable.AbstractEnergyData ... defines an abstract and a number of singleton types to deal with different data set for binding energies, ionization potentials, etc.
+ Larkins1977 ... F. Larkins' (1977) inner-shell (1s - 4p) subshell binding energies of the neutral atom;
Z = 1, ..., 45, with many (Z, subshell) combinations left undefined.
+ Nist2025 ... NIST's (2025) tabulated successive ionization potentials of the neutral atom and all its
ions, Z = 1, ..., 92; used by Empirical.ionizationPotential and by
Empirical.totalEnergy(data=Nist2025()); not supported by Empirical.bindingEnergy.
+ Williams2000 ... the subshell binding energies of Williams (2000), part of the LBNL X-Ray Data Booklet's
Table 1-1; Z = 1, ..., 36 only, shells 1s - 4p.
+ XrayDataBooklet ... the LBNL X-Ray Data Booklet's Table 1-1 [J. A. Bearden & A. F. Burr, Rev. Mod. Phys. 39,
125 (1967); M. Cardona & L. Ley, Photoemission in Solids I (1978); J. C. Fuggle &
N. Mårtensson, J. Electron Spectrosc. Relat. Phenom. 21, 275 (1980)] -- the same lineage
as Williams2000, and numerically identical wherever both are tabulated, but with the
fuller Z = 1, ..., 92 and shells 1s - 6p coverage; the default data set for
Empirical.bindingEnergy/scaledBindingEnergy and the functions built on them.JenaAtomicCalculator.PeriodicTable.AbstractRecombinationData — Type
abstract type PeriodicTable.AbstractRecombinationData ... defines an abstract and a number of singleton types to deal with different data sets of fitted recombination-rate-coefficient parameters.
+ Arnaud1985 ... M. Arnaud & R. Rothenflug, Astron. Astrophys. Suppl. Ser. 60, 425 (1985); their Table IIB
gives the dielectronic recombination fit parameters (ADI, BDI, T0, T1) for the H-like
sequence, but only for 4 specific ions: O VIII (Z=8), Mg XII (Z=12), Ca XX (Z=20),
Fe XXVI (Z=26) -- not a general Z-scaling formula. Their He-like sequence rate is instead
a genuine Z-scaling closed form (no table), which is implemented directly in
Empirical.dielectronicRecombinationPlasmaAlpha rather than stored here.JenaAtomicCalculator.PeriodicTable.AbstractYieldData — Type
abstract type PeriodicTable.AbstractYieldData ... defines an abstract and a number of singleton types to deal with different data sets for fluorescence, Auger and Coster-Kronig yields. These yields are dimensionless probabilities and are kept apart from the AbstractEnergyData above.
+ KrauseAdopted2016 ... applies the K-shell fluorescence yields as adopted by the xraylib project (2016)JenaAtomicCalculator.PeriodicTable.Element — Method
PeriodicTable.Element(charge::Int64, symbol::Symbol) ... simple constructur for defining an element A element::PeriodicTable.Element is returned.
JenaAtomicCalculator.PeriodicTable.Element — Type
struct PeriodicTable.Element ... defines a type for collecting data for each element.
+ nuclearCharge ::Int64 ... Nuclear charge
+ symbol ::Symbol ... Symbol of the element.
+ name ::String ... Name of the element.
+ mass ::Float64 ... Mean mass number of the element.
+ density ::Float64 ... Density of the element [g/cm^3].
+ firstIP ::Float64 ... First ionization potential [eV].
+ configuration ::String ... Ground configuration of the element.
+ atomicRadius ::Float64 ... Mean atomic radius of the neutral atom (Ghosh & Biswas, 2002).
+ polarizibility ::Float64 ... Mean polarizibility of the neutral atom (Ghosh & Biswas, 2002).
+ chemHardness ::Float64 ... Mean chemical hardness of the element (Ghosh & Biswas, 2002).JenaAtomicCalculator.PeriodicTable.Isotope — Method
PeriodicTable.Isotope(i::Int64) ... simple constructur for an empty instance of an isotope. A isotope::PeriodicTable.Isotope is returned.
JenaAtomicCalculator.PeriodicTable.Isotope — Type
struct PeriodicTable.Isotope ... defines a type for collecting data for an individual isotope.
+ massNumber ::Float64 ... Mass number of the isotope.
+ isotopeMass ::Float64 ... Mass of the isotope.
+ spin ::AngularJ64 ... Nuclear spin of the isotope
+ mu ::Float64 ... Magnetic dipole moment of the isotope in nuclear magnetons.
+ Q ::Float64 ... Electric quadrupole moment of the isotope.JenaAtomicCalculator.PeriodicTable.bindingEnergies_Larkins1977 — Method
PeriodicTable.bindingEnergies_Larkins1977(Z::Int64) ... to return the `stored values' of Larkins (1977) which are based on Sevier and others for an element with nuclear charge Z. An Array{Float64,1} of binding energies [in eV] is returned, with -1.0 standing for a subshell whose value this compilation does not give.
JenaAtomicCalculator.PeriodicTable.bindingEnergies_Williams2000 — Method
PeriodicTable.bindingEnergies_Williams2000(Z::Int64) ... former store_Williams2000(Z::Int64) ... to return the `stored values' of Williams et al. (2000), ... for the element with nuclear charge Z. An Array{Float64,1} of binding energies [in eV] is returned, with -1.0 standing for a subshell whose value this compilation does not give.
JenaAtomicCalculator.PeriodicTable.bindingEnergies_XrayDataBooklet — Method
PeriodicTable.bindingEnergies_XrayDataBooklet(Z::Int64) ... to return the `stored values' of Bearden et al. (1967), Cardona et al. (1978) and Fuggle et al. (1980) for the element with nuclear charge Z; all binding energies are given in eV. An Array{Float64,1} of binding energies [in eV] is returned, with -1.0 standing for a subshell whose value this compilation does not give.
JenaAtomicCalculator.PeriodicTable.dielectronicRecombinationParameters_Arnaud1985 — Method
PeriodicTable.dielectronicRecombinationParameters_Arnaud1985(Z::Int64) ... to return the H-like-sequence dielectronic recombination fit parameters (ADI, T0) of M. Arnaud & R. Rothenflug, Astron. Astrophys. Suppl. Ser. 60, 425 (1985), their Table IIB, for the bare, recombining nucleus of nuclear charge Z; the rate coefficient follows their Eq. (3) with BDI = 0 (as stated for all 4 tabulated ions, so the {1 + BDI exp(-T1/T)} bracket reduces to 1): alpha_d(T) [cm^3/s] = ADI * T^(-3/2) * exp(-T0/T), T, T0 in K, ADI in cm^3/s K^(3/2). Available for only 4 ions – O VIII (Z=8), Mg XII (Z=12), Ca XX (Z=20), Fe XXVI (Z=26) – since the paper tabulates specific ions rather than a general Z-scaling formula for this sequence. A (ADI, T0)::NTuple{2,Float64} is returned.
Note on transcription: Table IIB's column headers carry small unit-exponent annotations that are easy to
misread from a scanned 1985 paper. The values below were cross-checked by requiring T0 to scale
consistently with each ion's H-like ionization potential (Table I of the same paper): T0/IP works out to
55-60% across all 4 ions, a physically sensible and internally consistent ratio, which supports this
reading -- but the values should still be treated as best-effort and spot-checked against an independent
source before being relied on for precision work.JenaAtomicCalculator.PeriodicTable.fluorescenceYields_KrauseAdopted2016 — Method
PeriodicTable.fluorescenceYields_KrauseAdopted2016(Z::Int64) ... to provide the K-shell fluorescence yield omegaK of the neutral element with nuclear charge Z; this yield is the probability that a K-shell vacancy is filled radiatively rather than by an Auger transition, so that the associated Auger yield is simply aK = 1 - omega_K. The yields are dimensionless and are tabulated for Z = 3, ..., 100; a value of -1. is returned for Z = 1, 2, where a K-shell vacancy cannot decay radiatively. An omega::Float64 is returned.
Provenance (please read before relying on these numbers):
The values are those adopted by the xraylib project [data/fluor_yield.dat, as of the K-shell revision of
11-Apr-2016], which JAC follows here. Their history is layered and not fully documented upstream:
+ The base data of that file are due to M. Krause, C. Nestor Jr., C. Sparks Jr. and E. Ricci, "X-ray
fluorescence cross sections for K and L X-rays of the elements", ORNL-5399, Oak Ridge National
Laboratory (1978); this is the compilation behind M. O. Krause, J. Phys. Chem. Ref. Data 8, 307 (1979).
+ The K-shell values of that base data set were *replaced* in 2016 by the present ones. The xraylib
documentation names newer sources (Campbell 2009; Ayri et al. 2021; Kaur et al. 2021) only for the
L subshells, so that the origin of the revised K-shell values is not documented upstream.
+ The two sets differ appreciably: by factors 2 - 20 for Z <= 6 (Be: 3.3e-5 -> 6.9e-4), and in their trend
for heavy elements, where the ORNL-5399 values peak near Z = 74 (omega_K = 0.983) and fall off to 0.969
at Z = 92, whereas the adopted values rise monotonically to 0.972. The adopted values were preferred
because they are those in current use and because the ORNL-5399 set places Be below Li (omega_K decreasing
from Z = 3 to Z = 4), which is unphysical.
These yields are semi-empirical and should be understood as good to a few percent at best; cf. also the
review of Hubbell et al., J. Phys. Chem. Ref. Data 23, 339 (1994).JenaAtomicCalculator.PeriodicTable.getAtomicNumber — Method
PeriodicTable.getAtomicNumber(symbol::Symbol) ... returns the atomic number (nuclear charge Z) for the given element symbol.
JenaAtomicCalculator.PeriodicTable.getData — Method
PeriodicTable.getData(sa::String, zsymbol::Union{Int64,Symbol}) ... provides various data from the periodic table of elements.
("mass", Z::Int64)or("mass", symbol::Symbol)... to get mean mass value of the element with nuclear charge Z or symbol.("density", Z::Int64)or("density", symbol::Symbol)... to get the density [g/cm^3] of the element with nuclear charge Z or symbol.("1st IP", Z::Int64)or("1st IP", symbol::Symbol)... to get the first ionization potential [eV] of the element with nuclear charge Z or symbol.("ground configuration", Z::Int64)or("ground configuration", symbol::Symbol)... to get the ground configuration of the neutral atom with nuclear charge Z or symbol.("atomic radius", Z::Int64)or("atomic radius", symbol::Symbol)... to get the atomic radius of the neutral atom with nuclear charge Z or symbol.("polarizibility", Z::Int64)or("polarizibility", symbol::Symbol)... to get the polarizibility of the neutral atom with nuclear charge Z or symbol.("ground configuration", Z::Int64)or("ground configuration", symbol::Symbol)... to get the ground configuration of the neutral atom with nuclear charge Z or symbol.("chemical hardness", Z::Int64)or("chemical hardness", symbol::Symbol)... to get the chemical hardness of the neutral atom with nuclear charge Z or symbol. A value::Float64 for every key but "configuration", which gives a conf::Configuration, is returned.
JenaAtomicCalculator.PeriodicTable.getIsotopeData — Method
PeriodicTable.getIsotopeData(sa::String, zsymbol::Union{Int64,Symbol}) ... A STUB, and the docstring says so rather than advertising a call that raises. THE ONLY ACCEPTED KEYSTRING is "alpha" or "fine-structure constant alpha", which gives back FINE_STRUCTURE_CONSTANT; every other keystring raises, and zsymbol IS NOT READ AT ALL. Isotope data is not implemented here – PeriodicTable.Isotope is the type meant to carry it, and filling it needs isotope masses and abundances from a source still to be chosen and cited. Until 07-Nov-2026 this docstring offered a mass keystring, which has never existed – written here in words rather than as a call, because tools/checkDocstringKeystrings.py cannot tell an offer from a record of a withdrawn one and would read the example back as a live promise. A value::Float64 is returned.
JenaAtomicCalculator.PeriodicTable.ionizationPotentials_Nist2025 — Method
PeriodicTable.ionizationPotentials_Nist2025(Z::Int64) ... to return the `stored values' of the ionization potentials from NIST (2025) to readily estimate total and relative energies of atoms and ions. An Array{Float64,1} of ionization potentials [in eV] is returned, with -1.0 standing for a subshell whose value this compilation does not give.
Radial grids and orbitals
JenaAtomicCalculator.Radial.AbstractGridGaussLegendreScheme — Type
abstract type Radial.AbstractGridGaussLegendreScheme ... labels the kind of Gauss-Legendre grid to be constructed; it is used for dispatch and to avoid string comparisons. Concrete subtypes: + GridGaussLegendreQED ... generate a GL grid for QED computations over the interval [1, infinity). + GridGaussLegendreFinite ... generate a GL grid over a finite interval [tmin, tmax].
JenaAtomicCalculator.Radial.Density — Method
Radial.Density() ... constructor to define an 'empty' instance of the radial density. A density::Radial.Density is returned.
JenaAtomicCalculator.Radial.Density — Type
struct Radial.Density ... defines a struct for a radial density distribution.
+ name ::String ... A name for the radial density.
+ Dr ::Array{Float64,1} ... radial density function D(r).
+ grid ::RadialGrid ... radial grid on which the density is defined.JenaAtomicCalculator.Radial.Grid — Method
Radial.Grid(exponential::Bool; printout::Bool=false) ... constructor to define either a standard 'exponential' mesh (true) or a 'log-lin' mesh (false). A grid::Radial.Grid is returned.
JenaAtomicCalculator.Radial.Grid — Method
Radial.Grid(gr::Radial.Grid; rnt::Union{Nothing,Float64}=nothing, h::Union{Nothing,Float64}=nothing, hp::Union{Nothing,Float64}=nothing, rbox::Union{Nothing,Float64}=nothing, orderL::Union{Nothing,Int64}=nothing, orderS::Union{Nothing,Int64}=nothing, orderGL::Union{Nothing,Int64}=nothing, printout::Bool=false)
... constructor for modifying the given Radial.Grid by 'overwriting' the previously selected parameters.
The keyword nth= was removed on 12-Aug-2026. It was accepted and then silently dropped: the spacing
of the B-spline break points is set by orderGL in Radial.determineGrid, and Grid(gr; nth=3) left the
grid unchanged. Nothing in src/, examples/ or test/ ever passed it. A second knob for the same
quantity is not restored here; use orderGL.
A `grid::Radial.Grid` is returned.JenaAtomicCalculator.Radial.Grid — Method
Radial.Grid() ... constructor to define an 'empty' grid. A grid::Radial.Grid is returned.
JenaAtomicCalculator.Radial.Grid — Type
struct Radial.Grid ... the radial grid: its analytic definition, the B-spline break points that follow from it, and the mesh on which radial integrations are performed.
+ parameters ::Radial.GridParameters ... what was asked for.
+ knots ::Radial.KnotSequence ... the B-spline break points.
+ mesh ::Radial.RadialMesh ... the Gauss-Legendre mesh points and weights.
Until 12-Aug-2026 these seventeen numbers and arrays sat side by side in one flat struct, so that
nothing distinguished the definition from what was derived from it, and four of the fields (ntL, ntS,
nsL, nsS) duplicated information already present in the knots.
FOR COMPATIBILITY, AND BECAUSE THEY READ WELL, all the former field names remain available directly
on the Grid: grid.r, grid.wr, grid.rnt, grid.tL, grid.nsL and the rest all work exactly as before
(see Base.getproperty below). ntL, ntS, nsL and nsS are now COMPUTED from the knot sequence rather
than stored, which is the one behavioural difference: they can no longer be stale.JenaAtomicCalculator.Radial.GridGH — Method
Radial.GridGH(orderGH::Int64; printout::Bool=false) ... constructor to define Gauss-Hermite grid. A gridGH::Radial.GridGH is returned.
JenaAtomicCalculator.Radial.GridGH — Type
struct Radial.GridGH ... defines a type for Gauss-Hermite grid of given order
+ nt ::Int64 ... number of mesh points in the grid.
+ t ::Array{Float64,1} ... mesh points in the variable t.
+ wt ::Array{Float64,1} ... weights to the mesh points in t.JenaAtomicCalculator.Radial.GridGL — Method
Radial.GridGL(::GridGaussLegendreFinite, tmin::Float64, tmax::Float64, orderGL::Int64; printout::Bool=false) ... constructor to define Gauss-Legendre grid in the finite interval [tmin, tmax]. A gridGL::Radial.GridGL is returned.
JenaAtomicCalculator.Radial.GridGL — Method
Radial.GridGL(::GridGaussLegendreQED, orderGL::Int64; printout::Bool=false) ... constructor to define Gauss-Legendre grid for the typical QED computation in the interval [1.0, infinity). A gridGL::Radial.GridGL is returned.
JenaAtomicCalculator.Radial.GridGL — Method
Radial.GridGL() ... specified a default version of a Gauss-Legendre grid with 6 points in the interval [0.,1.]. A gridGL::Radial.GridGL is returned.
JenaAtomicCalculator.Radial.GridGL — Type
struct Radial.GridGL ... defines a type for Gauss-Legendre grid of given order but where the interval is hard-coded due to the given keystring
+ nt :Int64 ... number of mesh points in the grid.
+ t ::Array{Float64,1} ... mesh points in the variable t.
+ wt ::Array{Float64,1} ... weights to the mesh points in t.JenaAtomicCalculator.Radial.GridParameters — Type
struct Radial.GridParameters ... the ANALYTIC DEFINITION of the radial grid: the handful of numbers a user chooses, from which everything else follows.
+ rnt ::Float64 ... smallest grid point > 0.
+ h ::Float64 ... stepsize in the construction of the exponential grid.
+ hp ::Float64 ... asymptotic stepsize of the log-lin grid; hp = 0 gives a purely exponential one.
+ NoPoints ::Int64 ... No. of points of the physical grid, chosen so that its last point coincides
with the largest B-spline break point. NOTE that this counts the PHYSICAL
grid of the definition, which is a different quantity from the number of
mesh points length(mesh.r), even where the two happen to coincide.
+ orderGL ::Int64 ... order of the Gauss-Legendre integration; it also fixes the break points, by
taking every orderGL-th point of the physical grid.JenaAtomicCalculator.Radial.KnotSequence — Type
struct Radial.KnotSequence ... the B-SPLINE BREAK POINTS, separately for the large and the small component.
+ tL ::Array{Float64,1} ... radial break points for the B-splines of the large component.
+ tS ::Array{Float64,1} ... radial break points for the B-splines of the small component.
+ orderL ::Int64 ... B-spline order of the large components.
+ orderS ::Int64 ... B-spline order of the small components.
The counts ntL, ntS, nsL and nsS are NOT stored: they are functions of the above and are provided as
properties of Radial.Grid, so that they cannot fall out of step with the knots they describe.JenaAtomicCalculator.Radial.Orbital — Method
Radial.Orbital(label::String, energy::Float64) ... constructor for given string identifier and energy, and where useStandardGrid is set to true; the grid must be defined explicitly and neither the large and small components nor their derivatives are yet defined in this case. A orbital::Radial.Orbital is returned.
JenaAtomicCalculator.Radial.Orbital — Method
Radial.Orbital(subshell::Subshell, energy::Float64) ... constructor for given subshell and energy, and where useStandardGrid is set to true; the grid must be defined explicitly and neither the large and small components nor their derivatives are yet defined in this case. A orbital::Radial.Orbital is returned.
JenaAtomicCalculator.Radial.Orbital — Type
struct Radial.Orbital ... defines a type for a single-electron radial orbital function with a large and small component, and which can refer to either the standard or an explicitly given grid due to the logical flag useStandardGrid. Bound-state orbitals with energy < 0 are distinguished from free-electron orbitals by the flag isBound.
+ subshell ::Subshell ... Relativistic subshell.
+ isBound ::Bool ... Logical flag to distinguish between bound (true) and free-electron orbitals (false).
+ useStandardGrid ::Bool ... Logical flag for using the standard grid (true) or an explicitly given grid (false).
+ energy ::Float64 ... Single-electron energies of bound orbitals are always negative.
+ P ::Array{Float64,1} ... Large and ..
+ Q ::Array{Float64,1} ... small component of the radial orbital.
+ Pprime ::Array{Float64,1} ... dP/dr.
+ Qprime ::Array{Float64,1} ... dQ/dr.
+ grid ::Radial.Grid ... explic. defined radial grid for P, Q, if useStandardGrid = false.JenaAtomicCalculator.Radial.Potential — Method
Radial.Potential() ... constructor to define an 'empty' instance of the radial potential. A potential::Radial.Potential is returned.
JenaAtomicCalculator.Radial.Potential — Type
struct Radial.Potential ... defines a struct for a local radial potential.
+ name ::String ... A name for the potential.
+ Zr ::Array{Float64,1} ... radial potential function Z(r) = - r * V(r) as usual in atomic structure theory.
+ grid ::RadialGrid ... radial grid on which the potential is defined.JenaAtomicCalculator.Radial.RadialMesh — Type
struct Radial.RadialMesh ... the MESH on which radial functions are tabulated and integrated: a composite Gauss-Legendre rule laid over the intervals between the break points of the knot sequence.
+ r ::Array{Float64,1} ... mesh points, the Gauss-Legendre nodes of each interval of tL.
+ wr ::Array{Float64,1} ... the Gauss-Legendre weights belonging to r.JenaAtomicCalculator.Radial.SingleElecSpectrum — Method
`Radial.SingleElecSpectrum()` ... constructor for providing an 'empty' instance of this struct.
A `singleElecSpectrum::Radial.SingleElecSpectrum` is returned.JenaAtomicCalculator.Radial.SingleElecSpectrum — Type
struct Radial.SingleElecSpectrum ... defines a type for a (relativistic and quasi-complete) single-electron spectrum for different symmetries kappa and either (individually) Nkappa positive or Nkappa positive and negative states. All these orbitals are defined with regard to the same grid.
+ name ::String ... A name for this spectrum, may contain information about the original
type of basis functions.
+ symOrbitals ::Array{SingleSymOrbitals,1} ... Set of orbitals of the same kappa-symmetry.JenaAtomicCalculator.Radial.SingleSymOrbitals — Method
`Radial.SingleSymOrbitals()` ... constructor for providing an 'empty' instance of this struct.
A `singleSymOrbitals::Radial.SingleSymOrbitals` is returned.JenaAtomicCalculator.Radial.SingleSymOrbitals — Type
struct Radial.SingleSymOrbitals ... defines a type for a (relativistic and quasi-complete) single-electron spectrum for symmetry kappa with N positive and/or N negative states. All these states are defined with regard to the same grid.
+ kappa ::Int64 ... symmetry of the one-electron spectrum
+ NoStates ::Int64 ... Number of positive and negative states (if onlyPositive = true)
+ onlyPositive ::Bool ... True if only the positive part is kept.
+ pOrbitals ::Array{Orbital,1} ... Positive-energy orbitals states, in increasing order.
+ nOrbitals ::Array{Orbital,1} ... Negative-energy orbitals states, in increasing order.
+ grid ::RadialGrid ... radial grid on which the states are represented.Base.getproperty — Method
Base.getproperty(grid::Radial.Grid, s::Symbol) ... forwards the field names of the former flat Radial.Grid to the three structs that now hold them, and computes ntL, ntS, nsL and nsS from the knot sequence. About 700 accesses across JAC read these names; forwarding them is deliberate rather than transitional, since grid.r reads better than grid.mesh.r at the point of use. A literal grid.r is constant-folded and costs nothing.
JenaAtomicCalculator.Radial.determineGrid — Method
Radial.determineGrid(grid::Radial.Grid; printout::Bool=false) ... determines the detailed radial grid due to the given gridType and parameters; a gr::Radial.Grid is returned
JenaAtomicCalculator.Radial.determineNoPoints — Method
Radial.determineNoPoints(rnt::Float64, h::Float64, hp::Float64, rbox::Float64, orderGL::Int64) ... determines the number of points of the physical size if the grid parameters and the box-size is given; moreover, it is ensured that this NoPoints is consistent with the largest break point for the B-spline grid. An NoPoints::Int64 is returned.
JenaAtomicCalculator.Radial.determineZbar — Method
Radial.determineZbar(pot::Radial.Potential) ... determines the effective charge that is asymptotically seen by the electron in the potential pot. A Zbar::Float64 is returned.
JenaAtomicCalculator.Radial.generateGrid — Method
Radial.generateGrid(grid::Radial.Grid; boxSize::Union{Nothing,Float64}=nothing, boxSizeWithZeroWeights::Union{Nothing,Float64}=nothing, maximumFreeElectronEnergy::Union{Nothing,Float64}=nothing, maximumPrincipalQN::Union{Nothing,Int64}=nothing, lValue::Int64=0, Zeff::Union{Nothing,Float64}=nothing) ... generates a grid that fulfills a particular physical requirement. EXACTLY ONE of the four schemes below must be selected; a grid::Radial.Grid is returned and the reasoning is printed.
boxSize
... apply a fixed box size [a.u.], as an average-atom model needs. This does more than
Radial.Grid(grid; rbox=...): it afterwards rescales rnt so that the LAST BREAK POINT LANDS
EXACTLY ON THE REQUESTED SIZE. That is the reason this function exists -- for an average-atom
model the box IS the Wigner-Seitz radius, and a box that is merely close is a different
physical system.
boxSizeWithZeroWeights
... keep the grid and set the integration weights to zero beyond the given radius.
READ THIS BEFORE USING IT: that truncates INTEGRALS, it does NOT confine ORBITALS. The
B-spline basis still extends past the box, so the orbitals are entirely unchanged and only
their overlaps are cut short. It is not a model of a confined atom, and using it as one gives
a plausible-looking wrong answer.
maximumFreeElectronEnergy
... give a maximum free-electron energy [Hartree]; the asymptotic step hp is set so that the
shortest de Broglie wavelength is sampled with 40 points, the BOX IS HELD at its incoming
size, and the box is reported in wavelengths. This is the constructive counterpart of
Continuum.gridConsistency, which refuses below 15 points per oscillation and warns below 40.
THE BOX IS HELD DELIBERATELY, because Radial.Grid(grid; hp=...) keeps NoPoints fixed and so
lets the box follow hp. Refining hp alone would SHRINK the box in proportion -- measured
06-Nov-2026, from 15.3 to 8.0 wavelengths on the helium grid at 42 Hartree -- which buys
the sampling by spending the other requirement. Here the sampling is paid for in grid
points instead, so NoPoints rises (616 -> 945 on that case) and the box does not move.
WHY 40 AND NOT THE 20 THIS USED UNTIL 06-Nov-2026. Three convergence studies in this
repository put the 20 beyond defending. A 4.66 keV Auger rate is 5.6 % out at 17 points
per oscillation and converged to 0.02 % at 34 (06-Nov-2026); the 207Pb internal-conversion
orbital at 15.65 points comes back with an interior amplitude 3.3e+09 times its asymptotic
one, against 1.14 at 46.94 (22-Oct-2026); and across four systems the normalization constant
is 4 to 6 % out at 13 counted points and about 1 % out at 15 (06-Nov-2026). At 40 all four
of those systems are judged sound and reproduce their converged constant to better than
0.5 %. The cost is the point of stating it: halving hp roughly doubles the number of mesh
points in the asymptotic region, so this scheme is now about twice as expensive as it was.
AND 40 IS NOT A GUARANTEE, which matters more than the number. The error in a continuum
quantity is NOT monotone in the sampling density: measured 06-Nov-2026, two meshes at the
same 21 counted points per oscillation differ by 3.3 %, and uranium at 15 points is exact
while at 20 points it is 3.4 % out -- the matching point landing at an arbitrary phase of
the oscillation, the same signature Continuum.checkNormalizationRadius records for the
normalization radius. Nor is the sampling density the only requirement: measured
01-Sep-2026 on H 1s photoionization, a grid with 104 points per oscillation puts the two
gauges 6.7 % apart in a box of 2.88 wavelengths and 0.001 % apart in one of 4.77, at
IDENTICAL hp. So this scheme sets hp and reports the box, and HALVING hp UNTIL THE ANSWER
STOPS MOVING remains the only real check.
maximumPrincipalQN
... give the largest principal quantum number n to be represented; the box is set from the
hydrogenic outer turning point,
r_+ = (n^2/Zeff) (1 + sqrt(1 - l(l+1)/n^2)), rbox = 2.5 r_+
A BOX THAT IS TOO LARGE STARVES THE B-SPLINE BASIS EXACTLY AS BADLY AS ONE THAT IS TOO SMALL:
the number of splines is fixed, so a box much wider than the orbitals spends them on empty
space and the high-n members of each symmetry come back as a DIFFERENT STATE rather than an
inaccurate one -- which looks like an angular-momentum or kappa-sign bug and is not.
Bsplines.checkGridRepresentation and Bsplines.checkOrbitalConsistency detect that afterwards;
this scheme is the only thing in JAC that avoids it beforehand.
lValue defaults to 0, which gives the LARGEST turning point for the given n and hence the
safe box. Zeff must be given explicitly and is the EFFECTIVE charge: an outer electron of a
near-neutral system sees Zeff ~ Z - N + 1, not Z. Passing Z here is the standard way to get
a box several times too small.Radial integrals
JenaAtomicCalculator.RadialIntegrals.ScreenedPotentialCache — Type
struct RadialIntegrals.ScreenedPotentialCache ... holds a precomputed cache of kink-aware "screened potentials" Phi(i,i')(s), one for every overlapping pair of B-splines (i,i') from a GIVEN B-spline basis (e.g. primitives.bsplinesL or primitives.bsplinesS), for one fixed multipole rank k. THIS IS NOT ITSELF A PHYSICAL SLATER/RADIAL INTEGRAL – it is an auxiliary, basis-only tensor (it does not reference any orbital at all) from which many different direct and exchange two-electron radial integrals can afterwards be obtained CHEAPLY, by a simple grid-quadrature dot product against whatever B-spline or orbital density is actually needed (see RadialIntegrals.buildScreenedPotentialCache for how it is built, and SelfConsistent.computeTwoElectronV and SelfConsistent.computeFockMatrix for how it gets used – these are reached from solveAverageLevelField, solveOptimizedLevelField and solveAverageAtomField, each of which builds the LL, LS and SS caches once per rank and then reuses them for the whole SCF run). Until 13-Aug-2026 this sentence pointed instead at "computeDirectExchangeVTensor, once written", a function that was never written; the real consumers had meanwhile been in place and unnamed. Building this cache is the expensive, kink-aware step – it uses the SAME split-quadrature technique as buildScreenedPotentialPair, just applied ONCE per (basis-only) B-spline pair rather than once per SCF call; using it afterwards, many times over, for many different orbital pairs and many SCF iterations, is cheap. This follows the "moment array" idea underlying Zatsarinny \& Froese Fischer, Comput. Phys. Commun. 202, 287-303 (2016), their Eq. (16) – though here the array is stored in this partially- contracted Phi(i,i')(s) form, rather than as the full four-index R^k(ij;i'j') array of that paper, to avoid the O((N*band)^2) memory cost of also precomputing every (j,j') combination up front.
i and i' need NOT come from the same B-spline basis: a two-electron exchange-type integral needs the
LL and SS ("same-basis") combinations for its diagonal blocks, but ALSO an LS ("cross-basis") combination
for its off-diagonal blocks, since the large- and small-component B-spline bases share the same
underlying grid (just different spline orders) and therefore genuinely overlap with EACH OTHER too, not
only within themselves. See RadialIntegrals.buildScreenedPotentialCache for how the same-basis and
cross-basis cases are told apart and handled.
+ k ::Int64 ... the multipole rank this cache was built for
+ sameBasis::Bool ... true if this cache was built from two identical
B-spline lists (i.e. a same-basis/"LL" or "SS"
cache); false for a cross-basis/"LS" cache. Kept
here so a cache cannot be silently misused for the
wrong kind of contraction.
+ band ::Int64 ... the largest observed |i-i'| among overlapping
B-spline pairs (a property of the spline order,
kept here only as a diagnostic)
+ Phi ::Dict{Tuple{Int64,Int64}, Vector{Float64}} ... Phi[(i,i')] = the screened potential sourced from
the density B1_i(r)*B2_i'(r) (B1,B2 the two bases
this cache was built from, possibly identical),
tabulated on the standard grid; only present
(nonzero) for OVERLAPPING (i,i') pairs. i indexes
the FIRST basis, i' the SECOND.JenaAtomicCalculator.RadialIntegrals.GrantIL0 — Method
RadialIntegrals.GrantIL0(L::Int64, q::Float64, a::Radial.Orbital, b::Radial.Orbital, grid::Radial.Grid) ... computes Grant's (radial) integral for two relativistic orbitals: IL^0 (q; a,b) = int0^\infty dr jL (qr) [ Pa Q_b ] . A value::Float64 is returned.
JenaAtomicCalculator.RadialIntegrals.GrantILminus — Method
RadialIntegrals.GrantILminus(L::Int64, q::Float64, a::Radial.Orbital, b::Radial.Orbital, grid::Radial.Grid) ... computes Grant's (radial) integral for two relativistic orbitals: IL^- (q; a,b) = int0^\infty dr jL (qr) [ Pa Qb - Qa P_b ] . A value::Float64 is returned.
JenaAtomicCalculator.RadialIntegrals.GrantILplus — Method
RadialIntegrals.GrantILplus(L::Int64, q::Float64, a::Radial.Orbital, b::Radial.Orbital, grid::Radial.Grid) ... computes Grant's (radial) integral for two relativistic orbitals: IL^+ (q; a,b) = int0^\infty dr jL (qr) [ Pa Qb + Qa P_b ] . A value::Float64 is returned.
JenaAtomicCalculator.RadialIntegrals.GrantIab — Method
RadialIntegrals.GrantIab(a::Radial.Orbital, b::Radial.Orbital, grid::Radial.Grid, potential::Radial.Potential) ... computes the (radial) single-electron energy integral:
`I(ab) = <a | h_D | b> = delta_{kappa_a, kappa_b} int_0^infty dr [ c Q_a ( d/dr + kappa_a/r ) P_b + c P_a (-d/dr + kappa_a/r ) Q_b
- 2c^2 Q_a Q_b + V_nuc (r) (P_a P_b + Q_a Q_b) ]`
for the orbitals a and b on the grid. potential.Zr must provide the effective nuclear charge Z(r) on this grid.
A value::Float64 is returned.JenaAtomicCalculator.RadialIntegrals.GrantIabDamped — Method
RadialIntegrals.GrantIabDamped(tau::Float64, a::Radial.Orbital, b::Radial.Orbital, grid::Radial.Grid, potential::Radial.Potential) ... computes the (radial) single-electron energy integral:
`I(ab) = <a | h_D | b> = delta_{kappa_a, kappa_b} int_0^infty dr [ c Q_a ( d/dr + kappa_a/r ) P_b + c P_a (-d/dr + kappa_a/r ) Q_b
- 2c^2 Q_a Q_b + V_nuc (r) (P_a P_b + Q_a Q_b) ] * exp(-tau * r)`
for the orbitals a and b on the grid. potential.Zr must provide the effective nuclear charge Z(r) on this grid.
A value::Float64 is returned.JenaAtomicCalculator.RadialIntegrals.GrantJL — Method
RadialIntegrals.GrantJL(L::Int64, q::Float64, a::Radial.Orbital, b::Radial.Orbital, grid::Radial.Grid) ... computes Grant's (radial) integral for two relativistic orbitals: JL (q; a,b) = int0^\infty dr jL (qr) [ Pa Pb + Qa Q_b ] . A value::Float64 is returned.
JenaAtomicCalculator.RadialIntegrals.SlaterRk — Method
RadialIntegrals.SlaterRk(k::Int64, a::Radial.Orbital, b::Radial.Orbital, c::Radial.Orbital, d::Orbital, grid::Radial.Grid) ... computes the (relativistic) Slater integral
R^k (abcd) = int_0^infty dr int_0^infty ds (P_a P_c + Q_a Q_c) r_<^k / r_>^(k+1) (P_b P_d + Q_b Q_d)
of rank k for the four orbitals a, b, c, d, and over the given grid by using an explicit 2-dimensional integration scheme; a
value::Float64 is returned.JenaAtomicCalculator.RadialIntegrals.SlaterRkComponent — Method
RadialIntegrals.SlaterRkComponent(k::Int64, Ba::Array{Float64,1}, Bb::Array{Float64,1}, Bc::Array{Float64,1}, Bd::Array{Float64,1}, grid::Radial.Grid) ... computes one component of the (relativistic) Slater integral
R^k (abcd) = int_0^infty dr int_0^infty ds (P_a P_c + Q_a Q_c) r_<^k / r_>^(k+1) (P_b P_d + Q_b Q_d), namely
W^k (abcd) = int_0^infty dr int_0^infty ds B_a B_c r_<^k / r_>^(k+1) B_b B_d
of rank k for the four components Ba, Bb, ... above , and over the given grid by using an explicit 2-dimensional integration
scheme; a value::Float64 is returned.JenaAtomicCalculator.RadialIntegrals.SlaterRkDamped — Method
RadialIntegrals.SlaterRkDamped(tau::Float64, k::Int64, a::Radial.Orbital, b::Radial.Orbital, c::Radial.Orbital, d::Orbital, grid::Radial.Grid) ... computes the (relativistic) Slater integral
R^k (abcd) = int_0^infty dr int_0^infty ds (P_a P_c + Q_a Q_c) r_<^k / r_>^(k+1) (P_b P_d + Q_b Q_d) * exp(-tau * r - tau*s)
of rank k for the four orbitals a, b, c, d, and over the given grid by using an explicit 2-dimensional integration scheme; a
value::Float64 is returned.JenaAtomicCalculator.RadialIntegrals.SlaterRkDebyeHueckel — Method
RadialIntegrals.SlaterRkDebyeHueckel(k::Int64, a::Radial.Orbital, b::Radial.Orbital, c::Radial.Orbital, d::Orbital, grid::Radial.Grid, lambda::Float64) ... computes the (relativistic) Slater-Debye-Hueckel integral
R^k (abcd) = int_0^infty dr int_0^infty ds (P_a P_c + Q_a Q_c) [r_<^k / r_>^(k+1)]^(DH screened) (P_b P_d + Q_b Q_d)
of rank k for the four orbitals a, b, c, d, and over the given grid by using an explicit 2-dimensional integration
scheme; a value::Float64 is returned.JenaAtomicCalculator.RadialIntegrals.SlaterRkKinkAware — Method
RadialIntegrals.SlaterRkKinkAware(k::Int64, a::Radial.Orbital, b::Radial.Orbital, c::Radial.Orbital, d::Radial.Orbital, grid::Radial.Grid, vkCache::Dict{Tuple{Int64,Subshell,Subshell,Int64},Vector{Float64}}; rtol::Float64=1.0e-9) ... as the method without a cache, but memoising the screened potential V_k, which is the expensive part and depends on only TWO of the four orbitals. A value::Float64 is returned.
WHY THIS PAYS, measured 03-Sep-2026. The integral is int P_a(r) V_k[b,d](r) P_c(r) dr, and the inner
sum over r is a handful of multiplications while `buildScreenedPotential` costs ~1.4 ms -- an adaptive
quadrature and a spline through the (b,d) density. In the level-optimised field the same (k,b,d) triple
recurs across different (a,c) pairs: measured on a three-layer beryllium RAS, 358 coefficients carry only
180 distinct triples, a redundancy of 1.99x at the correlating layer. The caller's own cache over the
FULL coefficient quintuple cannot catch this -- it was measured to miss 100 % of the time, every
coefficient carrying a unique (k,a,b,c,d) -- because the reuse lives one level down.
THE KEY CARRIES mtpOut, WHICH IS NOT REDUNDANT EVEN THOUGH IT IS CONSTANT IN THE SCF. V_k is tabulated
only out to the extent of (a,c), so a potential built for a short (a,c) pair must not be handed to a
longer one -- exactly the dropped-tail trap that `buildScreenedPotential`'s own docstring warns about and
that moved an approved AutoIonization reference by 100 % on 13-Aug-2026. Every bound orbital of a
B-spline basis reaches the box boundary, so in the SCF the extent is the same for every pair and the
cache hits regardless (measured: truncated and full builds cost the same to 1 %); on the Auger path,
where (a,c) may hold a continuum orbital and (b,d) be short, the key is what keeps this correct.
THE CACHE IS OWNED BY THE CALLER AND MUST NOT OUTLIVE THE ORBITALS IT WAS BUILT FROM. It is keyed on
SUBSHELL LABELS, so a cache carried across an SCF iteration would hand back a potential computed for an
earlier orbital shape. A caller inside an iteration creates a fresh one per evaluation; only a caller
that knows its orbitals are frozen may keep one longer.JenaAtomicCalculator.RadialIntegrals.SlaterRkKinkAware — Method
RadialIntegrals.SlaterRkKinkAware(k::Int64, a::Radial.Orbital, b::Radial.Orbital, c::Radial.Orbital, d::Radial.Orbital, grid::Radial.Grid; rtol::Float64=1.0e-9) ... computes the same (relativistic) Slater integral as SlaterRk,
R^k (abcd) = int_0^infty dr int_0^infty ds (P_a P_c + Q_a Q_c) r_<^k / r_>^(k+1) (P_b P_d + Q_b Q_d)
but via the kink-aware screened potential RadialIntegrals.buildScreenedPotential(k,b,d,grid) instead of
the naive tensor-product Gauss-Legendre double sum SlaterRk uses (which is exact for smooth polynomials
within a break-point cell, but not for a function with a first-derivative discontinuity running through the
middle of one, as r_</r_>^(k+1) has at r=s). Since V_k(r) is smooth once built, the outer integral over r can
safely reuse the existing grid quadrature weights -- no further adaptive treatment is needed there.
A value::Float64 is returned.JenaAtomicCalculator.RadialIntegrals.SlaterRkReference — Method
RadialIntegrals.SlaterRkReference(k::Int64, a::Radial.Orbital, b::Radial.Orbital, c::Radial.Orbital, d::Orbital, grid::Radial.Grid) ... computes the (relativistic) Slater integral
R^k (abcd) = int_0^infty dr int_0^infty ds (P_a P_c + Q_a Q_c) r_<^k / r_>^(k+1) (P_b P_d + Q_b Q_d)
of rank k for the four orbitals a, b, c, d, and over the given grid by using an explicit 2-dimensional integration scheme
but without optimization (WO); a value::Float64 is returned.JenaAtomicCalculator.RadialIntegrals.V0 — Method
RadialIntegrals.V0(wa::Array{Float64,1}, mtp::Int64, grid::Radial.Grid) ... computes the (radial) integral int_0^infty dr wa; a value::Float64 is returned.
JenaAtomicCalculator.RadialIntegrals.Vinti — Method
RadialIntegrals.Vinti(a::Radial.Orbital, b::Radial.Orbital, grid::Radial.Grid) ... computes the (radial) Vinti integral for the two radia integrals a and b:
[ d kappa_a (kappa_a+1) - kappa_b (kappa_b+1) ]
R^(Vinti) = int_0^infty dr P_a [ -- - ------------------------------------------ ] P_b + similar (not equal) in Q_a, Q_b
[ dr 2 r ]
a value::Float64 is returned.JenaAtomicCalculator.RadialIntegrals.W5_Integral — Method
RadialIntegrals.W5_Integral(mu::Int64, nu::Int64, a::Radial.Orbital, b::Radial.Orbital, c::Radial.Orbital, d::Radial.Orbital, grid::Radial.Grid) ... computes the (radial) integral for four relativistic orbitals:
W_5 [ac|bd] = int_0^infty dr int_0^r ds [Pa Qc]_{r} * ( s^nu / r^(nu+1) ) * [Pb Qd]_{s}
as it frequently occurs in the frequency-independent Breit interaction.
A value::Float64 is returned.JenaAtomicCalculator.RadialIntegrals.Yk_ab — Method
RadialIntegrals.Yk_ab(k::Int64, r::Float64, rho_ab::Array{Float64,1}, mtp::Int64, grid::Radial.Grid) ... computes the (radial) integral
r<^k
Y_ab^k (r) = r * int_0^infty dr' ------ rho_ab(r')
r>^k+1
a value::Float64 is returned.JenaAtomicCalculator.RadialIntegrals.buildScreenedPotential — Method
RadialIntegrals.buildScreenedPotential(k::Int64, b::Radial.Orbital, d::Radial.Orbital, grid::Radial.Grid; rtol::Float64=1.0e-9, mtpOut::Union{Nothing,Int64}=nothing) ... computes the "screened potential"
V_k(r) = (1/r^(k+1)) int_0^r ds s^k rho_bd(s) + r^k int_r^r_max ds s^{-(k+1)} rho_bd(s),
rho_bd(s) = P_b(s)P_d(s) + Q_b(s)Q_d(s),
i.e. the r-dependent potential felt (via the Coulomb interaction of rank k) from the fixed orbital pair
(b,d), evaluated at every tabulated grid point r = grid.r[i]. This is the auxiliary quantity underlying
the two-electron Slater integral R^k(abcd) = int dr rho_ac(r) V_k(r); since V_k depends only on (b,d),
not on whatever it is later contracted against, it only needs to be built ONCE per orbital pair and can
then be reused cheaply (via the existing, already-tabulated grid quadrature, since V_k(r) is itself
smooth/kink-free once built correctly) for every downstream contraction -- e.g. RadialIntegrals.
SlaterRkKinkAware below, or a B-spline matrix element as needed for SCF orbital optimization.
The kink that the original r_</r_>^(k+1) kernel has at r=s is handled explicitly here: for each outer
point r WITHIN the source density's own extent, the integral over s is split into [0,r] and [r,r_max]
-- each smooth on its own -- rather than integrated across the kink with a single quadrature rule as
SlaterRk does. For r BEYOND the source's own extent (rho_bd is by construction zero there), V_k(r)
reduces to a single r-independent constant divided by r^(k+1) -- the standard multipole falloff of a
localized source -- computed once and reused for every such r, no adaptive quadrature needed there.
Getting this "beyond the source" branch right matters: it is NOT optional truncation. When V_k feeds a
B-spline MATRIX element (rather than a pre-truncated orbital-orbital integral), the matrix's row/column
B-splines span the FULL basis and can extend well past a compact orbital pair (b,d)'s own reach (e.g. a
2p orbital screening a 1s row built from B-splines spanning the whole grid) -- silently ending V_k's
array at the source's own extent, as an earlier version of this function did, drops that entire tail
contribution and was traced to a real, non-negligible bug: Ne's 1s orbital came out MEASURABLY too
deeply bound (eigenvalue off by roughly a fifth from the experimental K-shell value) because its Fock
matrix was silently missing part of its direct screening from the 2p shell.
rho_bd(s) is represented as a cubic spline (Dierckx.Spline1D) over the tabulated grid values, and each
piece is evaluated by a FIXED eight-point Gauss-Legendre rule per cell (RadialIntegrals.cellIntegral,
GBL_GaussLegendreCell) -- not, as this paragraph said until 05-Sep-2026, by adaptive Gauss-Kronrod:
the adaptive form was replaced when the sweep was introduced, since one grid cell is smooth and needs
no subdivision, and the description was not updated with it.
BOTH integrals are accumulated by a SINGLE SWEEP over the grid rather than integrated afresh at every
point: the inner moment grows with r and the outer moment shrinks with r, so each differs from its
neighbour by exactly one grid cell. An earlier version ran two full-range adaptive quadratures at each
of the ~1500 grid points, integrating the same material O(N) times over; profiling of both the SCF and
the CI paths (09-Aug-2026) put ~94% of a configuration-interaction matrix build inside this one loop.
The forward/backward sweeps are the standard construction (Hartree's Y_k, GRASP's YZK). Note that it is
the SPLIT AT THE KINK that is essential, not its repetition -- the split is retained exactly; only the
redundant re-integration is gone. Per-cell quadrature also keeps the same rtol while converging more
reliably, since one grid cell is smooth and needs no subdivision.
mtpOut lets the caller request the FULL range actually needed (e.g. grid.NoPoints for a
B-spline matrix element); left unspecified, it defaults to min(size(b.P,1),size(d.P,1)) as before, which
remains correct wherever V_k is only ever contracted against something ALSO naturally truncated to that
same orbital-pair extent (e.g. SlaterRkKinkAware).
A Vk::Vector{Float64}, of length mtpOut (or min(size(b.P,1),size(d.P,1)) if mtpOut is not given), is
returned.JenaAtomicCalculator.RadialIntegrals.buildScreenedPotentialCache — Method
RadialIntegrals.buildScreenedPotentialCache(k::Int64, bsplines1::Array{<:Any,1}, bsplines2::Array{<:Any,1}, grid::Radial.Grid; rtol::Float64=1.0e-9) ... builds a RadialIntegrals.ScreenedPotentialCache for multipole rank k from TWO lists of B-splines – typically primitives.bsplinesL and/or primitives.bsplinesS. For every pair (i,i'), i from bsplines1 and i' from bsplines2, whose supports overlap, the kink-aware screened potential
Phi_(i,i')(s) = int_0^infty dr B1_i(r) B2_i'(r) * r_<^k / r_>^(k+1)
is built ONCE, via RadialIntegrals.buildScreenedPotentialPair applied to the (compact-support)
density B1_i*B2_i', and cached. AGAIN: THIS IS NOT ITSELF A PHYSICAL SLATER INTEGRAL -- it is the
reusable, basis-only building block from which any two-electron direct or exchange radial integral for
this rank k can later be obtained cheaply, without repeating the expensive kink-aware quadrature on
every SCF call. Because B-splines only overlap with a small number of neighbors, the returned cache is
sparse (banded) in (i,i'), not a dense N x N object.
Whether bsplines1 and bsplines2 are the SAME list matters and is recognized explicitly (by object
identity, ===), not left for the caller to track:
- SAME list (e.g. both primitives.bsplinesL, or both primitives.bsplinesS): Phi_(i,i') is then
symmetric, Phi_(i,i')=Phi_(i',i), so only the i<=i' triangle is computed and mirrored into storage.
This is the common "LL" or "SS" case.
- DIFFERENT lists (e.g. primitives.bsplinesL and primitives.bsplinesS): no symmetry can be assumed -- an
index i from bsplines1 and an index i' from bsplines2 are not interchangeable, since the two bases can
have different spline orders (and therefore different [lower,upper] support ranges) even though they
live on the same grid. The full, non-mirrored set of overlapping pairs is computed instead, and
overlap is tested explicitly via each B-spline's own [lower,upper] range rather than assuming any
shared ordering convention between the two lists. This is the "LS" (equivalently "SL", with the two
lists swapped) case, needed for the off-diagonal blocks of an exchange-signature Fock matrix.
A RadialIntegrals.ScreenedPotentialCache is returned, with its sameBasis field set accordingly.JenaAtomicCalculator.RadialIntegrals.buildScreenedPotentialPair — Method
RadialIntegrals.buildScreenedPotentialPair(k::Int64, Ba::Vector{Float64}, orbComp::Vector{Float64}, grid::Radial.Grid; rtol::Float64=1.0e-9, mtpOut::Union{Nothing,Int64}=nothing) ... computes the same kind of "screened potential"
V_k(r) = (1/r^(k+1)) int_0^r ds s^k rho(s) + r^k int_r^r_max ds s^{-(k+1)} rho(s),
rho(s) = Ba(s) * orbComp(s),
as RadialIntegrals.buildScreenedPotential, but for a DENSITY BUILT FROM A SINGLE B-SPLINE (Ba,
a zero-padded array with support limited to that spline's own knot interval) times a single component
(P or Q) of a fixed orbital, rather than a full P_bP_d+Q_bQ_d orbital-pair density. This is the
building block for the "exchange"-signature InteractionStrength.XL_CoulombKinkAware, where -- unlike the
"direct" signature -- BOTH B-spline indices sit on opposite sides of the two-electron kernel, so no
single screened potential can be shared across the whole (nsL+nsS) x (nsL+nsS) matrix. Instead, one such
potential is built per ROW (per "a" B-spline), using only that spline's own compact support to define
rho, and then reused cheaply against every column ("d" B-spline) of that row.
V_k(r) is evaluated out to the full extent of orbComp by default (not just Ba's own narrow support),
since even a spatially localized source density still produces a potential everywhere via its
1/r^(k+1) tail; for r beyond Ba's support this tail integral is a single r-independent constant,
computed once and then just divided by r^(k+1) at each point -- so only the (typically few) grid points
inside Ba's own support incur the cost of an adaptive quadrature split at the kink.
Within that support the two moments are accumulated by a forward and a backward SWEEP over the grid
cells, for the same reason as in buildScreenedPotential: consecutive points differ by one cell,
so re-integrating the whole sub-range at each point repeats work. fullInner and fullOuter are the end
values of those same sweeps, so they cannot drift away from the pointwise values.
The optional mtpOut lets the caller request a LONGER output range explicitly -- needed, for instance, by
RadialIntegrals.buildScreenedPotentialCache, where BOTH Ba and orbComp are themselves compact B-splines
(not a broad orbital), so size(orbComp,1) alone would be far too short for how the result is used later.
A Vk::Vector{Float64}, of length mtpOut (or size(orbComp,1) if mtpOut is not given), is returned.JenaAtomicCalculator.RadialIntegrals.cellIntegral — Method
RadialIntegrals.cellIntegral(f, a::Float64, b::Float64) ... integrates f over the single interval [a,b] with a fixed 8-point Gauss-Legendre rule; a Float64 is returned. Used only by the screened-potential sweeps, where each interval is one grid cell and the integrand is smooth on it.
JenaAtomicCalculator.RadialIntegrals.countScreenedPotentials — Method
RadialIntegrals.countScreenedPotentials(onOff::Bool) ... switches the item-47 counters on or off and clears them; nothing is returned. While on, every call to buildScreenedPotential records its (k, b, d) and its (b, d), so that the REDUNDANCY ACROSS RANKS can be read off afterwards with RadialIntegrals.reportScreenedPotentials().
JenaAtomicCalculator.RadialIntegrals.isotope_boson — Method
RadialIntegrals.isotope_boson(a::Orbital, b::Orbital, potential::Array{Float64,1}, grid::Radial.Grid) ... computes the boson-field shift radial integral int_o^infty ... A value::Float64 is returned.
JenaAtomicCalculator.RadialIntegrals.isotope_field — Method
RadialIntegrals.isotope_field(a::Orbital, b::Orbital, deltaPotential::Array{Float64,1}, grid::Radial.Grid) ... computes the field-shift radial integral int_o^infty ... A value::Float64 is returned.
JenaAtomicCalculator.RadialIntegrals.isotope_nms — Method
RadialIntegrals.isotope_nms(a::Orbital, b::Orbital, Z::Float64, grid::Radial.Grid) ... computes the normal mass shift radial integral int_o^infty ... A value::Float64 is returned.
JenaAtomicCalculator.RadialIntegrals.isotope_smsB — Method
RadialIntegrals.isotope_smsB(a::Orbital, c::Orbital, Z::Float64, grid::Radial.Grid) ... computes the specific mass shift radial integral int_o^infty ... A value::Float64 is returned.
JenaAtomicCalculator.RadialIntegrals.isotope_smsC — Method
RadialIntegrals.isotope_smsC(a::Orbital, c::Orbital, Z::Float64, grid::Radial.Grid) ... computes the specific mass shift radial integral int_o^infty ... A value::Float64 is returned.
JenaAtomicCalculator.RadialIntegrals.overlap — Method
RadialIntegrals.overlap(orbital1::Radial.Orbital, orbital2::Radial.Orbital, grid::Radial.Grid)
- (orbital1::Radial.Orbital, orbital2::Radial.Orbital, grid::Radial.Grid)` ... computes the (radial) overlap integral <orbitala|orbitalb> for two relativistic orbitals of the same symmetry (kappa). A value::Float64 is returned.
JenaAtomicCalculator.RadialIntegrals.overlap — Method
RadialIntegrals.overlap(p1List::Array{Float64,1}, p2List::Array{Float64,1}, grid::Radial.Grid) ... computes the (radial) overlap integral of two (non-relativistic) radial orbital functions <p1|p2> as defined on grid. A value::Float64 is returned.
JenaAtomicCalculator.RadialIntegrals.qedDampedOverlap — Method
RadialIntegrals.qedDampedOverlap(lambda::Float64, a::Radial.Orbital, b::Radial.Orbital, grid::Radial.Grid) ... computes the damped (radial) integral int0^infty (Pa Pb + Qa Q_b) * e^{r/lambda} for the radial orbitals a, b on the given grid. A value::Float64 is returned.
JenaAtomicCalculator.RadialIntegrals.qedElectricFormFactor — Method
RadialIntegrals.qedElectricFormFactor(a::Radial.Orbital, b::Radial.Orbital, nm::Nuclear.Model, grid::Radial.Grid, qgrid::Radial.GridGL) ... computes the (radial) integral for the high-frequency electric self-energy form-factor contribution (point-like nucleus) for the radial orbitals a, b on the given grid; cf. Flambaum & Ginges, PRA 72, 052115 (2005), eq. (10), with the coefficient A(Z,r) taken from Kozioł's Rci-Q re-fit (arXiv:2512.01515, Table I) for s-orbitals (kappa=-1), where FG's original generic fit is known (per Rci-Q's own text) to be poorly suited for inner shells; p/d/f orbitals still use FG's original generic fit – a documented, narrower scope, mirroring Petersburg's own n<=4/kappa-restricted note. A value::Float64 is returned.
JenaAtomicCalculator.RadialIntegrals.qedLowFrequency — Method
RadialIntegrals.qedLowFrequency(a::Radial.Orbital, b::Radial.Orbital, nm::Nuclear.Model, grid::Radial.Grid, qgrid::Radial.GridGL) ... computes the (radial) integral for the low-frequency QED potential for the radial orbitals a, b on the given grid. A value::Float64 is returned.
JenaAtomicCalculator.RadialIntegrals.qedMagneticFormFactor — Method
RadialIntegrals.qedMagneticFormFactor(a::Radial.Orbital, b::Radial.Orbital, nm::Nuclear.Model, grid::Radial.Grid, qgrid::Radial.GridGL) ... computes the (radial) integral for the magnetic self-energy form-factor contribution (point-like nucleus) for the radial orbitals a, b on the given grid; cf. Flambaum & Ginges, PRA 72, 052115 (2005), eq. (7). Unlike the electric-type QED terms, the magnetic form factor couples the large and small radial components (a P-Q cross term) rather than PP + QQ. A value::Float64 is returned.
JenaAtomicCalculator.RadialIntegrals.qedUehling — Method
RadialIntegrals.qedUehling(a::Radial.Orbital, b::Radial.Orbital, nm::Nuclear.Model, grid::Radial.Grid, qgrid::Radial.GridGL) ... computes the (radial) integral for the Uehling potential for the radial orbitals a, b on the given grid. This included a formal t-integration that is performed internally on the (QED) grid qgrid. A value::Float64 is returned.
JenaAtomicCalculator.RadialIntegrals.qedUehlingSimple — Method
RadialIntegrals.qedUehlingSimple(a::Radial.Orbital, b::Radial.Orbital, pot::Radial.Potential, grid::Radial.Grid, qgrid::Radial.GridGL) ... computes the (radial) integral for the Uehling potential for the radial orbitals a, b on the given grid. This included a formal t-integration that is performed internally on the (QED) grid qgrid. A value::Float64 is returned.
JenaAtomicCalculator.RadialIntegrals.qedWichmannKrollSimple — Method
RadialIntegrals.qedWichmannKrollSimple(a::Radial.Orbital, b::Radial.Orbital, nm::Nuclear.Model, pot::Radial.Potential, grid::Radial.Grid, qgrid::Radial.GridGL) ... computes the (radial) integral for the simplified Wichmann-Kroll vacuum-polarization contribution for the radial orbitals a, b on the given grid; cf. Flambaum & Ginges, PRA 72, 052115 (2005), eq. (12). A closed-form (non-t-integrated) correction; qgrid is accepted only for interface consistency with the other local QED terms and is not used. A value::Float64 is returned.
JenaAtomicCalculator.RadialIntegrals.reportScreenedPotentials — Method
RadialIntegrals.reportScreenedPotentials() ... returns (calls, rankedKeys, pairKeys) for the calls to buildScreenedPotential seen since countScreenedPotentials(true). pairKeys is what a spline shared across multipole ranks would cost, rankedKeys what it costs today, and their ratio is the saving available.
JenaAtomicCalculator.RadialIntegrals.rkDiagonal — Method
RadialIntegrals.rkDiagonal(k::Int64, a::Radial.Orbital, b::Radial.Orbital, grid::Radial.Grid) ... computes the (radial and diagonal) integral of r^k for two radial orbital functions.
- (k::Int64, a::Radial.Orbital, b::Radial.Orbital, grid::Radial.Grid)` ... computes this integral for two relativistic orbitals: < r^k >ab = int0^\infty dr [Pa Pb + Qa Qb] r^k A value::Float64 is returned.
JenaAtomicCalculator.RadialIntegrals.rkDiagonal — Method
RadialIntegrals.rkDiagonal(k::Int64, p1List::Array{Float64,1}, p2List::Array{Float64,1}, grid::Radial.Grid) ... computes this integral for two non-relativistic orbitals: < r^k >ab = int0^\infty dr [Pa Pb] r^k A value::Float64 is returned.
JenaAtomicCalculator.RadialIntegrals.rkNonDiagonal — Method
RadialIntegrals.rkNonDiagonal(k::Int64, a::Radial.Orbital, b::Radial.Orbital, grid::Radial.Grid) ... computes the (radial and non-diagonal) integral of r^k for two relativistic orbitals: [ r^k ]ab = int0^\infty dr [Pa Qb + Qa Pb] r^k A value::Float64 is returned.
Self-consistent field
JenaAtomicCalculator.SelfConsistent.PairCoefficientCache — Type
struct SelfConsistent.PairCoefficientCache ... holds the orbital-independent angular coefficients of every CSF pair of ONE symmetry block, in a form whose size is set by the number of DISTINCT labels and values rather than by the number of pair-entries.
WHY IT IS NOT A `Dict` OF `Vector`s ANY MORE. It was, until 14-Sep-2026, and that cost 1.55 MB per CSF
against 0.181 for a plain Coulomb CI of the same ion -- about ten times more -- which is what put an open
d shell out of reach whatever the machine: a Ti III layer of 25 085 CSF was killed at a predicted 72 GB.
The CI matrix was never the problem; it IS built and diagonalised per symmetry block. The STORAGE was,
because every block's cache is held for the whole SCF run (the EOL target levels span symmetries and each
outer iteration revisits them) and because the old form paid a `Vector` header for every one of the n^2
ordered pairs, including the empty ones.
THE THREE REDUNDANCIES, MEASURED 13-Sep-2026 on the J = 2+ block of a Ti III 3p-opened space, 239 CSF:
57 121 ordered pairs, of which 34 686 (61 %) carry NOTHING and still held an empty Vector;
140 585 coefficient entries drawn from only 437 distinct (nu,a,b,c,d) labels -> 321 x reuse;
the same entries drawn from 15 560 distinct values -> 9 x reuse.
So: FLAT CSR arrays instead of a Dict of Vectors, so an empty pair costs one Int32 and no header; the
labels INTERNED in a table, an Int32 index per entry; the values likewise. Measured 11.4 x smaller on
that block, and the gain GROWS with block size, which is where it is needed.
NOT DONE, and deliberately: the further factor of two from hermiticity. `buildCIMatrixEOL` uses only
r <= s, but `combineAngularCoefficientsEOL` uses every ordered pair, so dropping the lower triangle needs
the relation between the (r,s) and (s,r) coefficient lists PROVED rather than assumed. It is the smallest
of the available gains and the only one resting on an unverified claim.
+ idxCsf ::Array{Int64,1} ... indices, in the full basis, of the CSFs of this block.
+ subshells ::Array{Subshell,1} ... the basis subshell list, so a label index can be turned back
into a Subshell.
+ labels1p ::Array{NTuple{3,Int64},1} ... distinct (nu, a, b) as subshell INDICES.
+ labels2p ::Array{NTuple{5,Int64},1} ... distinct (nu, a, b, c, d) as subshell indices.
+ values ::Array{Float64,1} ... distinct coefficient values, shared by the one- and two-particle
parts.
+ pairPtr ::Array{Int32,1} ... start of column s in `pairRow`; length n+1.
+ pairRow ::Array{Int32,1} ... the r of each STORED pair, ascending within a column.
+ ptr1p, lab1p, val1p ... CSR pointer and the two index arrays, one-particle; `ptr1p`
is indexed by the PAIR ORDINAL and has length nPairs+1.
+ ptr2p, lab2p, val2p ... the same, two-particle.
**THE PAIR INDEX IS SPARSE.** Until 11-Oct-2026 `ptr1p` and `ptr2p` were indexed by `k = (s-1)n + r`
and therefore had n^2+1 entries each, whatever the coupling actually was. A two-body operator connects
only CSFs that differ by at most a double substitution, so most pairs of a correlation space carry no
coefficient at all; the 14-Sep-2026 CSR redesign made an empty pair cheap to STORE but not to REACH,
because the pointer arrays stayed dense. A pair that produces no coefficient is now not indexed at
all, so every array here is O(coupling pairs), and the pair ordinal is found by a binary search in
`pairRow`.
**MEASURED, BECAUSE THE NATURAL GUESS IS WRONG.** The pair matrix is NOT sparse in the asymptotic
sense: the stored fraction falls with block size but plateaus, measured 37.5 % at n=77, 25.5 % at
n=312 and 19.8 % at n=783 for a core-valence singles-and-doubles space. So the cache still grows as
n^2 and this change is a constant factor, not a change of order -- the index 1.8-3.4 x smaller and the
cache as a whole 1.2-1.6 x. Two consequences worth knowing before relying on it:
* A space with ONE frozen core, where no two CSFs are further apart than a double substitution, stores
essentially every pair. The index is then 1.5 x LARGER than the dense form it replaced, since the
old one cost 8n^2 bytes and this one costs 12P; the break-even is P/n^2 = 2/3. That case is
harmless only because full coupling happens in small blocks, where the index is kilobytes.
* The binary search replaces a multiply-add on the READ path, which the EOL gradient walks once per
ordered pair. Measured 82 % slower per lookup and 8 ms per full sweep of 551 424 coefficients at
n=783, against ~150 s for one EOL iteration at that scale: real, and irrelevant.JenaAtomicCalculator.SelfConsistent.ScfVerdict — Type
struct SelfConsistent.ScfVerdict ... what the EOL rotation solver concluded about its own run, in numbers a caller can assert on rather than text a caller must grep. It is ADVICE and never a gate: nothing in JAC reads it, no computation is blocked by it, and a surprising physical result must remain obtainable with every field looking wrong.
+ converged ::Bool ... advice, NOT a proof. It means the run reached a stationary point TO
MACHINE RESOLUTION FROM THIS START. It does NOT mean the minimum:
measured 10-Sep-2026, two legitimate starts on one system land 0.05 to
0.57 mHa apart and BOTH report converged. Where a milli-Hartree
matters, run from more than one start and keep the lowest.
+ stopReason ::String ... which exit fired, verbatim: "converged", "energy below its own
resolution", "no descent", "energy stagnated", "direction collapsed",
"all subshells frozen", or "" for the iteration budget.
+ iterations ::Int64 ... iterations actually performed.
+ energyStillAvailable ::Float64 ... Ha still reachable along the search direction, the Newton decrement
dg^2/(2 <d,Hd>). **This is the field to assert on**, because |grad|
cannot be compared across systems and this can: measured on one ladder,
4.50e-11 Ha on a finished layer against 5.81e-06 on an unfinished one
where |grad| differed by only 48x. A LOWER BOUND -- only one direction
is measured -- and NaN where it was not measured or the curvature along
that direction was not positive.
+ gradientNorm ::Float64 ... |grad| at the exit, kept as a HINT only. It is not scale-free, and it
is partly supported on rotations the solver is forbidden to make: the
raw gradient carries negative-energy-branch components whose curvature
is -1.5e+04 Ha. Do not threshold on it.
+ finalStep ::Float64 ... the line-search step at the exit. A flat energy means two different
things and only this tells them apart: flat with a healthy step is
convergence, flat with a collapsed step is a search that cannot move.
+ energy ::Float64 ... the active-part energy at the exit, for reference.
+ descent ::Float64 ... how far this solve brought the energy DOWN from its own first iterate,
E(1) - E(final), in Hartree. Within one RAS layer the frozen part is constant, so this is the layer's
INCREMENT -- the quantity Rule 21 says to record and compare, rather than the total.
+ descentAtHalf ::Float64 ... the same descent measured at HALF the iterations it actually took,
E(1) - E(n/2). The pair is what makes the doubling test free: a correlation layer never truly converges,
so `maxIterations` is a cost dial and not a criterion, and the honest question is whether DOUBLING the
effort still moves the increment. Comparing these two answers it from one run, where it used to take two
-- and more correctly, since both numbers come from ONE trajectory rather than from two computations whose
earlier layers might have stopped in different places.JenaAtomicCalculator.SelfConsistent.averageAtomCellNorms — Method
SelfConsistent.averageAtomCellNorms(spectra::NamedTuple, primitives::Bsplines.Primitives, iCell::Int64; energyCap::Float64=1.0e3, previous::Union{Nothing,NamedTuple}=nothing) ... computes, for every box state of every kappa, the part of it that lies INSIDE the Wigner-Seitz cell, int_0^(R_WS) (P^2 + Q^2) dr; a NamedTuple (trueNorm, freeNorm) of Dict{Int64,Array{Float64,1}} is returned, indexed exactly as the eigenvalue lists are.
**THIS IS WHAT MAKES THE BOX STOP BEING THE CELL.** While the two coincided, every state was normalised
over the cell and its weight there was 1, so the electron count needed no radial integral -- but then the
cell wall also forced the density to zero at R_WS, which is wrong by a quarter of the free electrons, and
left a photoelectron with about one wavelength of room. With the box carried out well beyond the cell the
states are those of Johnson's model -- bound states that decay freely and continuum states that are real
scattering waves -- and what the cell contains is an integral over them, which is this.
The norms do NOT depend on the chemical potential, so they are computed once per SCF iteration and the
root solve for mu stays a sum of Fermi factors over stored numbers. A state far above the occupied range
is skipped rather than built: a box of this size carries states up to thousands of Hartree, and
`energyCap` keeps the ones a Fermi factor can still reach. The FREE norms do not change between
iterations either, the potential being zero, so passing a previous call's result as `previous` keeps them
-- which matters because a hot dilute cell needs some ninety free partial waves.JenaAtomicCalculator.SelfConsistent.averageAtomChemicalPotential — Method
SelfConsistent.averageAtomChemicalPotential(spectra::NamedTuple, norms::NamedTuple, temp::Float64, nm::Nuclear.Model) ... solves the neutrality condition nTotal(mu) = Z for the electrons INSIDE the Wigner-Seitz cell; a chemMu::Float64 is returned.
The spectra do not depend on mu, so this root solve is free compared with the diagonalizations that
produced them: one Fermi factor per box state per trial mu. The count is strictly increasing in mu,
which makes the root unique and bracketable, and the exit is on the RESIDUAL in electrons -- a quantity
with a meaning -- rather than on the step. The derivative is taken analytically from `df/dmu = f(1-f)/T`,
which is the one place a Fermi-factor derivative has ever gone wrong here (see the note in
`determineChemicalPotential`), so it is written once and used by both sums.JenaAtomicCalculator.SelfConsistent.averageAtomDensity — Method
SelfConsistent.averageAtomDensity(mu::Float64, spectra::NamedTuple, temp::Float64, primitives::Bsplines.Primitives) ... accumulates the radial electron density of the cell from the full per-kappa spectrum; a rhot::Array{Float64,1} is returned, normalised as rhot(r) = 4 pi r^2 rho(r), so that int_0^R rhot dr is the electron number – the convention Basics.computePotential uses for its average-atom fields.
It is the r-space form of exactly the sum `averageAtomElectronCount` evaluates for the number: the true
box states up to lMax and the free box states of the same box above it. The free states carry the
Dirichlet depletion at the cell boundary, which is why this tail is right where a uniform gas added as a
constant is not.
**A STATE IS BUILT ONLY WHERE ITS OCCUPATION MATTERS.** With ~50 kappa's and ~78 box states each,
building every orbital would mean some 4000 B-spline reconstructions per iteration, almost all of them
weighted by a Fermi factor below 1e-12; the cutoff leaves the few hundred that carry the density.JenaAtomicCalculator.SelfConsistent.averageAtomElectronCount — Method
SelfConsistent.averageAtomElectronCount(mu::Float64, spectra::NamedTuple, norms::NamedTuple, temp::Float64) ... counts the electrons INSIDE the Wigner-Seitz cell at chemical potential mu; a triple (nBound, nCont, nTotal)::Tuple{Float64,Float64,Float64} is returned.
`n = sum_(l<=lMax) (2j+1) sum_n f(eps_n) w_n + sum_(lMax<l<=lMaxFree) (2j+1) sum_n f(eps0_n) w0_n`,
with `w_n` the part of state n lying inside the cell (`averageAtomCellNorms`): the true box states where
the potential was solved, and the FREE box states of the same box above that -- the statement that a
partial wave of high l does not reach into the atom. A state is split into `nBound` or `nCont` by the
sign of its energy, so `nCont` is Johnson's mean charge Z* and, at neutrality, `nBound = Z - Z*`.
This is what the `int d eps` of Johnson's continuum term reduces to in a B-spline box: the energy
normalisation cancels the level spacing, leaving a plain sum over box states of the number each one puts
inside the cell.JenaAtomicCalculator.SelfConsistent.averageAtomFreeWaveLimit — Method
SelfConsistent.averageAtomFreeWaveLimit(mu::Float64, temp::Float64, radiusBox::Float64; tolerance::Float64=1.0e-6, lCap::Int64=160) ... returns the partial wave lMaxFree::Int64 beyond which the free box states of the cell can no longer hold tolerance electrons, so that the sum over partial waves may stop there.
The lowest state of partial wave l in a box of radius R lies at `eps_1 = j_(l,1)^2 / (2 R^2)` with
`j_(l,1)` the first zero of the spherical Bessel function j_l, taken here from McMahon's expansion --
accurate to 0.3 % for l >= 2 and 4 % at l = 0, far more than a stopping criterion needs. The whole wave
can hold at most `(2l+2) f(eps_1, mu, temp)` electrons, and the sum stops where that falls below the
tolerance.
**THE LIMIT IS PHYSICAL AND CANNOT BE GUESSED FROM lMax**, which is why it is computed rather than
offered as a parameter with a default. It scales as `k R` with the thermal momentum, so it is short for
a cold dense cell and long for a hot dilute one: measured 08-Oct-2026 for silicon, solid density at
10 eV needs no free wave beyond l = 5, while 0.1 g/cm^3 at 100 eV was still gaining +0.09 electrons
between l = 25 and l = 30. A fixed default would have been silently too small for exactly the
warm-dense conditions the model exists for.JenaAtomicCalculator.SelfConsistent.averageAtomPotential — Method
SelfConsistent.averageAtomPotential(scField::Basics.AbstractScField, rhot::Array{Float64,1}, grid::Radial.Grid, iCell::Int64; backgroundDensity::Float64=0.) ... builds the ELECTRONIC part of the average-atom potential from a given radial density rhot, and returns a pot::Radial.Potential holding Z(r) = -r V(r), as everywhere else in JAC.
**ONLY THE CHARGE INSIDE THE CELL IS USED, AND THE EXCHANGE IS MEASURED FROM ITS BACKGROUND VALUE**, which
is Johnson's neutral-cell model rather than a numerical convenience. `backgroundDensity` is the
free-electron density `n_free(mu,T)` of the plasma; given as zero the exchange is taken absolutely, which
leaves a step at the wall. Beyond `R_WS` the density belongs to the
NEIGHBOURING cells, which this atom must not be allowed to see: the direct integral is therefore cut at
`iCell`, and since the cell holds exactly Z electrons at neutrality, the total potential -- nuclear plus
electronic -- then vanishes identically beyond the wall with no truncation being applied to it. A bound
state consequently decays freely in a field that is zero outside, and a continuum state is a real
scattering wave there, which is what gives the box its separate job of being long enough to hold one.
It is the density-space counterpart of `Basics.computePotential(::AaDFSField, grid, orbitals, mu, temp)`
and uses the same two terms -- the direct `int dr' rhot(r')/r_>` and Slater exchange
`-(3 rhot / (4 pi^2 r^2))^(1/3)` for `AaDFSField`, the Hartree-Slater pair for `AaHSField`. It exists
because the spectrum formulation has a density but no subshell list, and because the density no longer
needs rebuilding once per kappa: the quadratic direct term is now evaluated ONCE per SCF iteration
rather than once per symmetry block, which for lMax = 7 is sixteen times less work.JenaAtomicCalculator.SelfConsistent.averageAtomSpectra — Method
SelfConsistent.averageAtomSpectra(pot::Radial.Potential, lMax::Int64, primitives::Bsplines.Primitives; lMaxFree::Int64=lMax, freeSpectra::Union{Nothing,NamedTuple}=nothing) ... diagonalizes the one-electron problem of every kappa with l <= lMax in the given potential, and the FREE-PARTICLE problem of every kappa with l <= lMaxFree in the same box, and returns the NamedTuple (kappas, kappasFree, lMax, lMaxFree, trueEigen, trueStart, freeEigen, freeStart): the Basics.Eigen of each problem, keyed by kappa, and the index at which its physical (electron-branch) states begin.
**THE WHOLE SPECTRUM OF EACH KAPPA IS KEPT, which is the point of this routine.** The average-atom
density used to be built from `Basics.generateShellList(1, nMax, lMax)`, i.e. `nMax - l` states per l --
about SEVEN of the ~78 the B-spline basis offers for each kappa. Johnson's continuum term is an integral
over eps which in a box becomes a plain sum over the box states, the energy normalisation cancelling the
level spacing, but ONLY if the sum runs over the WHOLE spectrum.
**THE FREE SPECTRA ARE WHAT MAKES THE PARTIAL-WAVE SUM CONVERGE**, and they are computed to a HIGHER
lMaxFree than the potential is solved to, deliberately. A partial wave with l above lMax barely reaches
into the potential, so its states are those of a free particle in the same box and need no
diagonalization in the field; the sum therefore runs over the true spectra up to lMax and over the free
ones from lMax+1 to lMaxFree, which is exact as both grow and converges in lMax as fast as the difference
`f(eps) - f(eps0)` falls away. Measured 08-Oct-2026 on silicon, this is the whole difference between a
usable and an unusable l-sum: the plain sum of true states alone still moved by +0.40 electrons between
lMax = 6 and 7 for a hot dilute plasma.
**THE IDEAL-GAS CLOSED FORM IS NOT USED, and that was measured rather than assumed.** The textbook
Blenski-Ishikawa prescription subtracts the free partial waves WITHIN lMax and adds back `n_free(mu,T) V`
in closed form. That is exact only where the box gas reproduces the uniform gas, and a Wigner-Seitz cell
is too small for it: measured on silicon at four conditions, the cell's continuum holds 0.97, 0.82, 0.91
and 0.94 of an ideal gas at the same mu, temperature and volume -- the Dirichlet depletion at the cell
wall, 3 to 18 %, and NOT a small correction. The closed form therefore converges in lMax to the wrong
number rather than slowly to the right one, which is the dangerous of the two failures: for solid-density
silicon at 10 eV it gives Z* = 3.22 with 10.78 bound electrons, against 4.00 and 9.999 here, and 4.00 is
the answer the shell structure demands -- the L shell closed and the M shell gone. Summing the free box
states instead costs one diagonalization per extra kappa and is right by construction.
**THE FREE SPECTRA ARE THE SAME AT EVERY SCF ITERATION**, the potential being zero, so a converged run
diagonalizes them once: pass a previous call's result back as `freeSpectra` and only the true half is
redone.JenaAtomicCalculator.SelfConsistent.averageLevelPrePass — Method
SelfConsistent.averageLevelPrePass(basis::Basis, nm::Nuclear.Model, primitives::Bsplines.Primitives, settings::AsfSettings; printout::Bool=true) ... prepares the starting basis for an optimized-level rotation, which is a LOCAL optimizer and therefore depends on where it begins; a basis::Basis is returned, either the one handed in or one refined by an average-level pre-pass.
**WHY THIS IS NOT SIMPLY "SKIP IF THE CALLER HANDED IN ORBITALS" -- 11-Oct-2026, priority item 54.** The
pre-pass exists because a rotation started from hydrogenic functions wastes its first iterations finding a
mean field, and a hydrogenic start has no reason to lie in the basin of the level one wants. It was made
unconditional on `StartFromPrevious` on 06-Oct-2026, for a measured reason that still holds: it optimizes
the configuration AVERAGE, a different functional from the level energy, and moved every subshell not
named in `frozenSubshells`, so a caller who already had good orbitals had them silently replaced -- worth
36.1 mHa on a 43Ca+ second layer, which ended 2.8 mHa WORSE than its own reference.
**THE DEFECT WAS THAT IT DID NOT ASK WHETHER THE HANDED-IN SET COVERS THE BASIS.** A restricted-active-space
layer hands in the orbitals of the PREVIOUS, SMALLER space, so the layer's own virtual subshells are not in
it and are taken hydrogenic; skipping then denies exactly those orbitals the only mean field they would
ever see. Measured on the Cf^17+ core-valence layer, where the handed-in set covered 1s-6p and 5f while
5g, 6d, 6f, 7s and 7p did not: the pre-pass is worth **0.046 Ha at the first iteration**, and a rotation
denied it does not recover the difference -- it descends at 0.028 mHa per iteration, so some 1500 further
iterations would be needed. That single difference is the whole of the 9254 cm^-1 by which one block of
that layer came out above a run made before the skip existed.
**SO BOTH REQUIREMENTS ARE MET AT ONCE, rather than one being traded for the other:** where the handed-in
set covers the basis there is nothing to pre-pass and it is skipped; where it does not, the pre-pass runs
with the handed-in subshells ADDED TO `frozenSubshells`, so they are kept at exactly the values handed in
-- `solveAverageLevelField` pins a frozen subshell at the value it was given (31-Aug-2026) -- while the
uncovered ones are given their mean field.JenaAtomicCalculator.SelfConsistent.buildCIMatrixEOL — Function
SelfConsistent.buildCIMatrixEOL(cache::PairCoefficientCache, orbitals::Dict{Subshell, Orbital}, grid::Radial.Grid, potential::Radial.Potential, radial1pCache::Dict{Tuple{Subshell,Subshell},Float64} = Dict{Tuple{Subshell,Subshell},Float64}(), radial2pCache::Dict{Tuple{Int64,Subshell,Subshell,Subshell,Subshell},Float64} = Dict{Tuple{Int64,Subshell,Subshell,Subshell,Subshell},Float64}(), vkCache::Dict{Tuple{Int64,Subshell,Subshell,Int64},Vector{Float64}} = Dict{Tuple{Int64,Subshell,Subshell,Int64},Vector{Float64}}()) ... (re-) builds the CI Hamiltonian matrix for one symmetry block from CACHED, orbital-independent angular coefficients (see cacheCsfPairCoefficientsEOL) and the CURRENT radial functions in orbitals – algebraically identical to Hamiltonian.setupMatrixKinkAware's pure-Coulomb contribution (kink-aware InteractionStrength.XLCoulombKinkAware, matching the rest of the average-level (ALField) line; Breit and QED are added only once, at the final Hamiltonian.performCIKinkAware call, exactly as for the AL scheme), but without repeating the (unchanged) angular-coefficient computation on every outer SCF+CI iteration. The trailing radial1pCache/radial2pCache arguments memoize each radial integral by its bare subshell labels (never by CSF-pair index), so a radial integral shared by many different CSF pairs – e.g. the same "1s-1s" self-interaction appearing in every CSF's diagonal term – is evaluated once per outer iteration rather than once per (r,s) occurrence; pass the SAME two Dicts into every block diagonalized within one outer iteration to also share the cache across blocks (found by profiling to be the dominant EOL cost for multi-CSF cases – see projecteol_implementation.md). A matrix::Array{Float64,2} is returned.
JenaAtomicCalculator.SelfConsistent.cacheCsfPairCoefficientsEOL — Method
SelfConsistent.cacheCsfPairCoefficientsEOL(sym::LevelSymmetry, basis::Basis) ... computes, once, the orbital-independent angular coefficients of every CSF pair of the symmetry block sym and stores them interned. The coefficients depend only on the CSFs and the subshell list, never on the radial functions, so they survive every outer SCF+CI iteration unchanged – which is the whole point of caching them. A cache::SelfConsistent.PairCoefficientCache is returned; see its docstring for the storage form and for what it replaced.
JenaAtomicCalculator.SelfConsistent.checkOneElectronSelfInteraction — Method
SelfConsistent.checkOneElectronSelfInteraction(configs::Array{Configuration,1}, scField::Basics.AbstractScField) ... answers whether a ONE-ELECTRON system is about to be solved in a mean-field potential built from its own density, printing the explanation when it is; a value::Bool is returned, true meaning that the field must be replaced. performSCF acts on that answer by switching to Basics.NuclearField(), so the condition is CORRECTED rather than merely reported – see the note there for why the correction is exact and not a guess.
WHY THIS IS WORTH SAYING OUT LOUD RATHER THAN A NOTE SOMEWHERE. A mean field such as DFS is built from the total
electron density, so with a SINGLE electron it contains that electron's own charge: the electron is repelled
by itself. The bound orbital and the continuum orbital then solve DIFFERENT one-body operators, which is not
a small error and does not look like one. Measured 30-Aug-2026 on H(1s) -> continuum: the Coulomb and
Babushkin photoionization cross sections, which are EQUAL for exact hydrogenic wavefunctions, come out in
the ratio 1.238, 1.299 and 1.294 at omega/I = 1.5, 2 and 3 under `DFSField()`, and 1.000000 at every one of
them under `NuclearField()` -- unchanged across boxes of 30 to 150 a.u., meshes of 0.05 to 0.01, and the
pure-sine, pure-Coulomb and Ong-Russek normalisations.
That 24-30 % discrepancy was carried on the priority list for weeks as a suspected defect of the CONTINUUM
machinery, and the three suspects it named were all innocent. `AsfSettings()` defaults to `DFSField()`, so
the default is the trap; the remark that would have prevented it existed only inside a test for another
module, where no user would meet it.JenaAtomicCalculator.SelfConsistent.checkScFieldIsSupported — Method
SelfConsistent.checkScFieldIsSupported(scField::Basics.AbstractScField) ... verifies that the given field is one that performSCF can actually iterate, and raises an explanatory error if it is not. Several members of Basics.AbstractScField are POTENTIALS rather than fields: they answer Basics.providesPotential but not Basics.providesScfDriver, and one of them is not self-consistent even in principle. Checked HERE, before a grid, a set of primitives and a many-electron basis have been built, so that an unsupported choice costs nothing and says what to do instead. Nothing is returned.
JenaAtomicCalculator.SelfConsistent.coefficients1p — Method
SelfConsistent.coefficients1p(c::SelfConsistent.PairCoefficientCache, r::Int64, s::Int64) ... rebuilds, lazily, the one-particle coefficients of the CSF pair (r,s) from the interned tables. A generator of Coefficient1p is returned, so nothing is allocated per pair and the caller's for cf in ... loop is unchanged.
JenaAtomicCalculator.SelfConsistent.coefficients2p — Method
SelfConsistent.coefficients2p(c::SelfConsistent.PairCoefficientCache, r::Int64, s::Int64) ... as SelfConsistent.coefficients1p, for the two-particle coefficients. A generator of Coefficient2p is returned.
JenaAtomicCalculator.SelfConsistent.combineAngularCoefficientsEOL — Method
SelfConsistent.combineAngularCoefficientsEOL(blockCaches, targetLevels::Array{Level,1}; pairs::Symbol=:all) ... generalizes SelfConsistent.computeAngularCoefficients (AL's single-CSF-average analog: loop CSFs, weight 1/ncsf) to CSF PAIRS, weighted by the EOL generalized weight d²rs = Σᵢ WTi · cr⁽ⁱ⁾ · cs⁽ⁱ⁾, with WT_i the normalized statistical (2Jᵢ+1) weight of each target level i in targetLevels (its own mixing vector c⁽ⁱ⁾ = level.mc) – never a user-supplied weight. Reuses the cached, orbital-independent per-CSF-pair coefficients from cacheCsfPairCoefficientsEOL for every relevant symmetry block in blockCaches; a level's mc vector is zero outside its own block, so multiple symmetry blocks combine correctly without special-casing. The dedup/condensation logic is identical to computeAngularCoefficients. A Tuple (coeffs1p::Array{Coefficient1p,1}, coeffs2p::Array{Coefficient2p,1}) is returned.
JenaAtomicCalculator.SelfConsistent.computeAngularCoefficients — Method
SelfConsistent.computeAngularCoefficients(scField::Basics.ALField, basis::Basis) ... computes all spin-angular coefficients for the average-level (AL) functional as obtained for the given basis. In the AL functional, only the diagonal matrix elements (from the trace of the Hamiltonian matrix) are considered, and the energy is averaged with regard to the number of CSF in the basis. This makes the total energy of the system comparable and independent of the size of the basis. A Tuple of two lists with one- and two-particle coefficients tpl::Tuple{coeffs1p::Array{Coefficient1p,1}, coeffs2p::Array{Coefficient2p,1}} is returned.
JenaAtomicCalculator.SelfConsistent.computeFockMatrix — Method
SelfConsistent.computeFockMatrix(subshell::Subshell, coeffs2p::Array{Coefficient2p,1}, bVectors::Dict{Subshell, Vector{Float64}}, primitives::Bsplines.Primitives, nucPot::Radial.Potential, storage::Dict{String,Array{Float64,2}}, occ::Float64, tensorCaches::Dict{Int64, NTuple{3,RadialIntegrals.ScreenedPotentialCache}}; coeffs2pUnscaled::Array{Coefficient2p,1}=Coefficient2p[], directKernels::Dict{Tuple{Int64,Subshell,Subshell},Array{Float64,2}} = Dict{Tuple{Int64,Subshell,Subshell},Array{Float64,2}}(), exchangeKernels::Dict{Tuple{Int64,Subshell},Array{Float64,2}} = Dict{Tuple{Int64,Subshell},Array{Float64,2}}()) ... computes the full per-subshell Hamiltonian matrix (one-electron + direct + exchange), matching the role of DBSRHF's hfmatrix.f90: Bsplines.setupLocalMatrix provides the one-electron (kinetic + nuclear + rest-mass) block natively in B-spline basis (reused unchanged), and computeTwoElectronV provides the two-electron block, divided by the subshell's own mean occupation – algebraically identical to DBSRHF's own hfm=qsum(i)*dhl (one-electron scaled up) followed by hfm=hfm/qsum(i) (whole matrix scaled down) once expanded, given the two-electron coefficients already carry their full (not per-electron) occupation weighting (verified this session against the DBSRHF avenergycoef reference for all of Ne's coefficients). Shared by the ALField and EOLField code lines. A (nsL+nsS) x (nsL+nsS) matrix::Array{Float64,2} is returned.
JenaAtomicCalculator.SelfConsistent.computeFunctional — Method
SelfConsistent.computeFunctional(coeffs1p::Array{Coefficient1p,1}, coeffs2p::Array{Coefficient2p,1}, orbitals::Dict{Subshell, Orbital}, grid::Radial.Grid, potential::Radial.Potential) ... computes the MCDHF energy functional using InteractionStrength.XL_CoulombKinkAware (kink-aware two-electron Slater integral) for the two-electron term. Used by the ALField/EOLField code line, cf. solveAverageLevelField. An energy::Float64 is returned.
JenaAtomicCalculator.SelfConsistent.computeFunctionalSplit — Method
SelfConsistent.computeFunctionalSplit(coeffs1p::Array{Coefficient1p,1}, coeffs2p::Array{Coefficient2p,1}, orbitals::Dict{Subshell, Orbital}, grid::Radial.Grid, potential::Radial.Potential, isFrozen::Function, frozenRk::Dict{NTuple{5,Any}, Float64}) ... the same functional as computeFunctional, but returned as the PAIR (eFrozen, eActive): the part built entirely from frozen subshells, and the rest. Two things follow from the split, and they are the reason it exists.
(1) PRECISION. The line search of the EOL driver decides descent by comparing two total energies.
For a heavy ion that total is enormous -- Cf^17+ sits at -32975.774170971636 Ha -- while an orbital
step in a correlation layer moves it in the twelfth digit, a relative 3e-16, which is the resolution
of the number itself. Measured on Cf^17+ with an SD layer into {7s,7p}: on three different boxes the
driver stopped with |dE| = 0.0 EXACTLY while the gradient was still 7e-3, three orders above its
tolerance. The frozen part is identical for the start point and for every trial of one line search --
the angular coefficients are fixed within an iteration and the frozen orbitals never move -- so
comparing eActive alone is the SAME test carried out on numbers a thousand times smaller, and the
cancellation that destroyed the digits never happens.
(2) COST. The radial integral over a quadruple of frozen subshells is constant for the whole run, so
it is memoised in `frozenRk`, which the caller owns and reuses across iterations. The existing
per-call cache inside computeFunctional cannot do this: it is discarded at every evaluation, and the
line search alone evaluates the functional up to 24 times per iteration. Measured share of frozen-only
quadruples for Cf^17+ with the spectroscopic shells frozen: 1287 of 1592 coefficients (80.8 %) for a
layer into {7s,7p} and 1287 of 2276 (56.5 %) into {7s,7p,7d,7f} -- the count is a property of the
frozen core, so it is the same absolute work saved in both.JenaAtomicCalculator.SelfConsistent.computeGeneralizedOccupationEOL — Method
SelfConsistent.computeGeneralizedOccupationEOL(blockCaches, targetLevels::Array{Level,1}, basis::Basis) ... computes the EOL generalized occupation number per subshell, q(nlj) = Σᵣ d²r · qr(nlj), with d²r = Σᵢ WTi · (cr⁽ⁱ⁾)² the DIAGONAL (r=r) case of the same statistical-(2J+1)-weighted generalized weight used in combineAngularCoefficientsEOL, and qr(nlj) the plain occupation of nlj in CSF r (basis.csfs[r].occupation). This REPLACES Basics.extractMeanOccupation(basis) – which averages FLATLY over every CSF in the whole basis, appropriate only for AL's single-average-CSF philosophy – with the occupation actually implied by the current target level(s)' own CI mixing, recomputed every outer iteration since the mixing coefficients change. Without this, computeFockMatrix's (1.0/occ) two-electron scaling uses a basis-wide average that can be wildly wrong for a multi-configuration target level (e.g. an essentially-pure 2s² level in a 2s²/2p² basis would otherwise see occ(2s) diluted by the unrelated 2p² CSFs, inflating its two-electron potential many-fold). A Dict{Subshell,Float64} is returned.
JenaAtomicCalculator.SelfConsistent.computeOrbitalEnergiesEOL — Method
SelfConsistent.computeOrbitalEnergiesEOL(subshells::Array{Subshell,1}, bVectors::Dict{Subshell, Vector{Float64}}, coeffs2p::Array{Coefficient2p,1}, genOcc::Dict{Subshell,Float64}, primitives::Bsplines.Primitives, grid::Radial.Grid, nucPot::Radial.Potential, storage::Dict{String,Array{Float64,2}}, matrixB::Array{Float64,2}; coeffs2pUnscaled::Array{Coefficient2p,1}=Coefficient2p[]) ... gives every subshell of a converged EOL orbital set a DEFINED energy, the diagonal Lagrange multiplier
eps_a = <a|F_a|a> = b_a^T F_a b_a / b_a^T B b_a ,
with F_a the same orbital-specific Fock operator `SelfConsistent.computeFockMatrix` builds to refine that
subshell. This is the exact analogue of what the AL field already stores: there the orbital IS an eigenvector
of F_a, so its stored energy `wc.values[ni]` and this Rayleigh quotient are the same number. A
rotation-optimized orbital is NOT such an eigenvector, and the quotient is then the honest generalisation --
the multiplier that the orthonormality constraint carries -- rather than an eigenvalue it does not have.
WHAT THIS IS NOT: the one-particle expectation <a|h_D|a>. That omits the electron-electron interaction
entirely and comes out 1.7x to 12x too DEEP (measured 12-Sep-2026, `tools/probe-eolOrbitalEnergy.jl`, Be-like
and Ne-like: 2s of Ne-like at -11.13 against the AL -1.94), while looking perfectly well-behaved. It is the
plausible wrong answer and must not be substituted here.
A subshell carrying ZERO generalized occupation keeps 0.0, and that is correct rather than a fallback: the
EOL functional does not depend on such an orbital at all, so no mean field and no multiplier is defined for
it. A `Dict{Subshell, Float64}` is returned.JenaAtomicCalculator.SelfConsistent.computeOrbitalGradient — Method
SelfConsistent.computeOrbitalGradient(bVectors::Dict{Subshell, Vector{Float64}}, coeffs1p::Array{Coefficient1p,1}, coeffs2p::Array{Coefficient2p,1}, subshells::Array{Subshell,1}, primitives::Bsplines.Primitives, nucPot::Radial.Potential, storage::Dict{String,Array{Float64,2}}, matrixB::Array{Float64,2}) ... the ANALYTIC gradient dE/dba of the same energy that energyFromBVectors evaluates, for every subshell, as a full B-spline coefficient vector. Nothing here is new machinery: the one-electron integral is I(a,b) = ba^T H1 bb with H1 = Bsplines.setupLocalMatrix, and the Slater integral is R^k(abcd) = ba^T M bc with M = InteractionStrength.XLCoulombKinkAware(k, a, orbb, c, orbd, primitives) – the matrix-valued overload that already exists for the Fock build. Each slot in which a subshell occurs contributes once, using the symmetry R^k(abcd) = R^k(badc) for the second pair. Must be checked against gradientByFiniteDifference before being trusted. A Dict{Subshell, Vector{Float64}} is returned.
JenaAtomicCalculator.SelfConsistent.computeTwoElectronV — Method
SelfConsistent.computeTwoElectronV(subshell::Subshell, coeffs2p::Array{Coefficient2p,1}, bVectors::Dict{Subshell, Vector{Float64}}, primitives::Bsplines.Primitives, tensorCaches::Dict{Int64, NTuple{3,RadialIntegrals.ScreenedPotentialCache}}; directKernels::Dict{Tuple{Int64,Subshell,Subshell},Array{Float64,2}} = Dict{Tuple{Int64,Subshell,Subshell},Array{Float64,2}}(), exchangeKernels::Dict{Tuple{Int64,Subshell},Array{Float64,2}} = Dict{Tuple{Int64,Subshell},Array{Float64,2}}()) ... computes the direct and exchange two-electron potential matrix for the given subshell, taking bVectors::Dict{Subshell,Vector{Float64}} – B-spline expansion coefficients – as the SOLE, canonical per-subshell state, rather than a persistent Dict{Subshell,Orbital}. Every coeffs2p entry relevant to subshell involves exactly one "partner" subshell (the diagonal self-term is its own partner); a partner's tabulated form is built only as a disposable, read-only byproduct (Bsplines.generateOrbitalFromVector), cached within this call so repeated coefficients sharing the same partner do not re-evaluate it, and discarded once this function returns – never re-fit back into bVectors, since bVectors are never derived FROM a tabulated form here in the first place; they come directly from diagonalization (solveAverageLevelField/solveOptimizedLevelField). Shared by the ALField and EOLField code lines. A (nsL+nsS) x (nsL+nsS) matrixV::Array{Float64,2} is returned.
JenaAtomicCalculator.SelfConsistent.determineChemicalPotential — Method
SelfConsistent.determineChemicalPotential(orbitals::Dict{Subshell, Orbital}, temp::Float64, radiusWS::Float64, nm::Nuclear.Model, grid::Radial.Grid) ... determines the chemical potential mu from the neutrality condition Sumi (2ji+1) f(eps_i, mu, temp) = Z, where f is the Fermi-Dirac factor; a safeguarded Newton iteration inside a bracket is used, and a chemMu::Float64 is returned.
Note: this general finite-temperature Fermi-Dirac root-finding utility was moved here from module Plasma
(where it originated as `determineChemicalPotential`), since Plasma.perform(::AverageAtomScheme,
...) needs SelfConsistent.solveAverageAtomField below, and solveAverageAtomField itself needs this
function internally at every SCF iteration; keeping it in Plasma would have made the two modules
depend on each other circularly. Nothing here is Plasma-scheme-specific.JenaAtomicCalculator.SelfConsistent.diagonalizeBlockEOL — Method
SelfConsistent.diagonalizeBlockEOL(sym::LevelSymmetry, idxCsf::Array{Int64,1}, matrix::Array{Float64,2}, basis::Basis) ... diagonalizes the (already-built) CI matrix of one symmetry block and reassigns the eigenvectors to Level instances w.r.t. the full basis (zero-padded outside this block), exactly as Hamiltonian.performCI/performCIKinkAware do internally per symmetry block – factored out here so it can be called every EOL outer iteration without their Multiplet-merge/tabulate overhead. An Array{Level,1} is returned.
JenaAtomicCalculator.SelfConsistent.energyFromBVectors — Method
SelfConsistent.energyFromBVectors(bVectors::Dict{Subshell, Vector{Float64}}, coeffs1p::Array{Coefficient1p,1}, coeffs2p::Array{Coefficient2p,1}, subshells::Array{Subshell,1}, primitives::Bsplines.Primitives, grid::Radial.Grid, nucPot::Radial.Potential) ... the EOL energy as a plain scalar function of the orbital B-spline coefficient vectors, with the angular coefficients held fixed. This is exactly the functional solveOptimizedLevelField reports, just expressed in the variables that are actually varied, so that it can be differentiated. Note that it includes coeffs1p – which the Fock matrix of the present scheme never receives, and which is the inconsistency the rotation-based path exists to remove. A value::Float64 is returned.
JenaAtomicCalculator.SelfConsistent.energyFromBVectorsSplit — Method
SelfConsistent.energyFromBVectorsSplit(bVectors::Dict{Subshell, Vector{Float64}}, coeffs1p::Array{Coefficient1p,1}, coeffs2p::Array{Coefficient2p,1}, subshells::Array{Subshell,1}, primitives::Bsplines.Primitives, grid::Radial.Grid, nucPot::Radial.Potential, isFrozen::Function, frozenRk::Dict{NTuple{5,Any}, Float64}) ... as energyFromBVectors, but returns the pair (eFrozen, eActive) of SelfConsistent.computeFunctionalSplit, which is what the line search compares and what carries the persistent radial memo.
JenaAtomicCalculator.SelfConsistent.expandBVector — Method
SelfConsistent.expandBVector(vec::Vector{Float64}, primitives::Bsplines.Primitives) ... expands a B-spline coefficient vector into its large and small radial components on the grid, (P, Q), exactly as the matrix contraction implies – P(r) = sumk vec[k] Bk^L(r) and likewise for Q. Deliberately NOT via Bsplines.generateOrbitalFromVector, which truncates at mtp and cleans small values: that round trip is lossy, and the whole point here is to reproduce the matrix product exactly. A tuple (P, Q) of Vector{Float64} over the full grid is returned.
JenaAtomicCalculator.SelfConsistent.freeElectronDensity — Method
SelfConsistent.freeElectronDensity(mu::Float64, temp::Float64) ... returns the number density of a FREE (ideal, uniform) electron gas at chemical potential mu and temperature temp, both in atomic units; a value::Float64 [electrons per a_o^3] is returned.
`n = (2 temp)^(3/2) / (2 pi^2) F_(1/2)(mu/temp)` with the Fermi-Dirac integral
`F_(1/2)(eta) = int_0^inf sqrt(u) du / (1 + exp(u-eta))`. This is the "exactly known free-particle
density" that the Blenski-Ishikawa prescription adds back after the free reference has been subtracted
from every partial wave.
**THE INTEGRAL IS TAKEN IN u = x^2 AND NOT IN u**, which costs nothing and buys five digits: the
integrand carries a sqrt(u) whose DERIVATIVE is singular at the origin, so a quadrature in u converges
slowly and misleadingly -- measured 08-Oct-2026, Simpson in u reached only 1.3e-04 and QuadGK in u with
rtol = 1e-10 was itself wrong by 1.4e-05, i.e. it reported success. In x the integrand is smooth and
twelve digits are stable.JenaAtomicCalculator.SelfConsistent.gradientByFiniteDifference — Method
SelfConsistent.gradientByFiniteDifference(bVectors::Dict{Subshell, Vector{Float64}}, virtuals::Dict{Subshell, Array{Vector{Float64},1}}, coeffs1p::Array{Coefficient1p,1}, coeffs2p::Array{Coefficient2p,1}, subshells::Array{Subshell,1}, primitives::Bsplines.Primitives, grid::Radial.Grid, nucPot::Radial.Potential; hStep::Float64=1.0e-4) ... the gradient of the EOL energy with respect to the allowed orbital rotations, by central finite differences. Slow but free of any derivation, so it is the reference against which an analytic gradient must later be checked, and on its own it answers the question "is this converged solution actually stationary?". Each direction is S-orthogonal to the orbital itself, so normalization contributes only at second order and is omitted. A Dict{Subshell, Vector{Float64}} is returned.
JenaAtomicCalculator.SelfConsistent.initializeBasis — Method
SelfConsistent.initializeBasis(configs::Array{Configuration,1}, nuclearModel::Nuclear.Model, primitives::Bsplines.Primitives, settings::AsfSettings; levelSymmetries::Array{LevelSymmetry,1}=LevelSymmetry[], printout::Bool=true) ... Initialized a many-electron basis from the given list of configurations, the nuclear model as well as ASF settings. It assumes that a proper set of primitives::Primitives has been initialized before. The initial set of orbitals in this basis is determined by the settings::AsfSettings. A basis::Basis is returned.
JenaAtomicCalculator.SelfConsistent.lastScfVerdict — Method
SelfConsistent.lastScfVerdict() ... returns what the EOL rotation solver concluded about its most recent run, so that a script can ASK whether a computation converged instead of capturing stdout and grepping it. A verdict::ScfVerdict is returned, or nothing if that solver has not run in this session.
MEASURED COST OF NOT HAVING THIS, and the reason the item existed: on 27-Sep-2026 a tuning scan suppressed
the SCF output to keep a table readable, and an UNCONVERGED ground-state SCF then looked like a physics
result -- the excitation energy came out non-monotonic and was one step from being written up as a
physical gate. It was an artefact, and it was caught only by re-running with the log captured and the
markers counted by hand.
IT IS ADVICE AND NEVER A GATE. Read `energyStillAvailable` rather than `converged` wherever a number will
do, and read `ScfVerdict`'s own documentation for what `converged` does and does not claim.JenaAtomicCalculator.SelfConsistent.orthonormalizeSameKappa — Method
SelfConsistent.orthonormalizeSameKappa(newOrbitals::Dict{Subshell, Orbital}, newbVectors::Dict{Subshell, Vector{Float64}}, subshells::Array{Subshell,1}, primitives::Bsplines.Primitives, matrixB::Array{Float64,2}) ... applies a Loewdin SYMMETRIC orthogonalization to every group of subshells sharing the same kappa AND the same shape (two differently-shaped realizations of one (n, kappa) are deliberately never orthogonalized against each other – see Basics.OrbitalShape), treating them as a SIMULTANEOUSLY-valid set rather than the sequence in which they happen to have been refined – this is the explicit "orthonormalize the orbital set" step shown as its OWN, separate box (after, not instead of, the per-orbital "apply projection" step) in the block diagram of Zatsarinny \& Froese Fischer, Comput. Phys. Commun. 202, 287-303 (2016), Fig. 1. The per-orbital Hamiltonian.projectHamiltonian step alone does not guarantee a simultaneously-consistent same-kappa set when subshells are refined one at a time with lagged (Jacobi-style) data from the previous outer iteration – this step corrects that afterwards, once per outer iteration, independent of processing order.
For a kappa-group of n>1 subshells with B-spline expansion coefficient vectors b_1...b_n (columns of a
(nsL+nsS) x n matrix B) and S-metric overlap matrix M (M_ij = b_i' * matrixB * b_j), the orthonormalized
set is B_new = B * M^(-1/2), computed via an eigendecomposition of the small (n x n) matrix M. Unlike
Gram-Schmidt, this treats every member of the group symmetrically -- no member is privileged by
processing order -- matching the paper's "simultaneous" variation of same-symmetry orbitals directly.
Groups of size 1 (no same-kappa partner) are left untouched, already trivially orthonormal.
A (orbitals::Dict{Subshell,Orbital}, bVectors::Dict{Subshell,Vector{Float64}}) tuple is returned.JenaAtomicCalculator.SelfConsistent.pairOrdinal — Method
SelfConsistent.pairOrdinal(c::SelfConsistent.PairCoefficientCache, r::Int64, s::Int64) ... returns the ordinal of the stored CSF pair (r,s), or 0 if the pair carries no angular coefficient at all; a value::Int64 is returned. The pairs of column s occupy pairPtr[s] : pairPtr[s+1]-1 and their r values ascend, so the lookup is a binary search over a short, contiguous run.
JenaAtomicCalculator.SelfConsistent.performSCF — Method
SelfConsistent.performSCF(basis::Basis, nm::Nuclear.Model, grid::Radial.Grid, settings::AsfSettings; levelSymmetries::Array{LevelSymmetry,1}=LevelSymmetry[], printout::Bool=false) ... Performs a SCF computation for the given list of configurations, the nuclear model as well as ASF settings. If explicit levelSymmetries are given, only these symmetries are considered. Internally, a proper set of primitives::Primitives is initialized and used in the computations. The generated SCF field is controlled by the settings::AsfSettings. A multiplet::Multiplet is returned.
JenaAtomicCalculator.SelfConsistent.performSCF — Method
SelfConsistent.performSCF(configs::Array{Configuration,1}, nm::Nuclear.Model, settings::AsfSettings; levelSymmetries::Array{LevelSymmetry,1}=LevelSymmetry[], printout::Bool=true) ... performs a SCF computation for which NO grid is given, so that the radial box is derived from the configurations themselves by Basics.recommendedGrid; a multiplet::Multiplet is returned.
This exists because choosing the box is the step most likely to be got wrong, and getting it wrong
does not look like a grid problem: the record attributes four separate "bugs" -- an E3 rate 1000x too
small, a Zeeman kappa <= -3 failure, a MultipolePolarizibility defect and a Breit sign flip -- to a
box that did not match the orbitals, and each was first blamed on the angular machinery. The derived
box beats JAC's hand-chosen default grid for every system it has been measured on (see
Basics.recommendedGrid), by 2.9e-3 Ha for argon and 2.3e-2 Ha for Ti+.
ONE CASE NEEDS THE GRID GIVEN BY HAND. The estimate cannot tell a spectroscopic Rydberg shell from a
CORRELATION shell of the same n and l, and reads both as diffuse: a beryllium basis carrying 3s and 3d
for correlation is given 67 a.u., which is right for a real 1s^2 2s 3s state and far too generous for
a correlation orbital that contracts onto the valence region. Where the high-n shells are there to
correlate rather than to be occupied, pass a grid, or pass `rbox` to Basics.recommendedGrid.JenaAtomicCalculator.SelfConsistent.performSCF — Method
SelfConsistent.performSCF(configs::Array{Configuration,1}, nm::Nuclear.Model, grid::Radial.Grid, settings::AsfSettings; levelSymmetries::Array{LevelSymmetry,1}=LevelSymmetry[], printout::Bool=true) ... Performs a SCF computation for the given list of configurations, the nuclear model as well as ASF settings. If explicit levelSymmetries are given, only these symmetries are considered. Internally, a proper set of primitives::Primitives is initialized and used in the computations. The generated SCF field is controlled by the settings::AsfSettings. A multiplet::Multiplet is returned.
JenaAtomicCalculator.SelfConsistent.positiveBranchSpectrum — Method
SelfConsistent.positiveBranchSpectrum(subshells::Array{Subshell,1}, primitives::Bsplines.Primitives, nucPot::Radial.Potential, matrixB::Array{Float64,2}, storage::Dict{String,Array{Float64,2}}) ... the positive-energy eigenvectors of the ONE-ELECTRON Dirac matrix of every kappa present, together with their eigenvalues. It depends only on the nuclear potential and the B-spline basis, NOT on the orbitals, so it is constant for a whole run and must be built once and passed in – both virtualDirections and projectOntoPositiveBranch used to rebuild it on every call, i.e. twice per iteration. Measured on Be-like C^2+: an iteration cost 1.77 s of which the line search was only 0.15 s, and this was the bulk of the remainder. A Dict{Int64, Tuple{Array{Vector{Float64},1}, Vector{Float64}}} is returned, keyed by kappa.
JenaAtomicCalculator.SelfConsistent.projectOntoPositiveBranch — Method
SelfConsistent.projectOntoPositiveBranch(bVectors::Dict{Subshell, Vector{Float64}}, subshells::Array{Subshell,1}, primitives::Bsplines.Primitives, nucPot::Radial.Potential, matrixB::Array{Float64,2}, storage::Dict{String,Array{Float64,2}}; spectrum=nothing, frozen::Array{Subshell,1}=Subshell[]) ... projects every orbital onto the POSITIVE-ENERGY branch of its own kappa block, then S-orthonormalizes the orbitals of each kappa among themselves, entirely in B-spline coefficient space. Returns the projected (bVectors, maximum negative-branch weight removed).
This is what keeps the rotation from collapsing into the Dirac sea. The Dirac operator is unbounded
below, so the energy has no minimum once an orbital acquires negative-continuum character. The
rotation DIRECTIONS are all positive-branch by construction, but the round trip
b -> Bsplines.generateOrbitalFromVector -> b truncates at mtp and cleans small values, and that
residue carries negative-branch content. Measured for Be with 48 directions: the 2s negative-branch
weight jumps from 5e-12 to 1.2e-04 in one step and to 3.3e-03 in the next, at which point <h1> for 2s
has gone from -1.6 to -43.5 and the energy to -69.9 Ha. Projecting after every step removes the
residue before it can be amplified. The orthonormalization is done here, in coefficient space, rather
than via orthonormalizeSameKappa, precisely to avoid that lossy round trip.JenaAtomicCalculator.SelfConsistent.referenceCsfIndices — Method
SelfConsistent.referenceCsfIndices(basis::Basis, refConfigs::Array{Configuration,1}) ... to find those CSFs of the given basis that belong to one of the reference configurations refConfigs. A CSF belongs to a reference configuration when its NON-RELATIVISTIC occupations agree with that configuration's shell by shell, so that a configuration named as 5f^1 matches a CSF carrying 5f5/2^1 or 5f7/2^1 alike. These indices are what the EOL target selection weights a level on, since the weight asks what a level IS rather than where it currently sits in the energy order. An indices::Array{Int64,1} is returned, in increasing order and empty if no CSF matches.
JenaAtomicCalculator.SelfConsistent.referenceSymmetries — Method
SelfConsistent.referenceSymmetries(configs::Array{Configuration,1}, subshells::Array{Subshell,1}) ... determines the level symmetries J^P that the given REFERENCE configurations span, by generating their relativistic configurations and the CSFs of each; an Array{LevelSymmetry,1} is returned.
**WHAT IT IS FOR, AND WHY RESTRICTING TO IT IS SAFE.** An EOL field optimizes its orbitals for a set of
TARGET levels, and when those are selected by reference configurations the target is scored by the weight
a level carries on the reference CSFs. A level in a symmetry the reference does not span carries ZERO
such weight and therefore can never be chosen as a target -- so the symmetry blocks outside this set are
provably useless to the SCF functional, not merely unlikely to be used. Building and holding a
pair-coefficient cache for them was measured on 08-Oct-2026 to waste 55 % of both the cache memory and
the setup time of a Ti III layer (18 symmetries present, 5 spanned by the reference).
The restriction is safe for the OUTPUT as well, which is the part worth checking before trusting it: the
returned multiplet comes from a separate final CI over the WHOLE basis, so the set computed here governs
only which blocks the SCF iterates on, never which levels are reported.JenaAtomicCalculator.SelfConsistent.rotateOrbitals — Method
SelfConsistent.rotateOrbitals(subshellList::Array{Subshell,1}, orbitals::Dict{Subshell, Orbital}, grid::Radial.Grid, settings::AsfSettings) ... rotates pairwise the orbitals to enhance the covergence of the SCF procedures; it follows that rotation schemes of C.F. Fischer ... . The pairwise rotation of the orbitals of the same symmetry is done from the inner-to-outer subshells. A rotation is not necessary if two subshells are filled of if both are fixed. For each rotation, a rotation parameter beta is determined. A pair (newOrbitals::Dict{Subshell, Orbital}, betaMax::Float64) us returned which contains the rotated orbitals as well as the maximum beta parameter that occurred during the pairwise rotation of the orbital set.
JenaAtomicCalculator.SelfConsistent.screenedProduct — Method
SelfConsistent.screenedProduct(Vk::Vector{Float64}, P::Vector{Float64}, Q::Vector{Float64}, primitives::Bsplines.Primitives) ... forms the vector whose i-th entry is INT Bi(r) f(r) wr V_k(r) dr, with f = P on the large block and Q on the small one – i.e. the product of the screened-potential matrix with a coefficient vector, WITHOUT ever building that matrix.
The matrix that InteractionStrength.XL_CoulombKinkAware assembles has entries
wm[i,k] = INT B_i B_k w_r V_k, a full double loop over roughly 110000 (i,k) pairs which re-expands
its B-spline arrays inside the inner loop -- and it is then contracted with a single vector.
Measured 10-Aug-2026 on Be-like C^2+: that assembly was 0.99 s of a 1.32 s gradient, and the
gradient was ~80% of a rotation iteration. Since the matrix is symmetric within each block, both
products a caller needs use the same potential and differ only in the vector.
A Vector{Float64} of length nsL+nsS is returned.JenaAtomicCalculator.SelfConsistent.selectTargetLevelsEOL — Method
SelfConsistent.selectTargetLevelsEOL(mp::Multiplet, levelSelectionCI::LevelSelection) ... to determine the target level(s) of the EOL functional from the (energy-sorted) multiplet mp, using levelSelectionCI EXCLUSIVELY; the three fields consulted are its configurations, symmetries and indices. If levelSelectionCI.configurations is non-empty, the target set is selected by REFERENCE WEIGHT, and is restricted to the listed J^P if levelSelectionCI.symmetries is non-empty as well – the one-orbital-set-per-J route for RAS layers. Otherwise either indices or symmetries may be given, never both: with symmetries the target set is the LOWEST level of each listed symmetry, which is the classic EOL use case, e.g. the lowest J=1/2^+ together with the lowest J=3/2^+; with indices it is those exact levels by their global, energy-sorted index. If levelSelectionCI is inactive, or both arrays are empty, the target set defaults to the single lowest level overall – a genuine OL (one-level) computation. An Array{Level,1} is returned.
JenaAtomicCalculator.SelfConsistent.setEolUnscaledOffDiagonal — Method
SelfConsistent.setEolUnscaledOffDiagonal(flag::Bool) ... sets the experimental switch that keeps the off-diagonal CSF-pair contributions OUT of the (1/occ) scaling in the EOL Fock matrix; nothing is returned.
JenaAtomicCalculator.SelfConsistent.setScfAndersonDepth — Method
SelfConsistent.setScfAndersonDepth(depth::Int64) ... sets the Anderson-mixing depth of the mean-field SCF; 0 restores the plain iteration. Nothing is returned.
JenaAtomicCalculator.SelfConsistent.setScfReorthonormalize — Method
SelfConsistent.setScfReorthonormalize(flag::Bool) ... sets the experimental switch that re-orthonormalizes same-kappa orbitals after the SCF damping step; nothing is returned.
JenaAtomicCalculator.SelfConsistent.solveAverageAtomField — Method
SelfConsistent.solveAverageAtomField(orbitals::Dict{Subshell, Orbital}, nuclearModel::Nuclear.Model, scField::Basics.AbstractScField, temp::Float64, radiusWS::Float64, primitives::Bsplines.Primitives; printout::Bool=true) ... solves the self-consistent field for a given local average-atom potential as specified by scField; a (new) set of orbitals::Dict{Subshell, Orbital} is returned.
A thin wrapper over `solveAverageAtomSpectra`, which does the work and also returns the chemical
potential, the electron counts and the converged density; this form is kept because the subshell
orbitals are all that the properties computed afterwards -- form factors, photoionization cross
sections -- need from the field.JenaAtomicCalculator.SelfConsistent.solveAverageAtomSpectra — Method
SelfConsistent.solveAverageAtomSpectra(orbitals::Dict{Subshell, Orbital}, nuclearModel::Nuclear.Model, scField::Basics.AbstractScField, temp::Float64, radiusWS::Float64, primitives::Bsplines.Primitives; printout::Bool=true, lMaxFree::Int64=-1, freeWaveTolerance::Float64=1.0e-6) ... solves the average-atom field self-consistently IN DENSITY SPACE, i.e. on the full per-kappa B-spline spectrum rather than on a list of subshells, and returns the NamedTuple (orbitals, chemMu, nBound, nCont, rhot, pot, spectra, lMax, radiusBox, accuracy, iterations).
The cycle is spectra -> chemical potential -> density -> potential -> spectra, each step the one named in
Johnson's average-atom equations: `averageAtomSpectra` for the box states of every kappa,
`averageAtomChemicalPotential` for neutrality, `averageAtomDensity` for `4 pi r^2 rho(r)`, and
`averageAtomPotential` for the field it generates. The density is mixed linearly between iterations,
which an average atom needs: the continuum responds to the potential far more strongly than a bound
orbital does, and an unmixed cycle oscillates between a too-ionized and a too-neutral solution instead of
settling.
**THE CELL RADIUS IS THE B-SPLINE BOX, NOT A SEPARATE PARAMETER**, and that is a physical statement rather
than an implementation detail: every state of the model, bound or free, is a box state normalised over
the cell, and the electron count that neutrality is imposed on is the count in THAT volume. A box larger
than the Wigner-Seitz cell therefore solves a different cell and shifts the neutrality condition bodily;
this routine computes with the box it is given and WARNS when the two disagree by more than 5 %.
`orbitals` is used only for its subshell list -- which fixes lMax and which orbitals are handed back for
the properties that follow -- and for the starting density of the first iteration. `lMaxFree` is the
partial wave to which the FREE box states stand in for the true ones; left unset it is derived at every
iteration from `averageAtomFreeWaveLimit`, i.e. from the temperature and the cell, and the printed table
carries the value actually used.JenaAtomicCalculator.SelfConsistent.solveAverageLevelField — Method
SelfConsistent.solveAverageLevelField(basis::Basis, nuclearModel::Nuclear.Model, primitives::Bsplines.Primitives, settings::AsfSettings; printout::Bool=true, andersonDepth::Int64=GBL_AL_ANDERSON_DEPTH) ... solves the average-level (AL) self-consistent field, validated to 5+ significant figures against literature for He/Be/Ne/Ar (see project memory), with a bVector-native architecture modeled directly on DBSRHF (Zatsarinny & Froese Fischer, CPC 202, 287 (2016)): B-spline expansion coefficients (Dict{Subshell,Vector{Float64}}) are the SOLE, canonical, persistent per-iteration orbital state – no Dict{Subshell,Orbital} is maintained across iterations at all, and there is no Bsplines.fitVectorToPrimitives "fit back" step, since bVectors are never derived from a tabulated form to begin with; they come directly from Basics.diagonalize's eigenvector for each subshell, in turn. Orthogonality between same-kappa subshells (e.g. Ne's 1s/2s) is enforced by projecting the Fock matrix (Hamiltonian.projectHamiltonian, reused unchanged) against each ALREADY-PROCESSED lower same-kappa subshell's bVector directly inside the generalized eigenvalue problem, before diagonalizing – matching DBSRHF's hfsolveHF.f90/hfeiv sequential approach – rather than a post-hoc Löwdin symmetric orthogonalization of the whole same-kappa group after the per-orbital loop. The target eigenvalue index is shifted down by one for each such projection applied, mirroring hfeiv's mm = m + (orthogonalized-count) - 1. A tabulated Orbital is only ever built as a disposable, read-only byproduct: once per unique "partner" subshell inside computeTwoElectronV (for the two-electron potential contraction), and once per subshell per iteration purely for reporting/energy-functional evaluation (reusing computeFunctional unchanged) – never stored as competing state, never refit. A final, single export pass (Bsplines.generateOrbitalFromVector) produces a standard Dict{Subshell,Orbital} for the returned basis::Basis, so every downstream consumer (properties, processes, CI/DCB Hamiltonian construction) is unaffected by this being a bVector-native SCF. Reached via performSCF's scField = Basics.ALField() dispatch. A (new) basis::Basis is returned.
WHAT accuracyScf MEANS HERE, and what it does not. The iteration stops when the overlap defect
`1 - |<b_old|b_new>|` of the worst subshell falls below settings.accuracyScf. That defect is QUADRATIC
in the orbital change: the change itself is `|| b_new - b_old ||_B = sqrt(2 * defect)`, so the default
accuracyScf = 1e-6 accepts orbitals that are still moving by 1.4e-3, and leaves the argon energy 6.2e-5
Ha short of the converged value. A user quoting an AL energy at the default is therefore quoting ~1e-4
and not ~1e-6. Both numbers are printed each iteration, and the driver states at the end whether the
field CONVERGED or merely STOPPED at maxIterationsScf -- the latter used to end in silence, so that a
field which never converged printed exactly what a converged one printed. Nothing about the criterion
itself was changed, since that would move every number JAC has ever produced with it.JenaAtomicCalculator.SelfConsistent.solveMeanFieldBasis — Method
SelfConsistent.solveMeanFieldBasis(basis::Basis, nuclearModel::Nuclear.Model, primitives::Bsplines.Primitives, settings::AsfSettings; printout::Bool=true) ... solves the self-consistent field for the given orbitals (from basis), the nuclear model as well as the (local) mean-field potential as specified by the settings::AsfSettings. A (new) basis::Basis is returned.
JenaAtomicCalculator.SelfConsistent.solveMeanFieldBasisAnderson — Method
SelfConsistent.solveMeanFieldBasisAnderson(basis::Basis, nuclearModel::Nuclear.Model, primitives::Bsplines.Primitives, settings::AsfSettings; printout::Bool=true, andersonDepth::Int64=2) ... solves the same mean-field (DFS/HS) self-consistent problem as SelfConsistent.solveMeanFieldBasis, but accelerates the iteration with Anderson mixing. The physics is identical – the same functional, the same fixed point; only the route to it differs, and the returned basis::Basis is the SAME self-consistent solution, reached in fewer iterations.
WHY. The plain iteration is an undamped fixed-point (Picard) map: build the screening potential from the
current orbitals, solve the one-electron Dirac equation in it, take the resulting orbitals as the new
ones. Such a map converges LINEARLY, the residual shrinking by a roughly constant factor r each step, so
the cost to reach a given accuracy scales as log(tol)/log(r). Measured on this code (12-Aug-2026), r is
0.44 for Ar 1s^2..3p^6, 0.57 for Ne 1s^2 2s^2 2p^6 and 0.69 for Fe [Ar] 3d^6 4s^2 -- 17, 25 and 37
iterations respectively to reach 1e-6, and the open-3d case additionally sits at residual ~1 for seven
iterations before descending at all. Anderson mixing forms the next screening potential from a
least-squares combination of the last few iterates and their residuals, which cancels the slowest-decaying
error components instead of waiting for them to decay geometrically.
WHAT IS MIXED. The fixed-point variable is the ELECTRONIC screening potential on the radial grid, not the
orbitals: it is one vector, the nuclear part is constant and drops out, and the map
potential -> orbitals -> potential is exactly the self-consistency condition. andersonDepth = 0 recovers
the plain iteration (and is then Jacobi rather than Gauss-Seidel, see below); the default 2 is the measured optimum here (3 is
nearly equal, larger is WORSE: 24 iterations at 5 and 36 at 12 for Ne), and it
choice and rarely needs changing.
ONE DELIBERATE DIFFERENCE FROM solveMeanFieldBasis. There the potential is rebuilt inside the kappa loop,
so each symmetry is solved in a field the earlier symmetries have already improved (a Gauss-Seidel
sweep); here it is built once per iteration and all symmetries see the same field (a Jacobi sweep), which
is what makes a single well-defined residual per iteration -- and hence Anderson -- possible. Both have
the SAME fixed point, so a converged result is unaffected; only an iteration stopped short of
convergence could differ.
A basis::Basis with the self-consistent orbitals is returned.JenaAtomicCalculator.SelfConsistent.solveOptimizedLevelField — Method
SelfConsistent.solveOptimizedLevelField(basis::Basis, nuclearModel::Nuclear.Model, primitives::Bsplines.Primitives, settings::AsfSettings; printout::Bool=true) ... solves the self-consistent field for the extended-optimal-level (EOL) functional: orbitals are optimized against a statistically-(2J+1)-weighted combination of one or more target ASF levels, with the combination weights coming from the levels' own CI mixing coefficients – never a user-supplied weight. The target level(s) are selected EXCLUSIVELY via settings.levelSelectionCI (either indices or symmetries, never both; if inactive/empty, defaults to indices=[1], a genuine OL/single-level computation). This nests a CI diagonalization inside the AL SCF loop (GRASP rmcdhf90's scf.f90, algorithm 5.1 of Froese Fischer, Comput. Phys. Rep. 3 (1986) 290): diagonalize -> build generalized coefficients from the target levels' mixing vectors -> refine every orbital (reusing computeFockMatrix/computeTwoElectronV unchanged) -> re-diagonalize -> repeat, converging on both orbital self-consistency and the weighted-average energy. Per-CSF-pair angular coefficients (cacheCsfPairCoefficientsEOL) are computed once and reused every outer iteration, since they depend only on the fixed CSF list, never on the current orbitals or mixing coefficients. A (new) multiplet::Multiplet is returned.
KNOWN LIMITATION (confirmed 28-Jul-2026, NOT yet fixed): when two or more CSFs of the SAME symmetry
block compete for the same correlation channel (e.g. Be's 1s^2 2p_1/2^2 vs 1s^2 2p_3/2^2, both
correlating with 1s^2 2s^2), this implementation can converge to a spurious, winner-take-all fixed
point where one competing CSF's mixing coefficient is driven to ~0 while a comparably-important
partner is not -- confirmed against a DFS-Field reference occupying the same CSF space, which lands
both more bound AND with both CSFs contributing substantially. Root cause: the off-diagonal
(CSF-pair) coefficients folded into computeTwoElectronV's two-electron potential scale
LINEARLY in a shrinking CSF's own mixing coefficient, while computeGeneralizedOccupationEOL's
occupation (the (1.0/occ) divisor in computeFockMatrix) scales QUADRATICALLY in it -- so the
ratio diverges as that coefficient shrinks, rather than settling. This is the concrete manifestation
of the "DA/inhomogeneous-term mechanism" gap vs. GRASP's setcof.f90 (which treats within-level
off-diagonal coupling as a separate inhomogeneous/source term, not folded into the same per-orbital
homogeneous eigenvalue division) -- see project_eol_implementation.md. Flooring `occ` before the
division was tried and REJECTED as a fix (non-monotonic in the floor constant).
MEASURED 09-Sep-2026, and the diagnosis above is CONFIRMED but is only HALF of the error. Be
1s^2 2s^2 + 1s^2 2p^2 at Z = 4, every route started from the same average-level basis:
Fock, off-diagonal terms SCALED by 1/occ E = -14.594824221 2p_3/2 <r> = 10.08, weight 1.9e-05
Fock, off-diagonal terms UNSCALED E = -14.610656334 2p_3/2 <r> = 3.41, weight 0.053
average level E = -14.613805206
rotation route E = -14.619514867 2p_1/2, 2p_3/2 agree to 5 digits
Keeping the off-diagonal contributions OUT of the 1/occ scaling -- Basics.FockRoute's
unscaledOffDiagonal, which is its default -- removes the winner-take-all collapse and is worth 15.8 mHa.
WHAT REMAINS IS A DEFECT OF THE EQUATIONS, not of the search, and this is the measurement that shows it:
STARTED AT the rotation minimum, this solver walks UPHILL by 8.86 mHa to the very same fixed point it
reaches from an average-level start (-14.610656351 against -14.610656334). Its fixed point is therefore
not a stationary point of the EOL functional. The reason is that an off-diagonal element such as
R^k(2s,2s,2p,2p) differentiates, with respect to the 2p orbital, into a term proportional to P(2s) -- an
inhomogeneous SOURCE on the right-hand side -- while computeTwoElectronV applies it as a matrix
multiplying P(2p). Removing the 1/occ scaling put that term at the right SIZE; it is still on the wrong
SIDE, which is what GRASP's setcof.f90 carries as a source term. Until that exists this route converges
quickly to an answer reliably above the rotation route's, and the signature to watch for is the two
spin-orbit partners of a subshell disagreeing in mean radius: 2.95 against 3.41 here, where the rotation
route gives 2.502 and 2.502.JenaAtomicCalculator.SelfConsistent.solveOptimizedLevelFieldByRotation — Method
SelfConsistent.solveOptimizedLevelFieldByRotation(basis::Basis, nuclearModel::Nuclear.Model, primitives::Bsplines.Primitives, settings::AsfSettings; printout::Bool=true, nVirtual::Int64=16, method::Symbol=:lbfgs, cgRestart::Int64=10, lbfgsMemory::Int64=12) ... EOL by direct minimization of the energy over orbital ROTATIONS, instead of by solving a per-subshell generalized eigenvalue problem. It sits beside the older solveOptimizedLevelField, which is left untouched; this one is what SelfConsistent.performSCF dispatches to for Basics.EOLField, and hence what every layer of a RasExpansion runs.
Why: the eigenvalue formulation is ill-posed exactly when a correlating CSF's weight becomes small.
Measured (09-Aug-2026) for Be 1s^2 2s^2 + 1s^2 2p^2, the present scheme converges to a DEGENERATE
stationary point -- the 2p^2 weight collapses to -4e-5, so the 2p orbital no longer enters the energy
at all and its gradient vanishes for a trivial reason (|g| = 9e-7). Its energy is 0.0195 Ha above the
true minimum. Minimizing over rotations cannot fall into that trap: the orbital is driven by the
energy gradient rather than selected from a spectrum, and it is free to change character -- which a
correlation orbital must be, and which maximum-overlap selection (tested, refuted) forbids.
Each outer step re-diagonalizes the CI, rebuilds the angular coefficients from the target level(s),
and takes one backtracking-line-search step along the negative gradient projected on the
active-virtual rotations. Occupied-occupied rotations are excluded as redundant.
A multiplet::Multiplet of the target block(s) is returned.
settings.frozenSubshells IS HONOURED: the orbitals it names are held exactly fixed and take no part in
the gradient, the search direction, the curvature history or the line search, while still entering the
energy and the CI matrix and still being orthogonalized against. That distinction is what a RAS layer
means by freezing an orbital, and Basics.generate sets the field for every step of a RasExpansion.
Freezing everything is allowed and is reported as such: the returned multiplet is then the CI result on
the orbitals as given.
WHAT "CONVERGED" MEANS HERE, measured 10-Sep-2026 and worth reading before quoting a number to better than
a milli-Hartree. THE ROUTE FINDS A STATIONARY POINT, NOT NECESSARILY THE MINIMUM, and which one it finds
depends on where it started. Three starting bases on three systems, one route, one tolerance:
case average-level start Fock-point start hydrogenic start spread(AL, Fock)
Be Z=4 -14.619514867 -14.619561354 -14.580896847 0.047 mHa
Be Z=26 -812.786662010 -812.787235260 -812.774914173 0.573 mHa
C Z=6 -37.722777567 -37.722694227 -37.681361605 0.083 mHa
ALL NINE REPORTED CONVERGED. Three things follow, none of them a defect to be fixed:
* A HYDROGENIC START COSTS 12 TO 41 mHa, which is why SelfConsistent.performSCF always starts this route
from an average-level basis and never from the initial guess. That decision predates this measurement;
the numbers are what it is worth.
* BETWEEN THE TWO LEGITIMATE STARTS the answers differ by 0.05 to 0.57 mHa, and NEITHER IS SYSTEMATICALLY
BETTER -- the Fock start wins on both Be cases, the average-level start on C. That is a flat valley with
several shallow stationary points, not one start stopping early.
* TIGHTENING accuracyScf DOES NOTHING. At 1e-8, 1e-10 and 1e-12 the Be Z=26 answers are BIT-IDENTICAL in
identical iteration counts, because the exit is not accuracyScf at all: it is the energy's own
double-precision resolution, 32 eps |E| = 3.64e-12 Ha there, four orders of magnitude below the
tolerance. Each run is converged as far as arithmetic permits and they still land 0.573 mHa apart.
So CONVERGED means "stationary to machine resolution FROM THIS START", not "the minimum". The variational
principle still holds -- a lower energy is the better calculation -- but nothing here identifies the lowest
of these as global. Where a milli-Hartree matters, run from more than one start and keep the lowest; it
costs one extra run and is the only honest way to bound the answer.JenaAtomicCalculator.SelfConsistent.virtualDirections — Method
SelfConsistent.virtualDirections(bVectors::Dict{Subshell, Vector{Float64}}, subshells::Array{Subshell,1}, primitives::Bsplines.Primitives, nucPot::Radial.Potential, matrixB::Array{Float64,2}, storage::Dict{String,Array{Float64,2}}; nVirtual::Int64=20, spectrum=nothing) ... builds, for each subshell, an S-orthonormal set of ALLOWED rotation directions: positive-branch eigenvectors of the one-electron Dirac matrix of that kappa, projected free of every occupied orbital of the same kappa. Rotations among the occupied orbitals themselves are deliberately excluded – they leave the CSF space invariant, are redundant, and would make the Hessian singular. A Dict{Subshell, Array{Vector{Float64},1}} is returned.
Statistical tensors of an ensemble
JenaAtomicCalculator.Statistical.ResonanceR — Method
Statistical.ResonanceR() ... constructor for an empty instance of Statistical.ResonanceR(). A resonanceR::Statistical.ResonanceR is returned.
JenaAtomicCalculator.Statistical.ResonanceR — Type
struct Statistical.ResonanceR ... defines a type for a resonance state in the continuum with a well-defined bound-ionic core, one or several electrons in the continuum, a width as well as a loss rate due to additional decay processes. It is used where an ensemble EVOLVES IN TIME and a width genuinely matters; an ordinary bound level needs no such dressing and is labelled by a Basics.LevelKey instead.
+ isBound ::Bool ... True if it just refers to a bound state with no electron in the continuum.
+ ionLevel ::Level ... Level of the bound-state core.
+ widths ::Float64 ... Widths of the resonance state.
+ lossRate ::Float64 ... Loss rate due to processes that are not considered explicitly in the time evolution.JenaAtomicCalculator.Statistical.Tensor — Method
Statistical.Tensor(k::Int64, q::Int64, a::LevelKey, value::ComplexF64; axis::Basics.AbstractQuantizationAxis=Basics.DefaultQuantizationAxis())
... constructor for a DIAGONAL statistical tensor component from integer rank and projection, the usual case; a
`tensor::Statistical.Tensor` is returned.JenaAtomicCalculator.Statistical.Tensor — Method
Statistical.Tensor() ... constructor for an empty instance of Statistical.Tensor(). A tensor::Statistical.Tensor is returned.
JenaAtomicCalculator.Statistical.Tensor — Type
struct Statistical.Tensor ... defines a type for a statistical tensor of given rank k, projection q and with respect to two levels. Both levels are named because that is the general definition, rho_kq(alpha J, alpha' J'); the diagonal case a == b is the usual one and covers alignment, orientation and every angular distribution.
+ k ::AngularJ64 ... Rank of the tensor.
+ q ::AngularM64 ... Projection of the tensor rank.
+ a ::LevelKey ... Level a with total symmetry alpha J.
+ b ::LevelKey ... Level b with total symmetry alpha' J'.
+ axis ::Basics.AbstractQuantizationAxis ... the axis this component refers to; see the module docstring.
+ value ::ComplexF64 ... value of the statistical tensor.JenaAtomicCalculator.Statistical.alignmentParameters — Method
Statistical.alignmentParameters(tensors::Array{Statistical.Tensor,1}) ... converts a list of statistical tensors into the NORMALIZED alignment parameters Akq = rhokq / rho00, which are the quantities an angular distribution or a polarization is usually expressed in. The rho00 component must be present and non-zero, since an empty ensemble has no alignment to speak of; an aTensors::Array{Statistical.Tensor,1} is returned, carrying the same ranks and the same axis.
JenaAtomicCalculator.Statistical.computeTensors — Method
Statistical.computeTensors(kmax::Int64, amplitudes::Dict{AngularM64,ComplexF64}, a::LevelKey; axis::Basics.AbstractQuantizationAxis=Basics.DefaultQuantizationAxis())
... computes all statistical tensors rho_kq of ranks k = 0..kmax for an ensemble described by COHERENT amplitudes
a_M, one per magnetic sublevel, i.e. for the density matrix rho_(M,M') = a_M conj(a_M'). This is the case of a
single, fully specified initial state; where the initial sublevels are unobserved and must be summed over
incoherently, use the population form below instead. A `tensors::Array{Statistical.Tensor,1}` is returned.JenaAtomicCalculator.Statistical.computeTensors — Method
Statistical.computeTensors(kmax::Int64, populations::Dict{AngularM64,Float64}, a::LevelKey; axis::Basics.AbstractQuantizationAxis=Basics.DefaultQuantizationAxis())
... computes the statistical tensors rho_kq of ranks k = 0..kmax for an ensemble given by its sublevel POPULATIONS
sigma(M), i.e. for a density matrix that is diagonal in M. This is the ordinary case in which the initial
sublevels are unobserved and summed over incoherently, and it yields q = 0 components only, since coherence
between different M is what a non-zero q describes. A `tensors::Array{Statistical.Tensor,1}` is returned.JenaAtomicCalculator.Statistical.computeTensors — Method
Statistical.computeTensors(kmax::Int64, densityMatrix::Dict{Tuple{AngularM64,AngularM64},ComplexF64}, a::LevelKey; axis::Basics.AbstractQuantizationAxis=Basics.DefaultQuantizationAxis())
... computes the statistical tensors rho_kq of ranks k = 0..kmax from the GENERAL density matrix rho(M,M') of the
ensemble in the given level, which is the definition itself and of which the population and amplitude forms
below are special cases. A pair (M,M') that is absent from the dictionary is taken as zero, so only the
non-vanishing elements need be supplied. A `tensors::Array{Statistical.Tensor,1}` is returned.JenaAtomicCalculator.Statistical.densityMatrix — Method
Statistical.densityMatrix(tensors::Array{Statistical.Tensor,1}) ... reconstructs the sublevel density matrix rho(M,M') from a COMPLETE set of statistical tensors, i.e. inverts computeTensors. The Clebsch-Gordan coefficients connecting the two form an orthogonal matrix, so the inverse is the same sum read the other way; it is exact rather than approximate, and a round trip through both returns the original matrix. All ranks k = 0..2J must be present for the result to be complete, since a truncated set describes a different ensemble. A dm::Dict{Tuple{AngularM64,AngularM64},ComplexF64} is returned.
JenaAtomicCalculator.Statistical.invariant — Method
Statistical.invariant(tensors::Array{Statistical.Tensor,1}, k::Int64) ... returns the ROTATIONALLY INVARIANT magnitude sqrt( SUMq |rhokq|^2 ) of the rank k, which does not depend on the axis the tensors were computed about. It is the honest quantity to quote when the axis is not the system's own symmetry axis: a single component such as rho_20 may be near zero merely because the axis is badly chosen, while this magnitude is not. A value::Float64 is returned.
JenaAtomicCalculator.Statistical.isPhysical — Method
Statistical.isPhysical(tensors::Array{Statistical.Tensor,1}; tolerance::Float64=1.0e-8) ... checks whether the given statistical tensors could be the rhokq of a genuine physical ensemble, for the DIAGONAL case a == b that every computeTensors method above produces. Two independent conditions are tested. HERMITICITY: every component must be matched in the same list by its partner rho{k,-q} = (-1)^q * conj(rho_kq); a missing partner is read as zero, exactly as tensorValue(...; withZeros=true) reads it, so an asymmetric list fails rather than raising. POSITIVITY: the sublevel density matrix rho(M,M'), reconstructed by Statistical.densityMatrix, must be Hermitian and positive-semidefinite, i.e. the ensemble it describes has no negative population along any direction. A level pair with a != b is a coherence between two different levels, not a single-level density matrix, and has no positivity notion defined here; this method raises on one rather than silently passing it. A physical::Bool is returned.
JenaAtomicCalculator.Statistical.rotate — Method
Statistical.rotate(tensors::Array{Statistical.Tensor,1}, alpha::Float64, beta::Float64, gamma::Float64; axis::Basics.AbstractQuantizationAxis=Basics.DefaultQuantizationAxis())
... rotates the given statistical tensors into a new frame obtained by the Euler angles (alpha, beta, gamma), using
rho_kq(new) = SUM_q' rho_kq'(old) * conj( D^k_(q'q)(alpha,beta,gamma) ). Each rank mixes only among its own
2k+1 components, which is the property that makes the tensors worth forming at all, and the rank-0 component is
left untouched. The new axis is recorded in the returned components, so that a rotated tensor cannot later be
mistaken for one about the original axis; a `tensors::Array{Statistical.Tensor,1}` is returned.JenaAtomicCalculator.Statistical.tensorValue — Method
Statistical.tensorValue(k::Int64, q::Int64, tensors::Array{Statistical.Tensor,1}; withZeros::Bool=false) ... returns the value of the statistical tensor component rho_kq if it is contained in the given list. With withZeros = true a missing component is reported as zero, which is the right reading for a component that was simply not populated; otherwise a missing component raises, so that a typo in k or q is not silently read as a vanishing alignment. A value::ComplexF64 is returned.
Typed result keys
JenaAtomicCalculator.ResultKeys.CascadeData — Type
struct ResultKeys.CascadeData ... the cascade's blocks and lines; was "cascade data:".
JenaAtomicCalculator.ResultKeys.CascadeScheme — Type
struct ResultKeys.CascadeScheme ... the scheme the cascade was run under; was "cascade scheme".
JenaAtomicCalculator.ResultKeys.CiMultiplet — Type
struct ResultKeys.CiMultiplet ... was "CI multiplet".
JenaAtomicCalculator.ResultKeys.DataFormat — Type
struct ResultKeys.DataFormat ... the format the cascade data was written in; was "data format:".
JenaAtomicCalculator.ResultKeys.DielectronicCaptureLines — Type
struct ResultKeys.DielectronicCaptureLines ... was "dielectronic-capture lines:". NOT the same quantity as DielectronicRecombination.Settings, which is the full recombination; this is the capture step alone.
JenaAtomicCalculator.ResultKeys.DielectronicMultiplets — Type
struct ResultKeys.DielectronicMultiplets ... was "dielectronic multiplets:".
JenaAtomicCalculator.ResultKeys.EiiCrossSections — Type
struct ResultKeys.EiiCrossSections ... was "EII cross sections:".
JenaAtomicCalculator.ResultKeys.FinalMultiplet — Type
struct ResultKeys.FinalMultiplet ... the final-state multiplet of a process computation; was "finalMultiplet", likewise without a colon.
JenaAtomicCalculator.ResultKeys.GeneratedMultiplets — Type
struct ResultKeys.GeneratedMultiplets ... the multiplets a cascade generated; was "generated multiplets:".
JenaAtomicCalculator.ResultKeys.GreenChannels — Type
struct ResultKeys.GreenChannels ... was "Green channels".
JenaAtomicCalculator.ResultKeys.Grid — Type
struct ResultKeys.Grid ... the radial grid used; was "grid:".
JenaAtomicCalculator.ResultKeys.HollowIonLineData — Type
struct ResultKeys.HollowIonLineData ... was "hollow-ion line data:".
JenaAtomicCalculator.ResultKeys.IjfMultiplet — Type
struct ResultKeys.IjfMultiplet ... the IJF-coupled multiplet of a hyperfine computation; was "IJF multiplet:". That branch is presently disabled in Basics.perform, and the key is carried so that re-enabling it needs no new name.
JenaAtomicCalculator.ResultKeys.ImpactExcitedMultiplets — Type
struct ResultKeys.ImpactExcitedMultiplets ... was "impact-excited multiplets:".
JenaAtomicCalculator.ResultKeys.InitialMultiplet — Type
struct ResultKeys.InitialMultiplet ... the initial-state multiplet of a process computation; was "initialMultiplet" – note that this one carried NO colon.
JenaAtomicCalculator.ResultKeys.InitialMultiplets — Type
struct ResultKeys.InitialMultiplets ... the multiplets a cascade starts from; was "initial multiplets:". PLURAL, and distinct from InitialMultiplet, which is the single initial-state multiplet of a process computation.
JenaAtomicCalculator.ResultKeys.IntermediateMultiplet — Type
struct ResultKeys.IntermediateMultiplet ... the intermediate-state multiplet, where the process has one; was "intermediateMultiplet", likewise without a colon.
JenaAtomicCalculator.ResultKeys.MeanFieldBasis — Type
struct ResultKeys.MeanFieldBasis ... was "mean-field basis".
JenaAtomicCalculator.ResultKeys.MeanFieldMultiplet — Type
struct ResultKeys.MeanFieldMultiplet ... was "mean-field multiplet".
JenaAtomicCalculator.ResultKeys.MeanPotential — Type
struct ResultKeys.MeanPotential ... was "mean potential".
JenaAtomicCalculator.ResultKeys.Multiplet — Type
struct ResultKeys.Multiplet ... the multiplet of a structure computation; was "multiplet:".
JenaAtomicCalculator.ResultKeys.Name — Type
struct ResultKeys.Name ... the computation's name; was "name" OR "name:" – the same quantity under two strings, which is why it is one key here.
JenaAtomicCalculator.ResultKeys.Orbitals — Type
struct ResultKeys.Orbitals ... was "orbitals".
JenaAtomicCalculator.ResultKeys.PhotoExcitationLineData — Type
struct ResultKeys.PhotoExcitationLineData ... was "photoexcitation line data:".
JenaAtomicCalculator.ResultKeys.PhotoExcitedMultiplets — Type
struct ResultKeys.PhotoExcitedMultiplets ... was "photoexcited multiplets:".
JenaAtomicCalculator.ResultKeys.PhotoIonizedMultiplets — Type
struct ResultKeys.PhotoIonizedMultiplets ... was "photoionized multiplets:".
JenaAtomicCalculator.ResultKeys.PhotoRecombinationLineData — Type
struct ResultKeys.PhotoRecombinationLineData ... was "photo-recombination line data:". LINE DATA, i.e. the cascade's own record, not the PhotoRecombination.Settings lines.
JenaAtomicCalculator.ResultKeys.ReferenceMultiplet — Type
struct ResultKeys.ReferenceMultiplet ... was "reference multiplet".
JenaAtomicCalculator.ResultKeys.SimulationData — Type
struct ResultKeys.SimulationData ... the data a cascade simulation consumed; was "data:".
JenaAtomicCalculator.ResultKeys.SimulationProperty — Type
struct ResultKeys.SimulationProperty ... the property a cascade simulation computed; was "property:".
JenaAtomicCalculator.ResultKeys.SuperConfigurationGroups — Type
struct ResultKeys.SuperConfigurationGroups ... the SuperConfigurations.Group per reference configuration; was "superconfiguration groups".
JenaAtomicCalculator.ResultKeys.SuperConfigurationIonizationCharges — Type
struct ResultKeys.SuperConfigurationIonizationCharges ... each stage's charge, matching SuperConfigurationIonizationGroups in order; was "superconfiguration ionization charges".
JenaAtomicCalculator.ResultKeys.SuperConfigurationIonizationElectronDensity — Type
struct ResultKeys.SuperConfigurationIonizationElectronDensity ... the converged self-consistent electron number density [a.u.]; was "superconfiguration ionization electron density".
JenaAtomicCalculator.ResultKeys.SuperConfigurationIonizationGroupPopulations — Type
struct ResultKeys.SuperConfigurationIonizationGroupPopulations ... the same equilibrium population, resolved per GROUP within each stage, summing to 1 over ALL stages together; was "superconfiguration ionization group populations".
JenaAtomicCalculator.ResultKeys.SuperConfigurationIonizationGroups — Type
struct ResultKeys.SuperConfigurationIonizationGroups ... one SuperConfigurations.Group array per ionization stage; was "superconfiguration ionization groups".
JenaAtomicCalculator.ResultKeys.SuperConfigurationIonizationStagePopulations — Type
struct ResultKeys.SuperConfigurationIonizationStagePopulations ... the equilibrium population fraction per stage, summing to 1; was "superconfiguration ionization stage populations".
JenaAtomicCalculator.ResultKeys.SuperConfigurationMixtureBoundFreeOpacity — Type
struct ResultKeys.SuperConfigurationMixtureBoundFreeOpacity ... added 18-Oct-2026: the mixture's own bound-free (photoionization) kappa(omega), on the SAME opacityOmegas grid, summed over every adjacent-stage pair of every species and weighted the same way the bound-bound spectrum is. Present ONLY when scheme.boundFreeApprox !== nothing; was "superconfiguration mixture bound-free opacity". See ResultKeys.SuperConfigurationMixtureFreeFreeOpacity for the SEPARATE free-free contribution.
JenaAtomicCalculator.ResultKeys.SuperConfigurationMixtureCharges — Type
struct ResultKeys.SuperConfigurationMixtureCharges ... one charge array per species (matching refConfigsPerSpeciesStages's own stage order), added 18-Oct-2026 when the mixture scheme gained its own stage axis; was "superconfiguration mixture charges".
JenaAtomicCalculator.ResultKeys.SuperConfigurationMixtureElectronDensity — Type
struct ResultKeys.SuperConfigurationMixtureElectronDensity ... the ONE converged electron number density [a.u.] shared by the WHOLE mixture (every species, every stage); was "superconfiguration mixture electron density".
JenaAtomicCalculator.ResultKeys.SuperConfigurationMixtureFreeFreeOpacity — Type
struct ResultKeys.SuperConfigurationMixtureFreeFreeOpacity ... added 19-Oct-2026: the mixture's own free-free (inverse-bremsstrahlung) kappa(omega), on the SAME opacityOmegas grid, summed over EVERY stage (no adjacency needed – a stage's own ion charge alone sets its free-free cross section) of every species and weighted the same way the bound-bound spectrum is. Present ONLY when scheme.freeFreeIncluded; was "superconfiguration mixture free-free opacity".
JenaAtomicCalculator.ResultKeys.SuperConfigurationMixtureOpacitySpectrum — Type
struct ResultKeys.SuperConfigurationMixtureOpacitySpectrum ... the number-fraction-weighted SUM of every species' own spectrum; was "superconfiguration mixture opacity spectrum".
JenaAtomicCalculator.ResultKeys.SuperConfigurationMixturePlanckOpacity — Type
struct ResultKeys.SuperConfigurationMixturePlanckOpacity ... the Planck mean of the BOUND-BOUND-ONLY mixture spectrum (unaffected by boundFreeApprox, so its meaning never changes); was "superconfiguration mixture planck opacity". See ResultKeys.SuperConfigurationMixtureTotalOpacitySpectrum for the Planck mean of the FULL (bound-bound+bound-free) spectrum once bound-free is turned on.
JenaAtomicCalculator.ResultKeys.SuperConfigurationMixtureResonanceCorrections — Type
struct ResultKeys.SuperConfigurationMixtureResonanceCorrections ... added 20-Oct-2026: one (species,stage,group,meanEnergy, gfEff,widthEv) tuple per ground- to-resonance line actually corrected from a Gaussian to a Voigt profile (an OPEN autoionization channel AND a genuine E1 array existing for that pair – see Plasma.resonanceAutoionizationWidth and Plasma.resonanceTransitionArrays for the two conditions). Present ONLY when scheme.resonanceContinuumGrid !== nothing; was "superconfiguration mixture resonance corrections". The correction itself is already folded into SuperConfigurationMixtureOpacitySpectrum – this key is for INSPECTING which lines were touched, not a separate contribution to add in.
JenaAtomicCalculator.ResultKeys.SuperConfigurationMixtureRosselandOpacity — Type
struct ResultKeys.SuperConfigurationMixtureRosselandOpacity ... added 18-Oct-2026, GENERALIZED 19-Oct-2026: the Rosseland mean of the TOTAL spectrum (bound-bound plus whichever of bound-free/free-free are on) – MUCH LESS floor-sensitive than bound-bound alone once a continuum contribution exists (measured stable across 9 orders of magnitude of the internal floor choice on a real case, vs. 12 orders of movement for bound-bound alone), but NOT unconditionally floor-free – see Plasma.displayMixtureSpectrumBreakdown's own docstring. Present whenever EITHER continuum switch is on; remains a LOWER BOUND whenever the OTHER one is still off.
JenaAtomicCalculator.ResultKeys.SuperConfigurationMixtureSpeciesOpacities — Type
struct ResultKeys.SuperConfigurationMixtureSpeciesOpacities ... one Stage-3 kappa(omega) array per species, in scheme's own order; was "superconfiguration mixture species opacities".
JenaAtomicCalculator.ResultKeys.SuperConfigurationMixtureStagePopulations — Type
struct ResultKeys.SuperConfigurationMixtureStagePopulations ... one stage-population array per species, summing to 1 WITHIN that species (not across the whole mixture); was "superconfiguration mixture stage populations".
JenaAtomicCalculator.ResultKeys.SuperConfigurationMixtureTotalOpacitySpectrum — Type
struct ResultKeys.SuperConfigurationMixtureTotalOpacitySpectrum ... added 18-Oct-2026, GENERALIZED 19-Oct-2026: bound-bound PLUS whichever of bound-free/free-free are switched on, i.e. SuperConfigurationMixtureOpacitySpectrum plus ...BoundFreeOpacity (if scheme.boundFreeApprox !== nothing) plus ...FreeFreeOpacity (if scheme.freeFreeIncluded), on the same opacityOmegas grid. Present whenever EITHER continuum switch is on; this is the spectrum both Plasma.planckMeanOpacity and Plasma.rosselandMeanOpacity are evaluated on for ...TotalPlanckOpacity and ...RosselandOpacity below.
JenaAtomicCalculator.ResultKeys.SuperConfigurationMixtureTotalPlanckOpacity — Type
struct ResultKeys.SuperConfigurationMixtureTotalPlanckOpacity ... added 18-Oct-2026, GENERALIZED 19-Oct-2026: the Planck mean of the TOTAL spectrum (bound-bound plus whichever of bound-free/free-free are on) – distinct from SuperConfigurationMixturePlanckOpacity, which stays bound-bound-only so its own meaning never changes. Present whenever EITHER continuum switch is on.
JenaAtomicCalculator.ResultKeys.SuperConfigurationOpacityContributions — Type
struct ResultKeys.SuperConfigurationOpacityContributions ... that gf weighted by the lower configuration's population; was "superconfiguration opacity contributions".
JenaAtomicCalculator.ResultKeys.SuperConfigurationOpacitySpectrum — Type
struct ResultKeys.SuperConfigurationOpacitySpectrum ... the Stage-3 summed per-absorber cross section kappa(omega), present only when scheme.opacityOmegas was non-empty; was "superconfiguration opacity spectrum".
JenaAtomicCalculator.ResultKeys.SuperConfigurationPopulations — Type
struct ResultKeys.SuperConfigurationPopulations ... the Boltzmann population fraction per group, matching SuperConfigurationGroups in order; was "superconfiguration populations".
JenaAtomicCalculator.ResultKeys.SuperConfigurationTransitionArrays — Type
struct ResultKeys.SuperConfigurationTransitionArrays ... one SuperConfigurations.TransitionArray per E1-connected pair of reference configurations; was "superconfiguration transition arrays".
JenaAtomicCalculator.ResultKeys.SuperConfigurationTransitionGf — Type
struct ResultKeys.SuperConfigurationTransitionGf ... each array's own oscillator-strength sum gf = (2/3)*meanEnergy*totalStrength, matching SuperConfigurationTransitionArrays in order; was "superconfiguration transition gf".