Atomic computations

JenaAtomicCalculator.Atomic.Computation — Type

struct Computation ... defines a type for defining (the model of simple) atomic computation of a single multiplet, including the SCF and CI as well as level properties and transition property calculations.

+ name                           ::String                          ... A name associated to the computation.
+ nuclearModel                   ::Nuclear.Model                   ... Model, charge and parameters of the nucleus.
+ grid                           ::Radial.Grid                     ... The radial grid to be used for the computation.
+ propertySettings               ::Array{Basics.AbstractPropertySettings,1}  ... List of atomic properties to be calculated.
+ configs                        ::Array{Configuration,1}          ... A list of non-relativistic configurations.
+ asfSettings                    ::AsfSettings                     
    ... Provides the settings for the SCF process and for the CI and QED calculations.
+ initialConfigs                 ::Array{Configuration,1}        
    ... A list of initial-state configurations for some transition property calculation, such as radiative transition, Auger, etc. 
+ initialAsfSettings             ::AsfSettings                     ... Provides the SCF and CI settings for the initial-state multiplet.
+ intermediateConfigs            ::Array{Configuration,1}          ... A list of initial-state configurations.
+ intermediateAsfSettings        ::AsfSettings                     ... Provides the SCF settings for the intermediate-state multiplet.
+ finalConfigs                   ::Array{Configuration,1}          ... A list of final-state configurations.
+ finalAsfSettings               ::AsfSettings                     ... Provides the SCF and CI settings for the final-state multiplet.
+ orbitalSource                  ::Basics.AbstractOrbitalSource    ... Says WHICH one-electron orbital set the initial, intermediate and
                                                                       final
                                                                       multiplets are built on. `SeparateOrbitals()` is the default and
                                                                       is what JAC
                                                                       has always done -- every multiplet from its own SCF. The
                                                                       alternatives exist
                                                                       because an explicit SECOND-ORDER amplitude is valid only on ONE
                                                                       orthonormal
                                                                       set: `ManyElectron.matrixElement_HminusE` drops the overlap term
                                                                       `-E <r|s>`,
                                                                       which vanishes identically only then. See
                                                                       `Basics.AbstractOrbitalSource`.
+ processSettings                ::Basics.AbstractProcessSettings  ... Provides the settings for the selected process.
source
JenaAtomicCalculator.Atomic.Computation — Method

Atomic.Computation(wa::Bool) ... to return a default computation::Atomic.Computation, which the keyword copy-constructor above then modifies; the argument wa is not read. The two examples below show the typical use.

Example for SCF computations:

    grid     = Radial.Grid(true)
    nuclearM = Nuclear.Model(18., FermiNucleus())
    settings = AsfSettings(AsfSettings(), selectLevelsCI = true, selectedLevelsCI = [1,2, 4,5, 7,8], jjLS = LSjjSettings(false) )
    configs  = [Configuration("[Ne] 3s^2 3p^5"), Configuration("[Ne] 3s 3p^6")]
    Atomic.Computation(Atomic.Computation(), name="Example", grid=grid, nuclearModel=nuclearM, configs=configs, asfSettings=settings )

Example for the computation of one atomic process:

    grid           = Radial.Grid(true)
    initialConfigs = [Configuration("[Ne] 3s 3p^6"), Configuration("[Ne] 3s^2 3p^4 3d")]
    finalConfigs   = [Configuration("[Ne] 3s^2 3p^5")] 
    photoSettings  = PhotoEmission.Settings(PhotoEmission.Settings(), multipoles=[E1, M1], gauges=[UseCoulomb], printBefore=true)
    Atomic.Computation(Atomic.Computation(), name="Example", grid=grid, nuclearModel=nuclearM;
                        initialConfigs=initialConfigs, finalConfigs=finalConfigs, 
                        process = Radiative(), processSettings=photoSettings ); 

Either example is adapted by overwriting the parameters that matter for the case at hand.
source
JenaAtomicCalculator.Atomic.Computation — Method

Atomic.Computation(comp::Atomic.Computation; name::Union{Nothing,String}=nothing, nuclearModel::Union{Nothing,Nuclear.Model}=nothing, grid::Union{Nothing,Radial.Grid}=nothing, propertySettings::Union{Nothing,Array{Basics.AbstractPropertySettings,1},Any}=nothing, configs::Union{Nothing,Array{Configuration,1}}=nothing, asfSettings::Union{Nothing,AsfSettings}=nothing, initialConfigs::Union{Nothing,Array{Configuration,1}}=nothing, initialAsfSettings::Union{Nothing,AsfSettings}=nothing, intermediateConfigs::Union{Nothing,Array{Configuration,1}}=nothing, intermediateAsfSettings::Union{Nothing,AsfSettings}=nothing, finalConfigs::Union{Nothing,Array{Configuration,1}}=nothing, finalAsfSettings::Union{Nothing,AsfSettings}=nothing, orbitalSource::Union{Nothing,Basics.AbstractOrbitalSource}=nothing, processSettings::Union{Nothing,Any}=nothing, printout::Bool=false)

... constructor for modifying the given Atomic.Computation by 'overwriting' the previously selected parameters.
    A `computation::Atomic.Computation` is returned.
source
JenaAtomicCalculator.Atomic.checkPropertySettings — Method

Atomic.checkPropertySettings(propertySettings) ... refuses a propertySettings list that carries TWO settings OF THE SAME TYPE. Nothing is returned; the offending case raises.

    **THE ARGUMENT IS DELIBERATELY UNTYPED**, and the first version of this guard got it wrong in exactly
    the way item 84 did: `[s1, s2]` written with two settings of ONE type has the concrete type
    `Vector{NuclearShielding.Settings}`, not `Array{Basics.AbstractPropertySettings,1}`, so a signature
    naming the abstract element type does not match the very case the guard exists for -- it raised a
    `MethodError` instead of the explanation. Anything that is not an array is passed over silently, since
    the keyword itself admits `Any`.

    **A `Computation` RUNS ONE COMPUTATION, FOR ONE PROPERTY OR ONE PROCESS, and higher complexity is not
    built on top of it** -- the maintainer's decision, 21-Oct-2026. A scan, a convergence study or a
    comparison of models is a SCRIPT: one `perform` does the structure, and the loop or the arithmetic sits
    around the terms it stored. The economics agree, measured on Th4+ [Rn] the same day: the
    self-consistent field costs 65.1 s and one shielding property on it 0.6 s, so the structure is 99 % of
    the work and six `Computation`s cost 5.8x what one field and a loop cost, for no physics.

    **IT RAISES RATHER THAN WARNS, AND THAT IS THE POINT.** Until this guard existed the duplicate was
    accepted and the result was LOST: every property branch of `Basics.perform` stores its outcome under a
    constant string key, so the second write replaced the first and `Base.merge` said nothing -- measured,
    two `NuclearShielding.Settings` differing only in `nVirtualMax` went in and ONE outcome came back, the
    second. There is no use for which that is the wanted behaviour, so a warning would leave a wrong number
    in circulation; this stops at construction, where the mistake is, rather than deep inside `perform`
    where only the symptom shows.

+ propertySettings  ::Array{Basics.AbstractPropertySettings,1}   ... the list as given to the Computation.
source
JenaAtomicCalculator.Atomic.warnAboutUnusedSettings — Method

Atomic.warnAboutUnusedSettings(comp::Atomic.Computation) ... warns about every AsfSettings field of the given computation that the path it will actually take can NEVER read, and whose value differs from the default. An Atomic.Computation carries FOUR such fields – asfSettings for the configs path, and initialAsfSettings / intermediateAsfSettings / finalAsfSettings for the initial/final path – deliberately, so that each multiplet may carry its own correlation model. Only the fields of the chosen path are consulted, and a value placed in one of the others is silently ignored: someone who sets eeInteractionCI = CoulombBreit(...) in asfSettings while giving initialConfigs gets a Coulomb-only CI with no indication why.

    THE COMPARISON AGAINST THE DEFAULT IS WHAT MAKES THIS USABLE. Every computation carries all four fields
    whether or not the user touched them, so a check that merely asked "is this path reading the field" would
    fire on every run and be ignored within a week. AsfSettings defines Base.:(==), so `!= AsfSettings()`
    separates "the user set this" from "untouched".

    IT IS A WARNING AND NEVER AN ERROR: one Computation may legitimately be built once and reused across paths.
    And it catches only a field that is NEVER consulted -- it cannot catch someone who fills initialAsfSettings
    where finalAsfSettings was meant, since both are read. Nothing is returned.
source

Adjusted level energies: fitted Coulomb corrections

JenaAtomicCalculator.AdjustedLevels.FitTarget — Type

struct AdjustedLevels.FitTarget ... one measured level this fit was matched against.

