B-Spline basis
JenaAtomicCalculator.Bsplines.Bspline — Type
struct Bsplines.Bspline ... defines a type for a (single) B-spline that is defined on a given radial grid from r[lower:upper]. Note that only the non-zero values are specified for the B-spline function and its derivative.
+ lower ::Int64 ... lower radial index (on the radial grid.r) from where the functions is nonzero.
+ upper ::Int64 ... upper radial index up to which the functions is nonzero.
+ bs ::Array{Float64,1} ... radial B-spline functions as defined on the predefined grid.r[lower:upper]
+ bp ::Array{Float64,1} ... derivative of bs on the predefined grid grid.r[lower:upper]JenaAtomicCalculator.Bsplines.Primitives — Type
struct Bsplines.Primitives ... defines a type for a set of primitive functions which typically belongs to a well-defined grid.
+ grid ::Radial.Grid ... radial grid on which the states are represented.
+ bsplinesL ::Array{Bspline,1} ... set of B-splines for the large components on the given radial grid.
+ bsplinesS ::Array{Bspline,1} ... set of B-splines for the small components on the given radial grid.JenaAtomicCalculator.Bsplines.ShiftInvertOperator — Type
struct Bsplines.ShiftInvertOperator ... the linear operator x -> (matrixA - sigma*matrixB)^-1 * matrixB * x that Bsplines.diagonalizeLocalMatrixNearEnergy hands to ArnoldiMethod.partialschur, which accepts any object implementing Base.size, Base.eltype and LinearAlgebra.mul! – this is the minimal such object, not a general-purpose type.
+ F ::SparseArrays.UMFPACK.UmfpackLU ... sparse LU factorization of (matrixA - sigma*matrixB).
+ Bsparse ::SparseMatrixCSC{Float64,Int64} ... the sparse overlap-side matrix, applied before F is used.
+ n ::Int64 ... the operator's dimension (both ways), i.e. length(keep).JenaAtomicCalculator.Bsplines.bandedSparseTriplets — Method
Bsplines.bandedSparseTriplets(rowSplines::Array{Bsplines.Bspline,1}, colSplines::Array{Bsplines.Bspline,1}, f::Function) ... the shared two-pointer sweep behind Bsplines.generateTTpMatrixSparse! and Bsplines.setupLocalMatrixSparse: visits only the (i,j) pairs whose B-splines have overlapping support – rowSplines/colSplines are each assumed enumerated in knot order (Bsplines.generatePrimitives), so lower/upper are monotonically non-decreasing in index and the overlapping columns for a given row form ONE contiguous range. jLo only ever advances: once column j stops overlapping row i (its upper <= row i's lower), it can never overlap any LATER row either, so the total work is O(n + band entries), not O(n^2) comparisons. Calls f(rowSplines[i], colSplines[j]) for each candidate pair and keeps it only if nonzero. A (Is::Array{Int64,1}, Js::Array{Int64,1}, Vs::Array{Float64,1}) triplet, ready for sparse(Is, Js, Vs, nrows, ncols), is returned.
JenaAtomicCalculator.Bsplines.boundaryDropCounts — Method
Bsplines.boundaryDropCounts(kappa::Int64, grid::Radial.Grid) ... returns the number of leading (near r=0) and trailing (near r=Rmax) large- and small-component B-splines that must be excluded from the generalized eigenvalue problem for the given symmetry kappa, following Zatsarinny & Froese Fischer's DBSRHF reference code (hfboundary.f90's Boundaryconditions, the finite/non-point-nucleus branch) and cross-checked against a live DBSRHF run on Sc: P needs l+1 excluded at r=0 (kappa-sign independent, since the large component's leading near-origin power depends only on l); Q needs l+2 excluded for kappa<0 (j=l+1/2, where the naive leading power l+1+kappa vanishes identically since kappa=-(l+1), pushing the true leading power one order higher) but only l for kappa>0 (j=l-1/2, kappa=l, no such cancellation) – both capped at (order-1), matching DBSRHF's own j>ksp-1/j>ksq-1 caps.
The trailing (outer-boundary) counts are kappa/l-INDEPENDENT in DBSR_HF (confirmed: identical trailP=3, trailQ=2 for every orbital
in the live Sc run) and tied to a small fixed parameter DBSR_HF calls ibzero (=2 by default): trailP = ibzero+1 and trailQ = ibzero.
This outer truncation is not optional: without it the diagonalized spectrum is subtly perturbed even for the kappa>0 states that
need no elimination at r=0 at all.
A tuple (dropP::Int64, dropQ::Int64, trailP::Int64, trailQ::Int64) is returned.JenaAtomicCalculator.Bsplines.canonicalSign — Method
Bsplines.canonicalSign(coeffs::AbstractVector{Float64}, nsL::Int64) ... the sign convention for a tabulated orbital: +1.0 or -1.0, taken from the LARGE-component B-spline coefficient of greatest magnitude. A Float64 is returned.
WHY NOT `sum(P[1:30])`, WHICH THIS REPLACES (07-Sep-2026). That criterion sums the large component over
the first thirty grid points -- deep inside the nucleus, where a p, d or f orbital is essentially zero.
For the 3p_1/2 of a C-like uranium RAS layer it evaluated to ~1e-15, i.e. PURE ROUND-OFF, so an orbital
change of one part in 1e8 could flip the sign of the whole tabulated orbital.
THAT MADE THE ENERGY FUNCTIONAL DISCONTINUOUS, and it is why the EOL solver stagnated. Measured on
C-like U: walking the line-search step across 2.20e-08 -> 2.25e-08 flips 3p_1/2 and moves the energy by
exactly 0.032 Ha, while every other orbital and every other diagnostic (the b-vectors, the positive-branch
weight, the orthonormality deviation, mtp) is unchanged. The line search then cannot step past the cliff,
every iteration buys ~3e-10 Ha, |grad| floors, and the run stops on a stagnant gradient -- which was the
state of eleven of twelve census runs and of layers 2-4 of every table in examples/example-Ai.jl.
The largest coefficient is O(1) by construction, so it cannot be decided by round-off. The convention it
picks may DIFFER from the old one for a given orbital; that is a gauge choice and no observable may
depend on it -- which is exactly what the test suite checks.JenaAtomicCalculator.Bsplines.checkGridRepresentation — Method
Bsplines.checkGridRepresentation(subshells::Array{Subshell,1}, Z::Float64, primitives::Bsplines.Primitives; occupations::Dict{Shell,Int64}=Dict{Shell,Int64}(), accuracy::Float64=1.0e-3, stopper::Bool=true, mass::Float64=1.0) ... checks whether the given radial grid can represent every subshell of the list, by solving the single-electron Dirac equation for a POINT nucleus on this grid and comparing each level with the closed-form point-nucleus energy Basics.computeDiracEnergy. Every subshell whose energy deviates by more than accuracy is listed, and an error is raised; with stopper = false a loud warning is printed instead and the computation proceeds. A tuple (isRepresentable::Bool, recommendedRbox::Float64) is returned.
A SUBSHELL FAILS ONLY WHEN THE GRID REPRESENTS NEITHER OF TWO HYDROGENIC PROXIES, when `occupations` is given: the orbital at the
BARE charge Z, and the orbital at the Slater screened charge of Basics.slaterScreening (floored at the asymptotic Z - NoElectrons +
1). That is not a way of being lenient; it is because NEITHER proxy is the real orbital and the real one lies between them, so a
grid which carries either end is not demonstrably wrong. Measured against the known answers:
Na 3s bare Zeff 11.0 r_+ = 1.64 | Slater Zeff 2.20 r_+ = 8.18 | real r_max ~ 3.2
Mg 3s bare Zeff 12.0 r_+ = 1.50 | Slater Zeff 2.85 r_+ = 6.32 | real r_max ~ 2.9
K 4s bare Zeff 19.0 r_+ = 1.68 | Slater Zeff 2.20 r_+ = 14.6 | real r_max ~ 4.2
The bare charge understates an outer orbital by about a factor of two and the screened charge overstates it by two to three, so
EITHER used alone over-rejects, in opposite directions. Until 17-Aug-2026 only the bare charge was used, and it rejected the valence
orbital of every heavy near-neutral system: on Th+ [Rn] 6d 7s^2, on its own recommended box of 52.7 a.u., it refused the 7s at
1.93e-3 and advised a box of 2.3 a.u. for an 89-electron ion, while with `gridStopper = false` that very run converged in ten
iterations and passed Bsplines.checkOrbitalConsistency, the test that actually catches a wrong state. Screening alone is no better:
it rejects three cases of the JAC test suite at up to 1.5e-1, demanding a 38.8 a.u. box for a system that computes correctly on
11.1.
Inner shells are unaffected either way, since there is almost nothing to screen -- the thorium 1s sees 89.7 rather than 90 -- so the
check stays exactly as strict where the bare-Z yardstick was already right.
WITHOUT `occupations` the bare charge alone is used, which reproduces the behaviour before 17-Aug-2026. That is all a caller holding
no occupation numbers can do, but it is NOT appropriate for a neutral or near-neutral heavy system; pass the occupations there.
WHY A POINT NUCLEUS IS THE RIGHT YARDSTICK, whatever the computation itself uses. The question asked here is not "is this orbital
physically accurate" but "can this GRID resolve an orbital of this size and shape at all", and only the point-nucleus spectrum has
closed-form energies to test against. An extended nucleus, or a Dirac-Fock rather than a bare nuclear field, changes each individual
orbital by a modest factor -- it does not change the ORDER of the spectrum, nor the radial scale that the box has to accommodate.
THE USUAL CAUSE IS A BOX THAT IS TOO LARGE, not one that is too small. The number of B-splines is fixed, so a box much wider than
the orbitals spends them on empty space and starves the physical region: at Z = 10 the default box of 614 a.u. leaves 5f_7/2 wrong
by 31%, while a box of 11 a.u. -- matched to the orbital -- gives it to 6e-5. The box recommended here is the one of
Basics.recommendedGrid, `r_plus + 16 n/Zeff`, so that the two cannot contradict each other.
+ subshells ::Array{Subshell,1} ... subshells that the grid must be able to carry.
+ Z ::Float64 ... nuclear charge.
+ occupations ::Dict{Shell,Int64} ... shell occupations; if empty, every subshell is tested at the bare charge.
+ accuracy ::Float64 ... largest tolerated relative deviation from the closed-form energy.
+ stopper ::Bool ... true, if a failure shall raise rather than warn.
A NamedTuple is returned, carrying the MEASUREMENT and not merely a verdict -- priority item 40:
`(ok, rboxWanted, nSubshells, nOffenders, nBorderline, worstSubshell, worstDeviation, accuracy, rbox)`.
`ok` and `rboxWanted` destructure first, so an existing `ok, rbox = ...` keeps working. **The field to
judge on is `worstDeviation` against `accuracy`**: it is the largest relative deviation over ALL subshells,
offending or not, and it says how much margin the grid had, which a bare `true` cannot.JenaAtomicCalculator.Bsplines.checkOrbitalBox — Method
Bsplines.checkOrbitalBox(orbitals::Dict{Subshell,Orbital}, grid::Radial.Grid; extentTolerance::Float64=0.9, densityFloor::Float64=1.0e-5, stopper::Bool=false) ... checks, on the CONVERGED orbitals rather than on a hydrogenic stand-in, whether the radial box was in fact large enough for them, and reports what it measured; a tuple (isAdequate::Bool, report::String) is returned, the report being a single line fit to be written into a summary file.
THE BOX IS AN ESTIMATE UNTIL SOMETHING CHECKS IT. Basics.recommendedGrid derives it from Slater's rules, a 1930s empirical recipe,
and nothing downstream ever asked whether the answer was right -- so every result carried an unquantified box error. The measure
used here is the orbital's own EXTENT,
`rEnd`, the radius beyond which its density has fallen below `densityFloor` of its maximum: if
`rEnd/rbox` approaches 1 the orbital is still substantial where the box ends and has been cut off.
WHY NOT THE AMPLITUDE AT THE WALL, which is the obvious choice: the B-spline basis imposes P(rbox) = 0, so the density at the wall
is zero BY CONSTRUCTION and measures the boundary condition rather than the orbital. Measured on argon in a 3 a.u. box -- an error
of 37 Ha in the total energy -- the wall density came to 9.2e-10, i.e. the most badly truncated case available scored better than
the correct one.
THE DEFAULT densityFloor = 1e-5 WAS CALIBRATED, not chosen, against argon boxes whose harm is known: 3.0 a.u. is wrong by 37 Ha and
6.0 a.u. by 2.3e-3 Ha, both of which must be flagged, while 10.2 a.u. gives the right answer and 61 a.u. costs 5e-9 Ha, neither of
which may be. On an uncut 61 a.u. box the outermost argon orbital ends at 6.92, 8.10 and 9.26 a.u. for floors of 1e-4, 1e-5 and
1e-6, so 1e-5 puts the correct box at extent/box = 0.80 against the 0.90 limit while both bad boxes reach 1.0. A floor of 1e-10
fails outright: the tail is then still alive at 13 a.u. and the CORRECT box is condemned.
WHAT THIS DOES NOT DO, and it is half the problem: it does not detect a box that is too LARGE. That failure has cost this codebase
more than truncation ever did, but it leaves no signature in the outer orbital's shape, only in its energy, and it is strongly
n-dependent. Measured on thorium at the full nuclear charge with hp = rbox/300 throughout, the 1s is unmoved (3e-9) across boxes
from 10 to 600 a.u. while the 7s degrades 1.0e-7 -> 2.0e-3 -> 1.1e-1 -> 2.4e-1; yet argon, whose outermost orbital has one node
instead of six, loses only 1.0e-9 on a box 25 times too large. Counting B-spline break points inside the orbital does not see it
either: over that same thorium range the count falls only from 60 to 47 while the error grows by six orders, because with hp scaled
to the box the mesh holds
`log(R/rnt)/h` points below any radius R independently of rbox. No threshold in the single-run data was
defensible, so none is imposed. Bsplines.checkOrbitalConsistency remains the guard for that side: a starved subshell shows up as its
two spin-orbit partners ceasing to describe the same shell.
AND A FLAG HERE IS NOT A DEFECT: a COUNT of these warnings is not a count of damage. The ratio measures where
the tail EXISTS, not how much WEIGHT it carries. Of eight flagged example branches examined on 20/21-Oct-2026 the energy error ran
0.002-0.04 % in five, 1-3 % in two and 29 % in one, and on a second pass every one of the eight proved harmless. THE DISCRIMINATOR
IS THE FLAGGED ORBITAL'S Z_eff ~ Z - N + 1 *AND* ITS n, BOTH CONDITIONS: an orbital is genuinely at risk when Z_eff ~ 1 AND n >= 3,
i.e. when it lies OUTSIDE the bulk of the electronic charge, whereas Z_eff >= 2 is safe even at extent/box = 0.99. A VALENCE orbital
of a compact neutral atom passes Z_eff ~ 1 and is NOT at risk, because its own shell partners screen it poorly: neutral C I
1s^2 2s^2 2p^2 with 2p_1/2 at 0.971 of a 10.1 a.u. box moves the total energy by 2.8e-06 relative against a matched 17.0 a.u. box,
and `Basics.recommendedGrid` reports that box as set by 2s seeing Z_eff = 3.25, while <r>(2p) = 1.84 a.u. makes 10 a.u. 5.4 mean
radii wide. The test that settles such a case needs THREE boxes rather than two, since the spread between two ADEQUATE boxes is the
scale against which a flagged one must be judged: for that C I branch the two adequate boxes differ by 0.402 % over ten impact
energies while the flagged box differs from the wider of them by 0.309 % and lies BETWEEN them at every energy, which truncation
cannot do. Two further false-positive classes: pseudo-states, which MUST fill their box, and a warning read against the wrong
CONFIGURATION, since the label names an orbital while the damage depends on the configuration it sits in.
+ orbitals ::Dict{Subshell,Orbital} ... the CONVERGED orbitals.
+ grid ::Radial.Grid ... the grid they were computed on.
+ extentTolerance ::Float64 ... largest tolerated rEnd/rbox before the orbital counts as cut off.
+ densityFloor ::Float64 ... fraction of the peak density that defines where an orbital ends.
+ stopper ::Bool ... true, if a truncated orbital shall raise rather than report.JenaAtomicCalculator.Bsplines.checkOrbitalConsistency — Method
Bsplines.checkOrbitalConsistency(orbitals::Dict{Subshell,Orbital}, grid::Radial.Grid; rTolerance::Float64=1.5, eTolerance::Float64=2.0, eInversion::Float64=0.05, stopper::Bool=true) ... checks the generated orbitals for the one failure mode that Bsplines.checkGridRepresentation cannot see: an SCF that has converged onto the WRONG STATE for some symmetry. It compares the two spin-orbit partners of every subshell – same n, same l, kappa of either sign – which must describe the same shell and therefore must be close in both mean radius and binding energy.
WHY THIS IS NEEDED IN ADDITION TO checkGridRepresentation. That function tests hydrogenic orbitals at the FULL nuclear charge, so it
only sees whether the grid can resolve a COMPACT orbital. It passes happily on a grid that cannot represent a diffuse, screened
outer orbital: Ge II [Ar] 3d^10 4s^2 4f on r_max = 614 a.u. returned E(4f_7/2) = -1.5758 with <r> = 5.20 against E(4f_5/2) = -0.0619
with <r> = 10.87 -- a different state entirely -- and produced a Lande factor of -2.264 against the exact 8/7, while the grid check
reported no problem at all.
THE TOLERANCES ARE CALIBRATED, not guessed. Genuine fine structure does separate the partners, and the more so the heavier the ion,
so a tight criterion would fire on correct results. Measured for hydrogen-like ions on matched boxes, |E_1/E_2| and <r>_1/<r>_2 are
Z = 10 2p 1.0013 / 0.9982 3d 1.0003 / 0.9996
Z = 26 2p 1.0092 / 0.9877 3d 1.0020 / 0.9969
Z = 54 2p 1.0426 / 0.9448 3d 1.0088 / 0.9867
Z = 92 2p 1.1540 / 0.8195 3d 1.0268 / 0.9601 4f 1.0097 / 0.9844
i.e. at worst 15% in energy and 18% in radius for a legitimate pair, against a factor 26 in energy and 2.1 in radius for the broken
Ge II case. The defaults of 2.0 and 1.5 sit in that gap with room on both sides.
A NamedTuple is returned, carrying the MEASUREMENT and not merely a verdict -- priority item 40, whose rule is
that a diagnostic hands back a measured quantity with its context so that the CALLER judges rather than the
code: `(ok, nPairs, nOffenders, offenders, worstPair, worstRadiusRatio, worstEnergyRatio, radiusTolerance,
energyInversionTolerance)`. `ok` destructures first and reads as advice, not proof. **The field to judge
on is `worstRadiusRatio` against `radiusTolerance`**, because it says how much margin the check had: a run
that passes at 1.9 against a tolerance of 1.5 is not the same as one that passes at 1.02, and a bare `true`
cannot tell them apart. The worst ratios are accumulated over ALL partner pairs, offending or not.JenaAtomicCalculator.Bsplines.computeNondiagonalD — Method
Bsplines.computeNondiagonalD(pm::Int64, kappa::Int64, bspline1::Bsplines.Bspline, bspline2::Bsplines.Bspline, grid::Radial.Grid) ... computes the (radial and non-diagonal) D_kappa^+/- integral for the two bsplines, all defined on grid, <bspline1| +/- d/dr + kappa/r |bspline2>; pm = +1/-1 provides the phase for taking the derivative.
A single, uniform composite Gauss-Legendre quadrature is applied here, with no special-casing at any grid point, exactly as in
Zatsarinny & Froese Fischer's DBSR_HF reference code (dbsr_lib_dbs.f90's ZINTYM). In particular the first point needs no separate
treatment: every grid.r[i] is already a genuine (nonzero) Gauss-Legendre node and never literally r=0.
A value::Float64 is returned.JenaAtomicCalculator.Bsplines.computeOverlap — Method
Bsplines.computeOverlap(bspline1::Bsplines.Bspline, bspline2::Bsplines.Bspline, grid::Radial.Grid) ... computes the (radial) overlap integral <bspline1|bspline2> for the two bsplines as defined on grid. A value::Float64 is returned.
JenaAtomicCalculator.Bsplines.computeVlocal — Method
Bsplines.computeVlocal(bspline1::Bsplines.Bspline, bspline2::Bsplines.Bspline, pot::Radial.Potential, grid::Radial.Grid) ... computes the (radial) integral <bspline1| V_pot |bspline2> for the two bsplines and the given radial potential as defined on grid. The quadrature is the uniform one described for Bsplines.computeNondiagonalD, with no special treatment of the first grid point. A value::Float64 is returned.
JenaAtomicCalculator.Bsplines.diagonalizeLocalMatrix — Method
Bsplines.diagonalizeLocalMatrix(kappa::Int64, matrixA::Array{Float64,2}, matrixB::Array{Float64,2}, primitives::Bsplines.Primitives) ... enforces the r=0 boundary condition for symmetry kappa (Bsplines.boundaryDropCounts) by eliminating the corresponding leading large- and small-component B-splines from the generalized eigenvalue problem (matrixA, matrixB) before diagonalizing, following Zatsarinny & Froese Fischer's DBSRHF reference code (hfboundary.f90's Boundary_conditions, finite-nucleus branch). Each returned eigenvector is re-embedded into the full (nsL+nsS)-length vector space, with exact zeros at the eliminated positions, so that all downstream code (Bsplines.generateOrbitalFromPrimitives, the bVector-native AL/EOL machinery, etc.) is unaffected in how it reconstructs P(r)/Q(r) – only the NUMBER of returned eigenpairs shrinks by (dropP+dropQ). Callers that pick an eigenpair by index must use Bsplines.findPositiveBranchStart on the returned values, NOT a fixed index counted from nsL/nsS. An eigen::Basics.Eigen is returned.
A NOTE ON COST, for whoever comes back to this (measured 12-Aug-2026). This is a FULL generalized eigendecomposition, but very
little of it is used: the SCF wants a short contiguous block at the bottom of the positive-energy branch --
Bsplines.generateOrbitalFromPrimitives takes ni = mm + n - l - 1 -- which in real bases is ONE TO FOUR eigenvectors out of ~665
(Ne, Ar, Fe and a 3s/3p/3d correlation basis were counted; in all of them the highest wanted state was still bound). About half
the spectrum is the Dirac sea and is discarded outright. Three routes were measured, and they behave quite differently.
(a) ASK FOR FEWER EIGENVECTORS. LinearAlgebra.eigen(A, range) reaches LAPACK's syevr; measured against a full decomposition it
gives 3.3x (n=239), 3.9x (671), 4.1x (1053), 3.5x (2005), 2.8x (4389). The speed-up SATURATES around 3-4x and does not improve
with a denser grid, because the tridiagonal reduction is O(n^3) and unavoidable -- only the back-transformation shrinks. Note
also that a two-stage scheme (all eigenvalues first, then the wanted vectors) cannot pay: eigenvalues alone already cost ~0.7
of the full solve. Any gain must come from ONE range-restricted call.
(b) EXPLOIT THAT THE MATRIX IS BANDED. It is 4.0% non-zero, and its half-bandwidth depends entirely on the ordering: 343 as stored
here (large-component block, then small-component block -- effectively dense), but 15 once the large and small components are
INTERLEAVED. That 15 is set by the spline order and stays 15 however dense the grid, so banded work is O(n b^2) against dense
O(n^3). This is the only route whose advantage GROWS with grid density, which is the case that matters when a fine grid is
needed for physical reasons. Measured with LAPACK's banded routines: eigenVALUES (dsbgv, JOBZ='N') 1.2x at n=400 rising to
7.8x at n=3200, agreeing with the dense solve to 1e-14. But dsbgvx WITH eigenvectors is SLOWER than dense and gets worse with
n (0.6x at 400, 0.1x at 3200), because it accumulates the n x n reduction matrix unblocked -- so the vectors would have to come
from banded INVERSE ITERATION, not from the banded driver. Route (b) is deliberately NOT implemented: LAPACK's banded routines
are not exposed by Julia's LinearAlgebra.LAPACK and would need a raw ccall, which JAC avoids at its present stage. If a
dependency ever becomes acceptable, a banded-matrix package is the safer way in. One trap worth recording because it does not
announce itself: passing Int32 where Julia's ILP64 LAPACK expects BlasInt returns info = 0 with silently WRONG eigenvalues.
(c) RESTRICT THE SOLVE TO AN ENERGY WINDOW. Built and MEASURED on 12-Aug-2026, then WITHDRAWN -- the reasoning is kept here so that
it is not attempted a third time. LAPACK can be asked for an energy window, but only for a STANDARD problem, so the generalized
one is first reduced with the Cholesky factor of the overlap matrix (B = L L', C = L^-1 A L^-T, x = L^-T y). On Ar, order 665:
the full solve 0.050 s against 0.013 s reduction + 0.014 s windowed solve, i.e. 1.7-1.8x, which is worth having since this solve
is 57.5% of a real SCF. Two facts sank it. The window must be the BOUND states to pay at all: taking the whole positive branch
instead (331 of 665 states) costs 0.075 s and is 0.6x, i.e. SLOWER than the full solve, so the gain comes from the smallness of
the bound set and not from skipping the Dirac sea. And DURING the iteration the wanted states are not all bound: with the
screened DFS potential of the starting orbitals, neutral Ne has ONE bound state in kappa = -1 and NONE in kappa = 1 or -2, its
2p sitting at +0.0252 a.u., so a bound window fails on a neutral atom in the very first iteration even though every wanted state
is bound once converged. (An earlier count that suggested otherwise had used the bare NUCLEAR potential, which binds far more
strongly.) An index window is no way out either: see above on why an eigenpair must never be picked by an index counted from
nsL/nsS.JenaAtomicCalculator.Bsplines.diagonalizeLocalMatrixNearEnergy — Method
Bsplines.diagonalizeLocalMatrixNearEnergy(kappa::Int64, matrixA::AbstractMatrix{Float64}, matrixB::AbstractMatrix{Float64}, primitives::Bsplines.Primitives, sigma::Float64, nev::Int64) ... solves the SAME generalized eigenvalue problem as Bsplines.diagonalizeLocalMatrix (same boundary-condition elimination via Bsplines.boundaryDropCounts, same re-embedding of each eigenvector into the full (nsL+nsS)-length space), but returns only the nev eigenpairs CLOSEST to sigma, found by a sparse shift-invert Arnoldi solve rather than a full dense decomposition. matrixA/matrixB are structurally sparse – every entry outside a B-spline pair's compact support is an exact (not merely small) 0.0, because Bsplines.generateTTpMatrix!/Bsplines.generateTTpMatrixSparse! never write to it – so sparse(...) recovers this at no cost to accuracy. matrixA/matrixB MAY be passed in already sparse (Bsplines.setupLocalMatrixSparse's own return type) – sparse(...) on an already-sparse matrix is a cheap copy, not a wasteful round-trip through a dense array – or still dense (Bsplines.setupLocalMatrix's return type, as before); AbstractMatrix{Float64} accepts either with no other code change. The shift-inverted operator x -> (matrixA - sigma*matrixB)^-1 * matrixB * x has its LARGEST-magnitude eigenvalues theta exactly where the ORIGINAL problem has eigenvalues lambda closest to sigma, via lambda = sigma + 1/theta; ArnoldiMethod.partialschur is asked for those directly, so cost scales with nev and the sparse LU's own fill-in, not with the full matrix dimension cubed.
**THIS ASSUMES `matrixA` CARRIES NO NONLOCAL TERM, AND THAT ASSUMPTION IS CHECKED, NOT TRUSTED.**
`Bsplines.setupExchangeMatrix` (the Dirac-Fock exchange, `settings.continuumExchange=true` in
`PhotoIonizationPseudostates.buildPseudostateLadder`) is genuinely NONLOCAL -- its own docstring says so
-- so an exchange-bearing `matrixA` is NOT banded and `sparse(...)` would silently discard real physics
as if it were exact zero. MEASURED on real overlap/local matrices (no exchange): 2.1% and 4.1% nonzero
after sparsification -- a genuinely dense or exchange-bearing matrix sits nowhere near that. This
function therefore checks the nonzero FRACTION after sparsifying and raises, rather than silently
returning a wrong answer, if it exceeds 20% (five times the measured local-matrix figure) -- it does not
try to verify sparsity index-by-index from spline-order theory, which would need to be re-derived for
every block layout; it tests the actual assumption being relied on.
THIS IS A FRESH, SEPARATE ROUTE FROM THE THREE ALREADY MEASURED AND RECORDED IN diagonalizeLocalMatrix'S
OWN DOCSTRING (12-Aug-2026) -- read that note before changing anything here. Route (a), a range-
restricted dense solve, saturates at 3-4x. Route (b), the true banded structure (bandwidth 15 once large/
small components are interleaved), was left unimplemented because Julia's LinearAlgebra.LAPACK exposes
no banded driver and the vector-producing one gets slower, not faster, with n. Route (c), an energy-
windowed LAPACK solve on the Cholesky-reduced standard form, was WITHDRAWN for the SCF bound-state use
case specifically because the wanted window is not reliably known during SCF ITERATION (an unconverged
neutral atom can have zero bound states in a symmetry) -- a trap that does not apply here: this function
is meant for a ONE-SHOT diagonalization in a FIXED external potential (a frozen ion-core mean field) with
the target window already fixed in advance, not for an iterating SCF. Nothing here reopens route (c) for
that other use case.
An eigen::Basics.Eigen is returned, with exactly `nev` entries (fewer only if the sparse solve itself
converges short, which Arnoldi reports rather than silently returning); every eigenvector is
normalized in the B-METRIC (`v' * matrixB * v = 1`), the SAME convention
`Bsplines.diagonalizeLocalMatrix` already returns, NOT the Euclidean norm Arnoldi/`partialeigen`
return natively -- this is corrected before the vector is handed back, not left for the caller to fix.JenaAtomicCalculator.Bsplines.exchangeOnOrbital — Method
Bsplines.exchangeOnOrbital(kappa::Int64, primitives::Bsplines.Primitives, orb::Radial.Orbital, coreOrbitals::Dict{Subshell,Orbital}, occupations::Dict{Subshell,Float64}; factor::Float64=1.0) ... applies the SAME nonlocal exchange operator as Bsplines.setupExchangeMatrix to ONE given function and returns the result projected onto the primitives, SUMi <Bi| (-K) |orb>, in the sign convention and the (nsL+nsS) layout that RandomPhase.inducedSourceVector and RandomPhase.exchangeSourceVector use. A vector::Array{Float64,1} is returned.
**WHY BOTH FORMS EXIST.** The matrix is what a Galerkin left-hand side needs, since there the unknown is a coefficient
vector; this one is what a right-hand side needs, where the function is already known as radial arrays P and Q and no
expansion coefficients are available. They are the same operator, and `setupExchangeMatrix(...) * c` must reproduce this
function whenever c really is orb's coefficient vector -- which is a test, and a sharp one, because the two routes share
only `Bsplines.ykOnGrid`.
**DO NOT OBTAIN c BY FITTING A FUNCTION THAT IS NOT IN THE SPAN.** `Bsplines.fitVectorToPrimitives` recovers a bound
orbital's coefficients to 1e-14, but a PERTURBED orbital reaching the box boundary is a different matter: measured on the
H 1s -> 2p Dalgarno-Lewis solutions in a 120 a.u. box, the fitted vector reproduces the SHAPE of K chi exactly -- the
result stays collinear with phi_a Y^1[phi_a,chi] to 5e-16 -- while carrying only 0.2490 of its NORM, both channels alike.
A shape that survives and a magnitude that does not is exactly what a collinearity test cannot see, so use this function
for a given function and the matrix only where c comes from a diagonalization.
+ kappa ::Int64 ... symmetry block of orb; it is not read off orb, which may carry none.
+ orb ::Radial.Orbital ... the function the operator is applied to; only P and Q are read.
+ coreOrbitals ::Dict{Subshell,Orbital} ... the core orbitals exchange is taken with; all of them are included.
+ occupations ::Dict{Subshell,Float64} ... their occupations, one per subshell of coreOrbitals.
+ factor ::Float64 ... an overall scaling, as in `Bsplines.setupExchangeMatrix`.JenaAtomicCalculator.Bsplines.findPositiveBranchStart — Method
Bsplines.findPositiveBranchStart(values::Array{Float64,1}; mass::Float64=1.0) ... returns the 1-based index of the first (ascending-sorted) eigenvalue above -1.999massc^2, the standard threshold marking the boundary between the unphysical negative-energy continuum ("Dirac sea") branch and the physical positive branch, following Zatsarinny & Froese Fischer's DBSRHF reference code (hfsolveHF.f90's hfeiv). The (n,l) bound state then sits at (this index) + (n-l) - 1 within the SAME values array – robust to however many leading B-splines were eliminated for a given symmetry kappa (Bsplines.boundaryDropCounts/diagonalizeLocalMatrix), unlike a fixed index counted from nsL/nsS. A value::Int64 is returned.
THE THRESHOLD SCALES WITH THE MASS, which is why mass is a keyword here rather than a constant. The negative-energy continuum starts
at -2 m c^2, so a fixed -1.999 c^2 is an electron-only value: a muon 1s level in lead lies near 10 MeV = 3.7e5 Hartree, far BELOW
the
electron threshold of 3.75e4, and every muon bound state of a heavy atom would then be rejected here as a spurious Dirac-sea state
-- silently, since this function returns an index and not an error.
WARNING: the threshold-based separation likewise returns garbage if `values` was diagonalized against a potential with no (or a
much-too-weak) attractive nuclear well -- e.g. a caller that passes only `Basics.computePotential(Basics.DFSField(1.0), grid,
basis)` (the ELECTRONIC mean-field potential alone) without adding `Nuclear.nuclearPotential(nm, grid)` first. Without a real
potential well the Dirac equation has no clean energetic gap between the unphysical Dirac-sea branch and genuine atomic bound
states, so the index returned can lie STILL within (or immediately adjacent to) the spurious negative-continuum branch, with
eigenvalues clustering right at -1.999*c^2 instead of at the expected atomic scale (roughly -1 to -2000 Hartree, not ~-37500 for a
typical ion). That produces orbitals which are numerical garbage rather than "slightly wrong". Always add the nuclear potential to
any potential passed into `Bsplines.generateOrbitals` or into this function.
MEASURED 08-Oct-2026, and the measurement bounds that warning rather than widening it. With a FREE-PARTICLE potential (V = 0,
used as the reference of the average-atom partial-wave sum) the basis carries ONE EXTRA state for each kappa > 0, and from
l = 7-8 upward it sits just above zero energy, so this function returns ITS index as the first physical state and every
subshell of that kappa is then addressed one too low. With a REAL nuclear potential there is NO such state: checked for
kappa = 1 ... 12 against a bare Z = 14 point nucleus in boxes of 3.2 and 30 a.u., and on 40 screened average-atom spectra,
with not one shift in either. So this is NOT a general off-by-one and nothing here needs a guard; it is a property of the
well-less case the paragraph above already warns about.
WHERE A V = 0 SPECTRUM MUST BE USED, the extra state is found by its SPIN-ORBIT PARTNER and needs no tolerance to be chosen:
kappa > 0 and kappa' = -(l+1) share l and therefore very nearly the same radial spectrum, and the partner carries no
artifact, so whichever of the two leading states of kappa agrees with the partner's leading state is the physical one. That
is how `SelfConsistent.averageAtomSpectra` does it.JenaAtomicCalculator.Bsplines.fitVectorToPrimitives — Method
Bsplines.fitVectorToPrimitives(orb::Radial.Orbital, primitives::Bsplines.Primitives, matrixB::Array{Float64,2}) ... projects the (already CLEANED/truncated) tabulated orbital orb onto the B-spline primitives basis via the standard Galerkin/least-squares projection matrixB * p = rhs, rhs[i] = <Bi|orb.P-or-Q>, using the existing grid quadrature. Unlike pulling the RAW diagonalization eigenvector – which reproduces the UNCLEANED tabulated function from BEFORE generateOrbitalFromPrimitives' own truncation-at-mtp and small-value cleanup are applied – this function GUARANTEES the returned coefficient vector is fully self-consistent with orb's OWN (already cleaned) tabulated P, Q arrays, inheriting orb's own well-defined truncation instead of carrying whatever small numerical noise the raw eigenvector's tail coefficients happen to have. This matters wherever B-spline expansion coefficients are themselves summed/weighted directly, rather than only ever used to reconstruct one smooth tabulated function – such sums do not automatically benefit from the cancellation that evaluating a single, already-cleaned tabulated function enjoys. See InteractionStrength.XLCoulombTensor and SelfConsistent.solveAverageLevelField, where using the raw eigenvector instead of this projection was traced to a real, non-negligible SCF discrepancy. The returned vector is explicitly re-normalized so that v'matrixBv = 1 EXACTLY (to floating-point precision), rather than trusting the least-squares fit to land there on its own – Hamiltonian.projectHamiltonian's projection operator (I - S*bb') is only truly idempotent for an exactly S-normalized b; feeding it a vector off by even a small residual leaves the "projection" not quite a projection, which compounds under repeated application across SCF iterations. A vector::Vector{Float64}, of length nsL+nsS, is returned.
JenaAtomicCalculator.Bsplines.generateGalerkinMatrix — Method
Bsplines.generateGalerkinMatrix(sh::Subshell, energy::Float64, pot::Radial.Potential, primitives::Bsplines.Primitives; mass::Float64=1.0, storage::Union{Nothing,Dict{String,Array{Float64,2}}}=nothing) ... generates the Galerkin-A matrix for the given potential and B-spline primitives; a matrix::Array{Float64,2} is returned.
Everything this function builds through `generateTTpMatrix!` -- the two overlap blocks and the two D_kappa blocks -- depends on
the GRID and on kappa alone, and never on the potential or the energy: `computeOverlap` sees only the B-splines and the grid, and
`computeNondiagonalD` adds only kappa. One storage dictionary is therefore valid for every continuum orbital of a whole
computation on one grid, and a caller that builds many of them should create it once and pass it in, exactly as it already does
with `primitives`. The blocks are then built on first use and looked up afterwards. **Omitting the keyword creates a private
dictionary and reproduces the previous behaviour exactly, printed line included.**JenaAtomicCalculator.Bsplines.generateOrbitalFromPrimitives — Method
Bsplines.generateOrbitalFromPrimitives(sh::Subshell, energy::Float64, mtp::Int64, ev::Array{Float64,1}, primitives::Bsplines.Primitives) ... generates the large and small components of a (relativistic) orbital for the subshell sh from the given primitives and the eigenvector ev. A (non-normalized) orbital::Orbital is returned.
JenaAtomicCalculator.Bsplines.generateOrbitalFromPrimitives — Method
Bsplines.generateOrbitalFromPrimitives(sh::Subshell, wc::Basics.Eigen, primitives::Bsplines.Primitives; mass::Float64=1.0) ... generates the large and small components for the subshell sh from the primitives and their eigenvalues & eigenvectors. A (normalized) orbital::Orbital is returned.
JenaAtomicCalculator.Bsplines.generateOrbitalFromVector — Method
Bsplines.generateOrbitalFromVector(sh::Subshell, energy::Float64, vector::Vector{Float64}, primitives::Bsplines.Primitives; canonicalize::Bool=true) ... generates a (normalized, cleaned) tabulated orbital directly from a given B-spline expansion coefficient vector, rather than from an eigenvector INDEXED out of a Basics.Eigen (as Bsplines.generateOrbitalFromPrimitives(sh,wc,primitives) requires). This is needed whenever the vector in hand is not literally an eigenvector of anything – e.g. after SelfConsistent.orthonormalizeSameKappa's Loewdin symmetric orthogonalization, which produces a LINEAR COMBINATION of eigenvectors that is itself not an eigenvector of the original problem. Reproduces generateOrbitalFromPrimitives(sh,wc,primitives)'s own reconstruction exactly (auto-detects mtp from where the density drops below 1e-13, zeros values below 1e-10, fixes the sign convention so the large component starts positive, and renormalizes to unit norm in the grid quadrature) – just without the wc/ni lookup indirection. A (normalized) orbital::Orbital is returned.
JenaAtomicCalculator.Bsplines.generateOrbitals — Method
Bsplines.generateOrbitals(subshells::Array{Subshell,1}, pot::Radial.Potential, nm::Nuclear.Model, primitives::Bsplines.Primitives; printout::Bool=true, mass::Float64=1.0) ... generates all single-electron orbitals from subshell list for the radial potential pot. A set of orbitals::Dict{Subshell, Orbital} is returned.
JenaAtomicCalculator.Bsplines.generateOrbitalsHydrogenic — Method
Bsplines.generateOrbitalsHydrogenic(subshells::Array{Subshell,1}, nm::Nuclear.Model, primitives::Bsplines.Primitives; printout::Bool=true, mass::Float64=1.0) ... generates all single-electron orbitals from subshell list for the nuclear potential as specified by nm. A set of orbitals::Dict{Subshell, Orbital} is returned.
JenaAtomicCalculator.Bsplines.generatePrimitives — Method
Bsplines.generatePrimitives(grid::Radial.Grid) ... generates the breaks, knots and the B-spline primitives of order k, both for the large and small components. The function applies the given grid parameters; no primitive is defined beyond grid[n_max]. The definition of the primitives follows the work of Zatsarinny and Froese Fischer, CPC 202 (2016) 287. A (set of) primitives::Bsplines.Primitives is returned.
The raw, full B-spline count -- including the corner spline that is nonzero at r=0 -- is kept here on purpose. The r=0 boundary
condition is enforced per symmetry kappa instead, with the correct (l- and kappa-sign-dependent) number of leading splines, inside
Bsplines.setupLocalMatrix; see Bsplines.boundaryDropCounts. This follows Zatsarinny & Froese Fischer's DBSR_HF reference code
(hf_boundary.f90's Boundary_conditions, for a finite/non-point nucleus).JenaAtomicCalculator.Bsplines.generateTTpMatrix! — Method
Bsplines.generateTTpMatrix!(TTp::String, kappa::Int64, primitives::Bsplines.Primitives, storage::Dict{String,Array{Float64,2}}) ... returns the TTp block of the (single-electron) Dirac Hamiltonian matrix for an electron with symmetry kappa without any potential. The following TTp strings are allowed: ["LL-overlap", "SS-overlap", "LS-Dkappa^-", "LS-Dkappa^+"].
Two modes are distinguished owing to the values that are available in the storage (Dict).
* The TTp matrix block from the storage is returned, if an entry is known; it is assumed that this matrix
block belong to the given set of primitives.
* The TTp matrix is computed and set to the storage otherwise; from the TTp string, the key string
key = string(kappa) * ":" * TTp is generated an applied in the storage dictionary.
All B-splines are supposed to be defined for the same (radial) grid; a matrix::Array{Float64,2} is returned which is quadratic for
'LL-overlap' and 'SS-overlap' and whose dimension depends on the number of B-splines for the large and small component, otherwise.JenaAtomicCalculator.Bsplines.generateTTpMatrixSparse! — Method
Bsplines.generateTTpMatrixSparse!(TTp::String, kappa::Int64, primitives::Bsplines.Primitives, storage::Dict{String,SparseMatrixCSC{Float64,Int64}}) ... the SAME four blocks as Bsplines.generateTTpMatrix! (same cases, same cache-dictionary pattern, same Bsplines.computeOverlap/Bsplines.computeNondiagonalD calls, UNCHANGED), but built directly as a SparseMatrixCSC via Bsplines.bandedSparseTriplets – no dense (nsL+nsS)-scale array is ever allocated, even transiently. A matrix::SparseMatrixCSC{Float64,Int64} is returned.
JenaAtomicCalculator.Bsplines.gridWindowForSupport — Method
Bsplines.gridWindowForSupport(bl, r::Array{Float64,1}) ... the fix behind Bsplines.generatePrimitives – BSplineKit.support(bl) returns a UnitRange{Int64} of KNOT indices into bl's own parent basis (knots(bl) reaches that knot vector directly, with no need to carry the basis object separately), and a B-spline is EXACTLY zero outside that interval (not merely small – B-spline theory, not an approximation), so it is a guaranteed superset of where bl(r) > 0. can ever hold. searchsortedfirst/searchsortedlast on the already-sorted r then find the matching grid-index window in O(log length(r)), with one point of margin on each side so the subsequent exact bl(r) > 0. test – unchanged, and still the one deciding inclusion – never misses a genuine boundary point; the margin can only cost a few wasted evaluations, never a wrong result. A tuple (irLo::Int64, irHi::Int64) is returned.
JenaAtomicCalculator.Bsplines.setupExchangeMatrix — Method
Bsplines.setupExchangeMatrix(kappa::Int64, primitives::Bsplines.Primitives, coreOrbitals::Dict{Subshell,Orbital}, occupations::Dict{Subshell,Float64}; factor::Float64=1.0) ... sets up the NONLOCAL exchange term of the Dirac-Fock operator for the symmetry block kappa, in the same B-spline basis and with the same (nsL+nsS) x (nsL+nsS) layout as Bsplines.setupLocalMatrix, so that the two simply add:
A = Bsplines.setupLocalMatrix(kappa, primitives, nuclear + direct, storage) + Bsplines.setupExchangeMatrix(kappa, ...)
is a Dirac-Fock matrix where `setupLocalMatrix` alone is a Dirac-Hartree one. A matrix::Array{Float64,2} is returned.
**WHY A MATRIX AND NOT A POTENTIAL.** Exchange maps a function at one radius to an integral over all radii, so no
`Radial.Potential` can carry it: a local V(r) exists only if the kernel is a delta function. In a finite basis, however,
every operator IS a matrix, and this one is exactly representable with nothing approximated. That is why no member of the
`Basics.computePotential` family can be a Dirac-Fock field, and why `Basics.ALField` -- which IS a Dirac-Fock SCF -- has no
`computePotential` method: it carries exchange as a matrix instead, through `SelfConsistent.computeFockMatrix`.
**WHAT THIS ADDS BESIDE THAT, SINCE JAC ALREADY HAD MATRIX EXCHANGE AND A CLAIM TO THE CONTRARY WOULD BE WRONG.**
`InteractionStrength.XL_Coulomb(L, a::Subshell, b::Orbital, c::Orbital, d::Subshell, primitives)` already builds the
radial exchange matrix for an arbitrary symmetry, and the two AGREE: measured 21-Oct-2026 on Ne for the two cases where
exactly one rank contributes, ||X - r W||/||X|| is 6.5e-08 (s_1/2, k = 0) and 1.3e-08 (p_3/2, k = 1), with the LL and SS
blocks matching to 4.1e-13 and 1.8e-15 and the whole residual sitting in the cross blocks at that quadrature's own
tolerance. Two independent methods -- `Bsplines.ykOnGrid`'s cumulative sweeps against per-call adaptive quadrature -- so
this is a check and not a reimplementation of a convention. What is new is (1) the FOCK ASSEMBLY: summed over core
subshells AND ranks with the occupations and the (2j+1) denominators, ready to add to `setupLocalMatrix`, where
`XL_Coulomb` returns one (b,k) term and leaves the Fock coefficient to the caller's `coeffs2p` -- which exists only for
OCCUPIED subshells, so a perturbed, virtual or continuum channel has none; and (2) the cost, 0.28 s for Ne's whole
four-subshell core against 5.6 CPU-minutes for two single-rank `XL_Coulomb` matrices on an idle machine. The AL line's own
fast path is `InteractionStrength.XL_CoulombTensor` with caches built once per rank, which is a different trade-off and is
not what that factor compares against.
**THE OPERATOR.** With w_b the occupation of core subshell b and rho_ub = P_u P_b + Q_u Q_b the transition density,
(K u)(r) = SUM_b SUM_k w_b <kappa||C^k||b>^2 / ((2j+1)(2j_b+1)) [ Y^k(rho_ub; r) / r ] phi_b(r) ,
both components of phi_b being multiplied by the SAME kernel and the same coefficient -- the parity rule l_a+k+l_b even
holds for the small components too, since each l shifts by one. The coefficient is the one in JAC's own closed-form
average energy (`BasicsAZ.meanEnergyInClosedForm`, where it multiplies G^k(ab)), obtained from it by variation; that energy
has been measured against the exact (2J+1)-weighted trace to 1.6e-09 over nine configurations, so the coefficient needs
no outside reference. Contracting this operator with phi_a returns SUM_b w_b SUM_k Lambda_k G^k(ab), which is the check.
**THE RETURNED MATRIX IS -K, THE TERM AS IT ENTERS THE HAMILTONIAN**, so it is ADDED and never subtracted, and it is
NEGATIVE semi-definite: <u|K|u> is the Coulomb self-energy of rho_ub, positive for every b and k. Both of those are
cheap tests that can fail, and so is its symmetry -- unlike `setupLocalMatrix`, which is not symmetric.
**IT IS THE CROSS-SUBSHELL TERM, AND THE CALLER MUST EXCLUDE THE ORBITAL'S OWN SUBSHELL.** Where the function being acted
on IS one of the core orbitals, that subshell contributes no nonlocal term at all: varying the a^w energy gives
(w_a-1)[Y^0(aa)/r - SUM_(k>=2) mu_k Y^k(aa)/r], which is LOCAL and belongs with the direct potential, together with the
(w_a-1) that removes the self-interaction. Passing such a subshell here would double-count it in the wrong form. For a
virtual, continuum or perturbed function -- the Dalgarno-Lewis and random-phase cases -- the question never arises.
+ kappa ::Int64 ... symmetry block of the function the operator acts on.
+ coreOrbitals ::Dict{Subshell,Orbital} ... the core orbitals that exchange is taken with; all of them are included.
+ occupations ::Dict{Subshell,Float64} ... their occupations, one per subshell of coreOrbitals.
+ factor ::Float64 ... an overall scaling, for calibrating or switching the term off; 1.0 is
Dirac-Fock and 0.0 reproduces `setupLocalMatrix` alone.JenaAtomicCalculator.Bsplines.setupLocalMatrix — Method
Bsplines.setupLocalMatrix(kappa::Int64, primitives::Bsplines.Primitives, pot::Radial.Potential, storage::Dict{String,Array{Float64,2}}; mass::Float64=1.0) ... sets up the local parts of the generalized eigenvalue problem for the symmetry block kappa and the given (local) potential pot. The B-spline (basis) functions are defined by primitives.bsplinesL for the large component and by primitives.bsplinesS for the small one, respectively. A matrix::Array{Float64,2} of dimension (nsL+nsS) x (nsL+nsS) is returned.
THE MATRIX IS FILLED ELEMENTWISE, AND DELIBERATELY SO -- it is not to be rewritten back into slice expressions. This function runs
once per kappa per SCF iteration, and the slice form allocated 13.9 MB on every call: a SECOND full (nsL+nsS)^2 matrix for the
overlap, of which only the SS block was ever read, plus a temporary for each side of every slice expression in steps (3) and (4).
In isolation such a call looks cheap, 0.0029 s; a hundred calls in a row average 0.0146 s each, the difference being garbage
collection of about 1 GB per SCF. Only the returned matrix is allocated now, and every step writes into it elementwise in the same
order and with the same arithmetic, so the result is bitwise what the slice expressions produced.JenaAtomicCalculator.Bsplines.setupLocalMatrixSparse — Method
Bsplines.setupLocalMatrixSparse(kappa::Int64, primitives::Bsplines.Primitives, pot::Radial.Potential, storage::Dict{String,SparseMatrixCSC{Float64,Int64}}; mass::Float64=1.0) ... the SAME four steps as Bsplines.setupLocalMatrix (same Bsplines.generateTTpMatrixSparse! fetches, same rest-mass subtraction on the SS block, same Bsplines.computeVlocal potential terms via Bsplines.bandedSparseTriplets – UNCHANGED physics), but every block stays sparse throughout: no dense (nsL+nsS) x (nsL+nsS) array is ever allocated, even transiently, which is the whole point – that allocation is what made a box matched to a resonance's own width (rbox~17000 for He's 2s2p, measured 472 GB dense) impossible regardless of how the eigenproblem itself was then solved. The four blocks are assembled with ONE sparse concatenation ([A B; C D], which SparseArrays keeps sparse, not Base's dense fallback). Exchange is deliberately NOT supported here – Bsplines.setupExchangeMatrix is genuinely nonlocal (its own docstring), so it stays on the existing dense Bsplines.setupLocalMatrix+Bsplines.setupExchangeMatrix path; nothing here accepts it. A matrix::SparseMatrixCSC{Float64,Int64} of dimension (nsL+nsS) x (nsL+nsS) is returned.
JenaAtomicCalculator.Bsplines.ykOnGrid — Method
Bsplines.ykOnGrid(k::Int64, rho::Array{Float64,1}, lower::Int64, upper::Int64, mtp::Int64, grid::Radial.Grid) ... computes the Coulomb kernel Yab^k(r)/r on EVERY grid point r[1:mtp] at once, for a density rho that is nonzero only on rho[lower:upper]. It is the vector-valued counterpart of `RadialIntegrals.Ykab, which returns the same quantity at ONE radius; that function costs O(mtp) per radius, hence O(mtp^2) for a whole matrix column, and it is exactly what made a B-spline representation of a NONLOCAL operator look unaffordable -- cf. the cost note inRandomPhase.gmres`, which declined to assemble such a matrix for this reason. Splitting the kernel at r_m,
Y^k(r_m)/r_m = r_m^(-k-1) SUM_(i<=m) rho_i w_i r_i^k + r_m^k SUM_(i>m) rho_i w_i r_i^(-k-1)
turns it into one forward and one backward partial sum and so into O(mtp) for the whole column. Below the support of rho
only the second sum survives and above it only the first, so the kernel is there an exact power of r and is written as
such rather than swept. A values::Array{Float64,1} of length mtp is returned.Bi-orthogonal transformation
JenaAtomicCalculator.BiOrthogonal.AbstractTransformKind — Type
BiOrthogonal.AbstractTransformKind ... the trait a computeTransformation call carries, naming which caller-side assumption it is resolving. Before 04-Nov-2026 this distinction lived only in five independently-worded calcBiorthogonal settings docstrings (PhotoEmission, PhotoExcitation, GeneralizedOscillatorStrength, AutoIonization, PhotoIonization), which is how PhotoIonization's own flag went dead – documented at length, never actually wired to a call. Tagging the mode in the type system makes a mismatched caller raise a MethodError naming both types instead of silently computing the wrong number. The trait picks an ENTRY POINT only: no numerical kernel in this module (appendixB, computeTransformationMatrices, generateCounterRotatingCiMatrices) dispatches on it, and none should – see the module's own commit history on why duplicating a kernel, rather than an entry point, is how this module's worst bug (the unpivoted-LU norm defect) went unnoticed for months.
JenaAtomicCalculator.BiOrthogonal.BoundStatePair — Type
BiOrthogonal.BoundStatePair <: BiOrthogonal.AbstractTransformKind ... two bound multiplets of EQUAL electron count, each independently SCF-optimized – the validated mode used by PhotoEmission, PhotoExcitation and GeneralizedOscillatorStrength.
JenaAtomicCalculator.BiOrthogonal.ContinuumJunction — Type
BiOrthogonal.ContinuumJunction <: BiOrthogonal.AbstractTransformKind ... an N-electron multiplet against an (N-1)-electron ionic one. The transform covers the bound spectator orbitals shared by the two sides only; the continuum orbital itself is generated afterward, per line, directly in the field of the (possibly now bi-orthogonally-transformed) ionic core, and is never itself passed through this module. Used by AutoIonization and PhotoIonization.
JenaAtomicCalculator.BiOrthogonal.ShapeCrossingJunction — Type
BiOrthogonal.ShapeCrossingJunction <: BiOrthogonal.AbstractTransformKind ... two CSF spaces of EQUAL electron count, built from orbital sets that coincide everywhere except in however many kappa blocks carry a reshaped (Basics.OrbitalShape) orbital – a second-order P/Q junction between an SCFShape and a CoreValenceCorrelationShape realization of the same label.
JenaAtomicCalculator.BiOrthogonal.alignOrbitalSigns — Method
BiOrthogonal.alignOrbitalSigns(leftBasis::Basis, rightBasis::Basis, grid::Radial.Grid) ... makes every right orbital agree in OVERALL SIGN with its left partner of the same subshell, which the biorthogonalisation below requires and which no sign convention can guarantee on its own. A tuple tpl(newRightBasis::Basis, phases::Array{Float64,1}, flipped::Array{Subshell,1}) is returned: the basis with the offending orbitals negated, the per-CSF phase that negation implies, and the subshells that were flipped. Nothing is changed when every overlap is already positive, and the phases are then all +1.
WHY IT IS NEEDED, and it is a property of the METHOD rather than a defect of the orbitals.
`BiOrthogonal.appendixB` factorises the overlap T = L U with NO pivoting, so `Cleft = inv(L)'` is UNIT
upper triangular -- every eigenvalue 1, its logarithm always real -- while `C11 = inv(U)` has eigenvalues
1/u_ii. **One negative pivot therefore makes one eigenvalue of Cright negative, and a real matrix with a
negative eigenvalue has no real logarithm**: `log(C)` returns a complex matrix, every entry of it becomes
complex, and the first nonzero one assigned into a `Dict{...,Float64}` threw an `InexactError` naming
neither the module nor the cause, three call levels below what the user invoked. Verified in isolation:
a near-identity overlap gives pivots +0.90 +1.07 +1.03 +0.86 and a REAL log, and negating one orbital
gives +0.90 +1.07 -1.03 +0.86 and a COMPLEX one whose largest imaginary part is exactly pi.
AND THE CURE IS A GAUGE CHOICE, NOT AN APPROXIMATION. An orbital's overall sign is arbitrary; negating
phi multiplies a CSF by (-1)^n, with n that orbital's occupation in the CSF, because the CSF is built from
n copies of it. Applying that phase to the CI coefficients alongside the negation leaves every
expectation value and every transition amplitude unchanged, and it makes the transformation a proper
rotation, which is what having a real generator means.
A SOUND SIGN CONVENTION UPSTREAM DOES NOT REMOVE THE CASE, which is worth saying because it was the
suspicion this item carried. `Bsplines.canonicalSign` already fixes each orbital by the sign of its
LARGEST B-spline coefficient -- a robust rule, and a real improvement on the `sum(P[1:30])` test it
replaced. But it canonicalises each basis SEPARATELY, and two independently optimised RAS bases hold
genuinely DIFFERENT radial functions under the same label; their overlap may be negative however each
one was canonicalised. The alignment has to be made between the two bases, which is here.JenaAtomicCalculator.BiOrthogonal.appendixB — Method
BiOrthogonal.appendixB(S::Matrix{Float64}) ... solves the differing-dimension biorthonormalisation of Appendix B of Olsen, Godefroid, Jönsson, Malmqvist & Froese Fischer, Phys. Rev. E 52, 4499 (1995), for an overlap matrix S of size n x m with m >= n. Writing S = (T Z) with T square of order n, the returned pair (Cleft, Cright) – of orders n and m – satisfies Cleft' * S * Cright = (I 0) exactly, I being the unit matrix of order n. The square problem on T is solved by a SYMMETRIC (Loewdin) split of its singular-value decomposition, and Eq. (B6) then reduces to C12 = -C11 * (Cleft' * Z), since Eq. (B4) already identifies Cleft' * T as inv(C11) – which holds for this split exactly as it does for a triangular one. A tuple tpl(Cleft::Matrix{Float64}, Cright::Matrix{Float64}) is returned.
WHY NOT THE UNPIVOTED LU THIS USED UNTIL 01-Nov-2026, and the measurement that settled it. The condition
Cleft' * S * Cright = (I 0) does not fix the pair; an LU split gives Cleft = inv(L)', which is unit
triangular and so leaves every orbital NORM untouched, while Cright = inv(U) carries the WHOLE scaling.
The two sides are then treated unequally, and for T a pure ROTATION the right-hand orbitals come back
with norms 1/cos(theta) although a rotation can change no norm at all. The symmetric split has
Sigma = I for a rotation, so BOTH factors are orthogonal and BOTH sets of norms are preserved exactly.
THAT WAS NOT COSMETIC. `BiOrthogonal.computeTransformation` returns correctly biorthogonal but
UNNORMALISED orbitals -- it must, since biorthogonality excludes normalisation -- and the N-vs-(N-1)
consumers (`AutoIonization`, `PhotoIonization` with calcBiorthogonal = true) then rebuild a MEAN FIELD
from the transformed ionic core in order to generate the continuum orbital. Measured on Mg, Z = 12,
initial [Ne] 3p^2 + [Ne] 3s^2 against final [Ne] 3s, with 1s and 2s mixed by theta = 0.37 -- a pure
relabelling of a uniformly closed pair, with provably ZERO physical consequence: under the LU split that
core's density carried 11.300876 electrons instead of 11, its DFS screening shifted by ~0.3 charge units
at every radius, and the Auger rate of a line that is BIT-IDENTICALLY invariant without the
transformation moved by +84.7 %. The error scales as theta^2, i.e. with the NORM defect
1/cos(theta) - 1, and not as theta, the orbital mixing -- which is what identified the cause. The
same-N consumers (`PhotoEmission`, `PhotoExcitation`, `GeneralizedOscillatorStrength`) never rebuild a
mean field, which is why they validated while this did not. See `tools/probeBiorthogonalNormDefect.jl`
and `TestFrames.testModule_BiOrthogonalRotation`.JenaAtomicCalculator.BiOrthogonal.checkClosureUnderDeexcitation — Method
BiOrthogonal.checkClosureUnderDeexcitation(basis::Basis) ... checks whether the CSF list of basis is closed under de-excitation (Olsen, Godefroid, Jönsson, Malmqvist & Froese Fischer, Phys. Rev. E 52, 4499 (1995)): for every CSF and every occupied subshell nl with n > n', if the (lower) subshell n'l is also present in basis.subshells and is not already fully occupied in that CSF, then moving one electron from nl to n'l (all other occupations unchanged) must produce the occupation pattern of some CSF already in basis.csfs. This is checked at the level of occupation-number patterns only (not the full recoupling of seniority/subshellJ/subshellX), which is a necessary but not by itself sufficient condition for closure – for the RAS/CAS-type configuration lists this transformation is intended for, an occupation-pattern match is expected to reflect true closure in practice. A Array{String,1} of human-readable violation descriptions is returned (empty if closed).
JenaAtomicCalculator.BiOrthogonal.computeTransformation — Method
BiOrthogonal.computeTransformation(kind::AbstractTransformKind, leftMp::Multiplet, rightMp::Multiplet, grid::Radial.Grid) ... computes the bi-orthogonal transformation of the two given multiplets by rotating the radial functions and by counter-rotating the corresponding CI coefficients. leftMp and rightMp must have the same number of electrons and be generated on the same radial grid; grid must be passed explicitly (an orbital's own .grid field is only a placeholder whenever useStandardGrid == true, which is the normal case). kind names which caller-side assumption this call resolves (BoundStatePair, ContinuumJunction or ShapeCrossingJunction) and is not otherwise used inside this function – it documents the call and lets a wrong pairing raise a MethodError naming both types, rather than silently returning a number. A warning (not an error) is issued if either multiplet's CSF list is not closed under de-excitation (see checkClosureUnderDeexcitation), in which case the transformation is only approximate. A tuple of two multiplets tpl(newLeftMp::Multiplet, newRightMp::Multiplet) is returned: same levels (J, parity, index, energy, relativeOcc) as the input, but each with a new, shared, biorthonormal Basis and a counter-rotated mc vector.
JenaAtomicCalculator.BiOrthogonal.computeTransformationMatrices — Method
BiOrthogonal.computeTransformationMatrices(leftBasis::Basis, rightBasis::Basis, grid::Radial.Grid) ... computes, for every kappa symmetry present in leftBasis or rightBasis, the pair of upper-triangular orbital transformation matrices (Cleft, Cright) that bring the (in general non-orthogonal) orbital sets of leftBasis and rightBasis into biorthonormal form, following Olsen, Godefroid, Jönsson, Malmqvist & Froese Fischer, Phys. Rev. E 52, 4499 (1995): for a fixed orbital ordering (here, by increasing principal quantum number n within a kappa symmetry), requiring the transformation matrices to be upper triangular reduces their determination to a triangular (LU) factorization of the overlap matrix Sij = <phii^left|phi_j^right>. With S = L*U (L unit-lower-triangular, U upper-triangular, no pivoting so the chosen n-ordering is preserved), Cleft = inv(L)' and Cright = inv(U) satisfy Cleft' * S * Cright = I exactly.
THE DIFFERING-DIMENSION CASE IS SUPPORTED (Appendix B of the same paper, added 04-Sep-2026). Nothing in
the biorthonormality condition requires the two sides to carry the same number of orbitals for a given
kappa. With n orbitals on the smaller side and m > n on the larger, the n x m overlap matrix splits as
S = (T Z) with T square of order n, and Cleft' * S * Cright = (I 0) is met by the ansatz
Cright = [C11 C12; 0 I]. Eqs. (B4) and (B6) then give Cleft' * T * C11 = I -- which is exactly the
square problem already solved above, on T -- and C12 = -(Cleft' * T)^(-1) * Cleft' * Z. Since (B4)
identifies Cleft' * T as inv(C11), the inverse is already in hand and C12 = -C11 * (Cleft' * Z); no
second factorisation is needed. Either side may be the larger, the two cases being related by
transposition. BOTH RETURNED MATRICES REMAIN SQUARE -- of order n_left and n_right -- so everything
downstream, which only forms linear combinations within one side, is unaffected.
A Dict{Int64, Tuple{Array{Subshell,1},
Array{Subshell,1}, Matrix{Float64}, Matrix{Float64}}}, keyed by kappa and giving the (ordered)
subshell lists together with (Cleft, Cright) for that symmetry block, is returned. THE ORDERING KEY IS
`(n, shape)`, not `n` alone (fixed 04-Nov-2026): two subshells sharing both `n` and `kappa` but differing
in `Basics.OrbitalShape` -- an `SCFShape` and a `CoreValenceCorrelationShape` realization of the same
label -- are a real, supported case since the shape-aware `Subshell` extension, and `sort` is not
guaranteed stable across such a tie without a second key.
A KAPPA PRESENT ON ONLY ONE SIDE IS NOW ITS OWN CASE, not skipped (fixed 04-Nov-2026, found by the
shape-crossing CI junction's own first real-data test: P's deeper layer can add a kappa -- there,
4f_5/2 and 4f_7/2 -- that Q's own excitation space never touches at all). There is then nothing to
biorthogonalize against on the empty side, so that side's transform is the IDENTITY and the other
side's is the (empty, 0x0) matrix of a side with no orbitals for this kappa: a kappa absent from BOTH
sides is still skipped, since there is then nothing to return for it either. Skipping the one-sided
case outright -- the previous behaviour -- silently dropped the untouched side's own subshells from
the dictionaries `generateBiorthogonalShellMatrices` returns, which is what produced a `KeyError` two
functions downstream rather than a correct, unchanged orbital.JenaAtomicCalculator.BiOrthogonal.generateBiorthogonalShellMatrices — Method
BiOrthogonal.generateBiorthogonalShellMatrices(leftBasis::Basis, rightBasis::Basis, grid::Radial.Grid) ... generates the biorthogonal forms of the orbitals of leftBasis and rightBasis, by applying the transformation matrices from computeTransformationMatrices to the radial functions (P, Q, Pprime, Qprime) of every orbital, kappa symmetry by kappa symmetry. Since orbitals of different length (different last tabulated grid point) can occur for the same kappa, each is zero-padded up to the longest orbital of its own side before the linear combination is formed. A tuple tpl(newLeftOrbitals::Dict{Subshell,Orbital}, newRightOrbitals::Dict{Subshell,Orbital}) is returned, with the SAME subshell keys as the original bases – only the radial functions have changed. A kappa present on only one side (fixed 04-Nov-2026, see computeTransformationMatrices) passes that side through with its orbitals exactly unchanged, since its transform there is the identity.
JenaAtomicCalculator.BiOrthogonal.generateCounterRotatingCiMatrices — Method
BiOrthogonal.generateCounterRotatingCiMatrices(basis::Basis, transformation::Dict, side::Symbol) ... generates the nCSF x nCSF matrix M that counter-rotates the CI (mixing-coefficient) vectors of basis's levels to compensate for the orbital transformation encoded in transformation (the output of computeTransformationMatrices); side is either :left or :right, selecting the (Cleft) or (Cright) half of the transformation and the correspondingly-ordered subshell list for that side. A general (not necessarily unitary) one-electron transformation newcreatork = suml Clk * oldcreatorl is implemented via the many-electron operator built from its matrix logarithm (a standard result: the generator of a one-body basis change is the one-body operator with the SAME matrix, in the log; holds for any invertible C, not only orthogonal/unitary ones). Concretely: (i) per kappa symmetry, factor G = log(C) (upper triangular, since C is upper triangular with nonzero diagonal); (ii) build the one-electron operator matrix Ghat over the full CSF list using the SAME reduced one-body coupling coefficients JAC already uses for one-body Hamiltonian terms (SpinAngular.computeCoefficients(OneParticleOperator(0,plus), csfR, csfS, subshells), weighted by Gab instead of a radial integral). The coefficient is used BARE: since 27-Aug-2026 the rank-0 coefficient carries sqrt(2 ja + 1) itself, so no factor belongs at the call site. A one-particle toy-model check (N=1, two orbitals) shows the OLD and NEW expansion coefficients are related by cold = C * cnew (not cnew = C * cold) – i.e. the CI vector transforms with the INVERSE of the orbital transformation – so (iii) M = exp(-Ghat) is returned. The transformed CI vector for a level is mcnew = M * mcold (same CSF ordering, only the coefficients change).
Electron continuum
JenaAtomicCalculator.Continuum.Settings — Type
struct Continuum.Settings ... defines a type for the parameters for computing continuum orbitals.
+ includeExchange ::Bool ... True, if the exchange with the bound electrons of the level is to be included,
false otherwise. SEE THE NOTE BELOW: `true` is honoured in exactly ONE place.
+ mtp ::Int64 ... No of grid points for which the continuum orbital(s) are to be computed.
DELIBERATELY POSITIONAL, AND DELIBERATELY OUTSIDE THE `Settings` CONVENTION -- decided 28-Aug-2026. Every other
`Settings` in the package carries a zero-argument constructor and a keyword copy-constructor, because every other one is
something a USER assembles and then varies. This one is not: it is an internal argument-holder that a process module
fills in on its way to `Continuum.generateOrbitalForLevel`, and it is built positionally at all 27 sites that construct it in
`src/` and `examples/` -- 20 of them the identical `Continuum.Settings(false, nrContinuum)`. Adding the convention here
would give a user a constructor for a struct they have no decision to make about. Do not "fix" this; it is the decision.
**`includeExchange = true` IS NOW REAL, AS OF 29-Oct-2026 (item 99), BUT ONLY UNDER `Continuum.generateOrbitalForLevel`
WITH THE GALERKIN SOLUTION METHOD** (`setDefaults("method: continuum, Galerkin")`). There it adds
`Bsplines.setupExchangeMatrix` -- the frozen nonlocal Dirac-Fock exchange operator built for item 75/S30, validated to
1.1e-16 against the whole-atom exchange energy -- against every occupied subshell of `level.basis`, with occupations from
`Basics.extractMeanOccupation(level.basis)`. **No iteration is needed**: with the core frozen, the exchange operator is
LINEAR in the unknown continuum orbital, so it simply adds to the Galerkin matrix that is already being solved once; this
is the same one-shot assembly a frozen-core bound Fock matrix uses, not a new convergence loop. Under any OTHER solution
method (`ContBessel`, `ContSine`, `AsymptoticCoulomb`, `NonrelativisticCoulomb`) `generateOrbitalForLevel` RAISES rather
than silently ignoring the flag -- those integrate directly against a local potential function and have no place to put a
nonlocal term without a genuine fixed-point iteration, which does not exist here (see the module docstring). And
`generateOrbitalLocalPotential` still raises on `true` unconditionally, for a different reason: it is handed a bare
`pot::Radial.Potential` with no `level` at all, so it has no bound orbitals to exchange with, Galerkin or not. All 27
EXISTING construction sites pass `false` and are completely unaffected; the field remains the way a caller OPTS IN.JenaAtomicCalculator.Continuum.asymptoticAmplitude — Method
Continuum.asymptoticAmplitude(P::Array{Float64,1}, grid::Radial.Grid, mtp::Int64, energy::Float64, Zbar::Float64) ... to determine the asymptotic amplitude and phase of a continuum orbital's large component by FITTING it to its known asymptotic form over the outer third of the mesh, instead of reading a maximum off it. Asymptotically P(r) --> A sin(theta(r) + delta) with theta(r) = q*r + y*ln(2*q*r), where q is the relativistic wavenumber and y the Coulomb parameter formed from the residual charge Zbar that the outgoing electron still feels; every CONSTANT phase – centrifugal, Coulomb gamma-function, relativistic – is absorbed into delta and so need not be known here. Writing the form as P = a*sin(theta) + b*cos(theta) makes the extraction a two-parameter LINEAR least squares, solved below through its 2x2 normal equations. A named tuple (A, delta, residual, nFitted) is returned.
Why a fit and not a window. Reading a maximum requires a crest inside the window, loses up to (q*hp)^2/8 to discrete
sampling, and must fail once half a wavelength exceeds the box, however the window is sized; the fit requires no crest,
has no node to divide by, averages the discretization away and carries the logarithmic Coulomb phase exactly. Measured
03-Nov-2026 against `Continuum.generateOrbitalPureSine`, whose amplitude is `sqrt(2/(pi*q))` in closed form, the fit is
exact to five or six digits from 68 eV down to 0.054 eV, whereas a fixed 300-point window returned 0.4462 of the true
amplitude at 0.136 eV -- a normalization 2.24 times too large -- while being exact at 0.272 eV. That the error is
ERRATIC rather than monotone in the energy is the signature of the defect, and is why it survived so long.
`residual` is the rms misfit as a FRACTION of the amplitude, so it is free of the arbitrary scale that the Galerkin
eigenvector carries. It measures whether the orbital has actually reached the form that was fitted: measured on He+ it
falls from 7.0e-2 at 1.449 eV to 1.5e-3 at 120 eV, and fitting the same Coulomb wave with a FREE phase model (Zbar = 0)
raises it by a factor of 5 to 20 at every energy while biasing the amplitude by up to 14 %. It is therefore the
scale-free quantity on which a refusal should rest.JenaAtomicCalculator.Continuum.asymptoticCharge — Method
Continuum.asymptoticCharge(Zbar::Float64) ... the residual charge that the ASYMPTOTIC FORM of the computed orbital actually carries, which is not always the charge in the potential: a FREE-wave solution method produces an orbital with no logarithmic Coulomb phase at all, whatever the potential says. Zbar is returned unchanged for the solution methods that solve in the potential, and 0.0 for those that do not, so that Continuum.asymptoticAmplitude is handed the form the orbital really has. A Float64 is returned.
MEASURED 03-Nov-2026 on one He+ orbital at 16.7 eV, as the fit residual with and without the logarithmic term:
solution method with Zbar with 0
ContBessel 7.83e-02 2.49e-05
ContSine 7.83e-02 2.49e-05
AsymptoticCoulomb 6.96e-16 7.85e-02
-- so each solver is described by exactly one of the two forms, and `AsymptoticCoulomb` is fitted to MACHINE PRECISION
by the right one. Taking the phase model from the potential alone is therefore wrong for two of the five methods, and
the error does not announce itself: it appears as a residual a hundred times too large on a perfectly sound orbital.JenaAtomicCalculator.Continuum.asymptoticFitReport — Method
Continuum.asymptoticFitReport(residual::Float64, required::Float64, fatal::Float64, cOrbital::Orbital) ... formats the measurement behind the residual tier of Continuum.reportContinuumAmplitude into the explanatory block that both its warning and its refusal print, so that the two cannot drift apart; a report::String is returned.
JenaAtomicCalculator.Continuum.checkContinuumAmplitude — Method
Continuum.checkContinuumAmplitude(P::Array{Float64,1}, energy::Float64, grid::Radial.Grid) ... checks that a NORMALIZED continuum orbital's large component does not blow up in the interior relative to its own asymptotic amplitude, which is how a radial mesh too coarse for the requested energy makes itself visible in the orbital it produced rather than in the grid it was produced on. A NamedTuple (ok, checked, interior, asymptotic, ratio, required, rIndex, note) is returned; nothing is raised here, so that the CALLER judges – the same contract as checkNormalizationRadius below.
WHY A POSTERIOR CHECK IS NEEDED AT ALL, when three guards already look at the grid. `gridConsistency` compares
`grid.hp` with the shortest de Broglie wavelength and requires 15 points across it; `checkNormalizationRadius` asks
whether the normalization point lies outside the atom; `Bsplines.checkGridRepresentation` and `checkOrbitalBox` test
BOUND orbitals. **ALL THREE ARE A PRIORI** -- they judge the mesh against the energy, before any orbital exists -- and
a mesh can satisfy every one of them and still fail. Measured 22-Oct-2026 on the 3.583e+04 Hartree electron of the
207Pb K-shell internal-conversion case, Z = 82, kappa = -4, where BOTH meshes below pass `gridConsistency`:
points per oscillation 15.65 46.94
max|P| anywhere 2.03e+08 6.59e-02
max|P| asymptotically 6.12e-02 5.77e-02
RATIO 3.32e+09 1.14
The 15.65 mesh is the one `example-Dq.jl` used, and the orbital it returns is wrong by ~4e+09 in amplitude and ~1e+19 in
amplitude SQUARED while every a-priori guard is satisfied. The spike sits at r = 6e-05 a.u., i.e. in the innermost
region, where a continuum orbital goes as r^gamma and must therefore be SMALL -- which is what makes the ratio a sharp
instrument rather than a heuristic.
THE THRESHOLD IS MEASURED, AND THE RATIO IS CONVENTION-INDEPENDENT. Over 144 cases spanning Z = 2, 18, 54, 92,
energies 0.01 to 50 Hartree and kappa from -1 to 8 -- including near-threshold and high centrifugal barriers, the two
regimes where a legitimately large interior amplitude might be expected -- the WORST ratio was 1.269, while the failing
cases give 3.3e+09 and 2.3e+10. So `required = 1.0e3` sits three orders above anything legitimate yet measured and six
orders below the defect. And because the ratio divides one amplitude by another, the normalization CONSTANT cancels:
the same good case gives 1.141 under all four of `PureSineNorm`, `CoulombSineNorm`, `OngRussekNorm` and `CoulombFunctionNorm`, so
one threshold serves every convention and the check cannot be evaded by changing the global.
NOT CHECKED IS NOT PASSED, and `checked` is the field that keeps the two apart. A grid with fewer than 400 points has
no asymptotic region to measure against, and an identically vanishing asymptotic amplitude leaves the ratio undefined;
both return `ok = true` because nothing failed, and a caller reading only `ok` would take either for a clean bill of
health.JenaAtomicCalculator.Continuum.checkMatchingRadius — Method
Continuum.checkMatchingRadius(cOrbital::Orbital, pot::Radial.Potential, l::Int64, Zbar::Float64, mtp::Int64; warn::Float64=CONT_MATCH_WARN, fatal::Float64=CONT_MATCH_FATAL, warnN::Float64=CONT_SCALE_WARN, fatalN::Float64=CONT_SCALE_FATAL, meshSound::Float64=CONT_MESH_SOUND)
... asks whether the ONE radius at which `normalizeOrbitalCoulombFunctions` matches the orbital was a fair place to
do it, and moves it if not. TWO quantities are extracted by `Continuum.matchAtRadius` over the outer two
wavelengths and BOTH must be constant there, because each is blind to what the other catches:
* the INNER PHASE SHIFT, a constant of the solution wherever the potential has reached its `-Zbar/r` tail. Its
spread catches an orbital whose `P` and `Pprime` are mutually inconsistent, i.e. one that does not satisfy the
equation it is supposed to;
* the NORMALIZATION CONSTANT itself, whose RELATIVE spread catches a distorted SHAPE. This second measure is
necessary rather than decorative: the phase is the ANGLE of a complex number built from `P` and `Pprime`, so
scaling both by the same factor leaves it EXACTLY unchanged. Measured 05-Nov-2026 -- a 30 % multiplicative
distortion of the outer half of an orbital, and 2 % point-to-point noise, each moved the phase spread by
NOTHING and the normalization spread by 4.8 % and 4.0 % against 1.5e-04 for the sound orbital.
A sound orbital has both near zero. Either one large says the matching point carries something that is not the
Coulomb solution, and the constant returned is then untrustworthy however confidently it was produced.
WHAT THIS DOES NOT CATCH, stated because a guard claiming to catch everything is the suspicious kind: a single
enormous INTERIOR spike leaves both measures untouched, since neither looks inside the matching region. That is
what `Continuum.checkContinuumAmplitude` is for, and the two tiers are complementary, not alternatives.
THE MEASURE IS SCALE-FREE AND NEEDS NO REFERENCE DATA. `iPhase` is an angle, so its spread is in radians
regardless of the orbital's arbitrary eigenvector scale, and the comparison is between radii of ONE orbital
rather than against a tabulated value.
IT ALSO SAYS WHICH GRID IS AT FAULT, which a single number cannot. The ratio of the total variation of
`iPhase` to its net change over the window separates the two failure modes: near 1 the phase drifts
SMOOTHLY, meaning the potential has not reached its tail inside the box and the BOX IS TOO SMALL; far above 1
it jitters from point to point, meaning the mesh does not resolve the oscillation and the MESH IS TOO COARSE.
AND THE REPAIR MOVES INWARD, NOT OUTWARD, which is worth stating because it is the opposite of what one
expects: the matching point is `size(cOrbital.P, 1)`, the OUTERMOST mesh point of the orbital, so there is no
larger radius to move to -- and that point is precisely where a B-spline Galerkin solution is most constrained
by the boundary condition at the box wall. So the repair is to step AWAY FROM THE WALL to the outermost radius
at which the phase has settled. Where no such radius exists on this grid, nothing in the code can repair it
and the function RAISES, naming the grid change needed, rather than returning a number.
AND THE MOVE IS GATED ON MESH DENSITY, which is a CORRECTION to the first form of this check rather than a
refinement of it. A move is taken only where the mesh carries at least `meshSound` points, counted, across one
oscillation. Measured 06-Nov-2026: a move at 30 counted points reproduced the converged normalization to
0.09 %, while the move the dielectronic-recombination test case took at about 18 turned a +6.0 % error into a
-5.6 % one and reported success. Below the gate the move is therefore DECLINED -- the ORIGINAL radius is kept,
`declined` is set, and the verdict is `:poor`, so the caller is told loudly with the uncertainty quoted. It
does not raise: the defect measured was a move that relocated an error while reporting success, and declining
the move removes exactly that and nothing more.
An orbital already sound at the box wall is untouched by this gate; it bites only where a radius would
otherwise have been moved. Note what the gate does NOT claim: the same sweep shows the error is non-monotone
in the density, so a coarse mesh is a reason to distrust a MOVE rather than proof that the orbital is bad.
A `(index, moved, declined, spread, jitter, scaleDrift, ppo, nProbes, inside, rTP, verdict)::NamedTuple` is
returned, with `verdict` one of `:sound`, `:moved`, `:poor`, `:unfair` or `:tooFewPoints`.
A `checkMatchingRadius::Continuum.checkMatchingRadius` is returned.JenaAtomicCalculator.Continuum.checkNormalizationRadius — Method
Continuum.checkNormalizationRadius(pot::Radial.Potential) ... checks that the point at which a continuum orbital's normalization and phase are fixed lies far enough outside the atom, and raises with the measurement behind it otherwise; nothing is returned.
WHY THIS EXISTS SEPARATELY FROM `gridConsistency`, which asks a related question and cannot answer this
one. `gridConsistency` receives only `(maxEnergy, grid)` and therefore knows nothing about the atom, so
the best it can do is an ABSOLUTE test -- `grid.r[nrContinuum] < 2.0` -- and an absolute length cannot be
right for every charge: 2 a.u. is deep inside hydrogen and far outside Ne^9+. What matters is the
DIMENSIONLESS product Zeff * r.
AND Zeff NEEDS NO ARGUMENT, which is the point of putting the check here. `Radial.Potential` carries
`Zr`, with `V(r) = -Zr(r)/r`, so `pot.Zr[n]` IS the effective charge the escaping electron still feels at
radius r[n] -- the residual ion's charge, seen from where the orbital is normalized. Every generator in
this module that solves in a potential already has it, so all twenty call sites of `gridConsistency`
across the package are protected without any of them being changed.
THE CRITERION, measured 01-Sep-2026 on H-like photoionization at Z = 1 and Z = 10, where the two gauges
are EQUAL for exact wavefunctions so every departure from 1.00000 is error and nothing else:
Zeff * r 2.12 4.09 4.84 6.50 9.77 10.74 14.70 21.69 48.32
Cou/Bab 0.004 0.085 4.15 3.78 1.072 0.9996 0.9997 1.00001 1.00000
The two charges fall on the SAME curve in this variable, which is what identifies it as the right one:
Zeff*r = 21.69 gives 1.00001 at Z = 1 and 1.00000 at Z = 10. Below 10 the errors are not small -- a
factor of 200 at the worst point -- and the failure is NON-MONOTONE (0.085 and then 3.78 on a FINER
grid), which is the signature of the normalization point landing at an arbitrary phase of the oscillation
rather than of insufficient resolution.
THE MANY-ELECTRON CASE, measured 02-Sep-2026, which is what the criterion had been waiting for. For a
many-electron ion the two gauges are NOT equal even for exact wavefunctions, so the H-like error measure
does not exist; CONVERGENCE does. Neon with a 1s hole -- the system of `testModule_Cascade_StepwiseDecay`,
i.e. the one case a refusal here would block -- decaying by Auger emission to Ne^2+, total rate against box:
Zeff * r 6.81 10.46 13.21 18.25 22.13 30.13 44.18 62.04
rate 9.432734 9.427362 9.427437 9.427417 9.427461 9.427415 9.427445 9.427469 (e-03)
THE THRESHOLD IS IN THE RIGHT PLACE: the rate settles to 9.42742e-03 within ~5e-6 from Zeff*r = 10.46 on,
and the only point that misses it is the one BELOW the criterion. **And the local-vs-asymptotic ambiguity
that held this up turns out not to be material**: the local Zr equals the asymptotic charge (2.000) to 0.1 %
at every radius where the check is evaluated, and differs (2.099) only at r = 3.2 a.u., which the check
refuses anyway.
BUT THE PENALTY FOR VIOLATING IT IS OBSERVABLE-DEPENDENT BY ORDERS OF MAGNITUDE, and that is the reason
this is still a warning. At Zeff*r = 6.8 the Auger rate above is wrong by 5.7e-4 RELATIVE; at Zeff*r = 4.8
the H-like photoionization gauge ratio is wrong by a FACTOR OF FOUR. A ratio of two amplitudes exposes the
continuum phase directly, while a rate built from one matrix element is far more forgiving of it. So the
number 10 is right for the quantity it was measured on, and very conservative for others -- which is why
promoting this to an unconditional `error` would refuse calculations whose error is 1e-4.
A FREE PARTICLE IS EXEMPT, and must be. When the residual system is neutral the electron sees no Coulomb
tail, Zeff -> 0, and `Zeff * r >= 10` could never be satisfied by any box; there is also nothing for it to
guard, since a plane wave has no Coulomb phase to get wrong. The check therefore applies only where a
Coulomb tail exists.
A NamedTuple is returned, carrying the MEASUREMENT rather than a verdict -- priority item 40, whose rule is
that a diagnostic hands back a measured quantity with its context so the CALLER judges:
`(ok, checked, Zeff, r, ZeffTimesR, required, rWanted, note)`. **`checked` is the field that matters most
and the reason this is not a bare Bool**: two paths leave the criterion UNTESTED -- a grid too short for
the probe point to exist, and a free particle with no Coulomb tail -- and both return `ok = true` because
nothing failed. NOT CHECKED IS NOT PASSED, and a caller reading only `ok` would take either for a clean
bill of health. `ZeffTimesR` against `required` is the quantity to judge on, and `rWanted` is the radius
that would satisfy it. Nothing raises: this warns, deliberately, for the reason given above.JenaAtomicCalculator.Continuum.continuumAmplitudeReport — Method
Continuum.continuumAmplitudeReport(wa::NamedTuple, cOrbital::Orbital, grid::Radial.Grid) ... formats the measurement from Continuum.checkContinuumAmplitude into the explanatory block that both the warning and the refusal in Continuum.reportContinuumAmplitude print, so that the two cannot drift apart; a report::String is returned.
JenaAtomicCalculator.Continuum.coulombMatchingPair — Method
Continuum.coulombMatchingPair(i::Int64, pot::Radial.Potential, energy::Float64, kappa::Int64, l::Int64, Zbar::Float64) ... evaluates, AT THE SINGLE MESH POINT i, the pair of reference solutions onto which the Coulomb-function normalization matches the numerical orbital: the regular and irregular relativistic Coulomb functions where the residual charge is appreciable, and the spherical Bessel pair where it is not. Both large components and their radial derivatives are returned, together with x = q r_i, the classical turning point xTP in the same variable, and the Coulomb phase – which depends on eta, lambda, l and kappa but NOT on the radius, and is therefore the same whichever point is matched at. Nothing is printed, so the function may be called at many radii in turn. A (fu, gu, fup, gup, cPhase, kind, x, xTP)::NamedTuple is returned.
JenaAtomicCalculator.Continuum.generateOrbitalAsymptoticCoulomb — Method
Continuum.generateOrbitalAsymptoticCoulomb(energy::Float64, sh::Subshell, pot::Radial.Potential, settings::Continuum.Settings) ... to generate a simple relativistic and non-normalized continuum orbital but by assuming an asymptotic sin/cos behaviour for both components at all mesh points. For this behaviour, both components and their derivatives can be calculated analytically. The effective charge Zbar is determined for the given potential and the non-Coulombic phase shifts is set to zero. An non-normalized cOrbital::Orbital is returned.
Warning: At present, only the real part eta.re is taken into account; check for consistency !!JenaAtomicCalculator.Continuum.generateOrbitalBessel — Method
Continuum.generateOrbitalBessel(energy::Float64, sh::Subshell, grid::Radial.Grid, settings::Continuum.Settings) ... to generate a simple, non-relativistic and non-normalized Bessel wave for the large component of the continuum orbital and a small component due to the kinetic-balance condition. A (non-normalized) orbital::Orbital is returned. While Pprime is obtained from the analytical expression of the large component, Qprime is set to zero here.
JenaAtomicCalculator.Continuum.generateOrbitalForLevel — Method
Continuum.generateOrbitalForLevel(energy::Float64, sh::Subshell, level::Level, nm::Nuclear.Model, grid::Radial.Grid, settings::Continuum.Settings, plasmaModel::Basics.AbstractPlasmaModel; nuclearPot::Union{Nothing,Radial.Potential}=nothing, primitives::Union{Nothing,Bsplines.Primitives}=nothing, storage::Union{Nothing,Dict{String,Array{Float64,2}}}=nothing) ... to generate a continuum orbital as Continuum.generateOrbitalForLevel(...) above, but with the combined local potential (nuclear + bound-electron mean field) Debye-Hueckel-screened according to the given plasma model. The WHOLE combined potential is screened, not just its nuclear part: screening only the (attractive) nuclear term while leaving the (repulsive) mean-field term unscreened leaves an uncancelled repulsive tail at large r once the Debye length becomes comparable to the box radius, giving an unphysical (negative) asymptotic effective charge for the continuum electron. For plasmaModel = Basics.NoPlasmaModel(), this delegates directly to the field-free method above, so that the computation of the standard (field-free) processes is never touched by this plasma-specific code path. A tupel of a (continuum) (orbital::Orbital, phase::Float64) is returned.
JenaAtomicCalculator.Continuum.generateOrbitalForLevel — Method
Continuum.generateOrbitalForLevel(energy::Float64, sh::Subshell, level::Level, nm::Nuclear.Model, grid::Radial.Grid, settings::Continuum.Settings; nuclearPot::Union{Nothing,Radial.Potential}=nothing, primitives::Union{Nothing,Bsplines.Primitives}=nothing, storage::Union{Nothing,Dict{String,Array{Float64,2}}}=nothing) ... to generate a continuum orbital for the (continuum) subshell sh, the energy and the effective charge within the given potential. The continuum orbital is generated orthogonal with regard to all subshells of the same symmetry in the basis. All further specifications about this generations are made by proper settings. All three keywords carry quantities that are CONSTANT for a whole computation – the nuclear potential depends only on the nuclear model and the grid, the B-spline primitives only on the grid, and the storage dictionary holds the TTp matrices, which depend on the grid and on kappa but never on the potential or the energy – so that a caller which generates many continuum orbitals need not rebuild them for every line and every partial wave; omitting them reproduces the previous behaviour exactly. A tupel of a (continuum) (orbital::Orbital, phase::Float64) is returned.
NOTE ON THE POTENTIAL: every continuum orbital is generated in a LOCAL (DFS) potential, whatever field the bound
orbitals of `level` actually came from -- that remains true of every run and is stated here rather than emitted as
a per-orbital warning as it was until 12-Aug-2026 (which produced one identical entry in jac-warn.report for every
partial wave, and said nothing about the run). **AS OF 29-Oct-2026 (item 99) exchange with the bound electrons CAN
be added on top of that local potential**, under `settings.includeExchange = true` and the Galerkin solution method
only -- see `Continuum.Settings`'s own docstring for what that does and why every other combination raises.JenaAtomicCalculator.Continuum.generateOrbitalGalerkin — Method
Continuum.generateOrbitalGalerkin(energy::Float64, sh::Subshell, pot::Radial.Potential, settings::Continuum.Settings; primitives::Union{Nothing,Bsplines.Primitives}=nothing, storage::Union{Nothing,Dict{String,Array{Float64,2}}}=nothing, coreOrbitals::Union{Nothing,Dict{Subshell,Orbital}}=nothing, occupations::Union{Nothing,Dict{Subshell,Float64}}=nothing) ... to generate a non-normalized continuum orbital within the given local potential by using the Galerkin method and a given B-spline basis. Both keywords carry quantities that are constant for a whole computation on one grid: the B-spline primitives depend on the radial grid alone, and the storage dictionary holds the TTp matrices, which depend on the grid and on kappa but never on the potential or the energy. A caller that generates many continuum orbitals should build both once and pass them in. Omitting either reproduces the previous behaviour exactly. A (non-normalized) orbital::Orbital is returned.
**`coreOrbitals`/`occupations`, ADDED 29-Oct-2026 (item 99), ADD EXCHANGE WITH A FROZEN CORE, AND NEED NO ITERATION
HERE.** When both are given, `Bsplines.setupExchangeMatrix` -- the same frozen nonlocal Dirac-Fock exchange operator
validated for item 75/S30 -- is added to the Galerkin matrix before it is solved. The core is frozen and the operator
is LINEAR in the unknown continuum orbital, so this is exactly the one-shot assembly `A = setupLocalMatrix +
setupExchangeMatrix` already uses for a frozen-core bound Fock matrix, not a new convergence loop: the matrix is built
once, and the same single generalized-eigenvalue solve below finds the continuum orbital, now of the Dirac-FOCK
problem instead of the Dirac-Hartree one. Omitting either keyword (the default) reproduces the previous behaviour
exactly -- this is the switch `Continuum.Settings.includeExchange` turns on, and its own docstring says why every
other solution method must raise instead of reaching this keyword.JenaAtomicCalculator.Continuum.generateOrbitalLocalPotential — Method
Continuum.generateOrbitalLocalPotential(energy::Float64, sh::Subshell, pot::Radial.Potential, settings::Continuum.Settings) ... to generate a continuum orbital for the (continuum) subshell sh, the energy and the given potential. The effective charge for the normalization of the continuum orbital is derived from the potential. All further specifications about this generations are made by proper settings; however, the function terminates if settings.includeExchange = true, UNCONDITIONALLY and for a different reason than in Continuum.generateOrbitalForLevel (item 99): this function is handed a bare pot::Radial.Potential with no level at all, so it has no bound orbitals to build an exchange operator from, whatever the solution method. A tupel of a (continuum) (orbital::Orbital, phase::Float64, normFactor::Float64) is returned.
JenaAtomicCalculator.Continuum.generateOrbitalNonrelativisticCoulomb — Method
Continuum.generateOrbitalNonrelativisticCoulomb(energy::Float64, sh::Subshell, Zeff::Float64, grid::Radial.Grid, settings::Continuum.Settings) ... RAISES. It was intended to generate a simple, non-relativistic and non-normalized Coulomb wave for the (continuum) subshell sh, with the small component from the kinetic-balance condition, but it has never produced an orbital and no orbital::Orbital is returned: the Coulomb wave needs a confluent hypergeometric function 1F1 with COMPLEX arguments, 1F1(l+1+i*eta, 2l+2, 2iqr), and GSL.hypergeom accepts real arguments only.
WHY IT RAISES RATHER THAN WARNS, since 03-Nov-2026. That limitation was already recorded here and at the head of the
function, but as a `println`, which goes to stdout and is suppressed by every `redirect_stdout(devnull)` path in the
package; execution then continued into the loops, which assign the complex result into a `Float64` array and die on
an `InexactError` naming neither this function nor the setting that selected it. Until the same date all three
dispatchers compounded it by passing a `Radial.Grid` into the `Radial.Potential` slot of the four-argument method, so
the branch raised a `MethodError` on a signature before ever reaching the physics. Both are now a single explained
refusal that names the alternatives: `AsymptoticCoulomb` for an analytic Coulomb wave, `BsplineGalerkin` to solve in
the actual potential. The formulas are left in place for whoever supplies a complex 1F1.JenaAtomicCalculator.Continuum.generateOrbitalNonrelativisticCoulomb — Method
Continuum.generateOrbitalNonrelativisticCoulomb(energy::Float64, sh::Subshell, pot::Radial.Potential, settings::Continuum.Settings) ... to generate a simple, non-relativistic and non-normalized Coulomb wave for the (continuum) subshell sh, the small component is simply obtained by the kinetic-balance condition. A orbital::Orbital is returned.
JenaAtomicCalculator.Continuum.generateOrbitalPureSine — Method
Continuum.generateOrbitalPureSine(energy::Float64, sh::Subshell, grid::Radial.Grid, settings::Continuum.Settings) ... to generate a simple, non-relativistic and non-normalized Bessel wave for the large component of the continuum orbital and a small component due to the kinetic-balance condition. A (non-normalized) orbital::Orbital is returned. While Pprime is obtained from the analytical expression of the large component, Qprime is set to zero here.
JenaAtomicCalculator.Continuum.gridConsistency — Method
Continuum.gridConsistency(maxEnergy::Float64, grid::Radial.Grid; minEnergy::Union{Nothing,Float64}=nothing, Zeff::Union{Nothing,Float64}=nothing) ... to check the consistency of the given grid with the energies of the required continuum electrons; an error message is issued if the grid.hp = 0. or 15 * grid.hp < wavelength(maxEnergy) or if the grid has less than 600 grid points. The function also returns the recommended grid point where the normalization and phase is to be determined. This number is currently set to nrContinuum = grid.NoPoints - 200 ... to correct for the wrong 'phase behaviour' at large r-values.
TWO QUANTITIES ARE TESTED, NOT ONE, AND THEY ARE INDEPENDENT. The first is the familiar one, the asymptotic step
against the de Broglie wavelength -- how finely one oscillation is SAMPLED. The second is how many oscillations
the grid holds at all, and it is the criterion this function lacked until 06-Nov-2026. Measured 01-Sep-2026 on H
1s photoionization at eps = 0.5 Ha, where the two gauges are equal for exact wavefunctions so every departure
from 1.00000 is error, with grid.hp held FIXED at 0.060 and only the box changed:
rbox wavelengths in box points per oscillation Cou/Bab
18.09 2.88 104.7 1.067
30.00 4.77 104.7 1.00001
THE SAMPLING IS IDENTICAL ON BOTH ROWS and one is 6.7 % wrong, so no criterion on grid.hp alone can separate
them. The phase and the normalization are read near the outer boundary, and reading them needs several complete
oscillations to read FROM; 2.88 is not enough and 4.77 is. Below 4 this function warns.
BUT THAT SECOND CRITERION APPLIES ONLY TO THE ASYMPTOTIC-SINE CONVENTIONS, and the warning is withheld for
`CoulombFunctionNorm`, the shipped default. Measured 06-Nov-2026 on Mg^10+ (1s^2) with a self-consistent
screened potential and a 10 eV electron: enlarging rbox from 6.5 to 30.0 a.u., i.e. from 0.89 to 4.09
oscillations, left the inner phase shift, the normalization constant and the orbital identical to six decimals
for kappa = -1, 1 and -2 alike. Exact Coulomb functions hold wherever the potential has reached its -Zbar/r
tail rather than only asymptotically, and there Zeff*r = 46 at the matching point, so the tail condition is met
well inside one oscillation. A measure may only guard the assumption its own routine makes.
THE TESTS WANT OPPOSITE ENDS OF THE ENERGY RANGE, which is what `minEnergy` is for. The mesh must sample
the SHORTEST oscillation, so it is tested at the fastest electron, `maxEnergy`; the box must CONTAIN the
longest, so that belongs to the slowest. A caller that knows its range passes `minEnergy` and is told
about both ends; one that passes only a maximum is told about the fast end alone, which is how every
call site behaved before 06-Nov-2026 and how most still do.
AND THE TWO ENDS CARRY DIFFERENT SEVERITIES, which is a decision and not an oversight -- the maintainer's,
06-Nov-2026. The fast end may be REFUSED, because at a fixed energy "enlarge the box to four wavelengths"
is an instruction that can be carried out. The slow end only WARNS, because the wavelength grows as
1/sqrt(E) without bound: no box of any size holds one wave at threshold, and several of JAC's own
calculations place their lowest energy AT threshold deliberately, a rate coefficient being the obvious one.
A refusal there would forbid the calculation rather than ask for a larger box. Nor can the offending
energies be dismissed as negligible: the colder the plasma, the more the slowest electrons contribute to
the very average they would be dropped from. So the slow end reports WHICH PART of the output is affected
and leaves the run to proceed. A `minEnergy` of zero or below, and an empty line list arriving as
`maxEnergy = 0`, are NOT ASKED rather than failed, since there is then no oscillation to count.
AND A FIXED POINTS-PER-OSCILLATION NUMBER CANNOT BE CALIBRATED, which is why the sampling test refuses at 15 and
only WARNS at 40 rather than refusing there. Three convergence studies in this repository demand three widely
different densities: 34 points converge a 4.66 keV Auger rate to 0.02 % (06-Nov-2026), 104 are not enough for
neutral H in a small box (01-Sep-2026), and 463 are needed for radiative recombination into H-like Bi at 1 eV
(17-Sep-2026). The ordering follows the Sommerfeld parameter eta = Zbar/q -- about 1 for the first two and 306
for the last -- because the asymptotic wavelength is the LONGEST one in the problem and therefore flatters a
heavy ion at low energy. So 40 is the value below which the published measurements show percent-level error and
is worth saying out loud; it is not a value above which anything is guaranteed, and only halving grid.hp until
the answer stops moving establishes that.
OPEN POINT, stated here rather than emitted as a per-call warning as it was until 12-Aug-2026: the grid
point at which the normalization and phase are fixed deserves a better choice than the present fixed
offset. It is a property of the method, not of any particular run.
MEASURED 01-Sep-2026, and it turns that open point into the sharpest of these checks. The offset is FIXED
AT 200 GRID POINTS from the end, so where it lands physically depends on hp and NoPoints and not on the
atom at all. On H-like photoionization, where the two gauges are equal for exact wavefunctions:
Zeff * r[NoPoints-200] 2.12 4.09 4.84 6.50 9.77 10.74 14.70 21.69 48.32
Cou/Bab 0.004 0.085 4.15 3.78 1.072 0.9996 0.9997 1.00001 1.00000
Z = 1 and Z = 10 fall on the SAME curve in the dimensionless variable Zeff*r, which is what identifies it
as the right one, and the errors below 10 are not small -- a factor of 200 at the worst point. THE
FAILURE IS NON-MONOTONE (0.085 and then 3.78 on a FINER grid), which is the signature of the
normalization point landing at an arbitrary phase of the oscillation and NOT of insufficient resolution.
Hence the optional `Zeff`: when it is given, this function refuses a grid with Zeff*r < 10. It is optional
only because the existing callers pass `(maxEnergy, grid)` and none of them can be changed from here; each
should be migrated to supply it, one module at a time. Until a caller does, the absolute `2.0` test is all
that guards it, and the table above shows that 2.0 establishes nothing: at Z = 1 it admits grids that are
wrong by two orders of magnitude.JenaAtomicCalculator.Continuum.matchAtRadius — Method
Continuum.matchAtRadius(i::Int64, cOrbital::Orbital, pot::Radial.Potential, l::Int64, Zbar::Float64) ... extracts, from the single mesh point i, the two numbers the Coulomb-function normalization is built on: the inner (non-Coulomb) phase shift iPhase and the normalization constant N, obtained by matching the orbital's large component and its derivative to the reference pair at that point. THE POINT OF HAVING THIS AS ITS OWN FUNCTION is that iPhase must be INDEPENDENT of i wherever the match is legitimate – the numerical solution is cos(iPhase) F + sin(iPhase) G exactly, once the potential has reached its -Zbar/r tail – so calling it at several radii turns an unverifiable one-point match into a measurement. A (N, iPhase, cPhase, kind, x, xTP)::NamedTuple is returned.
JenaAtomicCalculator.Continuum.matchingRadiusReport — Method
Continuum.matchingRadiusReport(wa::NamedTuple, cOrbital::Orbital, pot::Radial.Potential, mtp::Int64) ... says out loud what Continuum.checkMatchingRadius found, and RAISES where the matching radius cannot be made fair on the given grid; nothing is returned when the orbital may be used. A sound orbital prints nothing, so the check is silent in the normal case and unmissable otherwise.
WHY IT RAISES RATHER THAN WARNS IN THE LAST CASE. A warning on a continuum orbital is read past: the orbital
is consumed inside an amplitude loop that may run thousands of times, and the resulting cross section carries
no trace of it. Where the phase never settles, the normalization constant is not a property of the solution
at all, and every number built on it is wrong by an unknown factor -- which is the failure mode that reads as
box dependence and has twice been mistaken for physics in this code. The grid is NOT repaired here: it
belongs to the whole `Atomic.Computation`, and a silent re-solve would contract a continuum orbital from one
grid against bound orbitals from another.JenaAtomicCalculator.Continuum.normalizeOrbitalCoulombFunctions — Method
Continuum.normalizeOrbitalCoulombFunctions(cOrbital::Orbital, pot::Radial.Potential, settings::Continuum.Settings) ... to normalize the given continuum orbital with regard to a (asymptotic) wave function as per Salvat Code. The orbitasl are normalized to unit amplitude. An ( orbital::Orbital, (δ + Δ)::Float64, N::Float64 ) is returned.
THE MATCHING RADIUS IS NOW TESTED BEFORE IT IS TRUSTED (05-Nov-2026). This convention pins the orbital to the
exact Coulomb functions at ONE radius, and for a long time nothing asked whether that radius was a fair place
to do it: where the potential had not reached its `-Zbar/r` tail there, or where the orbital was corrupted,
the match still succeeded and returned a confident number. `Continuum.checkMatchingRadius` now extracts the
inner phase shift over the outer two wavelengths and requires it to be CONSTANT, which it is wherever the
match is legitimate; the matching point is moved away from the box wall when that helps, and the routine
RAISES when no radius on the grid will do. See that function for the measure and `Continuum.matchAtRadius`
for the one-radius extraction this was factored out of.JenaAtomicCalculator.Continuum.normalizeOrbitalCoulombSine — Method
Continuum.normalizeOrbitalCoulombSine(cOrbital::Orbital, pot::Radial.Potential, settings::Continuum.Settings) ... to normalize the given continuum orbital with regard to a (asymptotic) pure sine-function. An (on-energy-scale-normalized) orbital::Orbital is returned.
JenaAtomicCalculator.Continuum.normalizeOrbitalOngRussek — Method
Continuum.normalizeOrbitalOngRussek(cOrbital::Orbital, pot::Radial.Potential, settings::Continuum.Settings) ... to normalize the given continuum orbital with regard to a (asymptotic) pure sine-function. An (on-energy-scale-normalized) orbital::Orbital is returned.
JenaAtomicCalculator.Continuum.normalizeOrbitalPureSine — Method
Continuum.normalizeOrbitalPureSine(cOrbital::Orbital, grid::Radial.Grid, settings::Continuum.Settings; Zbar::Float64=0.0) ... to normalize the given continuum orbital with regard to a (asymptotic) pure sine-function. An (on-energy-scale-normalized) orbital::Orbital and its relative phase phi w.r.t. sin(kr + phi) is returned.
+ Zbar ::Float64 ... the residual charge the outgoing electron still feels, which enters only the PHASE that
`Continuum.asymptoticAmplitude` fits; the target amplitude keeps this convention's own
`sqrt(2/(pi*q))`. It defaults to 0.0, the genuinely free wave, so that a caller holding
only a grid -- as the test suite does -- gets the free-wave model; the three callers in
this module all have a potential and pass `Radial.determineZbar(pot)`. Measured
03-Nov-2026, fitting a Coulomb wave with the free model biases the amplitude by up to
14 % at 1.449 eV and raises the fit residual by a factor of 5 to 20.JenaAtomicCalculator.Continuum.reportContinuumAmplitude — Method
Continuum.reportContinuumAmplitude(P::Array{Float64,1}, cOrbital::Orbital, grid::Radial.Grid, sa::String; residual::Float64=NaN) ... validates the normalized large component P of cOrbital in the two stages of the module's guard order, naming the convention sa that produced it: first its FORM, against the residual of the asymptotic fit below, then its MAGNITUDE, through Continuum.checkContinuumAmplitude's interior/asymptotic ratio. They fail independently, which is why both are asked and in that order. Each stage warns where the result is suspect and raises where it is unusable; nothing is returned when neither fires.
+ residual ::Float64 ... the rms misfit of the orbital against its fitted asymptotic form, as a FRACTION of the
amplitude, from `Continuum.asymptoticAmplitude`. It is checked in two tiers before the
amplitude ratio below, because it is the only one of the two that sees a non-asymptotic
orbital at all. `NaN`, the default, means the caller has no fit to offer -- which is the
case for `normalizeOrbitalCoulombFunctions`, matching analytic functions instead -- and the tier is
then skipped rather than guessed at.
THE WARNING GOES TO `stderr` AND IS THEREFORE NOT SUPPRESSED by a `printout = false` path or by a
`redirect_stdout(devnull)`, which is deliberate: the orbital it concerns is unusable for every observable, and the
failure is otherwise entirely silent. It WARNS rather than raises, following `checkNormalizationRadius` below, whose
own note records why a normalization check is not promoted to an `error` -- there the penalty for violating the
criterion is observable-dependent by four orders. That reasoning is respected here and is also why the threshold is
set six orders below the measured defect rather than at the edge of the legitimate range.
THE GRID IS AN ARGUMENT AND MUST BE, although an `Orbital` carries a `grid` field of its own: on this path that field
comes back EMPTY -- `length(cOrbital.grid.r) == 0` for an orbital produced by `generateOrbitalLocalPotential` -- so
reading the spike radius from it yields `NaN` and the most useful line of the warning says nothing. Measured
22-Oct-2026 while calibrating this check.JenaAtomicCalculator.Continuum.resolveExchangeDefault — Method
Continuum.resolveExchangeDefault(explicit::Union{Nothing,Bool}, scField::Basics.AbstractScField) ... decides whether a continuum orbital built for THIS computation should carry exchange with the bound electrons: explicit, whenever it is given, always wins; otherwise the decision is made FROM THE SCF FIELD alone, so that the question never has to be put to a user who never asked it. true for ALField and EOLField – the two fields whose bound orbitals come from a genuine nonlocal Fock SCF, so the continuum orbital built in Continuum's own LOCAL potential is otherwise missing exactly the interaction its own bound orbitals were built with – and false for every other scField: a local potential (DFSField, HSField, KSField, CHField, ThomasFermiField, AaDFSField, AaHSField) has no exchange of its own to match, and NuclearField has no bound electrons at all. A value::Bool is returned. Item 99, route 1; this is the one function every process module's continuumExchange field is resolved through, via Basics.perform.
JenaAtomicCalculator.Continuum.twoFzero — Method
Continuum.twoFzero(CA::ComplexF64, CB::ComplexF64, CZ::ComplexF64) ... Calculates the Hypergeometric function 2F0(CA,CB;1/CZ) hypergeometric asymptotic series. Taken from Radial package by Salvat et al. A ComplexF64 value is returned.
JenaAtomicCalculator.Continuum.unsupportedScheme — Method
Continuum.unsupportedScheme(fn::String, setting::String, scheme, implemented::String, howToSet::String) ... raises because a dispatch on one of the two session-wide continuum choices – the SOLUTION method Defaults.GBL_CONT_SOLUTION or the NORMALIZATION convention Defaults.GBL_CONT_NORMALIZATION – reached its else branch, i.e. the value in force is one that this code path has no branch for. The message names the value, the path, what that path does implement and how to change the setting; nothing is returned, since it always raises.
WHY THIS IS A FUNCTION AND NOT SIX `error("stop a")` CALLS, which is what stood here until 03-Nov-2026. These two
settings are SESSION GLOBALS that a user sets once and that are then read far below, inside a cascade or a
second-order sum, so an unhandled value surfaces as a bare `stop a` from a place the caller never named. Worse, the
three dispatch sites do NOT implement the same set: `generateOrbitalLocalPotential` handles `ContSine()` and the two
`generateOrbitalForLevel` methods do not, so `setDefaults("method: continuum, pure sine")` followed by the level
route is a reachable trap that said only `stop a`. AND THE POINT IS THE NEXT SCHEME, not this one: a scheme added
to `Basics.AbstractContinuumSolutions` or `Basics.ContinuumNormalization` compiles and runs until it reaches a
dispatcher, and it must then fail loudly, naming itself and the site that needs the new branch.Hydrogenic ions
JenaAtomicCalculator.HydrogenicIon.energy — Method
HydrogenicIon.energy(sh::Shell, Z::Float64) ... to compute the (non-relativistic) energy for the given shell and for a point-like nuclear charge Z; the energy is printed in the current energy units to screen but is returned in Hartree. A energy::Float64 is returned.
JenaAtomicCalculator.HydrogenicIon.energy — Method
HydrogenicIon.energy(sh::Subshell, Z::Float64) ... to computes the Dirac energy for the hydrogenic subshell sh and for point-like nucleus with nuclear charge Z; a energy::Float64 in atomic units and without the rest energy of the electron is returned. That is the binding energy of a 1s_1/2 electron for Z=1 is -0.50000665.
JenaAtomicCalculator.HydrogenicIon.orbital — Method
HydrogenicIon.orbital(sh::Subshell, nm::Nuclear.Model, grid::Radial.Grid) ... to compute a relativstic hydrogenic Dirac orbital for the given nuclear model by using an explicit diagonalization of the Dirac Hamiltonian in a B-spline basis; an orbital::Radial.Orbital is returned.
JenaAtomicCalculator.HydrogenicIon.radialOrbital — Method
HydrogenicIon.radialOrbital(sh::Shell, Z::Float64, r::Float64) ... to compute the (non-relativistic) orbital function P(r) for the given shell and nuclear charge Z; a value::Float64 is returned.
JenaAtomicCalculator.HydrogenicIon.radialOrbital — Method
HydrogenicIon.radialOrbital(sh::Shell, Z::Float64, grid::Radial.Grid) ... to compute the same but for all r-values as specified by the given grid; a PList::Array{Float64,1} is returned.
JenaAtomicCalculator.HydrogenicIon.radialOrbital — Method
HydrogenicIon.radialOrbital(sh::Shell, Z::Float64, rlist::Array{Float64,1}) ... to compute the same but for an array of r-values [r1, r2, ...]; a PList::Array{Float64,1} is returned.
JenaAtomicCalculator.HydrogenicIon.radialOrbital — Method
HydrogenicIon.radialOrbital(sh::Subshell, Z::Float64, r::Float64) ... to compute a relativistic hydrogenic Dirac orbital for the given subshell and nuclear charge Z; a value::Float64 is returned; contributed by C Naumann (2022). Implementation of the analytical solution of the Dirac equation for a point-like nucleus following the book by Johnson: Atomic Structure Theory.
JenaAtomicCalculator.HydrogenicIon.radialOrbital — Method
HydrogenicIon.radialOrbital(sh::Subshell, Z::Float64, grid::Radial.Grid) ... to compute a relativistic hydrogenic Dirac orbital on the given grid; an Array with the large and small component is returned; contributed by C Naumann (2022).
JenaAtomicCalculator.HydrogenicIon.radialOrbital — Method
HydrogenicIon.radialOrbital(sh::Subshell, nm::Nuclear.Model, grid::Radial.Grid) ... to compute a relativstic hydrogenic Dirac orbital for the given nuclear model by using an explicit diagonalization of the Dirac Hamiltonian in a B-spline basis; an orbital::Radial.Orbital is returned; contributed by C Naumann (2022).
JenaAtomicCalculator.HydrogenicIon.rkExpectation — Method
HydrogenicIon.rkExpectation(srk::String, sh::Shell, Z::Float64) ... to compute the (non-relativistic) r^k expectation value for the shell sh of an ion with charge Z; a value::Float64 [in a_o^k] is returned. The string can takes values srk = ["r", "r^2", "1/r"]
Multipole moments
JenaAtomicCalculator.MultipoleMoment.amplitude — Method
MultipoleMoment.amplitude(mp::EmMultipole, gauge::EmGauge, omega::Float64, finalLevel::Level, initialLevel::Level, grid::Radial.Grid; display::Bool=false) ... to compute the multipole-moment amplitude <alphaf Jf || Q^(M) (omega, gauge) || alphai Ji> for the given final and initial level. All the amplitudes are calculated by means of Johnson's (2007) multipole-transition amplitudes from which also all constrains w.r.t the allowed gauges are inherited. A value::ComplexF64 is returned.
JenaAtomicCalculator.MultipoleMoment.amplitude — Method
MultipoleMoment.amplitude(K::Integer, level::Level, grid::Radial.Grid; display::Bool=false) ... to compute the K-th order (static) electric multipole-moment < alpha J J | Θ^(K) | alpha J J > for the given level. A value::Float64 is returned. This functon has been contributed by Jan Gilles (2024) but is rather different and mixes normal and reduced ME; it should become obsolete in a later version.
JenaAtomicCalculator.MultipoleMoment.dipoleAmplitude — Method
MultipoleMoment.dipoleAmplitude(finalLevel::Level, initialLevel::Level, grid::Radial.Grid; display::Bool=false) ... to compute the dipole amplitude <(alphaf Jf, kappa) Ji || D || alphai J_i> for the given final and initial level. A value::ComplexF64 is returned.
JenaAtomicCalculator.MultipoleMoment.emmStaticAmplitude — Method
MultipoleMoment.emmStaticAmplitude(k::Int64, finalLevel::Level, initialLevel::Level, grid::Radial.Grid; display::Bool=false) ... to compute the (reduced static) electric-multipole-moment (EMM) amplitude <alphaf Jf || T^(Ek) || alphai Ji> for the given final and initial level. A value::ComplexF64 is returned.
THE sqrt(2J_f+1) IS APPLIED HERE, AND UNTIL 15-Sep-2026 IT WAS NOT. `SpinAngular.computeCoefficients` returns
the rank-k coefficients in a normalization that yields the reduced matrix element up to that factor -- the same
convention `WeakInteractionMoment.oneParticleAmplitude` absorbs, where both factors were MEASURED against exact
one-electron reduced matrix elements rather than assumed. This routine contracted them without it and so
returned an amplitude too small by sqrt(2J_f+1).
WHICH SIDE WAS RIGHT WAS DECIDED BY PUBLISHED DATA, not by inspection -- that the two routines differed had been
known since `examples/example-Cn.jl` branch a printed them side by side. Against Cserveny & Roberts,
PRA 112, 032816 (2025), Table II for Ba+ (all-order, Breit + QED, ~1 %), the ratios of the UNNORMALIZED
amplitudes to the published values are 0.813 / 0.571 / 0.558 / 0.458 for <6s||d||6p_1/2>, <6s||d||6p_3/2>,
<6s||Q2||5d_3/2>, <6s||Q2||5d_5/2> -- NOT constant, so not a convention difference at all -- while divided by
sqrt(2J_f+1) they become 1.150 / 1.142 / 1.116 / 1.122, i.e. ONE 12-15 % mean-field error common to all four.
Rule 18: the factor belongs here, not at a call site; the hand-compensation that branch g of that example
carried is exactly the drift the rule exists to stop.
AND THE TWO SUBSHELL LISTS ARE MERGED, as `oneParticleAmplitude` merges them. Passing
`initialLevel.basis.subshells` alone raised a `BoundsError` whenever the two levels came from separately
computed multiplets, which is the ordinary way a polarizibility or Stark calculation obtains them.JenaAtomicCalculator.MultipoleMoment.transitionAmplitude — Method
MultipoleMoment.transitionAmplitude(mp::EmMultipole, gauge::EmGauge, omega::Float64, finalLevel::Level, initialLevel::Level, grid::Radial.Grid; display::Bool=false) ... to compute Johnson's (2007) multipole-transition amplitude <alphaf Jf || T^(M, absorption) (omega, gauge) || alphai Ji> for the given final and initial level. Allowed gauges are {Velocity, Length} for the electric-multipole transition amplitudes and Magnetic for the magnetic-multipole transition amplitudes, respectively. A value::ComplexF64 is returned.