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.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.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.JenaAtomicCalculator.Atomic.Computation — Method
Atomic.Computation() ... constructor for an 'empty' instance::Atomic.Computation. A computation::Atomic.Computation is returned.
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.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.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.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.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.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.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.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.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.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)", ...]`.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.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.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.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.
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.
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.
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.
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).
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.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.
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.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.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.
JenaAtomicCalculator.DalgarnoLewis.Settings — Method
DalgarnoLewis.Settings() ... constructor for an empty instance of DalgarnoLewis.Settings. A settings::DalgarnoLewis.Settings is returned.
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.
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.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.
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.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.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.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.
JenaAtomicCalculator.RandomPhase.Settings — Method
RandomPhase.Settings() ... constructor for an empty instance of RandomPhase.Settings. A settings::RandomPhase.Settings is returned.
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.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.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.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.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.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.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.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.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.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.
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).