+ index            ::Int64    ... position in THIS symmetry block's own energy-sorted spectrum, 1 =
                                    lowest -- NOT a global JAC level index, and NOT comparable across
                                    different symmetry blocks (see this module's own docstring).
+ measuredEnergy   ::Float64  ... the measured excitation energy relative to this SAME block's lowest
                                    level, in cm^-1.
+ fittedEnergy     ::Float64  ... the corresponding excitation energy from the fitted, re-diagonalized
                                    spectrum, in cm^-1, for direct comparison.
source
JenaAtomicCalculator.AdjustedLevels.FittedBlock — Type

struct AdjustedLevels.FittedBlock ... one symmetry block's share of a AdjustedLevels.FittedMultipletOrthogonalMultiBlock fit: the radial parameters are shared GLOBALLY across every block of such a fit, but each block keeps its own CSFs, its own re-diagonalized levels and its own measured targets.

+ sym          ::LevelSymmetry              ... which J^P block this is.
+ multiplet    ::ManyElectron.Multiplet      ... this block's re-diagonalized, fitted levels.
+ fitTargets   ::Array{FitTarget,1}          ... the measured levels THIS block was matched against.
source
JenaAtomicCalculator.AdjustedLevels.FittedMultiplet — Type

struct AdjustedLevels.FittedMultiplet ... the result of AdjustedLevels.fitScaleFactor. See this module's own docstring for what this is, and – at least as importantly – is NOT.

+ multiplet       ::ManyElectron.Multiplet     ... the single-symmetry-block multiplet from the FITTED,
                                                     re-diagonalized Hamiltonian; same CSFs/orbitals as
                                                     the input Basis.
+ scaleFactors    ::Array{ScalingParameter,1}   ... the fitted scaling parameter(s) -- never empty.
+ fitTargets       ::Array{FitTarget,1}          ... the measured levels this fit was matched against.
+ rmsDeviation      ::Float64                    ... root-mean-square deviation, fitted vs measured, over
                                                       the fit targets, in cm^-1.
+ source            ::String                    ... a dated citation for the measured data used.
source
JenaAtomicCalculator.AdjustedLevels.FittedMultipletGrouped — Type

struct AdjustedLevels.FittedMultipletGrouped ... the result of AdjustedLevels.fitGroupedParameters. The sibling of AdjustedLevels.FittedMultipletOrthogonal for the grouped (Slater-vs-CI) route – a DIFFERENT type, deliberately, matching that module convention, so a reader can tell at a glance which of the three class-aware routes produced a given result.

+ multiplet             ::ManyElectron.Multiplet         ... the single-symmetry-block multiplet from the
                                                                FITTED, re-diagonalized Hamiltonian.
+ groupedParameters      ::Array{GroupedParameter,1}       ... the fitted factors, one PER FAMILY (at
                                                                  most two), translated back to the
                                                                  familiar language.
+ orthogonalParameters   ::Array{OrthogonalParameter,1}     ... what was actually fit -- the orthogonal
                                                                   directions over the (at most two)
                                                                   grouped parameters, each with its own
                                                                   determinacy; the sibling of
                                                                   `FittedMultipletOrthogonal`'s own field.
+ fitTargets             ::Array{FitTarget,1}                ... the measured levels this fit was matched
                                                                    against.
+ rmsDeviation           ::Float64                           ... root-mean-square deviation, fitted vs
                                                                    measured, over the fit targets, in
                                                                    cm^-1, from the EXACT re-diagonalized
                                                                    spectrum (not the linearized estimate).
+ degreesOfFreedom       ::Int64                             ... length(fitTargets) - length(groupedParameters);
                                                                    see `FittedMultipletOrthogonal`'s own
                                                                    field of the same name for what this
                                                                    guards against.
+ source                 ::String                           ... a dated citation for the measured data used.
source
JenaAtomicCalculator.AdjustedLevels.FittedMultipletGroupedMultiBlock — Type

struct AdjustedLevels.FittedMultipletGroupedMultiBlock ... the result of AdjustedLevels.fitGroupedParametersMultiBlock: ONE shared pair of GROUP factors, fit SIMULTANEOUSLY against measured levels drawn from SEVERAL symmetry blocks of the SAME basis – the grouped-route sibling of AdjustedLevels.FittedMultipletOrthogonalMultiBlock, and the form this route is actually meant to be used in: at most two global parameters make pooling several blocks' targets the easiest way in this module to reach a genuinely positive degreesOfFreedom.

+ blocks                ::Array{FittedBlock,1}            ... one entry per symmetry block, in the order
                                                                 given to `fitGroupedParametersMultiBlock`.
+ groupedParameters      ::Array{GroupedParameter,1}        ... the fitted factors, GLOBAL across every
                                                                   block -- the same family in two blocks
                                                                   is the SAME parameter, not two
                                                                   independent ones.
+ orthogonalParameters   ::Array{OrthogonalParameter,1}      ... the orthogonal breakdown of the GLOBAL
                                                                    (at most two-dimensional) parameter
                                                                    space, read at the converged point,
                                                                    over EVERY target in EVERY block
                                                                    together.
+ rmsDeviation            ::Float64                           ... root-mean-square deviation over every
                                                                     target in every block together, in
                                                                     cm^-1.
+ degreesOfFreedom        ::Int64                             ... total targets (all blocks) minus the
                                                                     number of GLOBAL groups (at most two)
                                                                     -- see `FittedMultipletOrthogonal`'s
                                                                     own field of the same name.
+ source                  ::String                            ... a dated citation for the measured data.
source
JenaAtomicCalculator.AdjustedLevels.FittedMultipletOrthogonal — Type

struct AdjustedLevels.FittedMultipletOrthogonal ... the result of AdjustedLevels.fitOrthogonalParameters. The sibling of AdjustedLevels.FittedMultiplet for the orthogonal route – a DIFFERENT type, deliberately, so that a reader (or a method dispatch) can tell at a glance whether one or several parameters were fit, without inspecting array lengths.

+ multiplet             ::ManyElectron.Multiplet         ... the single-symmetry-block multiplet from the
                                                               FITTED, re-diagonalized Hamiltonian.
+ radialParameters      ::Array{RadialParameter,1}        ... the fitted factors, one per integral class,
                                                                translated back to the familiar language.
+ orthogonalParameters  ::Array{OrthogonalParameter,1}     ... what was actually fit -- the orthogonal
                                                                 directions, each with its own determinacy.
+ fitTargets            ::Array{FitTarget,1}                ... the measured levels this fit was matched
                                                                  against.
+ rmsDeviation          ::Float64                           ... root-mean-square deviation, fitted vs
                                                                  measured, over the fit targets, in cm^-1,
                                                                  from the EXACT re-diagonalized spectrum
                                                                  (not the linearized estimate).
+ degreesOfFreedom      ::Int64                             ... length(fitTargets) - length(radialParameters).
                                                                  THE OVERFITTING GUARD: zero or negative
                                                                  means every class was fit with no spare
                                                                  data to check it against (zero) or more
                                                                  classes than data at all (negative) --
                                                                  a legitimate fit (the SVD cutoff still
                                                                  protects an individual undetermined
                                                                  direction) but not one whose per-class
                                                                  values should be read as independently
                                                                  confirmed. `fitOrthogonalParameters`
                                                                  prints a warning when this is <= 0.
+ source                ::String                           ... a dated citation for the measured data used.
source
JenaAtomicCalculator.AdjustedLevels.FittedMultipletOrthogonalMultiBlock — Type

struct AdjustedLevels.FittedMultipletOrthogonalMultiBlock ... the result of AdjustedLevels.fitOrthogonalParametersMultiBlock: ONE shared set of radial parameters, fit SIMULTANEOUSLY against measured levels drawn from SEVERAL symmetry blocks of the SAME basis – the capability this module's own docstring names as missing from both single-block routes. An F^k(4f,4f)-type class means the SAME physical radial integral in every block it appears in, so pooling blocks turns a borderline, exactly-determined (or worse) per-block fit into a comfortably over-determined one, at no extra configuration-space cost – see degreesOfFreedom.

+ blocks                ::Array{FittedBlock,1}            ... one entry per symmetry block, in the order
                                                                 given to `fitOrthogonalParametersMultiBlock`.
+ radialParameters       ::Array{RadialParameter,1}         ... the fitted factors, GLOBAL across every
                                                                   block -- the same class in two blocks is
                                                                   the SAME parameter, not two independent
                                                                   ones.
+ orthogonalParameters   ::Array{OrthogonalParameter,1}      ... the orthogonal breakdown of the GLOBAL
                                                                    parameter space, read at the converged
                                                                    point, over EVERY target in EVERY
                                                                    block together -- the sibling of
                                                                    `FittedMultipletOrthogonal`'s own field.
+ rmsDeviation            ::Float64                           ... root-mean-square deviation over every
                                                                     target in every block together, in
                                                                     cm^-1.
+ degreesOfFreedom        ::Int64                             ... total targets (all blocks) minus the
                                                                     number of GLOBAL parameters -- THE
                                                                     OVERFITTING GUARD, see
                                                                     `AdjustedLevels.FittedMultipletOrthogonal`'s
                                                                     own field of the same name.
+ source                  ::String                            ... a dated citation for the measured data.
source
JenaAtomicCalculator.AdjustedLevels.GroupedParameter — Type

struct AdjustedLevels.GroupedParameter ... one fitted scaling parameter for one of the TWO Cowan families AdjustedLevels.twoBodyParameterGroup sorts every integral class into – the sibling of AdjustedLevels.RadialParameter for the grouped route, carrying the member classes too so a group label is never read as a bare, unexplained name.

+ groupLabel      ::String          ... which family this factor multiplies, `"Slater (F^k/G^k)"` or
                                          `"Configuration-interaction (R^k)"` -- see
                                          `AdjustedLevels.twoBodyParameterGroup`.
+ value            ::Float64        ... the fitted factor itself; NOT 1.0 by construction unless this
                                          group turned out to be exactly undetermined by the given targets.
+ memberClasses    ::Array{String,1} ... the raw `AdjustedLevels.twoBodyParameterClass` labels folded
                                           into this one group, e.g. `["F^0(3d,3d)", "F^2(3d,3d)", ...]`.
source
JenaAtomicCalculator.AdjustedLevels.OrthogonalParameter — Type

struct AdjustedLevels.OrthogonalParameter ... one ORTHOGONAL combination of RadialParameters – a direction in parameter space, found from the measured targets themselves (see AdjustedLevels.fitOrthogonalParameters's own docstring for how), not stored or universal. value is the fitted SHIFT along this direction, away from the uniform, unadjusted (every RadialParameter = 1) starting point – NOT an absolute scale like ScalingParameter.value, since a direction is only meaningful as a combination of DEVIATIONS.

+ label         ::String                         ... an arbitrary but stable name, e.g. "mode 1".
+ value         ::Float64                         ... the fitted shift along this direction.
+ composition   ::Array{Tuple{String,Float64},1}  ... which `RadialParameter`s make up this direction,
                                                        and with what weight; together the weights form
                                                        one column of an orthogonal (unit-norm) matrix.
+ determinacy   ::Float64                          ... how strongly the given targets pin this direction
                                                         down -- the matching singular value of the
                                                         sensitivity matrix. Near zero means the targets
                                                         cannot tell this combination from no change at
                                                         all, and `value` was accordingly left at 0.0.
source
JenaAtomicCalculator.AdjustedLevels.RadialParameter — Type

struct AdjustedLevels.RadialParameter ... one fitted scaling parameter for ONE automatically-discovered integral class – the sibling of AdjustedLevels.ScalingParameter for the orthogonal route: fitScaleFactor always returns exactly one, uniform across every rank and every shell pair; fitOrthogonalParameters returns one PER (operator type, shell pair, rank) class it finds among this block's two-body coefficients – Cowan's own F^k (direct)/G^k (exchange)/R^k (configuration-interaction) separation, not multipole rank alone (see AdjustedLevels.twoBodyParameterClass and AdjustedLevels.buildParameterMatrices).

+ parameterClass   ::String    ... which integral class this factor multiplies, e.g. "F^2(4f,4f)" or
                                    "G^2(2p,3d)" -- see `AdjustedLevels.twoBodyParameterClass`.
+ value             ::Float64  ... the fitted factor itself; NOT 1.0 by construction unless that class
                                    turned out to be exactly undetermined by the given targets.
source
JenaAtomicCalculator.AdjustedLevels.ScalingParameter — Type

struct AdjustedLevels.ScalingParameter ... one fitted scaling parameter. fitScaleFactor always returns an Array with exactly ONE of these (parameterClass = "Coulomb (uniform)"); fitOrthogonalParameters (see this module's -inc-orthogonal file) returns one PER integral class it discovers, which is why this type – and its sibling RadialParameter there – are named for the ROLE, not the count.

+ parameterClass   ::String    ... which class of integral this factor multiplies.
+ value             ::Float64  ... the fitted factor itself, e.g. 0.82; NOT 1.0 by construction.
source
Base.show — Method

Base.show(io::IO, fm::AdjustedLevels.FittedMultipletGroupedMultiBlock) ... ALWAYS prints the "fitted, not ab initio" disclosure first, the GLOBAL (at most two) group factors, the overfitting-guard warning when degreesOfFreedom <= 0, and then each block's own share of the fit. Nothing is returned.

source
Base.show — Method

Base.show(io::IO, fm::AdjustedLevels.FittedMultipletGrouped) ... ALWAYS prints the "fitted, not ab initio" disclosure first, exactly as the other two routes' Base.show methods do, plus which raw classes each group actually contains. Nothing is returned.

source
Base.show — Method

Base.show(io::IO, fm::AdjustedLevels.FittedMultipletOrthogonalMultiBlock) ... ALWAYS prints the "fitted, not ab initio" disclosure first, the GLOBAL parameters, the overfitting- guard warning when degreesOfFreedom <= 0, and then each block's own share of the fit. Nothing is returned.

source
Base.show — Method

Base.show(io::IO, fm::AdjustedLevels.FittedMultipletOrthogonal) ... ALWAYS prints the "fitted, not ab initio" disclosure first, exactly as the single-parameter route's Base.show(io::IO, ::AdjustedLevels.FittedMultiplet) does, plus the orthogonal breakdown and each direction's determinacy, so a near-zero determinacy is visible without inspecting the struct by hand. Nothing is returned.

source
Base.show — Method

Base.show(io::IO, fm::AdjustedLevels.FittedMultiplet) ... ALWAYS prints the "fitted, not ab initio" disclosure first, even on an incidental println(fm) or @show fm – the one design choice this module makes beyond what NistCalibration does, because a skippable disclosure is not loud enough for a result built from adjustable parameters. Nothing is returned.

source
JenaAtomicCalculator.AdjustedLevels.buildOneAndTwoBodyMatrices — Method

AdjustedLevels.buildOneAndTwoBodyMatrices(sym::LevelSymmetry, basis::Basis, nm::Nuclear.Model, grid::Radial.Grid) ... to build the one-body and two-body (PURE COULOMB) CI matrices for the given symmetry block, separately – see this module's own docstring for why this parallels rather than calls Hamiltonian.setupMatrix. A (idxCsf, oneBody, twoBody) tuple is returned, with idxCsf::Array{Int64,1} the basis.csfs indices of this block and oneBody, twoBody::Array{Float64,2} upper-triangular (the same convention Hamiltonian.setupMatrix uses, relying on Basics.diagonalize's Symmetric wrapper to read only that triangle).

source
JenaAtomicCalculator.AdjustedLevels.buildParameterMatrices — Method

AdjustedLevels.buildParameterMatrices(sym::LevelSymmetry, basis::Basis, nm::Nuclear.Model, grid::Radial.Grid) ... the orthogonal route's generalization of AdjustedLevels.buildOneAndTwoBodyMatrices: instead of summing every two-body (Coulomb) contribution into ONE lumped matrix, each contribution is kept in the matrix belonging to its own (operator type, shell pair, rank) class, via AdjustedLevels.twoBodyParameterClass – Cowan's own F^k/G^k/R^k separation, which rank alone cannot give: two different shell pairs can share the same rank (a p-d pair's F^2 and G^2 both exist at k=2), and a correlation model with more than one active shell pair would otherwise have them fitted as if they were one physical quantity. A CLOSED subshell is never separately parametrized (Cowan's RCE fits the open shell(s) only, see this function's own comment on why), and a class whose matrix turns out to be a multiple of the identity on this block – the rank-0 monopole within one fixed- occupation open shell, most often – is folded into oneBody too, since no splitting could ever determine it. Even a single OPEN shell with l>=1 still separates into several classes, not one: its own relativistic j-splitting (e.g. 4f5/2 against 4f7/2) already gives distinct F^k, G^k and R^k integrals at a given rank, which a single rank-only bucket could not have told apart either. A (idxCsf, oneBody, parameterClasses, matrices) tuple is returned: idxCsf::Array{Int64,1} as in buildOneAndTwoBodyMatrices; oneBody::Array{Float64,2} the shared one-body matrix; parameterClasses ::Array{String,1} a label per discovered class; matrices::Array{Array{Float64,2},1} the matching upper-triangular two-body matrices, one per class, same convention as buildOneAndTwoBodyMatrices.

source
JenaAtomicCalculator.AdjustedLevels.fitGroupedParameters — Method

AdjustedLevels.fitGroupedParameters(sym::LevelSymmetry, basis::Basis, nm::Nuclear.Model, grid::Radial.Grid, targets::Array{Tuple{Int64,Float64},1}, source::String; determinacyThreshold::Float64=1.0e-6, maxIterations::Int64=20, tolerance::Float64=1.0e-6) ... the single-block form of AdjustedLevels.fitGroupedParametersMultiBlock, for a caller who only has targets from ONE symmetry block – a thin wrapper calling the multi-block route with exactly one block and unwrapping its result, so the Gauss-Newton mechanics exist in exactly one place. Same targets convention as AdjustedLevels.fitScaleFactor. A fm::AdjustedLevels.FittedMultipletGrouped is returned.

source
JenaAtomicCalculator.AdjustedLevels.fitGroupedParametersMultiBlock — Method

AdjustedLevels.fitGroupedParametersMultiBlock(blocks::Array{Tuple{LevelSymmetry,Array{Tuple{Int64,Float64},1}},1}, basis::Basis, nm::Nuclear.Model, grid::Radial.Grid, source::String; determinacyThreshold::Float64=1.0e-6, maxIterations::Int64=20, tolerance::Float64=1.0e-6) ... the grouped-route sibling of AdjustedLevels.fitOrthogonalParametersMultiBlock: instead of one parameter PER Cowan class (routinely more classes than any realistic set of measured levels can determine once a correlating configuration is present), this fits exactly ONE parameter per Cowan FAMILY – AdjustedLevels.twoBodyParameterGroup's "Slater (F^k/G^k)" and "Configuration-interaction (R^k)" – SIMULTANEOUSLY against targets drawn from SEVERAL symmetry blocks of the SAME basis, same calling convention as fitOrthogonalParametersMultiBlock. Each block's classes are folded into its (at most two) group matrices via AdjustedLevels.groupParameterMatrices BEFORE the global class list is built, so the Gauss-Newton solve below never sees more than two unknowns regardless of how rich the correlating configuration's own class list is. The iteration is otherwise the SAME Gauss-Newton + SVD scheme fitOrthogonalParametersMultiBlock uses (warm-started from the single uniform factor minimizing the combined rms over every block, the best iterate tracked rather than trusting the last one), just over the grouped matrices. A fm::AdjustedLevels.FittedMultipletGroupedMultiBlock is returned.

source
JenaAtomicCalculator.AdjustedLevels.fitOrthogonalParameters — Method

AdjustedLevels.fitOrthogonalParameters(sym::LevelSymmetry, basis::Basis, nm::Nuclear.Model, grid::Radial.Grid, targets::Array{Tuple{Int64,Float64},1}, source::String; determinacyThreshold::Float64=1.0e-6, maxIterations::Int64=20, tolerance::Float64=1.0e-6) ... the orthogonal (Uylings/Raassen-style) route: discovers the integral classes present in sym's block via buildParameterMatrices, fits one scaling parameter PER class against targets (same convention as fitScaleFactor's own targets), and reports the fit in terms of the ORTHOGONAL combinations the targets can actually determine. THE FIT IS A GAUSS-NEWTON ITERATION, not a single linearized step (that single-step version was tried first and MEASURED to leave a real, growing residual even in an idealised recovery test with exactly as many targets as free parameters – one linear step is only the leading-order correction to a genuinely nonlinear eigenvalue problem). At each iteration: diagonalize EXACTLY at the current parameters, build the sensitivity matrix J[target,class] = d(energy)/d(parameter) from the CURRENT eigenvectors (no extra diagonalization beyond the one already needed), take the MINIMUM-NORM correction via LinearAlgebra.svd (a direction the targets cannot determine is left untouched rather than amplifying noise), and re-center there for the next round. Iteration stops when the rms stops improving by more than tolerance, or after maxIterations – AND THE BEST ITERATE SEEN is what is returned, never just the last one: an undamped Gauss-Newton step is not guaranteed to improve the fit (measured directly: without this guard, one real case got WORSE after iterating, 175 to 323 cm^-1), so every candidate point is compared against the best found so far. MEASURED RANGE OF VALIDITY: on an idealised recovery test (synthetic targets generated from this route's own model, so a perfect fit exists in principle), this converges to the true parameters for corrections up to roughly 30% per class; beyond that the iteration can stall in a poorly-conditioned region well short of the solution (a slow, near-linear crawl, not an oscillation) rather than diverging outright. A correction this large is exactly the sign that the underlying ab initio calculation needs more correlation (more configurations), not a better fit – see this module's own docstring. value on each returned OrthogonalParameter is the TOTAL accumulated shift along that direction, and determinacy is read at the CONVERGED point, not the starting one – so a mode whose shift is reported but whose determinacy is still near zero signals the fit has not actually converged along it. THE ITERATION IS WARM-STARTED from the single-factor (uniform) optimum over these same matrices, not from all-ones: "every rank equal" is itself a point inside this route's own parameter space, so this route's rms can never be worse than fitScaleFactor's on the same targets – it WAS, measured, before this warm start was added, since a plain Gauss-Newton iteration can fail to reach even that nested point within maxIterations when starting far from it (confirmed on a real case: Pr IV 4f^2, J=2, where the orthogonal route returned a worse rms than the single-factor route on identical targets – mathematically impossible for the true optimum of a strictly richer, nested model). A fm::AdjustedLevels.FittedMultipletOrthogonal is returned.

source
JenaAtomicCalculator.AdjustedLevels.fitOrthogonalParametersMultiBlock — Method

AdjustedLevels.fitOrthogonalParametersMultiBlock(blocks::Array{Tuple{LevelSymmetry,Array{Tuple{Int64,Float64},1}},1}, basis::Basis, nm::Nuclear.Model, grid::Radial.Grid, source::String; determinacyThreshold::Float64=1.0e-6, maxIterations::Int64=20, tolerance::Float64=1.0e-6) ... the multi-block generalization of AdjustedLevels.fitOrthogonalParameters: ONE shared parameter per (type, shell pair, rank) class – see AdjustedLevels.twoBodyParameterClass – fit SIMULTANEOUSLY against targets drawn from SEVERAL symmetry blocks of the SAME basis, e.g. [(sym2, targets2), (sym4, targets4)] for two different J^P blocks of one open-shell reference. THIS IS WHAT MAKES CLASS-SEPARATED FITTING ACTUALLY WORTH HAVING, not merely correct: a class shared by several blocks is the SAME physical radial integral in every one of them, so pooling the blocks' targets turns an exactly-determined (or worse) per-block fit into a comfortably over-determined one, without adding a single CSF – see AdjustedLevels.FittedMultipletOrthogonalMultiBlock's own degreesOfFreedom field. The iteration is otherwise the SAME Gauss-Newton + SVD scheme fitOrthogonalParameters uses (warm-started the same way, from the single uniform factor minimizing the COMBINED rms over every block), just with each block's own Jacobian rows and residuals stacked together before the one, shared SVD solve each iteration – a class absent from a given block simply contributes a zero column there. A fm::AdjustedLevels.FittedMultipletOrthogonalMultiBlock is returned.

source
JenaAtomicCalculator.AdjustedLevels.fitScaleFactor — Method

AdjustedLevels.fitScaleFactor(sym::LevelSymmetry, basis::Basis, nm::Nuclear.Model, grid::Radial.Grid, targets::Array{Tuple{Int64,Float64},1}, source::String; scaleBounds::Tuple{Float64,Float64}=(0.5,1.2)) ... to fit ONE Coulomb scale factor within scaleBounds so that the re-diagonalized spectrum of sym's block matches targets (pairs of (position in the sorted spectrum, measured energy relative to the block's own lowest level, in cm^-1)) as closely as possible in the least-squares sense. A fm::AdjustedLevels.FittedMultiplet is returned.

source
JenaAtomicCalculator.AdjustedLevels.goldenSectionMinimize — Method

AdjustedLevels.goldenSectionMinimize(f::Function, a::Float64, b::Float64; tolerance::Float64=1.0e-4, maxIterations::Int64=60) ... a plain, dependency-free golden-section search for the minimum of f on [a,b], assumed unimodal there – sufficient for the smooth, single-parameter scan this module needs, see its own docstring. A (xBest, fBest)::Tuple{Float64,Float64} is returned.

source
JenaAtomicCalculator.AdjustedLevels.groupParameterMatrices — Method

AdjustedLevels.groupParameterMatrices(classes::Array{String,1}, matrices::Array{Array{Float64,2},1}) ... to fold AdjustedLevels.buildParameterMatrices's per-class two-body matrices into the TWO Cowan families AdjustedLevels.twoBodyParameterGroup sorts every class into, by plain matrix ADDITION – since every class in one group shares the SAME intended scale factor, the matrix a single shared factor would multiply is exactly the sum of the matrices the individual classes would have used. A (groupLabels, groupMatrices, memberLists)::Tuple{Array{String,1},Array{Array{Float64,2},1}, Array{Array{String,1},1}} is returned: groupLabels the (at most two) group names found, sorted; groupMatrices the matching summed two-body matrices, same upper-triangular convention as buildParameterMatrices; memberLists which raw classes were folded into each group, so a reader of the fitted result can see exactly what a group label stands for rather than trusting the name alone.

source
JenaAtomicCalculator.AdjustedLevels.identifyReferenceLevels — Method

AdjustedLevels.identifyReferenceLevels(sym::LevelSymmetry, basis::Basis, nm::Nuclear.Model, grid::Radial.Grid, referenceShells::Array{Tuple{Int64,Int64,Int64},1}, nLevels::Int64; threshold::Float64=0.5) ... for sym's symmetry block of a CORRELATED basis, to find the GLOBAL (energy-sorted, at the UNSCALED c=1.0 Hamiltonian) indices of the nLevels LOWEST levels whose AdjustedLevels.referenceLevelWeight on referenceShells exceeds threshold – exactly the index convention AdjustedLevels.fitScaleFactor, fitOrthogonalParameters and fitGroupedParameters (and their multi-block siblings) expect as the first element of each targets tuple. referenceShells is a list of (n, l, occupation) triples that must ALL match, e.g. [(3,2,2)] for a bare 3d^2 reference configuration. Use this BEFORE calling any fitting route on a basis built from more than one configuration – plain energy-sort position is only safe for a bare, single-configuration basis (see referenceLevelWeight's own docstring for why). A (globalIndices, weights)::Tuple{Array{Int64,1},Array{Float64,1}} is returned, in energy order; raises if fewer than nLevels reference-dominant levels are found.

source
JenaAtomicCalculator.AdjustedLevels.mergeIntoMultiplet — Method

AdjustedLevels.mergeIntoMultiplet(fm::AdjustedLevels.FittedMultiplet, abInitioMultiplet::ManyElectron.Multiplet) ... to combine a FittedMultiplet's single, re-fitted symmetry block with the REST of an ordinary, ab initio multiplet – typically the very same Hamiltonian.performCI result fitScaleFactor's own basis came from, which carries every OTHER symmetry block a fit never touches, such as a ground state of different J^P. This is the step named in this module's own docstring as happening at the end of an SCF+RAS line: the levels of abInitioMultiplet belonging to fm's own symmetry are replaced outright by fm.multiplet.levels, every other symmetry block is kept unchanged, and the result is re-sorted by energy exactly as Hamiltonian.performCI itself does after merging its own per-block multiplets – so that the combined multiplet can be handed to Einstein.computeLines or any other property/process computation needing levels from more than one symmetry. A mp::ManyElectron.Multiplet is returned.

source
JenaAtomicCalculator.AdjustedLevels.mergeIntoMultiplet — Method

AdjustedLevels.mergeIntoMultiplet(fm::AdjustedLevels.FittedMultipletGrouped, abInitioMultiplet::ManyElectron.Multiplet) ... the grouped-route form of mergeIntoMultiplet(::FittedMultipletOrthogonal, ...): fm's own symmetry block replaces the matching block of abInitioMultiplet, every other block is kept unchanged, and the result is re-sorted by energy. A mp::ManyElectron.Multiplet is returned.

source
JenaAtomicCalculator.AdjustedLevels.mergeIntoMultiplet — Method

AdjustedLevels.mergeIntoMultiplet(fm::AdjustedLevels.FittedMultipletGroupedMultiBlock, abInitioMultiplet::ManyElectron.Multiplet) ... the grouped-route form of mergeIntoMultiplet(::FittedMultipletOrthogonalMultiBlock, ...): EVERY block carried by fm replaces its own matching block of abInitioMultiplet in one call, every OTHER symmetry block is kept unchanged, and the result is re-sorted by energy. A mp::ManyElectron.Multiplet is returned.

source
JenaAtomicCalculator.AdjustedLevels.mergeIntoMultiplet — Method

AdjustedLevels.mergeIntoMultiplet(fm::AdjustedLevels.FittedMultipletOrthogonal, abInitioMultiplet::ManyElectron.Multiplet) ... the same merge step as the single-parameter route's mergeIntoMultiplet(::FittedMultiplet, ...), for a FittedMultipletOrthogonal result: fm's own symmetry block replaces the matching block of abInitioMultiplet, every other block is kept unchanged, and the result is re-sorted by energy. A mp::ManyElectron.Multiplet is returned.

source
JenaAtomicCalculator.AdjustedLevels.mergeIntoMultiplet — Method

AdjustedLevels.mergeIntoMultiplet(fm::AdjustedLevels.FittedMultipletOrthogonalMultiBlock, abInitioMultiplet::ManyElectron.Multiplet) ... the multi-block generalization of the other mergeIntoMultiplet methods: EVERY block carried by fm replaces its own matching block of abInitioMultiplet in one call, every OTHER symmetry block is kept unchanged, and the result is re-sorted by energy. A mp::ManyElectron.Multiplet is returned.

source
JenaAtomicCalculator.AdjustedLevels.referenceLevelWeight — Method

AdjustedLevels.referenceLevelWeight(vec::Array{Float64,1}, idxCsf::Array{Int64,1}, basis::Basis, referenceShells::Array{Tuple{Int64,Int64,Int64},1}) ... the summed |coefficient|^2 of the CI eigenvector vec (ordered as idxCsf lists) over exactly the CSFs whose occupation matches EVERY (n, l, occupation) triple in referenceShells – the same idea as NIST ASD's own "leading percentages" column. NEEDED once a correlating configuration is present: a rich correlating configuration can put an INTRUDER state, dominantly of ITS OWN character, between two levels that are physically the ones a caller wants, so a plain energy-sort position can silently pick up the wrong state – measured directly on a real case (a 2-configuration J=2 block whose 3rd-lowest level is, by this weight, 99.7% the bare reference configuration, not an intruder, but which had to be CHECKED rather than assumed). A value::Float64 in [0,1] is returned.

source
JenaAtomicCalculator.AdjustedLevels.shellOccupation — Method

AdjustedLevels.shellOccupation(csf::ManyElectron.CsfR, subshells::Array{Subshell,1}, n::Int64, l::Int64) ... the total occupation csf carries over EVERY subshell of principal quantum number n and orbital angular momentum l – combining BOTH relativistic j-partners of one nl shell into the single number a nonrelativistic shell notation (e.g. "3d") would quote. The building block AdjustedLevels.referenceLevelWeight uses to tell whether a CSF belongs to a given reference configuration. A value::Int64 is returned.

source
JenaAtomicCalculator.AdjustedLevels.twoBodyParameterClass — Method

AdjustedLevels.twoBodyParameterClass(a::Subshell, b::Subshell, c::Subshell, d::Subshell, nu::Int64) ... to classify ONE two-body coefficient coeff.V * XL_Coulomb(nu, orbital[a], orbital[b], orbital[c], orbital[d], ...) into Cowan's own RCE integral classes, by the SHELL (n,l) of each involved orbital – not the (possibly split, j-dependent) subshell itself, so that a p1/2/p3/2 or f5/2/f7/2 pair shares ONE parameter exactly as Cowan's nonrelativistic scheme does, rather than fitting a spin-orbit splitting of the Slater parameter itself that nobody asks for. Three cases, read directly off which subshells coincide (the same convention SpinAngular.computeCoefficients itself uses to build a direct term as (sha,shb,sha,shb) and an exchange term as (sha,shb,shb,sha)):

    - DIRECT, `a==c && b==d`: the density-density (F^k) term -- labelled `"F^k(shellA,shellB)"`, shells
      sorted so the label does not depend on which orbital happened to be listed first.
    - EXCHANGE, `a==d && b==c && a!=b`: the antisymmetrization (G^k) term -- `"G^k(shellA,shellB)"`,
      shells sorted likewise; a==b falls through to the DIRECT case above instead (equivalent electrons
      have no separate exchange term, exactly as `SpinAngular`'s own same-shell coefficient has none).
    - OTHERWISE: a genuine configuration-interaction (R^k) term connecting two different orbital
      occupations -- `"R^k(shellA,shellB;shellC,shellD)"`, canonicalized over the integral's own 4-index
      symmetry `R^k(ab,cd) = R^k(ba,dc) = R^k(cd,ab) = R^k(dc,ba)` by taking the lexicographically
      smallest of the four equivalent labellings, so the SAME physical integral is never split into
      several distinct classes merely because of which CSF pair it was read off from.

    A value::String is returned.
source
JenaAtomicCalculator.AdjustedLevels.twoBodyParameterGroup — Method

AdjustedLevels.twoBodyParameterGroup(className::String) ... to sort one AdjustedLevels.twoBodyParameterClass label into Cowan's own TWO scaling families – "Slater (F^k/G^k)" for a direct or exchange integral (the class name starts with "F^" or "G^"), "Configuration-interaction (R^k)" for a class connecting different orbital occupations (the class name starts with "R^"). This is the grouping AdjustedLevels.fitGroupedParameters and AdjustedLevels.fitGroupedParametersMultiBlock use, matching published Cowan-code practice of scaling the two families by different empirical factors rather than one shared number. A value::String is returned.

source

Perturbed orbitals: the Dalgarno-Lewis equation

JenaAtomicCalculator.DalgarnoLewis.PerturbedOrbital — Type

struct DalgarnoLewis.PerturbedOrbital ... defines a type for the solution chi of a single Dalgarno-Lewis equation: the response of one electron, driven by one multipole operator from one source orbital at one energy, to a perturbation of frequency omega. UNLIKE an ordinary Radial.Orbital, this is not normalized to 1 – its magnitude is fixed by the source term's own strength, which is the physically meaningful quantity a caller reads off directly (e.g. by forming <final| O' |chi>, an ordinary one-body matrix element, with no further sum needed) – and it is not an eigenstate of anything, so "energy" here names the TARGET energy the equation was solved at, not a property chi itself possesses.

+ subshell       ::Subshell          ... the relativistic kappa-channel chi was solved in.
+ sourceSubshell ::Subshell          ... the subshell of the orbital that drove this equation.
+ multipole      ::EmMultipole       ... the multipole rank Mp of the operator O^(Mp).
+ gauge          ::EmGauge           ... the gauge the operator was evaluated in.
+ omega          ::Float64           ... the perturbing frequency; the equation was solved at the target
                                          energy sourceEnergy + omega (emission) or sourceEnergy - omega
                                          (absorption), per the sign convention of the caller's source term.
+ targetEnergy   ::Float64           ... the energy (H_eff - targetEnergy) was shifted by before solving.
+ P              ::Array{Float64,1}  ... large and ..
+ Q              ::Array{Float64,1}  ... small component of chi, on the standard grid, truncated at its
                                          own last significant point exactly as an ordinary Orbital is.
+ residual        ::Float64           ... the norm of (matrixA - targetEnergy*matrixB)*c - source, in the
                                          SAME units as the source vector itself -- a measured quantity
                                          confirming the linear solve actually satisfied the equation to
                                          the precision claimed, not a bare pass/fail. A caller that wants
                                          to trust chi should check this is small relative to norm(source),
                                          not merely that the solve returned without error.
source
JenaAtomicCalculator.DalgarnoLewis.Settings — Type

struct DalgarnoLewis.Settings ... defines a type for the details and parameters of a Dalgarno-Lewis inhomogeneous-equation solve.

+ regularization  ::Float64   ... a small, positive energy shift added to the target energy's imaginary
                                   part when the shifted matrix (matrixA - E*matrixB) is close to singular
                                   (the target energy lands near a genuine bound-state pole); 0.0 turns
                                   this off, and the solve then RAISES at an exact pole rather than
                                   returning a number silently dominated by rounding error. Mirrors the
                                   EXPLICIT "skip when the denominator vanishes" guard the sum-over-states
                                   code already carries (MultiPhotonTransition.computeReducedAmplitudeEmission),
                                   rather than inventing a new convention for the same physical situation.
+ singularityTolerance ::Float64  ... how close (in the same energy units) the target energy may come to
                                   the nearest matrix eigenvalue before `regularization` is required; the
                                   solve raises, naming the distance, if this is exceeded with
                                   regularization == 0.0, rather than returning a number silently
                                   dominated by rounding error.
+ printBefore     ::Bool     ... True if a short overview is to be printed before the solve starts.
source
JenaAtomicCalculator.DalgarnoLewis.Settings — Method

DalgarnoLewis.Settings(settings::DalgarnoLewis.Settings; regularization::Union{Nothing,Float64}=nothing, singularityTolerance::Union{Nothing,Float64}=nothing, printBefore::Union{Nothing,Bool}=nothing) ... the standard JAC keyword copy-constructor. A settings::DalgarnoLewis.Settings is returned.

source
JenaAtomicCalculator.DalgarnoLewis.amplitude — Method

DalgarnoLewis.amplitude(multipole::EmMultipole, finalOrbital::Orbital, chi::DalgarnoLewis.PerturbedOrbital, grid::Radial.Grid; omega::Union{Nothing,Float64}=nothing) ... computes <finalOrbital || O^(multipole) || chi>, i.e. the ordinary one-body matrix element a caller forms from a solved PerturbedOrbital, using chi's OWN gauge (chi.gauge) throughout – Coulomb/Magnetic via InteractionStrength.MabEmission directly, Babushkin via DalgarnoLewis.amplitudeKernel (fixed 11-Oct-2026; see that function's own docstring for why it, not MabEmission directly, is the right one here). The FREQUENCY this operator itself carries defaults to chi.omega (the equation's own omega, right for the single-operator case this function was first written for – e.g. a polarizability-type <i|O(omega)|chi(omega)>, where the probe and the perturbation share one frequency) – but a SECOND, genuinely two-photon-shaped use needs the OTHER photon's frequency here instead: in <final|O2(omega2)|chi1(omega1)>, the omega carried by O2 is omega2, which need not equal chi1.omega = omega1 at all except through the shared constraint omega1 + omega2 = Ei - Ef. The omega keyword exists for exactly that case; passing it explicitly changes NOTHING for any existing caller, since every one of them already relies on the default. A value::ComplexF64 is returned.

source
JenaAtomicCalculator.DalgarnoLewis.amplitudeKernel — Method

DalgarnoLewis.amplitudeKernel(multipole::EmMultipole, gauge::EmGauge, omega::Float64, a::Orbital, b::Orbital, grid::Radial.Grid) ... computes the same one-body multipole amplitude as InteractionStrength.MabEmission, EXCEPT that the Babushkin (length) branch's eps = a.energy <= b.energy ? 1 : -1 orientation correction is always taken as eps = +1, never read off a or b's .energy field. THIS IS THE FUNCTION DalgarnoLewis.solve AND DalgarnoLewis.amplitude USE FOR THE BABUSHKIN GAUGE – fixed 11-Oct-2026, after being wrongly marked insufficient earlier the same day; read this before changing it again.

    THE FORMULA ITSELF WAS NEVER WRONG. Grant (1974, J. Phys. B 7 1458), kept in
    `apps/papers/1974.jpb-grant-gauge-invariance.pdf`, derives the electric-multipole radial matrix
    element for an ARBITRARY gauge parameter G_L as M_e(G_L) = M_e(0) + G_L*M_longitudinal (his eq 4.10),
    a PURE LINEAR-ALGEBRA IDENTITY with no eigenstate assumption anywhere -- G_L is just a number. Setting
    G_L = sqrt((L+1)/L) (the Babushkin/length choice; his eq 6.9 confirms it reduces to the ordinary
    dipole LENGTH form at L=1) and expanding ALGEBRAICALLY (verified here by hand, term by term) gives
    EXACTLY `GrantJL(L) + (kapa-kapb)/(L+1)*GrantILplus(L+1) + GrantILminus(L+1)` -- i.e. THIS function,
    with its constant +1. No comparison of a and b's energies enters that derivation at any point.

    WHAT eps IS ACTUALLY FOR. Separately, Grant's Theorem A' shows the `GrantILplus`+`GrantILminus` piece
    VANISHES when a and b are BOTH genuine eigenstates of the SAME Hamiltonian (via the continuity
    equation) -- confirmed directly, 11-Oct-2026: for 1s/2p_1/2 at their own on-shell frequency the
    combination is ~1e-11 relative to GrantJL once box-truncation noise is accounted for, against ~1e-5
    in an earlier, looser check. On that near-cancellation, `MabEmission`'s `eps` exists to fix the
    OVERALL SIGN between two genuine, comparably-bound orbitals in the typical caller's convention
    (PhotoEmission and everywhere else in JAC) -- it is a convenience for THAT calling pattern, not a
    piece of Grant's general formula, and this function correctly leaves it out.

    WHY THE EARLIER "~12.9x TOO SMALL" VERDICT WAS WRONG, NOT THE FORMULA. The validation used to reject
    this function compared it against an explicit sum over the complete eigenbasis in which EACH TERM
    used `InteractionStrength.MabEmission`'s own ENERGY-DEPENDENT eps (varying from term to term, since a
    complete 1819-state basis spans states both above and below the two fixed endpoints) -- while this
    function, used consistently by `solve`'s source-vector step and by `amplitude`'s extraction step,
    computes the UNIFORM-sign version throughout. That is two different quantities, not one compared
    against itself. Rebuilt so BOTH sides use this SAME uniform function for every term: ratio 1.000000
    to 6 figures, checked at two different omega (0.3 and 0.15 a.u.) on H 2s -> 2p_1/2 -> 1s.

    THE ROLE-BASED CONVENTION THIS RELIES ON. `solve` and `amplitude` always call this function with `a`
    the EARLIER/DRIVING orbital in the Dalgarno-Lewis chain (the real source orbital in `solve`, chi
    itself in `amplitude`) and `b` the LATER/TARGET one (a synthetic primitive in `solve`, the final
    orbital in `amplitude`) -- NEVER swapped. A constant eps works BECAUSE that role assignment never
    swaps, not because +1 is the universally correct sign for an arbitrary (a,b) pair; this function is
    not a general-purpose replacement for `InteractionStrength.MabEmission` outside that calling pattern.
    The Coulomb/velocity and Magnetic branches carry no eps ambiguity at all (nothing in their formulas
    depends on it) and are passed through to `InteractionStrength.MabEmission` unchanged.
    A value::ComplexF64 is returned.
source
JenaAtomicCalculator.DalgarnoLewis.solve — Method

DalgarnoLewis.solve(multipole::EmMultipole, gauge::EmGauge, omega::Float64, targetSubshell::Subshell, sourceOrbital::Orbital, potential::Radial.Potential, primitives::Bsplines.Primitives; settings::DalgarnoLewis.Settings=DalgarnoLewis.Settings(), extraSource::Union{Nothing,Array{Float64,1}}=nothing, staticDrive::Bool=false, coreOrbitals::Union{Nothing,Dict{Subshell,Orbital}}=nothing, coreOccupations::Union{Nothing,Dict{Subshell,Float64}}=nothing) ... solves (Heff - targetEnergy) |chi> = O^(multipole, gauge) |sourceOrbital> for chi, in the kappa-channel of targetSubshell, where Heff is the one-body Dirac Hamiltonian for potential on the SAME B-spline primitives sourceOrbital was (or could have been) generated from, and targetEnergy = sourceOrbital.energy + omega. Reuses Bsplines.setupLocalMatrix for the Hamiltonian matrix exactly as Bsplines.generateOrbitals does – the only difference from an ordinary bound- or continuum-orbital generation is that this matrix is SOLVED against a source, not diagonalized. The source vector is built by calling InteractionStrength.MabEmission between sourceOrbital and a synthetic single-primitive orbital for every primitive of the target channel in turn – measured (08-Oct-2026) to reproduce PhotoEmission.amplitude exactly for the Coulomb/velocity gauge on a one-electron CSF, so no new angular-coefficient code is used for that gauge. gauge == Basics.Coulomb/Basics.Magnetic/Basics.Babushkin are all usable (Babushkin fixed 11-Oct-2026, via DalgarnoLewis.amplitudeKernel – see that function's own docstring for why it, not InteractionStrength.MabEmission directly, is used to build the source vector for that gauge). extraSource, when given, is ADDED to the (nsL+nsS)-length source vector before the linear solve – this is the hook RandomPhase uses to couple several such equations together (an induced potential's matrix elements, in this module's own primitive basis) WITHOUT this module needing any notion of what that extra term represents; nothing (the default) reproduces every existing caller unchanged. coreOrbitals and coreOccupations, given TOGETHER, add the nonlocal Dirac-Fock exchange operator of Bsplines.setupExchangeMatrix to the left-hand side, so that Heff becomes Dirac-Fock rather than Dirac-Hartree; omitting both keeps the purely local operator every existing caller gets. They must then describe the same field potential does, and in its CANONICAL form – the full Hartree term over every occupied subshell, with no (wa-1) and no own-subshell local exchange – since the exchange is built over every occupied subshell including the source orbital's own. Measured on Ne (21-Oct-2026): with AL orbitals the eigenstate residual the guard below reports falls from 1.22/1.23 to 1.2e-03, and the static dipole polarizability from 3.759245 (Dirac-Hartree-Slater) to 1.976847 a.u., box-independent over rbox = 20/40/70 to all seven digits. That remaining 1e-03 is not convergence (a 40-fold tightening moves it nowhere) and not the grid (a 2.5-fold refinement likewise); it is CONSISTENT with, though not proven to be, the difference between plain and kink-aware Slater quadrature. A chi::DalgarnoLewis.PerturbedOrbital is returned.

source
JenaAtomicCalculator.DalgarnoLewis.twoPhotonAmplitude — Method

DalgarnoLewis.twoPhotonAmplitude(multipole1::EmMultipole, multipole2::EmMultipole, gauge::EmGauge, omega1::Float64, omega2::Float64, initialOrbital::Orbital, finalOrbital::Orbital, targetSubshell::Subshell, potential::Radial.Potential, primitives::Bsplines.Primitives; settings::DalgarnoLewis.Settings=DalgarnoLewis.Settings()) ... computes, for ONE intermediate kappa-channel (targetSubshell) and both time orderings, the un-reduced second-order amplitude a two-photon EMISSION process needs:

        Sum_nu <final|O2(omega2)|nu><nu|O1(omega1)|initial> / (E_initial - omega1 - E_nu)
      + Sum_nu <final|O1(omega1)|nu><nu|O2(omega2)|initial> / (E_initial - omega2 - E_nu)

    with the sum over nu COMPLETE (every state of this channel, not a truncated pseudostate set) by
    construction, exactly DalgarnoLewis's whole reason for existing. A caller still forms the physical
    amplitude by summing this over every allowed intermediate symmetry (targetSubshell), weighting each
    by its own Wigner-6j recoupling factor and multipole exchange phase -- that part is system-specific
    (it depends on Ji, Jf and the multipole ranks) and stays with the caller, exactly as
    `MultiPhotonTransition.computeReducedAmplitudeEmission` leaves it to ITS OWN caller.

    THE SIGN TRICK, recorded here because it is not obvious and cost real effort to get right (11-Oct-2026).
    `DalgarnoLewis.solve` can only be driven at a POSITIVE omega (`InteractionStrength.MabEmission`'s
    radial integrals raise a domain error for a negative one), but the first denominator above needs chi
    solved at targetEnergy = E_initial - omega1, i.e. at omega = -omega1 relative to initialOrbital. The
    fix is NOT to negate omega: it is to solve FROM finalOrbital instead, at omega2 = (E_initial-omega1) -
    E_final (POSITIVE, since omega1 + omega2 = E_initial - E_final by energy conservation), and then use
    the EXCHANGE ANTISYMMETRY of MabEmission under swapping its two orbital arguments -- measured
    directly, ratio exactly -1.000000 between a 1s-2p and a 2p-1s Coulomb-gauge matrix element -- to show
    the two resulting double sums are identical. VALIDATED (11-Oct-2026): for H 2s -> 1s this function's
    result, fed through the K=0 Wigner-6j/exchange-phase assembly, reproduces an INDEPENDENT explicit sum
    over the complete eigenbasis of the identical matrix to 7 significant figures (ratio 1.000000) in
    BOTH gauges, and the K=1 channel it leaves to the caller comes out at a 1.5e-11 share of K=0 --
    matching, to the digit, the share already measured by the sum-over-states code this is meant to
    replace. See example-As.jl branch (c) for the full H 2s -> 1s application and its result.

    GAUGE INVARIANCE, CHECKED DIRECTLY AND STRONGER THAN EXPECTED (11-Oct-2026). Calling this function
    with gauge = Basics.Coulomb and gauge = Basics.Babushkin, same omega1/omega2, agrees to 8 significant
    figures -- at every omega1 sampled across the full physical range (0, E_initial-E_final), not only at
    the two-photon-resonant midpoint omega1 = omega2 where the general theorem guarantees it. A SINGLE
    leg (one `DalgarnoLewis.amplitude` call alone, not the full two-time-ordering combination this
    function forms) shows NO such agreement (ratio -2.47, not close to 1) -- gauge invariance belongs to
    the complete two-photon amplitude, exactly as expected, and is not a property of either term alone.
    A value::ComplexF64 is returned.
source

Coupled (random-phase) response

JenaAtomicCalculator.RandomPhase.CoupledResponse — Type

struct RandomPhase.CoupledResponse ... defines a type for the result of a many-electron Dalgarno-Lewis orchestration: one DalgarnoLewis.PerturbedOrbital per active electron, driven by the same multipole operator at the same frequency, independent-particle or coupled depending on the Settings it was solved with.

+ multipole          ::EmMultipole                                       ... the multipole rank Mp of
                                                                              the external operator.
+ gauge               ::EmGauge                                           ... the gauge it was evaluated
                                                                              in; see `DalgarnoLewis`'s
                                                                              own docstring for which
                                                                              gauges are currently usable.
+ channelOrbitals     ::Dict{Tuple{Subshell,Subshell},PerturbedOrbital}  ... EVERY channel's perturbed
                                                                              orbital, keyed by the
                                                                              (active, target) pair.
                                                                              **Added 14-Oct-2026 because
                                                                              `perturbedOrbitals` alone
                                                                              makes the physics
                                                                              unreachable:** with
                                                                              `allChannels` one electron
                                                                              carries several channels, the
                                                                              observable is the COHERENT
                                                                              SUM over all of them, and a
                                                                              caller given only the primary
                                                                              ones cannot form it -- it
                                                                              gets a 3-channel sum of a
                                                                              7-channel solve, which is a
                                                                              different quantity.  Empty on
                                                                              the uncoupled path.
+ omega                ::Float64                                          ... the perturbing frequency,
                                                                              shared by every electron.
+ perturbedOrbitals    ::Dict{Subshell,DalgarnoLewis.PerturbedOrbital}    ... chi, keyed by the ACTIVE
                                                                              (source) subshell it was
                                                                              solved for.
+ nIterations          ::Int64                                            ... always 1 in the
                                                                              independent-particle limit
                                                                              (couplingEnabled = false),
                                                                              which needs no iteration;
                                                                              the iteration count reached
                                                                              otherwise.
+ converged             ::Bool                                            ... always true in the
                                                                              independent-particle limit;
                                                                              otherwise whether the
                                                                              induced potential's relative
                                                                              change fell below
                                                                              settings.accuracy before
                                                                              settings.maxIterations.
source
JenaAtomicCalculator.RandomPhase.Settings — Type

struct RandomPhase.Settings ... defines a type for the details and parameters of a many-electron Dalgarno-Lewis orchestration, independent-particle or (direct-term-only) self-consistently coupled.

+ activeSubshells   ::Array{Subshell,1}        ... the electrons whose response is solved for; an empty
                                                     array (the default) means every subshell of the
                                                     `activeOrbitals` dictionary `RandomPhase.solve` is
                                                     called with.
+ targetSubshells   ::Dict{Subshell,Subshell}   ... for each active subshell, the kappa-channel chi is
                                                     solved in -- the same `targetSubshell`
                                                     `DalgarnoLewis.solve` itself requires explicitly;
                                                     this module does not derive it from a selection rule
                                                     any more than `DalgarnoLewis.solve` does.
+ couplingEnabled    ::Bool                      ... True to iterate the self-consistent (direct-term-
                                                     only) induced-potential coupling; False (the default)
                                                     for the independent-particle limit. See the module's
                                                     own docstring for what the coupled path has, and has
                                                     not yet, been checked against.
+ maxIterations      ::Int64                     ... the coupled iteration's budget; unused (every
                                                     electron solved once) while couplingEnabled is false.
+ accuracy           ::Float64                   ... the coupled iteration stops once the induced
                                                     potential's relative change between iterations falls
                                                     below this; unused while couplingEnabled is false.
+ mixing             ::Float64                    ... the LINEAR DAMPING of the induced potential between
                                                     iterations (newInduced = mixing*justComputed +
                                                     (1-mixing)*previous); the plain, undamped iteration
                                                     (mixing = 1.0) was measured NOT to converge on even a
                                                     small two-electron case (11-Oct-2026 -- the induced
                                                     SOURCE itself is small, under 0.3% of the external
                                                     one, so the instability is in the ITERATION, not an
                                                     oversized physical term); unused while couplingEnabled
                                                     is false.
+ dalgarnoLewis       ::DalgarnoLewis.Settings    ... the settings passed through to every individual
                                                     `DalgarnoLewis.solve` call.
+ printBefore         ::Bool                      ... True if a short overview is to be printed before
                                                     the orchestration starts.
+ andersonDepth       ::Int64                     ... depth of the Anderson history used to accelerate the
                                                     coupled iteration.  **THE DEFAULT IS 0, i.e. plain
                                                     linear mixing, and that is a MEASURED choice rather
                                                     than a cautious one:** Anderson was implemented for
                                                     priority item 62 and does NOT repair this fixed point
                                                     -- on the Ne case in `solve`'s own note it is WORSE
                                                     than heavy damping at every depth tried.  It is kept
                                                     because it is sound, costs nothing when unused, and
                                                     may help a better-posed case;  do not switch it on
                                                     without checking that it converges.
+ directSolve         ::Bool                      ... True if the coupled equations are SOLVED as one linear
                                                     system, (I - M) s = b on the concatenated channel
                                                     sources, instead of being iterated.  **This is the
                                                     only route that can reach the fixed point at all**:
                                                     the iteration's spectral radius was measured at
                                                     about 2.7 on a closed shell (14-Oct-2026), so no
                                                     damping or acceleration converges, while (I - M)
                                                     stays invertible.  Implemented with
                                                     `RandomPhase.gmres` over `RandomPhase.sourceMap`,
                                                     so no matrix is ever formed.  `maxIterations` then
                                                     bounds the Krylov dimension and `accuracy` is the
                                                     relative residual demanded.  **THE DEFAULT IS TRUE
                                                     since 14-Oct-2026**, because an iterating default
                                                     cannot converge at all;  and on this route
                                                     `nIterations` of the returned `CoupledResponse`
                                                     counts KRYLOV STEPS rather than sweeps.
+ allChannels         ::Bool                      ... True if the induced field is built from EVERY target
                                                     symmetry the multipole can reach from each active
                                                     subshell, rather than from the single one named in
                                                     `targetSubshells`.  **This is what an RPA actually
                                                     asks for**, and the one-target truncation was measured
                                                     on 14-Oct-2026 to change the iteration's spectral
                                                     radius between 1.94 and 3.66 on nothing but the choice
                                                     of target -- because the two spin-orbit partners of a
                                                     subshell carry OPPOSITE angular signs and cancel, so a
                                                     truncated set breaks a cancellation rather than merely
                                                     dropping a term.  `targetSubshells` is still required
                                                     and still names each active subshell's PRIMARY channel,
                                                     which is the one whose chi is returned;  the extra
                                                     channels are solved too and enter the induced density.
                                                     **THE DEFAULT IS TRUE since 14-Oct-2026.** It was
                                                     false until then, which made the default coupled path
                                                     the one measured to give a sign-reversed total; see
                                                     `RandomPhase.solve`'s note for the numbers.
source
JenaAtomicCalculator.RandomPhase.Settings — Method

RandomPhase.Settings(settings::RandomPhase.Settings; activeSubshells::Union{Nothing,Array{Subshell,1}}=nothing, targetSubshells::Union{Nothing,Dict{Subshell,Subshell}}=nothing, couplingEnabled::Union{Nothing,Bool}=nothing, maxIterations::Union{Nothing,Int64}=nothing, accuracy::Union{Nothing,Float64}=nothing, mixing::Union{Nothing,Float64}=nothing, dalgarnoLewis::Union{Nothing,DalgarnoLewis.Settings}=nothing, printBefore::Union{Nothing,Bool}=nothing, andersonDepth::Union{Nothing,Int64}=nothing, allChannels::Union{Nothing,Bool}=nothing, directSolve::Union{Nothing,Bool}=nothing) ... the standard JAC keyword copy-constructor. A settings::RandomPhase.Settings is returned.

source
JenaAtomicCalculator.RandomPhase.angularCoefficient — Method

RandomPhase.angularCoefficient(L::Int64, tSub::Subshell, aSub::Subshell) ... the one-electron angular factor the rank-L induced interaction carries on the channel aSub -> tSub, namely AngularMomentum.CL_reduced_me(tSub, L, aSub), or 0.0 where the triangular and parity selection rules forbid the channel. It exists as a named function, rather than inline, because the convention is the thing most easily got wrong here and Rule 18 asks for it to be visible.

    **THE ARGUMENT ORDER IS THE CALLER'S BUSINESS, AND THE TWO ENDS OF THE INDUCED TERM USE DIFFERENT ONES.**
    This function is the bare reduced matrix element with its selection rules attached, and nothing else;  it does
    not know which end of the induced interaction it is serving.  `RandomPhase.inducedPotentialZr` calls it
    SOURCE-FIRST, as `angularCoefficient(L, b, t_b)`, because the weight it needs is the sum over the magnetic
    substates of a filled subshell and that sum is CL_reduced_me(b, L, t_b)^2 / (2L+1) -- positive definite, so the
    order is not free.  The receiving end does NOT call this function at all:  a one-body potential's matrix element
    carries `InteractionStrength.eMultipole`'s own reduction, which is `RandomPhase.receivingCoefficient`.  The two
    orders differ by (-1)^(j_1 - j_2), i.e. by a SIGN on every channel with |Delta j| = 1, so getting one of them
    wrong corrupts the BALANCE between channels rather than the scale.

    **AND THERE IS NO `(-1)^L` ANYWHERE ON THE DIRECT PATH -- amended 18-Oct-2026, priority item 75.**  It was
    applied once in `RandomPhase.solve`, on the reading that the induced direct term is the two-electron matrix
    element <t_a t_b| 1/r12 |a b> that `InteractionStrength.XL_Coulomb` assembles.  The direct term is not assembled
    that way here:  a charge density is built, Poisson is solved for a potential, and that potential's ONE-BODY
    matrix element is taken at the other end, so the two-electron product's phase never enters.  EXCHANGE is a
    different object and does go through XL_Coulomb's convention, which is why
    `RandomPhase.exchangeAngularCoefficient` keeps target-first at both of its ends.
    A coefficient::Float64 is returned, which is 0.0 for a channel the selection rules forbid.
source
JenaAtomicCalculator.RandomPhase.exchangeAngularCoefficient — Method

RandomPhase.exchangeAngularCoefficient(L::Int64, Lp::Int64, tSubA::Subshell, aSub::Subshell, tSubB::Subshell, bSub::Subshell, term::Symbol) ... the angular coefficient the EXCHANGE part of the induced interaction carries on the channel aSub -> tSubA, from the partner channel bSub -> tSubB, at Coulomb rank Lp and perturbation rank L. term is :E1 or :E2, the two exchange terms (below). A coefficient::Float64 is returned, 0.0 where the selection rules forbid it.

    **WHY THERE ARE TWO TERMS AND WHY THEY DIFFER.** Varying the Hartree-Fock potential
    `V_HF phi_a = sum_b [ <b|b> phi_a - <b|phi_a> phi_b ]` to first order gives two exchange pieces with
    DIFFERENT pairings of the four subshells:

        E1 = -sum_b <chi_b|1/r12|phi_a> phi_b      pairs (t_a, b)   and (t_b, a)
        E2 = -sum_b <phi_b|1/r12|phi_a> chi_b      pairs (t_a, t_b) and (b,   a)

    **WHY A 6j APPEARS AT ALL, where the direct term needs none.** The direct term carries only the
    perturbation's rank L at both ends, so one `CL_reduced_me` per end suffices. Exchange carries a COULOMB
    rank Lp that differs from L, so the free index must be recoupled from Lp back to L. That recoupling is
    the 6j, and the two terms use the same one with `j_b` and `j_tb` swapped in the bottom row:

        E1:  (-1)^(j_tb + j_b + L + Lp) * 6j{ j_ta  j_a  L ;  j_tb  j_b   Lp }
        E2:  (-1)^(j_tb + j_b + L + Lp) * 6j{ j_ta  j_a  L ;  j_b   j_tb  Lp }

    **NONE OF THIS WAS RECALLED FROM A TEXTBOOK, AND THAT IS DELIBERATE -- Rule 18.** The m-resolved form
    uses only Wigner-Eckart, which is unambiguous once the 3j convention is fixed, and the coefficient was
    then READ OFF numerically and matched against enumerated 6j argument orderings.

    **COVARIANCE IS A COMPLETE TEST OF THE STRUCTURE AND BLIND TO THE SCALE -- amended 20-Oct-2026, item
    75.** It fixes the 6j, the pairing and the phase, and it caught both of the author's errors below. What
    it cannot see is a factor depending only on (j_b, L, Lp), an overall normalisation included, since such a
    factor leaves every magnetic quantum number untouched. The scale is fixed elsewhere and by other means:
    for the E2 branch by the frozen-Hartree comparison recorded in `RandomPhase.exchangeSourceVector`, which
    holds for a closed subshell; for the E1 branch it is still open, though no longer for want of something to
    compare against -- `Bsplines.setupExchangeMatrix` has supplied the frozen NONLOCAL exchange since
    21-Oct-2026, and the comparison it makes possible is reported in `RandomPhase.exchangeSourceVector`: the
    identity does not close, so the E1 scale awaits one common convention rather than one more measurement.
    Do not read the 1.11e-16 below as a check on the magnitude.

    **COVARIANCE, THEN, IN ITS OWN RIGHT.** The m-resolved term must be
    PROPORTIONAL to `ME(t_a, m_ta, L, q, a, m_a)`, i.e. the ratio must be independent of every magnetic
    quantum number, because the problem is rotationally covariant. Only a correct form satisfies that, and
    it caught both of the author's errors: a first E1 built with the FORWARD chi amplitude showed
    m-dependence of 3.3e-1, as large as the coefficient itself -- `<chi_b|` is a BRA and needs the
    bra/ket-SWAPPED amplitude -- and E2 had been omitted altogether, which only became visible because it
    is covariant on its own to 1e-17.

    **THE PHASE WAS VALIDATED OUT OF SAMPLE.** It was read off 11 cases, so it was then checked on an
    exhaustive sweep of j = 1/2...7/2 and L, Lp = 0...3: **970 informative cases per term, worst deviation
    1.11e-16**. A formula tested on the data that produced it is a fit and not a check. A further 3126
    combinations vanish on both sides and carry no information; they were counted and excluded rather than
    allowed to inflate the agreement.
source
JenaAtomicCalculator.RandomPhase.exchangeSourceVector — Method

RandomPhase.exchangeSourceVector(multipole::EmMultipole, activeOrbitals::Dict{Subshell,Orbital}, chis::Dict{Tuple{Subshell,Subshell},DalgarnoLewis.PerturbedOrbital}, aSub::Subshell, tSubA::Subshell, grid::Radial.Grid, primitives::Bsplines.Primitives; occupations::Union{Nothing,Dict{Subshell,Float64}}=nothing, maxRank::Int64=8) ... builds the EXCHANGE induced source for the channel aSub -> tSubA, summed over every partner channel in chis and over the Coulomb ranks Lp, in the same B-spline projection and sign convention RandomPhase.inducedSourceVector uses. An extraSource::Array{Float64,1} of length primitives.grid.nsL + primitives.grid.nsS is returned.

    **IT IS NOT A POTENTIAL, which is why it needs its own function rather than a weight.** The direct term
    returns a radial potential multiplying `phi_a`; exchange returns `phi_b` and `chi_b` instead, each
    multiplied by a two-orbital Yukawa function -- so there is nothing to hand to `inducedSourceVector`.
    The two terms are, with the angular coefficients from
    `RandomPhase.exchangeAngularCoefficient`:

        E1:  Y^Lp[chi_b, phi_a](r) * phi_b(r)
        E2:  Y^Lp[phi_b, phi_a](r) * chi_b(r)

    **AND IT SUMS OVER RANKS, which changes the SHAPE of the computation and not just a weight.** The
    direct term carries only the perturbation's own rank L; this one needs every Lp the selection rules
    allow, so a case with 42 channels and about five ranks costs some thousands of Yukawa sweeps per
    iteration rather than tens.

    **THE OCCUPATION IS ALREADY IN THE COEFFICIENT, so do not apply it twice.** The derivation summed over
    every m_b of the partner subshell, which for a filled subshell IS its occupation 2j_b+1; `occupations`
    therefore enters only as the RATIO N_b/(2j_b+1) for a subshell that is not full. For the same reason
    the self term b = a is KEPT HERE IN FULL: it is exactly what cancels the direct term's spurious
    self-interaction, and `inducedPotentialZr` must then be called with `withExchange=true` so that it does
    not remove that self-interaction a second time.

    **HYDROGEN IS NOT THE TEST OF THIS NORMALISATION, AND THE CLAIM THAT IT IS HAS BEEN WITHDRAWN --
    measured 20-Oct-2026, priority item 75.** The appeal is obvious and it is a trap: for one electron
    V_HF = J - K vanishes identically, so a reader concludes that the induced direct and induced exchange
    sources must be the same vector and that comparing them needs no reference value. Two measurements say
    otherwise.

    FIRST, THE IDENTITY HAS THREE TERMS AND THE THIRD ONE CANNOT BE FORMED HERE. Varying
    (J[phi] - K[phi]) phi = 0, which holds for ANY single orbital, gives delta(J-K)[chi] phi_a + (J-K) chi = 0:
    the FROZEN potential acting on chi is part of it. The problem carries exactly two radial shapes,
    v1 = phi_a Y_1[phi_a, chi] and v2 = chi Y_0[phi_a, phi_a], and the identity splits into
    `v1:  A - B1 - C_K = 0` and `v2:  -B2 + C_J = 0`, where A is the induced direct coefficient, B1 and B2
    the two induced exchange coefficients, and C_J, C_K the frozen Hartree and frozen exchange ones. **C_K
    BECAME MEASURABLE ON 21-Oct-2026 with `Bsplines.setupExchangeMatrix`, AND THE v1 EQUATION DOES NOT CLOSE
    -- see the module's own docstring for what that leaves open.** C_K itself is not in doubt: it comes out
    EXACTLY occ*Lambda_1 to ten digits and `K chi` is collinear with v1 to 3e-16. The failure is in the
    relative convention of the three terms, measured on H 1s in a 120 a.u. box:

        channel        A          B1 (coded)    C_K       A-B1-C_K    B1 the identity needs
        1s -> 2p_3/2  -0.666661   +0.212687   +0.166667   -1.046014        -0.833328
        1s -> 2p_1/2  -0.666678   -0.101583   +0.166667   -0.731761        -0.833344

    The identity needs the SAME B1 on both channels while the coded one differs between them by a factor
    -2.09, so no sign and no overall scale can repair it; four conventions were tried and all four fail
    (B1 against A, against A*aCoeff, against (A-C_K)*aCoeff, and B1/aCoeff, with aCoeff =
    `RandomPhase.receivingCoefficient`), the implied factors coming out 1.78/-2.15 and 3.20/-4.74 and never
    one number. `tools/mResolvedPolarizability.jl` CASE M carries the measurement. Comparing the
    direct source against this function's output tests neither equation: measured on H 1s in a 120 a.u. box
    the ratios are 1.402708 (2p_3/2) and 1.811708 (2p_1/2) with cos 0.826089 and 0.899776, and both are
    REPRODUCED EXACTLY by the split below -- they are the angle between a pure v1 and a v1/v2 mixture, not a
    defect.

    SECOND, HYDROGEN IS THE ONE CASE WHERE THE FACTOR UNDER TEST IS NOT 1. `scale` above is N_b/(2j_b+1),
    which is exactly 1 for every closed subshell and 1/2 for a single electron -- so the open-shell
    occupation rule, the only thing a hydrogen comparison could calibrate, is also the only thing hydrogen
    cannot be calibrated against. Its left-hand side is nuclear-only as well, so C_J = 0 there while a
    many-electron mean field supplies it.

    **WHAT IS SETTLED, AND IT IS THE PART THAT MATTERS FOR A CLOSED SHELL.** The v2 equation IS checkable
    and it holds: C_J is the frozen Hartree coefficient of the partner subshell, N_b, and B2 comes out as
    `1.0` EXACTLY for every subshell and every multipole rank -- analytically, since at Lp = 0 the 6j with a
    zero argument is 1/sqrt((2j_a+1)(2j_t+1)) and cancels both reduced matrix elements. With `scale` = 1 for
    a closed subshell, B2 = 1 = C_J/N_b per electron and the E2 branch is correctly normalised. The radial
    assembly is sound too: the E1 term is collinear with the direct term to cos = -1.000000000000, the E2
    term lies along v2 to a residual of 2e-16, and E1 + E2 reproduces this function to 3e-16.
    `tools/mResolvedPolarizability.jl` CASE L carries the measurement.
source
JenaAtomicCalculator.RandomPhase.gmres — Method

RandomPhase.gmres(applyA::Function, b::Array{Float64,1}, maxIterations::Int64, tolerance::Float64) ... solves A x = b for a linear operator available only through its action applyA, by the standard Arnoldi/GMRES construction: build an orthonormal Krylov basis of b, A b, A^2 b, ..., and pick the combination minimising the residual over it.

    **WHY A KRYLOV SOLVER HERE AND NOT A MATRIX FACTORISATION.** The coupled system's operator is
    (I - M) on the concatenated channel sources, and M is never formed: assembling it in the B-spline
    basis would need one `RadialIntegrals.Yk_ab` sweep per column, which is O(N^2) per column and so
    hours of work for a case the map itself sweeps in seconds. GMRES needs only the action, and one
    action is one `RandomPhase.sourceMap` call. It is also indifferent to the spectral radius -- which
    is the whole point, since that radius is about 2.7 here and no fixed-point iteration can converge.

    This is unrelated to the Krylov/Lanczos CI eigensolver that was measured and DECLINED in Aug-2026:
    that was an EIGENVALUE problem for CI matrices, rejected because diagonalisation was a small share of
    wall time, and it proposed a new package dependency. This is a LINEAR SYSTEM whose iteration provably
    cannot converge, and it uses nothing beyond `LinearAlgebra`.

    A tuple (x, iterations, relativeResidual) is returned. The residual is the true GMRES residual
    ||b - A x|| / ||b||, so a caller can tell a converged solve from an exhausted one.
source
JenaAtomicCalculator.RandomPhase.inducedPotentialZr — Method

RandomPhase.inducedPotentialZr(multipole::EmMultipole, activeOrbitals::Dict{Subshell,Orbital}, chis::Dict{Tuple{Subshell,Subshell},DalgarnoLewis.PerturbedOrbital}, excludeSubshell::Subshell, grid::Radial.Grid; occupiedOrbitals::Union{Nothing,Dict{Subshell,Orbital}}=nothing, occupations::Union{Nothing,Dict{Subshell,Float64}}=nothing, withExchange::Bool=false) ... builds the DIRECT (Hartree, "ring") induced potential ONE electron of excludeSubshell feels from every OTHER active electron's CURRENT chi – its (N-1) PARTNERS IN ITS OWN SUBSHELL INCLUDED, whenever occupations is given – at the multipole's own rank L, in the SAME "Zr" (= -rV(r)) convention Radial.Potential and Bsplines.computeVlocal use throughout JAC – so that the minus sign below is the ordinary nuclear-potential-style sign, not a new convention. The induced density itself is 2[PbPchi_b + QbQchi_b] – the psichi + chipsi symmetrization for a real response – which is exact only at omega = 0, since at finite omega the two terms are the two time orderings and are different functions.

    **THE WEIGHT IS sqrt(2j_b+1) TIMES THE CHANNEL'S REDUCED MATRIX ELEMENT, AND THE sqrt IS NOT A TYPO.**
    Until 14-Oct-2026 each electron b was weighted by the full (2j_b+1), treating it statistically as a
    filled shell, with no angular factor at all -- which made the coupled iteration diverge (see
    `RandomPhase.solve`). The weight is fixed, without any literature, by the L = 0 HARTREE LIMIT:

      * at L = 0 with t_b = b the induced potential must be the ordinary first-order Hartree potential,
        2*(2j_b+1)*Y_0[rho]/r, which is what the old code had and what is not in dispute;
      * the source this potential feeds is `DalgarnoLewis.solve`'s, which is REDUCED -- it comes from
        `DalgarnoLewis.amplitudeKernel`, a reduced one-electron matrix element -- so the induced term must
        be reduced to match:  `RandomPhase.angularCoefficient` at this end, and
        `RandomPhase.receivingCoefficient`, which divides by sqrt(2j_a+1), where the potential acts;
      * and `AngularMomentum.CL_reduced_me(b, 0, b) = sqrt(2j_b+1)` EXACTLY, checked for s, p, d and f.

    Equating the two therefore gives weight * sqrt(2j_b+1) = 2*(2j_b+1), i.e. a weight of
    2*sqrt(2j_b+1): the occupation splits in half, one sqrt(2j_b+1) staying here and the other being
    carried by the reduced matrix element's own normalisation. This is precisely the sqrt(2j+1) Rule 18
    is about, and it is written out because the two quantities it sits between -- an ordinary potential
    and a reduced source -- are otherwise denoted alike.

    **AND THE WEIGHT IS POSITIVE DEFINITE, WHICH AN EARLIER VERSION OF THIS DOCSTRING DENIED -- 18-Oct-2026,
    priority item 75.**  Written out as the explicit sum over the magnetic substates of a filled subshell, the
    weight of the channel b -> t_b is sum_m <b m|C^L_0|t_b m> <t_b m|C^L_0|b m> = CL_reduced_me(b, L, t_b)^2/(2L+1),
    where the (2L+1) is 3j orthogonality at fixed middle projection and not a calibration.  It cannot change sign.
    The text here previously argued the opposite -- that the two spin-orbit partners of a subshell enter the induced
    field with OPPOSITE signs, that the cancellation is "physical", and that it is "a large part of why the
    uncorrected term was far too strong".  THAT CLAIM IS WITHDRAWN:  the alternation was an artefact of calling
    `RandomPhase.angularCoefficient` target-first at this end, which differs from source-first by
    (-1)^(j_b - j_t_b) and so flips exactly the |Delta j| = 1 channels -- 25 of Ba+'s 42 core channels.

    **THE RADIAL PART IS VERIFIED AGAINST JAC'S OWN, TO TEN DIGITS.** `InteractionStrength.XL_Coulomb`
    builds the corresponding two-electron strength from `RadialIntegrals.SlaterRkComponent`, so the two
    can be compared entry by entry if the source orbital is chosen to BE a single B-spline, which makes
    its coefficient vector a unit vector. Done on the Ne case for three spline pairs, this route and
    JAC's agree to every digit printed -- ratio 1.000000, values -7.3537752978e-03 against
    -7.3537752978e-03 -- SIGN INCLUDED. So the radial machinery and the "Zr" sign convention here are the
    ones JAC uses elsewhere, and the angular factor was the only thing this module lacked.
    A VindZr::Array{Float64,1} of length grid.NoPoints is returned.
source
JenaAtomicCalculator.RandomPhase.inducedSourceVector — Method

RandomPhase.inducedSourceVector(VindZr::Array{Float64,1}, sourceOrbital::Orbital, primitives::Bsplines.Primitives) ... projects the induced potential VindZr (in the SAME "Zr" convention as inducedPotentialZr returns) onto every B-spline primitive against sourceOrbital, exactly reproducing Bsplines.computeVlocal's own formula and sign – the one difference being that computeVlocal's SECOND argument is itself a single primitive, where here it is a general tabulated orbital, so the shared formula is written out again rather than called. This is DalgarnoLewis.solve's extraSource keyword's own input.

    **IT CARRIES NO ANGULAR COEFFICIENT, DELIBERATELY, AND THE CALLER MUST SUPPLY ONE.** What this
    function returns is the bare radial projection;  the reduction belonging to the active channel is applied by
    `RandomPhase.solve` and `RandomPhase.sourceMap` through `RandomPhase.receivingCoefficient`. Until 14-Oct-2026
    nothing applied any angular factor at all, which is what made the coupled iteration diverge. A caller that uses
    this function directly, as a diagnostic does, must multiply by `receivingCoefficient(L, active, target)` --
    ACTIVE first, divided by sqrt(2j_active+1), and with no (-1)^L.
    An extraSource::Array{Float64,1} of length primitives.grid.nsL + primitives.grid.nsS is returned.
source
JenaAtomicCalculator.RandomPhase.projectOntoUnoccupied — Method

RandomPhase.projectOntoUnoccupied(chi::DalgarnoLewis.PerturbedOrbital, targetSubshell::Subshell, occupiedOrbitals::Dict{Subshell,Orbital}, grid::Radial.Grid) ... removes from chi every component along an OCCUPIED orbital of chi's own kappa, and returns the result as an orbital::Orbital. A channel label such as 5p_3/2 -> 3d_5/2 names a kappa SYMMETRY and not one target orbital, so the solved chi spans that whole symmetry – filled members included. A core electron cannot be excited into a filled orbital, so those components are forbidden and must not appear in any observable built from chi.

    **WHY THIS EXISTS AS ITS OWN FUNCTION -- 16-Oct-2026, item 73(c).** The projection had been applied to
    the POLARIZABILITY assembly since 14-Oct and never to the induced DENSITY, although both are built from
    the same chi. The consequence was measured and is large: the density's rank-1 moment, which must equal
    the polarizability computed from the same chi, instead ran from -886 to +2081 times it across 42 core
    channels of Ba+. With the projection applied the ratio is **exactly 3.00000 on every one of them**, and
    that residue is the (2L+1) of `RandomPhase.inducedPotentialZr`. Two separately-correct pieces again
    failed to compose because nothing required them to.
source
JenaAtomicCalculator.RandomPhase.reachableChannels — Method

RandomPhase.reachableChannels(L::Int64, aSub::Subshell) ... every target symmetry a rank-L multipole can reach from the subshell aSub, i.e. every kappa allowed by the triangular condition on j and by the parity rule lt + la + L even. This is what an RPA's induced field has to be built from, and it needs no input from the caller because the selection rules determine it completely.

    **ONLY THE kappa OF THE RETURNED SUBSHELLS MATTERS.** `DalgarnoLewis.solve` takes a `targetSubshell`
    purely to read `targetSubshell.kappa` off it -- the channel is a symmetry, not a particular orbital --
    so each entry here is built with the LOWEST principal quantum number that symmetry admits, n = l+1,
    and that n carries no meaning. A caller must not read anything into it.

    Worked, because it is easy to under-count: from 2p_3/2 with L = 1 the reachable symmetries are
    s_1/2, d_3/2 and d_5/2 -- THREE channels, where `Settings.targetSubshells` can name only one. The p
    symmetries are excluded by parity and j = 7/2 by the triangular condition. An
    `Array{Subshell,1}` is returned, ordered by l and then by j, and it is empty only for a rank and
    symmetry that admit nothing at all. The order is by l and then by kappa, so the j = l+1/2 partner comes
    before the j = l-1/2 one.
source
JenaAtomicCalculator.RandomPhase.receivingCoefficient — Method

RandomPhase.receivingCoefficient(L::Int64, aSub::Subshell, tSub::Subshell) ... the one-electron angular factor the rank-L induced potential carries where it ACTS, i.e. at the active end of the channel aSub -> tSub, namely AngularMomentum.CL_reduced_me(aSub, L, tSub) / sqrt(2*j_a+1), or 0.0 where the triangular and parity selection rules forbid the channel. It is the counterpart of RandomPhase.angularCoefficient, which is the factor the induced DENSITY carries at the other end, and they are deliberately two functions because they are two different reductions of the same algebra.

    **WHY IT IS NOT `angularCoefficient`, AND HOW THAT WAS DECIDED -- 18-Oct-2026, priority item 75.** The induced
    potential and the EXTERNAL drive are both ordinary one-body potentials, acting on the same electron, in the same
    Dalgarno-Lewis equation; and a one-body potential has ONE matrix element, so the same radial function v(r) must
    produce the same source vector down either path. `DalgarnoLewis.solve` reduces its drive with
    `InteractionStrength.eMultipole`, which is CL_reduced_me(a, L, t)/sqrt(2j_a+1) times the bare radial integral --
    source first, and DIVIDED. Pushing v(r) = r down both paths on the nine E1 channels of Ne, the induced path as
    it stood returned -sqrt(2j_a+1)*CL(t,L,a)/CL(a,L,t) times the drive instead of 1.0, i.e. sqrt(2j_a+1) in
    magnitude with a channel-dependent sign, reproducible to 2.0e-15.

    **AND THE DRIVE IS THE ANCHORED SIDE, which is what makes that an arbitration rather than one more comparison:**
    `eMultipole`'s normalisation is fixed by the EXACT alpha(H 1s) = 4.5 a.u. through the polarizability assembly
    alpha = (2/3)(2j_a+1) eMultipole(1, phi_a, chi), which reproduces 4.49972686 on this grid. So the drive's
    reduction was never in question and the induced term's was.
    A coefficient::Float64 is returned, which is 0.0 for a channel the selection rules forbid.
source
JenaAtomicCalculator.RandomPhase.solve — Method

RandomPhase.solve(multipole::EmMultipole, gauge::EmGauge, omega::Float64, activeOrbitals::Dict{Subshell,Orbital}, potential::Radial.Potential, primitives::Bsplines.Primitives; settings::RandomPhase.Settings=RandomPhase.Settings(), occupiedOrbitals::Union{Nothing,Dict{Subshell,Orbital}}=nothing, occupations::Union{Nothing,Dict{Subshell,Float64}}=nothing, staticDrive::Bool=false) ... solves one DalgarnoLewis equation per active electron named in settings.activeSubshells (or, if that is empty, per subshell of activeOrbitals), all driven by the SAME external multipole operator at the SAME frequency omega. With settings.couplingEnabled == false (the default), this is the independent-particle limit: each chi is exactly what a bare DalgarnoLewis.solve call for that electron alone would return. With settings.couplingEnabled == true, the electrons are iterated together, each one's source gaining the DIRECT induced-potential contribution of every OTHER active electron's CURRENT chi (RandomPhase.inducedPotentialZr + RandomPhase.inducedSourceVector), until the induced potential's relative change falls below settings.accuracy or settings.maxIterations is reached – see the module's own docstring for what this coupled path has, and has not yet, been checked against. WHAT THIS FUNCTION HAS BEEN VALIDATED TO DO, AND WHAT IT STILL CANNOT DO – 18-Oct-2026, priority item 62 closed. At omega = 0 with staticDrive = true the coupled response has been checked against an INDEPENDENT m-resolved implementation – explicit magnetic substates, no angular reduction, no 6j, no CL convention – function by function rather than in a total: on the nine E1 channels of Ne the chi returned here is CL(a,1,ta)/sqrt(2ja+1) times that calculation's, the whole difference being the normalisation InteractionStrength.eMultipole puts on the drive, to 9.9e-11 against a GMRES tolerance of 1e-8. Checking the TOTAL would not have shown this: the two angular conventions tried before cbdedacb agree to 0.7 % on Ne's screened total while differing by 0.644 to 2.194 PER CHANNEL, which is how a convention error survived two repairs here. WHAT IS STILL ABSENT IS EXCHANGE, AND THE REASON CHANGED ON 21-Oct-2026. The blocker named until then was a frozen NONLOCAL exchange operator; Bsplines.setupExchangeMatrix is that operator and it is built and validated. What blocks the wiring now is ONE angular convention shared by the induced direct term, the reduced exchange coefficient and the frozen operator – a derivation, not code – so the verified exchange lines in this file stay deliberately unwired; the module's own docstring states the measurement that leaves it open. A direct-only induced field over-screens, so a number from this function is a direct-only result in a strongly-coupled regime and NOT a validated screening correction. Do not read the paragraph above as more than it says: it establishes that two routes compute the SAME thing, not that the thing is the measured one. A response::RandomPhase.CoupledResponse is returned.

source
JenaAtomicCalculator.RandomPhase.sourceMap — Method

RandomPhase.sourceMap(multipole::EmMultipole, gauge::EmGauge, omega::Float64, activeOrbitals::Dict{Subshell,Orbital}, channels::Array{Tuple{Subshell,Subshell},1}, sources::Array{Float64,1}, potential::Radial.Potential, primitives::Bsplines.Primitives, dlSettings::DalgarnoLewis.Settings; occupiedOrbitals::Union{Nothing,Dict{Subshell,Orbital}}=nothing, occupations::Union{Nothing,Dict{Subshell,Float64}}=nothing, staticDrive::Bool=false) ... one application of the coupled map: given the induced source of EVERY channel, concatenated into a single vector, solve each channel's Dalgarno-Lewis equation and rebuild every channel's source from the resulting chi's. This is exactly one sweep of the fixed-point iteration, isolated so that it can serve as the matrix-vector product of a linear solver as well.

    **THE MAP IS AFFINE, AND THAT IS WHAT MAKES THE DIRECT SOLVE POSSIBLE.** Writing it as
    F(s) = b + M s, the drive b is simply F(0) -- the sources rebuilt from the UNCOUPLED chi's -- and the
    action of the linear part follows as M s = F(s) - b, with no matrix ever formed. The fixed point is
    the solution of (I - M) s = b, which exists whenever (I - M) is invertible, whether or not the
    spectral radius of M is below one.
    **`staticDrive` IS PASSED STRAIGHT THROUGH TO `DalgarnoLewis.solve`, and at omega = 0 it is not
    optional** -- the dynamic kernel is identically zero there, so every channel would be driven by
    nothing. `RandomPhase.solve` raises rather than let that happen; this function is the lower level and
    trusts its caller.
    A newSources::Array{Float64,1} of the same length is returned, together with the chis it passed
    through, as a tuple (newSources, chis).
source