Alpha-variation (q-factors)

JenaAtomicCalculator.AlphaVariation.Outcome — Type

struct AlphaVariation.Outcome ... defines a type to keep the outcome of a alpha-variation computation, such as the q (and Q) sensitivity coefficients as well as other results.

+ level                     ::Level              ... Atomic level to which the outcome refers to.
+ omega                     ::Float64            ... Level energy at the physical value of alpha.
+ q                         ::Float64            ... Sensitivity coefficient, q = d omega / dx  at x = 0, in the same
                                                        (atomic-unit) energy scale as omega.
+ Q                         ::Float64            ... Dimensionless sensitivity coefficient, Q = q / (omega - omega_ground),
                                                        referred to the lowest level of the SAME multiplet; 0. for the
                                                        ground level itself, where this ratio is undefined.
source
JenaAtomicCalculator.AlphaVariation.Outcome — Method

AlphaVariation.Outcome() ... constructor for an empty instance of AlphaVariation.Outcome for the computation of alpha-variation properties. A outcome::AlphaVariation.Outcome is returned.

source
JenaAtomicCalculator.AlphaVariation.Settings — Type

struct AlphaVariation.Settings <: AbstractPropertySettings ... defines a type for the details and parameters of computing alpha-variation parameters.

+ calcQ                    ::Bool             ... True if the q (and Q) sensitivity coefficients need to be calculated, and false
                                                  otherwise.
+ variationX               ::Float64          ... The finite-difference step x = (alpha/alpha_0)^2 - 1 used to shift alpha in the two
                                                    auxiliary SCF/CI computations; the physical alpha corresponds to x = 0.
+ printBefore              ::Bool             ... True if a list of selected levels is printed before the actual computations start.
+ levelSelection           ::LevelSelection   ... Specifies the selected levels, if any.
source
JenaAtomicCalculator.AlphaVariation.Settings — Method

AlphaVariation.Settings(set::AlphaVariation.Settings; calcQ::Union{Nothing,Bool}=nothing, variationX::Union{Nothing,Float64}=nothing, printBefore::Union{Nothing,Bool}=nothing, levelSelection::Union{Nothing,LevelSelection}=nothing)

... keyword copy-constructor for re-defining selected values of a settings::AlphaVariation.Settings.
    A `settings::AlphaVariation.Settings` is returned.
source
JenaAtomicCalculator.AlphaVariation.Settings — Method

AlphaVariation.Settings() ... constructor for an empty instance of AlphaVariation.Settings for the computation of alpha variation parameters. A settings::AlphaVariation.Settings is returned.

source
JenaAtomicCalculator.AlphaVariation.computeOutcomes — Method

AlphaVariation.computeOutcomes(multiplet::Multiplet, nm::Nuclear.Model, grid::Radial.Grid, configs::Array{Configuration,1}, asfSettings::AsfSettings, settings::AlphaVariation.Settings; output=true) ... to compute (as selected) the alpha-variation parameters for the levels of the given multiplet and as specified by the given settings. The multiplet is taken as the x = 0 (physical-alpha) reference; if settings.calcQ, two further SCF/CI computations are performed for the same configs & asfSettings at alpha shifted by x = +settings.variationX and x = -settings.variationX (with x = (alpha/alpha_0)^2 - 1), and q = d omega/dx is obtained from the simple symmetric finite-difference formula q = (omega(+x) - omega(-x)) / (2x). Levels are matched across the three multiplets by OVERLAP of their mixing coefficients (AlphaVariation.matchLevelByOverlap), not by position, so a level crossing under the shift does not silently difference two different physical states; this requires configs & asfSettings to be exactly the ones that produced multiplet – a minimal consistency check on the electron number is done for this reason, in addition to matchLevelByOverlap's own checks. The results are printed in neat tables to screen but nothing is returned otherwise.

source
JenaAtomicCalculator.AlphaVariation.determineOutcomes — Method

AlphaVariation.determineOutcomes(multiplet::Multiplet, settings::AlphaVariation.Settings) ... to determine a list of Outcomes's for the computation of the alpha-variation parameters for the given multiplet. It takes into account the particular selections and settings. An Array{AlphaVariation.Outcome,1} is returned. Apart from the level specification, all physical properties are set to zero during the initialization process.

source
JenaAtomicCalculator.AlphaVariation.displayOutcomes — Method

AlphaVariation.displayOutcomes(stream::IO, outcomes::Array{AlphaVariation.Outcome,1}) ... to display a list of levels that have been selected for the computations. A small neat table of all selected levels and their energies is printed but nothing is returned otherwise.

source
JenaAtomicCalculator.AlphaVariation.displayResults — Method

AlphaVariation.displayResults(stream::IO, outcomes::Array{AlphaVariation.Outcome,1}) ... to display the energies as well as the q- and Q-sensitivity coefficients for the selected levels. A neat table is printed but nothing is returned otherwise.

source
JenaAtomicCalculator.AlphaVariation.matchLevelByOverlap — Method

AlphaVariation.matchLevelByOverlap(target::Level, candidates::Array{Level,1}) ... identifies, among candidates, the level whose mixing-coefficient vector has the LARGEST overlap with target's – the state that IS the same physical state, rather than the one that merely sits at the same POSITION in an energy-sorted list. This is what makes alpha-variation safe across a level crossing: for these ions q can reach 1e5-1e6 cm^-1 against level spacings of only a few thousand, so a step as small as a few percent can re-order the levels, and a positional match would then silently difference two DIFFERENT physical states (challenge S6, closed by this function). target and every level in candidates must share one CSF basis, in the same order – true whenever both were built from the same configs and asfSettings, since CSF generation is purely combinatorial and does not depend on alpha. RAISES if the best overlap is not a clear majority (< 0.5): either this level has no clean counterpart at the shifted alpha (the step is too large for the level spacing here, and variationX needs to shrink), or candidates was not built from the same basis as target. A tuple (level::Level, overlap::Float64) is returned.

source

Atomic form factors

JenaAtomicCalculator.FormFactor.Outcome — Type

struct FormFactor.Outcome ... defines a type to keep the outcome of a form-factor computation, such as the standard form factor as well other results.

+ level                     ::Level              ... Atomic level to which the outcome refers to.
+ qValues                   ::Array{Float64,1}   ... momentum transfer |q|.
+ standardFs                ::Array{Float64,1}   ... standard atomic form factor F(q) for an (assumed) spherical charge distr.
+ modifiedFs                ::Array{Float64,1}   ... modified atomic form factor F(q) for such a charge distribution.
source
JenaAtomicCalculator.FormFactor.Settings — Type

struct FormFactor.Settings <: AbstractPropertySettings ... defines a type for the details and parameters of computing alpha-variation parameters.

+ qList                    ::Array{Float64,1} ... List of q-values in [a.u.]
+ printBefore              ::Bool             ... True if a list of selected levels is printed before the  
                                                    actual computations start. 
+ levelSelection           ::LevelSelection   ... Specifies the selected levels, if any.
source
JenaAtomicCalculator.FormFactor.Settings — Method

FormFactor.Settings(set::FormFactor.Settings; qList::Union{Nothing,Array{Float64,1}}=nothing, printBefore::Union{Nothing,Bool}=nothing, levelSelection::Union{Nothing,LevelSelection}=nothing)

... keyword copy-constructor for re-defining selected values of a settings::FormFactor.Settings.
    A `settings::FormFactor.Settings` is returned.
source
JenaAtomicCalculator.FormFactor.amplitude — Method

FormFactor.amplitude(q::Float64, finalLevel::Level, initialLevel::Level, grid::Radial.Grid; display::Bool=false) ... to compute the momentum transfer amplitude <(alphaf Jf, kappa) Ji || T^(1) || alphai J_i> for the given final and initial level. A value::ComplexF64 is returned.

source
JenaAtomicCalculator.FormFactor.computeOutcomes — Method

FormFactor.computeOutcomes(multiplet::Multiplet, nm::Nuclear.Model, grid::Radial.Grid, settings::FormFactor.Settings; output=true) ... to compute (as selected) the alpha-variation parameters for the levels of the given multiplet and as specified by the given settings. The results are printed in neat tables to screen but nothing is returned otherwise.

source
JenaAtomicCalculator.FormFactor.determineOutcomes — Method

FormFactor.determineOutcomes(multiplet::Multiplet, settings::FormFactor.Settings) ... to determine a list of Outcomes's for the computation of the alpha-variation parameters for the given multiplet. It takes into account the particular selections and settings. An Array{FormFactor.Outcome,1} is returned. Apart from the level specification, all physical properties are set to zero during the initialization process.

source
JenaAtomicCalculator.FormFactor.displayOutcomes — Method

FormFactor.displayOutcomes(stream::IO, outcomes::Array{FormFactor.Outcome,1}) ... to display a list of levels that have been selected for the computations. A small neat table of all selected levels and their energies is printed but nothing is returned otherwise.

source
JenaAtomicCalculator.FormFactor.displayResults — Method

FormFactor.displayResults(stream::IO, outcomes::Array{FormFactor.Outcome,1}) ... to display the energies, M_ms and F-parameters, etc. for the selected levels. A neat table is printed but nothing is returned otherwise.

source
JenaAtomicCalculator.FormFactor.modifiedF — Method

FormFactor.modifiedF(q::Float64, level::Level, grid::Radial.Grid) ... to compute the (real) Fourier transform of the (spherically-symmetric) charge distribution but including a correction due to the local (DFS) potential, relative to the rest mass of the electron. A value::Float64 is returned.

source
JenaAtomicCalculator.FormFactor.standardF — Method

FormFactor.standardF(q::Float64, level::Level, grid::Radial.Grid) ... to compute the (real) Fourier transform of the (spherically-symmetric) charge distribution. A value::Float64 is returned.

source

Crystal-field splittings

JenaAtomicCalculator.CrystalField.AbstractCrystalFieldModel — Type

abstract type CrystalField.AbstractCrystalFieldModel ... the physical model used to represent the external crystal-field source acting on the atom/ion. Concrete subtypes carry only what differs between models; every computational function below dispatches on model::AbstractCrystalFieldModel, so a new model (e.g. a superposition model, or an Uldry-style covalency/hybridization correction) can be added later as a new subtype without touching these signatures.

source
JenaAtomicCalculator.CrystalField.CfBasisVector — Type

struct CrystalField.CfBasisVector ... one M_J sublevel of one parent (free-ion) level; the diagonalization basis of a crystal-field computation is the list of all CfBasisVector's belonging to the selected parent level(s) – just one level if no J-mixing is requested, several (possibly of different J) otherwise.

+ M             ::AngularM64   ... M_J projection of this sublevel.
+ parentLevel   ::Level        ... the (unperturbed) free-ion level this M_J value belongs to.
source
JenaAtomicCalculator.CrystalField.CfLevel — Type

struct CrystalField.CfLevel ... one crystal-field (Stark) sublevel, i.e. one eigenstate of the diagonalized crystal-field Hamiltonian. Since the crystal field breaks the M_J degeneracy of (and, under J-mixing, possibly also couples) the parent free-ion level(s), a CfLevel is in general a mixture over several CfBasisVector's and therefore has no single well-defined J or M – unlike a plain ManyElectron.Level.

+ energy    ::Float64                             ... Stark sublevel energy.
+ cfBasis   ::Array{CrystalField.CfBasisVector,1}   ... the common basis of M_J sublevels for the whole CfMultiplet.
+ mc        ::Vector{ComplexF64}                   ... mixing coefficients of this sublevel with regard to cfBasis
                                                        (complex in general, see the module docstring note on
                                                        why the crystal-field matrix is not real for a generic
                                                        lattice).
source
JenaAtomicCalculator.CrystalField.CfMultiplet — Type

struct CrystalField.CfMultiplet ... the ordered list of crystal-field (Stark) sublevels that arise from splitting one or several parent free-ion levels in an external point-charge lattice.

+ name      ::String                       ... a name associated with this crystal-field multiplet.
+ cfLevels  ::Array{CrystalField.CfLevel,1}  ... the list of Stark sublevels.
source
JenaAtomicCalculator.CrystalField.Lattice — Type

struct CrystalField.Lattice ... the set of point charges that together define the external crystal field.

+ ions            ::Array{CrystalField.PointCharge,1}   ... the point charges of the lattice.
+ symmetryLabel   ::String                              ... optional point-group label (e.g. "Oh", "C2"), for
                                                             documentation/display only; no symmetry is
                                                             exploited internally in the first implementation.
source
JenaAtomicCalculator.CrystalField.Outcome — Type

struct CrystalField.Outcome ... defines a type to keep the outcome of a crystal-field computation for one parent level (or, under J-mixing, one group of jointly-diagonalized parent levels).

+ Jlevel        ::Level               ... (one of) the parent free-ion level(s) this outcome refers to.
+ cfMultiplet   ::CrystalField.CfMultiplet  ... the resulting Stark sublevels.
source
JenaAtomicCalculator.CrystalField.PointCharge — Type

struct CrystalField.PointCharge ... one neighboring ion of the crystal lattice, in a spherical frame centered on the atom/ion under study.

+ charge   ::Float64   ... charge of the ion, in units of the elementary charge.
+ rho      ::Float64   ... distance of the ion from the central atom/ion, in Bohr radii.
+ theta    ::Float64   ... polar angle of the ion, in radian.
+ phi      ::Float64   ... azimuthal angle of the ion, in radian.
source
JenaAtomicCalculator.CrystalField.PointChargeModel — Type

struct CrystalField.PointChargeModel <: CrystalField.AbstractCrystalFieldModel ... the classical point-charge crystal-field model of Gaigalas & Kato, CPC 261 (2021) 107772.

+ scaleField   ::Float64   ... empirical overall scaling of the crystal-field strength;
                               1.0 = unscaled ab-initio point-charge value. Provided so an
                               Uldry-style (Phys. Rev. B 85, 125133 (2012)) empirical
                               rescaling can be applied later without introducing a new model
                               type.
source
JenaAtomicCalculator.CrystalField.Settings — Type

struct Settings <: Basics.AbstractPropertySettings ... defines the settings for computing the crystal-field (Stark) splitting of one or several atomic levels.

+ lattice          ::CrystalField.Lattice               ... the external point-charge lattice.
+ model            ::CrystalField.AbstractCrystalFieldModel  ... the crystal-field model to be used.
+ maxRank          ::Int64                               ... maximum tensor rank k retained in the multipole
                                                               expansion of the crystal-field potential
                                                               (k=0 is omitted throughout: it is a common
                                                               energy shift of all levels and does not
                                                               contribute to the splitting pattern).
                                                               PREFER maxRank = 4 OVER 6 WITH BOX/B-SPLINE
                                                               ORBITALS. The r < R point-charge model weights
                                                               the orbital by r^k, so k = 6 amplifies the tiny
                                                               numerical tail that a B-spline basis leaves out
                                                               to the box boundary. Measured on a hydrogenic
                                                               4f generated on such a grid: <r^6> ~ 4e5 against
                                                               <r^2> ~ 1.1, from a tail near r ~ 600 a.u. that
                                                               carries no physics whatever. The cost of the cap
                                                               is small and has been measured too -- for Er3+
                                                               4f^11 the total splitting is 359.25 cm^-1 at
                                                               k = 4 and 371.42 at k = 6, i.e. k = 6 adds ~3 %,
                                                               which is far less than the tail can distort.
                                                               This is a GENERIC hazard of the r < R model at
                                                               high rank with box-basis orbitals, not something
                                                               peculiar to this module; curing it needs either
                                                               properly decaying bound orbitals or an explicit
                                                               tail cutoff, and neither exists here yet.
+ includeJmixing   ::Bool                                 ... if true, allow mixing between the selected levels
                                                               even if they belong to different total J.
+ printBefore      ::Bool                                 ... True if a list of selected levels is printed
                                                               before the actual computations start.
+ levelSelection   ::LevelSelection                       ... specifies the levels for which the crystal-field
                                                               splitting is to be computed.
source
JenaAtomicCalculator.CrystalField.Settings — Method

CrystalField.Settings(set::CrystalField.Settings; lattice::Union{Nothing,Lattice}=nothing, model::Union{Nothing,AbstractCrystalFieldModel}=nothing, maxRank::Union{Nothing,Int64}=nothing, includeJmixing::Union{Nothing,Bool}=nothing, printBefore::Union{Nothing,Bool}=nothing, levelSelection::Union{Nothing,LevelSelection}=nothing)

... keyword copy-constructor for re-defining selected values of a settings::CrystalField.Settings.
    A `settings::CrystalField.Settings` is returned.
source
JenaAtomicCalculator.CrystalField.characteristicSplitting — Method

CrystalField.characteristicSplitting(cfMultiplet::CrystalField.CfMultiplet) ... computes the "characteristic crystal-field splitting" (CXS) of Uldry, Vernay & Delley, Phys. Rev. B 85, 125133 (2012), Sec. II F: a single scalar descriptor of the overall strength of a crystal-field multiplet, defined there as the energy difference between the barycenter of the group of Stark sublevels lying above the largest gap in the spectrum and that of the group lying below it (their own examples use case-specific variants, e.g. "two lowest vs. three highest" for Cu2+/CuO, or "highest negative vs. average of positive" for Ti3+/LaTiO3; splitting the spectrum at its single largest gap generalizes both of these into one algorithm, since that gap is exactly where their examples split it by hand). A value::Float64 (in Hartree) is returned; 0.0 if cfMultiplet has fewer than 2 sublevels.

+ cfMultiplet   ::CrystalField.CfMultiplet   ... the Stark sublevels of one crystal-field outcome.
source
JenaAtomicCalculator.CrystalField.computeInteractionMatrix — Method

CrystalField.computeInteractionMatrix(levels::Array{Level,1}, lattice::CrystalField.Lattice, model::CrystalField.AbstractCrystalFieldModel, grid::Radial.Grid, maxRank::Int64) ... builds the full crystal-field Hamiltonian matrix over the MJ-resolved basis of all levels (one CrystalField.CfBasisVector per MJ of every level in levels), following the Wigner-Eckart decomposition of Eq. (3): for every tensor rank k = 1, .., maxRank the MJ-independent reduced matrix element <levelP||C^(k)||levelQ> is computed once (via CrystalField.reducedMatrixElement) and reused for every pair of MJ values, each weighted by CrystalField.multipoleLatticeSum(lattice,k,q) and the appropriate 3-j symbol and phase. The off-diagonal (crystal-field) part is scaled by model.scaleField if model is a CrystalField.PointChargeModel. The matrix is generally COMPLEX (see the module docstring note) since CrystalField.multipoleLatticeSum(lattice,k,q) is complex for any lattice without the right symmetry to make it real; the returned matrix is explicitly Hermitized ((matrix+matrix')/2, adjoint not transpose) as a safeguard against residual floating-point asymmetry, since the upper and lower triangles are summed independently rather than mirrored. A tuple (matrix::Array{ComplexF64,2}, cfBasis::Array{CrystalField.CfBasisVector,1}) is returned.

+ levels   ::Array{Level,1}                             ... the parent (unperturbed) levels to be diagonalized jointly.
+ lattice  ::CrystalField.Lattice                        ... the external point-charge lattice.
+ model    ::CrystalField.AbstractCrystalFieldModel      ... the crystal-field model to be applied.
+ grid     ::Radial.Grid                                ... the radial grid.
+ maxRank  ::Int64                                      ... maximum tensor rank k to be included.
source
JenaAtomicCalculator.CrystalField.computeOutcomes — Method

CrystalField.computeOutcomes(multiplet::Multiplet, lattice::CrystalField.Lattice, grid::Radial.Grid, settings::CrystalField.Settings) ... the standard top-level driver of the module. Selects the levels of multiplet specified by settings.levelSelection (or just the lowest level if no selection is active) and computes their crystal-field splitting: if settings.includeJmixing == false, each selected level is diagonalized separately (its own MJ manifold only, one CrystalField.Outcome per level); if settings.includeJmixing == true, all selected levels are diagonalized jointly in a single, common MJ-resolved basis via CrystalField.computeRepresentation(...), and a single CrystalField.Outcome is returned. An Array{CrystalField.Outcome,1} is returned.

    THIS IS THE DIRECT FORM, in which the lattice is handed over separately. `settings.lattice` is then NOT
    read and the argument wins, so the two must not be filled with different lattices. The STANDARD route is
    the method below, taking `(multiplet, nm, grid, settings)` as every other property does and reading the
    lattice from the settings, which is where an `Atomic.Computation` has to carry it.

+ multiplet   ::Multiplet              ... the (unperturbed) atomic levels.
+ lattice     ::CrystalField.Lattice    ... the external point-charge lattice;  overrides settings.lattice.
+ grid        ::Radial.Grid            ... the radial grid.
+ settings    ::CrystalField.Settings   ... the crystal-field computation settings.
source
JenaAtomicCalculator.CrystalField.computeOutcomes — Method

CrystalField.computeOutcomes(multiplet::Multiplet, nm::Nuclear.Model, grid::Radial.Grid, settings::CrystalField.Settings; output=true) ... the STANDARD-ROUTE entry point, and the reason it exists is the signature rather than the physics: every property module is reached by Basics.perform through (multiplet, nuclearModel, grid, settings), so this is what lets a crystal-field splitting be asked for with Atomic.Computation(...; propertySettings=[CrystalField.Settings(...)]) like any other property, instead of by calling the module directly. The lattice is taken from settings.lattice, which is where the standard route must carry it, and the results are printed to screen and to the summary file as every registered property does. An Array{CrystalField.Outcome,1} is returned, or nothing for output=false.

    `nm` IS ACCEPTED AND NOT USED, deliberately: the crystal field is set by the EXTERNAL point charges and
    is independent of the nucleus, so there is nothing for it to do here. It is in the signature because
    `perform` passes it to every property alike.

+ multiplet   ::Multiplet              ... the (unperturbed) atomic levels.
+ nm          ::Nuclear.Model          ... the nuclear model;  carried by the standard route, unused here.
+ grid        ::Radial.Grid            ... the radial grid.
+ settings    ::CrystalField.Settings   ... the settings, whose `lattice` field supplies the point charges.
source
JenaAtomicCalculator.CrystalField.computeRepresentation — Method

CrystalField.computeRepresentation(levels::Array{Level,1}, lattice::CrystalField.Lattice, model::CrystalField.AbstractCrystalFieldModel, grid::Radial.Grid, maxRank::Int64) ... builds the crystal-field representation for the given (possibly J-mixed) set of parent levels: calls CrystalField.computeInteractionMatrix(...) to obtain the full (complex Hermitian) Hamiltonian matrix over the M_J-resolved basis, diagonalizes it with LinearAlgebra.eigen(Hermitian(matrix)) – NOT Basics.diagonalize(MatrixWithLinearAlgebra(), ...), which only accepts real matrices and is therefore unsuitable here, see the module docstring note – and repacks the eigenpairs into a CrystalField.CfMultiplet of CrystalField.CfLevel's. Hermiticity guarantees real eigenvalues even though the matrix and eigenvectors are complex. A cfMultiplet::CrystalField.CfMultiplet is returned.

+ levels   ::Array{Level,1}                             ... the parent (unperturbed) levels to be diagonalized jointly.
+ lattice  ::CrystalField.Lattice                        ... the external point-charge lattice.
+ model    ::CrystalField.AbstractCrystalFieldModel      ... the crystal-field model to be applied.
+ grid     ::Radial.Grid                                ... the radial grid.
+ maxRank  ::Int64                                      ... maximum tensor rank k to be included.
source
JenaAtomicCalculator.CrystalField.displayResults — Method

CrystalField.displayResults(stream::IO, outcomes::Array{CrystalField.Outcome,1}) ... prints the crystal-field (Stark) splitting pattern for every outcome to stream, sorted by increasing sublevel energy and given relative to the lowest sublevel of each outcome, both in Hartree and in cm^-1 (directly comparable to Table 1 of Gaigalas & Kato), followed by the characteristic crystal-field splitting (CXS) of Uldry, Vernay & Delley (Sec. II F). Nothing is returned.

+ stream     ::IO                              ... the output stream.
+ outcomes   ::Array{CrystalField.Outcome,1}    ... the computed crystal-field outcomes.
source
JenaAtomicCalculator.CrystalField.electrostaticIntegral — Method

CrystalField.electrostaticIntegral(k::Int64, orbitalA::Radial.Orbital, orbitalB::Radial.Orbital, grid::Radial.Grid) ... computes the one-electron reduced matrix element [kappaa||C^(k)||kappab] * <r^k>ab (Eq. (4) of Gaigalas & Kato) of the rank-k crystal-field tensor operator between two relativistic orbitals, by combining AngularMomentum.CLreducedme(...) (which already enforces the la+l_b+k parity selection rule of Eq. (5)) with RadialIntegrals.rkDiagonal(k, orbitalA, orbitalB, grid). A value::Float64 is returned.

+ k          ::Int64            ... tensor rank.
+ orbitalA   ::Radial.Orbital   ... one relativistic orbital.
+ orbitalB   ::Radial.Orbital   ... the other relativistic orbital.
+ grid       ::Radial.Grid      ... the radial grid.
source
JenaAtomicCalculator.CrystalField.fitScaleField — Method

CrystalField.fitScaleField(levels::Array{Level,1}, lattice::CrystalField.Lattice, grid::Radial.Grid, targetSplitting::Float64, maxRank::Int64; tolerance::Float64=1.0e-6, maxIterations::Int64=20)

... finds the CrystalField.PointChargeModel.scaleField value -- the S_xtal empirical rescaling
    parameter of Uldry, Vernay & Delley, Phys. Rev. B 85, 125133 (2012), Sec. IV -- for which
    CrystalField.characteristicSplitting(...) of the crystal-field representation of `levels`
    matches `targetSplitting` (in Hartree). Whenever `levels` contains a single parent level
    (no J-mixing), the interaction matrix's diagonal is a multiple of the identity (the shared
    level energy), so only the scaleField-proportional off-diagonal part affects the eigenvalue
    differences: CXS is then EXACTLY proportional to scaleField, and a single evaluation at
    scaleField=1.0 already gives the exact answer. Under J-mixing this proportionality is only
    approximate, so a short secant iteration (seeded from that exact linear estimate) refines it
    further. A scaleField::Float64 is returned.

+ levels            ::Array{Level,1}      ... the parent (unperturbed) levels to be diagonalized jointly.
+ lattice           ::CrystalField.Lattice ... the external point-charge lattice.
+ grid              ::Radial.Grid         ... the radial grid.
+ targetSplitting   ::Float64             ... the target characteristic splitting, in Hartree.
+ maxRank           ::Int64               ... maximum tensor rank k to be included.
+ tolerance         ::Float64             ... relative convergence tolerance on targetSplitting.
+ maxIterations     ::Int64               ... maximum number of secant iterations.
source
JenaAtomicCalculator.CrystalField.multipoleLatticeSum — Method

CrystalField.multipoleLatticeSum(lattice::CrystalField.Lattice, k::Int64, q::Int64) ... computes the purely geometric lattice-sum coefficient of rank k, component q,

        A_kq = sum_i  charge_i / rho_i^(k+1) * (-1)^(q+1) sqrt(4pi/(2k+1)) Y^k_{-q}(theta_i, phi_i)

    summed over the ions of `lattice` (Eq. (1)-(2) of Gaigalas & Kato, CPC 261 (2021) 107772,
    with the r<R branch of Eq. (2) since every lattice ion lies outside the electron shell of
    the central atom/ion); independent of the atomic system. Uses AngularMomentum.sphericalYlm(...).
    A value::ComplexF64 is returned.

+ lattice   ::CrystalField.Lattice   ... the external point-charge lattice.
+ k         ::Int64                 ... tensor rank of the multipole term.
+ q         ::Int64                 ... tensor component, -k <= q <= k.
source
JenaAtomicCalculator.CrystalField.reducedMatrixElement — Method

CrystalField.reducedMatrixElement(k::Int64, rLevel::Level, sLevel::Level, grid::Radial.Grid) ... computes the rank-k reduced matrix element <rLevel||C^(k)||sLevel> between two ASF levels, by looping over all CSF pairs of the two levels' own basis, obtaining the many-electron spin-angular coefficients from SpinAngular.computeCoefficients(...) for a SpinAngular.OneParticleOperator(k, ...), contracting each with CrystalField.electrostaticIntegral(...) and finally sandwiching the resulting CSF x CSF matrix between the two levels' mixing vectors – following exactly the pattern of Hfs.amplitude (module-Hfs.jl). As in Hfs.amplitude, each coeff.T is divided by sqrt(2*ja+1) to undo the internal "GRASP-like" normalization that SpinAngular.computeCoefficients applies for rank>0 one-particle operators (see the note on Hfs.amplitude). No same-parity restriction is imposed here: for odd k the la+lb+k selection rule already built into CLreduced_me allows rLevel and sLevel to belong to different overall parities, which is exactly the "ASF mixing with different parities" capability described in the Program Summary of Gaigalas & Kato. A value::Float64 is returned.

+ k        ::Int64   ... tensor rank.
+ rLevel   ::Level   ... bra level.
+ sLevel   ::Level   ... ket level.
+ grid     ::Radial.Grid   ... the radial grid.
source

Einstein A and B coefficients

JenaAtomicCalculator.Einstein.Channel — Type

struct Einstein.Channel ... defines a type for a single Einstein emission/absorption channel that specifies the multipole, gauge and amplitude.

+ multipole         ::EmMultipole        ... Multipole of the photon emission/absorption.
+ gauge             ::EmGauge            ... Gauge for dealing with the (coupled) radiation field.
+ amplitude         ::Complex{Float64}   ... Amplitude of this multiple channel.
source
JenaAtomicCalculator.Einstein.Line — Type

struct Einstein.Line ... defines a type for a Einstein line that may include the definition of sublines and their corresponding amplitudes.

+ initialLevel   ::Level            ... initial-(state) level
+ finalLevel     ::Level            ... final-(state) level
+ omega          ::Float64          ... photon energy = transition energy
+ photonRate     ::EmProperty       ... Total rate of this line.
+ angularBeta    ::EmProperty       ... Angular beta_2 coefficient.
+ channels       ::Array{Einstein.Channel,1}   ... List of radiative (photon) channels.
source
JenaAtomicCalculator.Einstein.Line — Method

Einstein.Line(initialLevel::Level, finalLevel::Level, photonRate::EmProperty) ... constructor an Einstein line between a specified initial and final level. A line::Einstein.Line is returned.

source
JenaAtomicCalculator.Einstein.Settings — Type

struct Einstein.Settings <: AbstractPropertySettings ... defines a type for the details and parameters of computing Einstein lines and coefficients

+ multipoles              ::Array{EmMultipoles}          ... Specifies the multipoles of the radiation field that are to be included.
+ printBefore             ::Bool                         ... True, if all energies and lines are printed before their evaluation.
+ lineSelection           ::LineSelection                ... Specifies the selected levels, if any.
+ photonEnergyShift       ::Float64                      ... An overall energy shift for all photon energies.
+ mimimumPhotonEnergy     ::Float64                      ... minimum transition energy for which (photon) transitions are included into
                                                             the
                                                                computation.
+ maximumPhotonEnergy     ::Float64                      ... maximum transition energy for which (photon) transitions are included.
source
JenaAtomicCalculator.Einstein.Settings — Method

Einstein.Settings(set::Einstein.Settings; multipoles::Union{Nothing,Array{EmMultipole,1}}=nothing, printBefore::Union{Nothing,Bool}=nothing, lineSelection::Union{Nothing,LineSelection}=nothing, photonEnergyShift::Union{Nothing,Float64}=nothing, mimimumPhotonEnergy::Union{Nothing,Float64}=nothing, maximumPhotonEnergy::Union{Nothing,Float64}=nothing)

... keyword copy-constructor for re-defining selected values of a settings::Einstein.Settings.
    A `settings::Einstein.Settings` is returned.
source
JenaAtomicCalculator.Einstein.computeAmplitudesProperties — Method

Einstein.computeAmplitudesProperties(line::Einstein.Line, grid::Radial.Grid, settings::Einstein.Settings) ... to compute all amplitudes and properties of the given line; a line::Einstein.Line is returned for which the amplitudes and properties are now evaluated.

source
JenaAtomicCalculator.Einstein.computeLines — Method

Einstein.computeLines(multiplet::Multiplet, grid::Radial.Grid, settings::Einstein.Settings; output::Bool=true) ... to compute the Einstein transition amplitudes and all properties as requested by the given settings. A list of lines::Array{Einstein.Lines} is returned.

source
JenaAtomicCalculator.Einstein.determineChannels — Method

Einstein.determineChannels(finalLevel::Level, initialLevel::Level, settings::Einstein.Settings) ... to determine a list of Einstein.Channel for a transitions from the initial to final level and by taking into account the particular settings of for this computation; an Array{Einstein.Channel,1} is returned.

source
JenaAtomicCalculator.Einstein.determineLines — Method

Einstein.determineLines(multiplet::Multiplet, settings::Einstein.Settings) ... to determine a list of EinsteinLine's for transitions between the lines from the given multiplet and by taking into account the particular selections and settings of for this computation; an Array{Einstein.Line,1} is returned. Apart from the level specification, all physical properties are set to zero during the initialization process.

source
JenaAtomicCalculator.Einstein.displayLifetimes — Method

Einstein.displayLifetimes(stream::IO, lines::Array{Einstein.Line,1}) ... to list all lifetimes of the selected lines as can be derived from the calculated data. A neat table is printed but nothing is returned otherwise.

source
JenaAtomicCalculator.Einstein.displayLines — Method

Einstein.displayLines(stream::IO, lines::Array{Einstein.Line,1}) ... to display a list of lines and channels that have been selected due to the prior settings. A neat table of all selected transitions and energies is printed but nothing is returned otherwise.

source
JenaAtomicCalculator.Einstein.displayRates — Method

Einstein.displayRates(stream::IO, lines::Array{Einstein.Line,1}) ... to list all results, energies, rates, etc. of the selected lines. A neat table is printed but nothing is returned otherwise.

source

Hyperfine coefficients and energy splittings

JenaAtomicCalculator.Hfs.HfBasisVector — Type

struct Hfs.HfBasisVector ... defines a type for a hyperfine basis vector that enables one to think about and deal with individual hyperfine levels. These hyperfine levels have representations with regard to (tensor) product states, which are formed from a set of isomeric states as well as a set of electronic ASF level J. Hyperfine basis vectors are obtained from diagonalizing the hyperfine Hamiltonian in a tensor basis of isomeric + ASF states.

+ F         ::AngularJ64        ... Total angular momentum F
+ parity    ::Parity            ... Total parity of the basis vector = nuclear x electronic parity.
+ isomer    ::Nuclear.Isomer    ... Isomeric state of the nucleus.
+ LevelJ    ::Basis             ... Electronic level that is part of the electronic basis.

There is no need to introduce a type HfBasis since such a hfBasis = Hfs.HfBasisVector[...] can be readily formed at all
source
JenaAtomicCalculator.Hfs.HfLevel — Type

struct Hfs.HfLevel ... defines a type for HfLevel with a representation that refers to a product basis of isomeric and ASF states; the HfLevel is the pendant to a (electronic) Level/state, if hyperfine-resolved transitions are considered. Each hyperfine level has a representation mc that refers to the hfBasis, and which contains all information about the representation of the underlying nuclear and electronic basis states. The electronic basis is formed by a selected set of ASF, typically taken from some (electronic) multiplet. In contrast to a pure (electronic) CSF basis, the use of ASF simplifies the interpretation of physical findings but cannot reduce the computational effort (perhaps, even results in slightly increase the computational effort). A HfLevel is defined by:

+ F              ::AngularJ64               ... Total angular momentum F.
+ M              ::AngularM64               ... Total projection M, only defined if a particular magnetic sublevel is referred to.
+ parity         ::Parity                   ... Parity of the level which corresponds to the electronic system.
+ energy         ::Float64                  ... energy
+ hfBasisVectors ::Array{HfBasisVector,1}   ... the product basis nuclear (isomeric) state x selected ASF.
+ mc             ::Vector{Float64}          ... Vector of mixing coefficients w.r.t hfBasisVectors.
source
JenaAtomicCalculator.Hfs.HfMultiplet — Type

struct Hfs.HfMultiplet ... defines a type for a multiplet of hyperfine levels (HfLevel's) which are based on a (tensor) product basis of nuclear (isomeric) x ASF states.

+ name     ::String                ... A name associated to the multiplet.
+ hfLevels ::Array{HfLevel,1}      ... List of hyperfine levels (HfLevel's)
source
JenaAtomicCalculator.Hfs.InteractionMatrix — Type

struct Hfs.InteractionMatrix ... defines a type for storing the T^1 and T^2 interaction matrices for a given basis.

+ calcM1   ::Bool               ... true, if the matrixM1 has been calculated and false otherwise.
+ calcE2   ::Bool               ... true, if the matrixE2 has been calculated and false otherwise.
+ calcM3   ::Bool               ... true, if the matrixM3 has been calculated and false otherwise.
+ matrixM1 ::Array{Float64,2}   ... T^M1 interaction matrix
+ matrixE2 ::Array{Float64,2}   ... T^E2 interaction matrix
+ matrixM3 ::Array{Float64,2}   ... T^M3 interaction matrix
source
JenaAtomicCalculator.Hfs.Outcome — Type

struct Hfs.Outcome ... defines a type to keep the outcome of a HFS computation, such as the HFS A and B coefficients as well other results.

    NO g_J FACTOR IS CARRIED HERE, and that is deliberate. A `gJ` field existed until 18-Aug-2026 but nothing ever
    assigned it: `computeAmplitudesProperties` constructed the outcome with the literal `1.`, so every HFS table JAC
    printed showed g_J = 1.00000000 for every level, as though computed. Hfs CANNOT supply it -- the Lande factor comes
    from the Zeeman N^(1) operator, not from the hyperfine T^(1), whose radial weight is different -- and it cannot
    borrow it either, since `LandeZeeman` already calls `Hfs.amplitude` and the dependency would be circular. Use
    `LandeZeeman` for g_J; it is validated to six decimals against Andersson & Jonsson, cf. `example-Cd.jl`.

+ Jlevel                    ::Level            ... Atomic level to which the outcome refers to.
+ AIoverMu                  ::Float64          ... HFS A * I / mu value.
+ BoverQ                    ::Float64          ... HFS B / Q value
+ CoverOmega                ::Float64          ... HFS C / Omega value
+ amplitudeM1               ::Complex{Float64} ... M1 amplitude
+ amplitudeE2               ::Complex{Float64} ... E2 amplitude
+ amplitudeM3               ::Complex{Float64} ... M3 amplitude
+ nuclearI                  ::AngularJ64       ... nuclear spin
+ hfsMultiplet              ::HfMultiplet      ... Multiplet of HfLevel's as associated with the JLevel.
source
JenaAtomicCalculator.Hfs.Outcome — Method

Hfs.Outcome() ... constructor for an empty instance of Hfs.Outcome for the computation of HFS properties. A outcome::Hfs.Outcome is returned.

source
JenaAtomicCalculator.Hfs.Settings — Type

struct Settings <: AbstractPropertySettings ... defines a type for the details and parameters of computing HFS A and B coefficients.

+ calcM1                    ::Bool             ... True if T^M1-amplitudes (HFS A values) need to be calculated, and false otherwise.
+ calcE2                    ::Bool             ... True if T^E2-amplitudes (HFS B values) need to be calculated, and false otherwise.
+ calcM3                    ::Bool             ... True if T^M3-amplitudes (HFS C values) need to be calculated, and false otherwise.
+ calcNondiagonal           ::Bool             
    ... True if also (non-)diagonal hyperfine amplitudes are to be calculated and printed, and false otherwise.
+ calcHfMultiplet           ::Bool             
    ... True if representation of all hyperfine levels need to be generated in the IJF-coupled ASF basis;
        only the nuclear spin and the selected atomic levels are considered in the basis. false otherwise.
+ printBefore               ::Bool             ... True if a list of selected levels is printed before the actual computations start.
+ levelSelection            ::LevelSelection   ... Specifies the selected levels, if any.
source
JenaAtomicCalculator.Hfs.Settings — Method

Hfs.Settings(set::Hfs.Settings; calcM1::Union{Nothing,Bool}=nothing, calcE2::Union{Nothing,Bool}=nothing, calcM3::Union{Nothing,Bool}=nothing, calcNondiagonal::Union{Nothing,Bool}=nothing, calcHfMultiplet::Union{Nothing,Bool}=nothing, printBefore::Union{Nothing,Bool}=nothing, levelSelection::Union{Nothing,LevelSelection}=nothing)

... keyword copy-constructor for re-defining selected values of a settings::Hfs.Settings.
    A `settings::Hfs.Settings` is returned.
source
JenaAtomicCalculator.Hfs.Settings — Method

Hfs.Settings(; calcM1::Bool=true, calcE2::Bool=false, calcM3::Bool=false, calcNondiagonal::Bool=false, calcHfMultiplet::Bool=false, printBefore::Bool=false, levelSelection::LevelSelection=LevelSelection()) ... keyword constructor to create a Hfs.Settings with selected non-default values. A settings::Hfs.Settings is returned.

source
JenaAtomicCalculator.Basics.sortByEnergy — Method

Basics.sortByEnergy(multiplet::Hfs.HfMultiplet) ... to sort all hyperfine levels in the multiplet into a sequence of increasing energy; a (new) multiplet::Hfs.HfMultiplet is returned.

source
JenaAtomicCalculator.Basics.tabulate — Method

Basics.tabulate(stream::IO, ::HfEnergies, multiplet::Hfs.HfMultiplet) ... tabulates the energies of all hyperfine levels of the given multiplet; nothing is returned.

source
JenaAtomicCalculator.Basics.tabulate — Method

Basics.tabulate(stream::IO, ::HfEnergiesRelative, multiplet::Hfs.HfMultiplet) ... tabulates the hyperfine level energies relative to the lowest level of the multiplet; nothing is returned.

source
JenaAtomicCalculator.Hfs.amplitude — Method

Hfs.amplitude(mp::EmMultipole, rLevel::Level, sLevel::Level, grid::Radial.Grid; printout::Bool=true) ... to compute the T^(M1), T^(E2) or T^(M3) hyperfine amplitude for a given pair of levels. A value::ComplexF64 is returned.

    CONVENTION -- read this before using the result in a recoupling formula (clarified 05-Aug-2026). What is returned is the
    "GRASP-like" amplitude, i.e. <alpha_r J_r || T^(mp) || alpha_s J_s> / sqrt(2J_r+1), and NOT the reduced matrix element in the
    standard Wigner-Eckart normalization. That is exactly what the A, B and C constants formed in computeAmplitudesProperties expect --
    A*I/mu = amplitude/sqrt(J(J+1)), verified against the measured A(H 1s) to 0.06% -- but it is NOT what a Wigner-6j expression
    expects. Use Hfs.reducedMeElectronic for the latter; building a 6-j directly on this function is what left
    computeHyperfineRepresentation too small by sqrt(2J+1) until 05-Aug-2026.

    Note (26-Jul-2026): coeff.T, for rank>0 one-particle operators, is returned by SpinAngular.computeCoefficientsNonScalar already in
    "GRASP-like" convention, i.e. with an internal factor sqrt(2*j_a+1) applied (see the active "GRASP like spin-angular coefficient"
    step in that function) -- this is NOT what the paper's Eq. (48)-type reduced-matrix-element sum <leftCsf||W^(k)||rightCsf> = sum_ab
    d^k_ab [n_a kappa_a||w^(k)||n_b kappa_b] needs (the "pure" coefficient, without that factor). By contrast, IsotopeShift.amplitude's
    rank-0 case uses SpinAngular.computeCoefficientsScalar, where the equivalent conversion step is deliberately commented out, and
    IsotopeShift.amplitude applies its own sqrt(2j_a+1) factor externally to match its formula. This function previously used coeff.T
    directly with no compensating division, leaving an uncorrected sqrt(2j_a+1) factor in every M1/E2/M3 hyperfine amplitude --
    confirmed for H(1s) M1: the A-constant was too large by ~1.42 (= sqrt(2), the j=1/2 value) after the separate missing-alpha fix in
    InteractionStrength.hfs_tM1. Fixed by dividing each term by sqrt(2*j_a+1), undoing the internal GRASP-like conversion, matching
    IsotopeShift's convention.
source
JenaAtomicCalculator.Hfs.computeAmplitudesProperties — Method

Hfs.computeAmplitudesProperties(outcome::Hfs.Outcome, nm::Nuclear.Model, grid::Radial.Grid, settings::Hfs.Settings, im::Hfs.InteractionMatrix) ... to compute all amplitudes and properties of for a given level; an outcome::Hfs.Outcome is returned for which the amplitudes and properties are evaluated explicitly.

source
JenaAtomicCalculator.Hfs.computeHyperfineMultiplet — Method

Hfs.computeHyperfineMultiplet(level::Level, nm::Nuclear.Model, grid::Radial.Grid) ... to compute a hyperfine multiplet, i.e. a representation of hyperfine levels within a hyperfine-coupled basis as defined by the given (electronic) level; a hfMultiplet::hfMultiplet is returned.

source
JenaAtomicCalculator.Hfs.computeHyperfineMultiplet — Method

Hfs.computeHyperfineMultiplet(multiplet::Multiplet, nm::Nuclear.Model, grid::Radial.Grid, settings::Hfs.Settings; output=true) ... to compute a hyperfine multiplet, i.e. a representation of hyperfine levels within a hyperfine-coupled basis as defined by the given (electronic) multiplet; an hfMultiplet::Hfs.HfMultiplet is returned.

source
JenaAtomicCalculator.Hfs.computeHyperfineRepresentation — Method

Hfs.computeHyperfineRepresentation(hfBasisVectors::Array{HfBasisVector,1}, grid::Radial.Grid; hfMultipoles::Array{EmMultipole,1}=EmMultipole[Basics.M1, Basics.E2], printout::Bool=false) ... to set-up and diagonalize the Hamiltonian matrix of H^(DFB) + H^(hfs) within the atomic hyperfine (IJF-coupled) basis; a hfMultiplet::Hfs.HfMultiplet is returned.

    REPAIRED 05-Aug-2026. This function had never run: its body addressed an undefined `hfBasis.vectors[...]` instead of its own
    argument, it called Hfs.HfLevel(...) with seven arguments against a six-field struct, and it carried `* 1.0e-6 # fudge-factor to
    keep HFS interaction small` on BOTH the magnetic and the electric contribution -- a debugging leftover that would have scaled every
    hyperfine splitting down by a million. The fudge factor is removed: the splitting of the initial ion is precisely the observable
    this representation exists to produce. Nothing can regress, since the function could not previously be called.

    The matrix is block diagonal in F and parity by construction (the guards below), so the eigenvectors do not mix different F; each
    hyperfine level is Sum_k mc[k] |(I J_k) F>, where the Clebsch-Gordan coupling already sits inside each HfBasisVector and mc
    describes the J-mixing among vectors of equal F.

    With mu = Q = 0 the hyperfine Hamiltonian vanishes identically and only the electronic energies remain on the diagonal. Since those
    are non-degenerate, the eigenvectors come out as pure unit vectors, i.e. mc = [.. 1.0 ..] on a single basis vector. The "no
    hyperfine mixing" case therefore needs no separate code path -- it is the exact output of this same routine.
source
JenaAtomicCalculator.Hfs.computeInteractionAmplitudeM — Method

Hfs.computeInteractionAmplitudeM(mp::EmMultipole, leftIsomer::Nuclear.Isomer, rightIsomer::Nuclear.Isomer) ... to compute the hyperfine interaction amplitude (<leftIsomer || M^(mp)) || rightIsomer>) for the interaction of two nuclear levels; this ME is geometrically fixed if the left and right isomer are the same, and it depends on the nuclear ME otherwise. An amplitude::ComplexF64 is returned.

source
JenaAtomicCalculator.Hfs.computeInteractionAmplitudeT — Method

Hfs.computeInteractionAmplitudeT(mp::EmMultipole, aLevel::Level, bLevel, grid::Radial.Grid) ... to compute the T^(mp) interaction amplitude for two levels of the same basis, i.e. (<aLevel || T^(mp) || bLevel>). A me::ComplexF64 is returned.

    NO CALLER IN `src/`: the A, B and C constants are formed inside `computeAmplitudesProperties`, which builds the
    electronic part inline. This offers the same quantity as a SEPARATE reduced matrix element, for a user who wants
    <a || T^(mp) || b> itself rather than the constants derived from it. Its nuclear partner
    `computeInteractionAmplitudeM` IS called, from `Hfs` and from `HyperfineInduced`.
source
JenaAtomicCalculator.Hfs.computeInteractionMatrix — Method

Hfs.computeInteractionMatrix(basis::Basis, grid::Radial.Grid, settings::Hfs.Settings) ... to compute the T^M1 and/or T^E2 interaction matrices for the given basis, i.e. (<csfr || T^(n)) || csfs>). An im::Hfs.InteractionMatrix is returned.

    Note (26-Jul-2026): each coeff.T here is divided by sqrt(2*j_a+1), undoing the "GRASP-like" sqrt(2*j_a+1) factor that
    SpinAngular.computeCoefficientsNonScalar applies internally for rank>0 one-particle operators -- see the matching note on
    Hfs.amplitude for the full explanation. Applies uniformly to the M1, E2, and M3 blocks below (all use the same rank>0 SpinAngular
    path).
source
JenaAtomicCalculator.Hfs.computeModifiedEinsteinRates — Method

Hfs.computeModifiedEinsteinRates(upperOutcome::Outcome, lowerOutcome::Outcome, multipoles::Array{EmMultipole,1}, gauge::EmGauge, grid::Radial.Grid) ... to compute and tabulate the modified Einstein amplitudes and rates for the hyperfine-resolved transitions between the upper and lower outcome. The procedures assumes that the two outcomes provide a proper IJF expansion (multiplet) of the hyperfine levels of interest. A neat table is printed but nothing is returned otherwise

    NO CALLER IN `src/`: it is a user entry point that computes AND tabulates, i.e. it is meant to be invoked for
    its printed table rather than for a returned value that another routine consumes.
source
JenaAtomicCalculator.Hfs.computeOutcomes — Method

Hfs.computeOutcomes(multiplet::Multiplet, nm::Nuclear.Model, grid::Radial.Grid, settings::Hfs.Settings; output=true) ... to compute (as selected) the HFS A, B and C parameters as well as hyperfine energy splittings for the levels of the given multiplet and as specified by the given settings. The results are printed in neat tables to screen and, if requested, an arrays{Hfs.Outcome,1} with all the results are returned.

source
JenaAtomicCalculator.Hfs.defineHyperfineBasis — Method

Hfs.defineHyperfineBasis(level::Level, nm::Nuclear.Model) ... to define/set-up an atomic hyperfine (IJF-coupled) basis for the given electronic level; an Array{Hfs.HfBasisVector,1} is returned.

source
JenaAtomicCalculator.Hfs.defineHyperfineBasis — Method

Hfs.defineHyperfineBasis(multiplet::Multiplet, nm::Nuclear.Model; printout::Bool=true) ... the single-isomer method; an Array{Hfs.HfBasisVector,1} is returned. It simply assembles one Nuclear.Isomer from the given nuclear model and defers to the method above, so that the two cannot diverge.

source
JenaAtomicCalculator.Hfs.defineHyperfineBasis — Method

Hfs.defineHyperfineBasis(multiplet::Multiplet, isomers::Array{Nuclear.Isomer,1}; printout::Bool=true) ... to define/set-up an atomic hyperfine (IJF-coupled) basis for the given electronic multiplet and ONE OR MORE nuclear states; an Array{Hfs.HfBasisVector,1} is returned, one vector for every (isomer, electronic level, F) triple allowed by F = I + J.

    Admitting more than one isomer (06-Aug-2026) is what makes nuclear hyperfine mixing expressible: two nuclear levels of the same F,
    built on the same electronic level, then appear as two basis vectors, and diagonalizing the hyperfine matrix over that basis mixes
    them. Nothing else in the machinery changes. The parity stored on each vector is the TOTAL one, nuclear x electronic.

    REPAIRED 05-Aug-2026; see the note on the single-level method above. The nuclear moments are carried into each basis vector through
    a Nuclear.Isomer built from the given model, so that a model with mu = Q = 0 produces a basis whose hyperfine Hamiltonian vanishes
    identically -- the device used to switch the hyperfine structure of intermediate and final levels off without a separate code path.
source
JenaAtomicCalculator.Hfs.determineOutcomes — Method

Hfs.determineOutcomes(multiplet::Multiplet, settings::Hfs.Settings) ... to determine a list of Outcomes's for the computation of HFS A- and B-parameters for the given multiplet. It takes into account the particular selections and settings. An Array{Hfs.Outcome,1} is returned. Apart from the level specification, all physical properties are set to zero during the initialization process.

source
JenaAtomicCalculator.Hfs.displayNondiagonal — Method

Hfs.displayNondiagonal(stream::IO, multiplet::Multiplet, grid::Radial.Grid, settings::Hfs.Settings) ... to compute and display all non-diagonal hyperfine amplitudes for the selected levels. A small neat table of all (pairwise) hyperfine amplitudes is printed but nothing is returned otherwise.

source
JenaAtomicCalculator.Hfs.displayOutcomes — Method

Hfs.displayOutcomes(outcomes::Array{Hfs.Outcome,1}) ... to display a list of levels that have been selected for the computations A small neat table of all selected levels and their energies is printed but nothing is returned otherwise.

source
JenaAtomicCalculator.Hfs.displayResults — Method

Hfs.displayResults(stream::IO, outcomes::Array{Hfs.Outcome,1}, nm::Nuclear.Model, settings::Hfs.Settings) ... to display the energies, A- and B-values, Delta E_F energy shifts, etc. for the selected levels. All nuclear parameters are taken from the nuclear model. A neat table is printed but nothing is returned otherwise.

source
JenaAtomicCalculator.Hfs.recouplingElectronicOperator — Method

Hfs.recouplingElectronicOperator(spinI::AngularJ64, Ja::AngularJ64, Fa::AngularJ64, Jb::AngularJ64, Fb::AngularJ64, L::Int64) ... to return the factor that turns an ELECTRONIC reduced matrix element of rank L into the corresponding one between IJF-coupled levels, for an operator that acts on the electrons alone and leaves the nucleus untouched:

        <(I J_b) F_b || T^L || (I J_a) F_a>
            = (-1)^(I+J_b+F_a+L) sqrt((2F_a+1)(2F_b+1)) {J_b F_b I; F_a J_a L} <J_b || T^L || J_a>

    A value::Float64 is returned. This is the standard result for a tensor acting on one part of a coupled system (Edmonds 7.1.7), with
    the nucleus as the spectator.

    VERIFIED (work/diag-recoupling.jl, 05-Aug-2026) over 454 combinations of I, J_a, J_b, F_a and L = 1, 2: the sum over F_b of the
    squared factor equals (2F_a+1)/(2J_a+1) to better than 1e-15, which is exactly what leaves a radiative width unchanged by hyperfine
    coupling. For I = 0 the factor reduces to 1.

    Lives here, in the property module, rather than in any one process module: both hyperfine-resolved dielectronic recombination and
    hyperfine-induced transitions need it, and a second copy is how two implementations of the same formula start to drift apart.
source
JenaAtomicCalculator.Hfs.recouplingNuclearOperator — Method

Hfs.recouplingNuclearOperator(J::AngularJ64, Ia::AngularJ64, Fa::AngularJ64, Ib::AngularJ64, Fb::AngularJ64, L::Int64) ... the mirror image of Hfs.recouplingElectronicOperator: the factor that turns a NUCLEAR reduced matrix element of rank L into the corresponding one between IJF-coupled levels, for an operator that acts on the nucleus alone and leaves the electrons untouched:

        <(I_b J) F_b || W^L || (I_a J) F_a>
            = (-1)^(J+I_b+F_a+L) sqrt((2F_a+1)(2F_b+1)) {I_b F_b J; F_a I_a L} <I_b || W^L || I_a>

    A value::Float64 is returned. It is the same expression with the roles of the nuclear and electronic angular momenta interchanged,
    because the coupled state is symmetric in the two: whichever subsystem the operator acts on, the other is the spectator that appears
    in the 6-j.

    This is the factor that carries a hyperfine-induced NUCLEAR transition -- the isomer changes while the electronic level does not --
    and it is therefore what the 229Th and 205Pb cases rest on. For J = 0 it reduces to 1.
source
JenaAtomicCalculator.Hfs.reducedMeElectronic — Method

Hfs.reducedMeElectronic(mp::EmMultipole, rLevel::Level, sLevel::Level, grid::Radial.Grid) ... to return the electronic reduced matrix element <alphar Jr || T^(mp) || alphas Js> in the STANDARD (Wigner-Eckart) normalization, i.e. the quantity that may be inserted directly into a Wigner-6j recoupling expression. A value::ComplexF64 is returned.

    WHY THIS EXISTS (05-Aug-2026). Hfs.amplitude does NOT return that quantity, despite what its own header line says: it returns the
    reduced element divided by sqrt(2J+1), the "GRASP-like" normalization. The two differ by a factor that is invisible in every place
    where the same convention is used on both sides, and fatal in any place that mixes them -- as Hfs.computeHyperfineRepresentation
    did, building a 6-j expression directly out of Hfs.amplitude and coming out too small by exactly sqrt(2J+1).

    HOW THIS WAS SETTLED, since the two candidate conventions cannot both be right: A(H 1s) computed in the BARE NUCLEAR potential --
    NuclearField(), not a DFS field, whose self-interaction on a one-electron system puts the 1s orbital at -0.194 instead of -0.5 a.u.
    and invalidates the benchmark entirely -- gives 1421.21 MHz against the measured 1420.406 MHz, a ratio of 1.00057, using
    computeAmplitudesProperties' formula A*I/mu = amplitude/sqrt(J(J+1)). Inserting a further sqrt(2J+1) would give 1004.9 MHz, i.e. 29%
    low. So the A/B/C constants are right as they stand and it is the recoupling side that needed the factor.

    Note that A*I/mu = amplitude/sqrt(J(J+1)) and A*I/mu = <J||T^1||J>/sqrt(J(J+1)(2J+1)) are the SAME statement once <J||T^1||J> =
    amplitude*sqrt(2J+1); computeAmplitudesProperties therefore needs no change, and none was made. This function only makes the
    convention explicit so that the next caller who needs a genuine reduced matrix element does not have to rediscover it.

    For J_r != J_s the factor is taken as the symmetric ((2J_r+1)(2J_s+1))^(1/4), which reduces to sqrt(2J+1) on the diagonal and keeps
    the hyperfine matrix symmetric. The diagonal is what the H(1s) benchmark pins down; the off-diagonal convention is not separately
    verified here, and matters only through J-mixing, which is of order 1e-5 whenever the hyperfine splitting is small against the fine
    structure.
source
JenaAtomicCalculator.Hfs.warnOnContactObservable — Method

Hfs.warnOnContactObservable(outcomes::Array{Hfs.Outcome,1}) ... prints one advisory note, and only where it applies, if a selected level carries an UNPAIRED s subshell while the CSF basis holds no core s -> s single excitation. The A (and C) constant of such a level is dominated by the spin density AT the nucleus, and that density is set by CORE POLARIZATION, which is a singles effect and is simply absent from such a basis. Nothing is returned and nothing is blocked.

    THE NOTE IS ABOUT THE CSF SPACE, NOT ABOUT THE ROUTE, and that is what makes it decidable here: a `Basis` records its
    orbitals but NOT which route produced them, so a route-dependent caveat could never be checked. The presence of a core
    s -> s single excitation can be, and the note therefore disappears exactly when the user has done the thing that cures it.

    THE MEASUREMENT, 04-Oct-2026, 43Ca+ [Ar] 4s, ONE CSF, same grid and nucleus, only the route differing:

        RAS/EOL reference step       A(2S_1/2) = -603.8 MHz     published Dirac-Fock:  -589.09, -589, -588.933 MHz
        plain DFS                                -808.2         experiment:            -806.402 MHz;  correlated:  -808.12

    READ THE TWO COLUMNS THE RIGHT WAY ROUND. The EOL value agrees with the published DIRAC-FOCK values to 2.5 %, so the
    EOL route is doing its job; the ~25 % that separates it from experiment is the core-valence correlation that Dirac-Fock
    omits, and which the literature puts at 22 % of the total for this very state. The DFS value lands on the experiment to
    0.2 % ACCIDENTALLY, because a local Slater exchange potential mimics core polarization; it is not a better wavefunction
    and must not be chosen for being closer. A note recommending DFS for contact observables was written on the strength of
    the Yb+ row alone and is WRONG; it was removed once Ca+ supplied a system with a published Dirac-Fock number to check
    against.

    THE DEFICIT IS A PROPERTY OF THE UNPAIRED s ELECTRON AND NOT OF Z, measured the same day with one CSF throughout:
    A(EOL)/A(DFS) = 0.747 for Ca+ [Ar] 4s (19 electrons), 0.745 for Mn+ [Ar] 3d^5 4s (24) and 0.756 for Yb+ 4f^14 6s (69).
    Enriching the orbital basis does not touch it -- quadrupling the virtual span on Yb+ moved A by 0.3 % against a 24 % gap
    -- because the missing physics is a CSF, not an orbital. A 4f-hole constant such as A(2F_7/2) moved only +2.2 % in the
    same runs, since it comes from <r^-3> rather than from a density at the nucleus, and energies and fine-structure
    intervals are unaffected throughout.
source

Hyperfine Paschen-Back splittings

JenaAtomicCalculator.HfsPaschenBack.Component — Type

struct HfsPaschenBack.Component ... one dominant zero-field Hfs.HfLevel contribution to a field-dressed eigenstate.

+ hfLevel  ::Hfs.HfLevel  ... the zero-field hyperfine level this component belongs to.
+ weight   ::Float64      ... |eigenvector coefficient|^2 for this hfLevel basis component.
source
JenaAtomicCalculator.HfsPaschenBack.Outcome — Type

struct HfsPaschenBack.Outcome ... one field-dressed eigenstate of the hyperfine (B,E)-field perturbation matrix.

+ energy      ::Float64                           ... field-dressed energy, in atomic units.
+ components  ::Array{HfsPaschenBack.Component,1}  ... the zero-field Hfs.HfLevel components this eigenstate is
                                                         built from, sorted by descending weight.
source
JenaAtomicCalculator.HfsPaschenBack.Settings — Type

struct HfsPaschenBack.Settings <: AbstractPropertySettings ... defines a type for the details and parameters of an exact hyperfine Paschen-Back (Breit-Rabi) computation.

+ includeBField        ::Bool                     ... True if the static magnetic-field coupling is to be included.
+ bField               ::Float64                  ... Strength of the magnetic field, in Tesla (same convention as
                                                         LandeZeeman.Settings.BField/StarkZeeman.Settings.bField).
+ bDirection            ::NTuple{3,Float64}        ... Cartesian direction of the magnetic field; default (0.,0.,1.).
+ includeNuclearZeeman  ::Bool                     ... True if the small nuclear-Zeeman term (g_I mu_N B I_z) is to be
                                                         added to the electronic one -- the term that distinguishes a
                                                         genuine Breit-Rabi diagram from its leading-order approximation.
+ includeEField         ::Bool                     ... True if the static electric-field (Stark) coupling is to be included.
+ eField                ::Float64                  ... Strength of the electric field, in V/cm (same convention as
                                                         StarkShift.Settings.EField/StarkZeeman.Settings.eField).
+ eDirection             ::NTuple{3,Float64}        ... Cartesian direction of the electric field; default (0.,0.,1.).
+ includeSchwinger       ::Bool                     ... True if Schwinger's QED correction Delta-N1 is included in the
                                                         electronic magnetic-dipole coupling (same role as
                                                         LandeZeeman.Settings.includeSchwinger/StarkZeeman.Settings.includeSchwinger).
+ hfMultiplets           ::Array{Hfs.HfMultiplet,1} ... The zero-field hyperfine multiplet(s) admitted into the
                                                         perturbation matrix -- see the module docstring; built
                                                         independently, ahead of time, by the caller.
+ printBefore            ::Bool                     ... True if a list of selected hyperfine levels is printed before
                                                         the actual computation starts.
source
JenaAtomicCalculator.HfsPaschenBack.Settings — Method

HfsPaschenBack.Settings(set::HfsPaschenBack.Settings; includeBField::Union{Nothing,Bool}=nothing, bField::Union{Nothing,Float64}=nothing, bDirection::Union{Nothing,NTuple{3,Float64}}=nothing, includeNuclearZeeman::Union{Nothing,Bool}=nothing, includeEField::Union{Nothing,Bool}=nothing, eField::Union{Nothing,Float64}=nothing, eDirection::Union{Nothing,NTuple{3,Float64}}=nothing, includeSchwinger::Union{Nothing,Bool}=nothing, hfMultiplets::Union{Nothing,Array{Hfs.HfMultiplet,1}}=nothing, printBefore::Union{Nothing,Bool}=nothing)

... keyword copy-constructor for re-defining selected values of a settings::HfsPaschenBack.Settings.
    A `settings::HfsPaschenBack.Settings` is returned.
source
JenaAtomicCalculator.HfsPaschenBack.computeHfsZeemanMatrix — Method

HfsPaschenBack.computeHfsZeemanMatrix(settings::HfsPaschenBack.Settings, grid::Radial.Grid) ... builds and diagonalizes the Hfs.HfLevel-basis hyperfine Paschen-Back perturbation matrix for every HfLevel of every Hfs.HfMultiplet in settings.hfMultiplets – see the module docstring for the full construction. A tuple (eigenvalues::Array{Float64,1}, eigenvectors::Array{ComplexF64,2}, basisList::Array{Hfs.HfLevel,1}) is returned.

source
JenaAtomicCalculator.HfsPaschenBack.computeOutcomes — Method

HfsPaschenBack.computeOutcomes(multiplet::Multiplet, nm::Nuclear.Model, grid::Radial.Grid, settings::HfsPaschenBack.Settings; output=true) ... to compute the field-dressed hyperfine Paschen-Back eigenenergies and mixing coefficients for every HfLevel of every Hfs.HfMultiplet in settings.hfMultiplets, in the given static magnetic and/or electric field(s). multiplet/nm are accepted only for the uniform AbstractPropertySettings dispatch signature and are not read – see the module docstring. The results are printed in a neat table; an Array{HfsPaschenBack.Outcome,1} is returned if output, nothing otherwise.

source
JenaAtomicCalculator.HfsPaschenBack.determineOutcomes — Method

HfsPaschenBack.determineOutcomes(eigenvalues, eigenvectors, basisList::Array{Hfs.HfLevel,1}) ... packages the raw diagonalization result into a sorted (by energy) array of HfsPaschenBack.Outcome, each carrying its dominant zero-field Hfs.HfLevel components (weight > 1.0e-3, sorted by descending weight). An Array{HfsPaschenBack.Outcome,1} is returned.

source
JenaAtomicCalculator.HfsPaschenBack.displayOutcomes — Method

HfsPaschenBack.displayOutcomes(hfMultiplets::Array{Hfs.HfMultiplet,1}) ... to display the list of zero-field hyperfine levels admitted into the Paschen-Back perturbation matrix. A small neat table is printed but nothing is returned otherwise.

source
JenaAtomicCalculator.HfsPaschenBack.displayResults — Method

HfsPaschenBack.displayResults(stream::IO, outcomes::Array{HfsPaschenBack.Outcome,1}) ... to display the field-dressed hyperfine Paschen-Back eigenenergies and their dominant zero-field HfLevel components. A neat table is printed but nothing is returned otherwise.

source
JenaAtomicCalculator.HfsPaschenBack.expandMSublevels — Method

HfsPaschenBack.expandMSublevels(hfMultiplets::Array{Hfs.HfMultiplet,1}) ... expands each Hfs.HfLevel of every given Hfs.HfMultiplet into its full set of 2F+1 (F,M) sublevels.

    Hfs.computeHyperfineRepresentation deliberately stores only ONE HfLevel per F, carrying the placeholder
    M = F rather than a real projection -- its own comment explains why: at zero field the 2F+1 sublevels are
    exactly degenerate and M cancels by the Wigner-Eckart theorem in every quantity Hfs.jl itself computes, so
    storing all of them would be pure duplication. An external field is exactly the thing that "becomes
    meaningful" once M stops being a mere label, which is this module's reason to exist, so the expansion
    happens HERE rather than in Hfs.jl: the energy, hfBasisVectors and mc of a given F are UNCHANGED across its
    2F+1 copies (the zero-field Hamiltonian is a scalar in M), and the only thing that varies is the M label
    itself -- the reduced matrix elements HfsPaschenBack.recoupledElectronicMe/recoupledNuclearZeemanMe compute
    from hfBasisVectors/mc are themselves M-independent; only the final Wigner-Eckart projection
    (StarkZeeman.mResolvedAmplitude) needs the true M of each copy. An Array{Hfs.HfLevel,1} is returned, with
    fresh, sequential `index` fields (the original Hfs-assigned index is no longer unique once a level has been
    expanded into several M-copies).
source
JenaAtomicCalculator.HfsPaschenBack.recoupledElectronicMe — Method

HfsPaschenBack.recoupledElectronicMe(reducedMeOf::Function, levi::Hfs.HfLevel, levj::Hfs.HfLevel, grid::Radial.Grid) ... the F-coupled reduced matrix element <levj||T^(1)||levi> of a rank-1 operator that acts on the ELECTRONS alone (reducedMeOf(bra::Level, ket::Level) is the caller-supplied ordinary J-basis reduced matrix element, e.g. LandeZeeman.amplitude(ZeemanN1(),bra,ket,grid) or MultipoleMoment.emmStaticAmplitude(1,bra,ket,grid)), obtained by recoupling that J-basis element into the (I,J)->F basis via Hfs.recouplingElectronicOperator and summing over each HfLevel's own mc-weighted mixture of hfBasisVectors – see the module docstring. A value::ComplexF64 is returned, exactly 0. if no basis-vector pair of levi/levj shares a common nuclear state (the operator conserves the isomer, since it does not touch the nucleus).

source
JenaAtomicCalculator.HfsPaschenBack.recoupledNuclearZeemanMe — Method

HfsPaschenBack.recoupledNuclearZeemanMe(levi::Hfs.HfLevel, levj::Hfs.HfLevel) ... the F-coupled reduced matrix element <levj||mu^(1)||levi> of the nuclear-Zeeman operator, which acts on the nucleus alone and therefore requires the ELECTRONIC level – not merely its J – to be literally identical on both sides (Hfs.recouplingNuclearOperator's spectator), summed over each HfLevel's own mc-weighted mixture of hfBasisVectors exactly as HfsPaschenBack.recoupledElectronicMe does for the electronic term. The nuclear reduced matrix element itself is Hfs.computeInteractionAmplitudeM(Basics.M1,isomer,isomer), the same one Hfs.jl already uses for the hyperfine A-constant, converted here from nuclear magnetons to atomic units. A value::Float64 is returned, exactly 0. if no basis-vector pair shares both the same electronic level and the same nuclear state.

source

Isotope shifts

JenaAtomicCalculator.IsotopeShift.AbstractIsotopeShiftKind — Type

abstract type IsotopeShift.AbstractIsotopeShiftKind ... selects the isotope-shift amplitude to be computed; used for typed dispatch in IsotopeShift.amplitude().

+ NMSamplitude        ... normal mass-shift amplitude        H^(NMS).
+ SMSamplitudeA       ... specific mass-shift amplitude A    H^(SMS,A).
+ SMSamplitudeB       ... specific mass-shift amplitude B    H^(SMS,B).
+ SMSamplitudeC       ... specific mass-shift amplitude C    H^(SMS,C).
+ FieldShiftAmplitude ... field-shift amplitude              H^(field-shift).
+ BosonFieldAmplitude ... boson-field shift amplitude        H^(boson-field).
source
JenaAtomicCalculator.IsotopeShift.Outcome — Type

struct IsotopeShift.Outcome ... defines a type to keep the outcome of a isotope-shift computation, such as the K and F parameters as well other results.

+ level                     ::Level              ... Atomic level to which the outcome refers to.
+ Knms                      ::Float64            ... K_nms parameter
+ Ksms                      ::Float64            ... K_sms parameter
+ Fme                       ::Float64            ... F parameter from matrix element.
+ Fdensity                  ::Float64            ... F parameter from density.
+ Xboson                    ::Float64            ... X boson-field shift constant.
+ amplitudeKnms             ::Complex{Float64}   ... K_nms amplitude
+ amplitudeKsmsA            ::Complex{Float64}   ... K_sms,A amplitude
+ amplitudeKsmsB            ::Complex{Float64}   ... K_sms,B amplitude
+ amplitudeKsmsC            ::Complex{Float64}   ... K_sms,C amplitude
source
JenaAtomicCalculator.IsotopeShift.Settings — Type

struct IsotopeShift.Settings <: AbstractPropertySettings ... defines a type for the details and parameters of computing isotope-shift M and F parameters.

+ calcNMS                  ::Bool             ... True if mass-shift parameters M_nmn need to be calculated, and false otherwise.
+ calcSMS                  ::Bool             ... True if mass-shift parameters M_sms need to be calculated, and false otherwise.
+ calcF                    ::Bool             ... True if the field-shift parameter need to be calculated, and false otherwise.
+ calcBoson                ::Bool             ... True if the boson-field shift parameter need to be calculated, and false otherwise.
+ printBefore              ::Bool             ... True if a list of selected levels is printed before the actual computations start. 
+ bosonMass                ::Float64          ... mass of the scalar boson [e_electron].
+ levelSelection           ::LevelSelection   ... Specifies the selected levels, if any.
source
JenaAtomicCalculator.IsotopeShift.Settings — Method

IsotopeShift.Settings(set::IsotopeShift.Settings; calcNMS::Union{Nothing,Bool}=nothing, calcSMS::Union{Nothing,Bool}=nothing, calcF::Union{Nothing,Bool}=nothing, calcBoson::Union{Nothing,Bool}=nothing, printBefore::Union{Nothing,Bool}=nothing, bosonMass::Union{Nothing,Float64}=nothing, levelSelection::Union{Nothing,LevelSelection}=nothing) ... keyword constructor to modify selected fields of an IsotopeShift.Settings object; for fields not given, the values of set are used. A settings::IsotopeShift.Settings is returned.

source
JenaAtomicCalculator.IsotopeShift.Settings — Method

IsotopeShift.Settings(; calcNMS::Bool=true, calcSMS::Bool=false, calcF::Bool=false, calcBoson::Bool=false, printBefore::Bool=true, bosonMass::Float64=0., levelSelection::LevelSelection=LevelSelection()) ... keyword constructor to overwrite selected value of isoshift computations. A settings::IsotopeShift.Settings is returned.

source
JenaAtomicCalculator.IsotopeShift.amplitude — Method

IsotopeShift.amplitude(::BosonFieldAmplitude, rLevel::Level, sLevel::Level, potential::Array{Float64,1}, grid::Radial.Grid) ... to compute the boson-field shift amplitude <alphar Jr || H^(boson-field) || alphas Js> for a given pair of levels. The potential must provide the effective boson-field potential. A value::ComplexF64 is returned.

source
JenaAtomicCalculator.IsotopeShift.amplitude — Method

IsotopeShift.amplitude(::FieldShiftAmplitude, rLevel::Level, sLevel::Level, potential::Array{Float64,1}, grid::Radial.Grid) ... to compute the field-shift amplitude <alphar Jr || H^(field-shift) || alphas Js> for a given pair of levels. The potential must provide delta V^(nuc). A value::ComplexF64 is returned.

source
JenaAtomicCalculator.IsotopeShift.amplitude — Method

IsotopeShift.amplitude(::NMSamplitude, rLevel::Level, sLevel::Level, nm::Nuclear.Model, grid::Radial.Grid) ... to compute the normal mass-shift amplitude <alphar Jr || H^(NMS) || alphas Js> for a given pair of levels. A value::ComplexF64 is returned.

source
JenaAtomicCalculator.IsotopeShift.amplitude — Method

IsotopeShift.amplitude(::SMSamplitudeA, rLevel::Level, sLevel::Level, nm::Nuclear.Model, grid::Radial.Grid) ... to compute the specific mass-shift amplitude A <alphar Jr || H^(SMS,A) || alphas Js> for a given pair of levels. A value::ComplexF64 is returned.

source
JenaAtomicCalculator.IsotopeShift.amplitude — Method

IsotopeShift.amplitude(::SMSamplitudeB, rLevel::Level, sLevel::Level, nm::Nuclear.Model, grid::Radial.Grid) ... to compute the specific mass-shift amplitude B <alphar Jr || H^(SMS,B) || alphas Js> for a given pair of levels. A value::ComplexF64 is returned.

source
JenaAtomicCalculator.IsotopeShift.amplitude — Method

IsotopeShift.amplitude(::SMSamplitudeC, rLevel::Level, sLevel::Level, nm::Nuclear.Model, grid::Radial.Grid) ... to compute the specific mass-shift amplitude C <alphar Jr || H^(SMS,C) || alphas Js> for a given pair of levels. A value::ComplexF64 is returned.

source
JenaAtomicCalculator.IsotopeShift.computeAmplitudesProperties — Method

IsotopeShift.computeAmplitudesProperties(outcome::IsotopeShift.Outcome, nm::Nuclear.Model, grid::Radial.Grid, settings::IsotopeShift.Settings) ... to compute all amplitudes and properties for a given level; an outcome::IsotopeShift.Outcome is returned for which the amplitudes and properties are now evaluated explicitly.

source
JenaAtomicCalculator.IsotopeShift.computeOutcomes — Method

IsotopeShift.computeOutcomes(multiplet::Multiplet, nm::Nuclear.Model, grid::Radial.Grid, settings::IsotopeShift.Settings; output=true) ... to compute (as selected) the isotope-shift M and F parameters for the levels of the given multiplet and as specified by the given settings. The results are printed in neat tables to screen but nothing is returned otherwise.

source
JenaAtomicCalculator.IsotopeShift.determineOutcomes — Method

IsotopeShift.determineOutcomes(multiplet::Multiplet, settings::IsotopeShift.Settings) ... to determine a list of Outcomes's for the computation of the isotope-shift M and F parameters for the given multiplet. It takes into account the particular selections and settings. An Array{IsotopeShift.Outcome,1} is returned. Apart from the level specification, all physical properties are set to zero during the initialization process.

source
JenaAtomicCalculator.IsotopeShift.displayOutcomes — Method

IsotopeShift.displayOutcomes(outcomes::Array{IsotopeShift.Outcome,1}) ... to display a list of levels that have been selected for the computations. A small neat table of all selected levels and their energies is printed but nothing is returned otherwise.

source
JenaAtomicCalculator.IsotopeShift.displayResults — Method

IsotopeShift.displayResults(stream::IO, outcomes::Array{IsotopeShift.Outcome,1}, settings::IsotopeShift.Settings) ... to display the energies, M_ms and F-parameters, etc. for the selected levels. A neat table is printed but nothing is returned otherwise.

source
JenaAtomicCalculator.IsotopeShift.kingPlotChargeRadiusChange — Method

IsotopeShift.kingPlotChargeRadiusChange(deltaNuMeasured::Float64, Kms::Float64, F::Float64, massA::Float64, massAprime::Float64) ... to extract the change in the nuclear mean-square charge radius, delta<r^2>^(A,A'), implied by a MEASURED isotope shift of one transition together with JAC's own calculated Kms and F for that same transition, by inverting the standard King relation deltaNu = Kms(1/massA - 1/massAprime) + Fdelta<r^2>, i.e. deltaNu' = Kms + Fmudelta<r^2> for the MODIFIED shift deltaNu' = mu*deltaNu (see IsotopeShift.kingPlotModifiedShift) – note the extra factor of mu against F here, easy to miss since it is absent from the deltaNu'-vs-Kms relation one line up.

    SIGN CONVENTION, WORTH READING BEFORE PASSING IN TABLE VALUES. deltaNuMeasured, Kms and F must all be
    for the SAME transition direction, upper level minus lower level (i.e. the ordinary, positive transition
    energy/frequency convention a measurement like an isotope-shift paper uses). `IsotopeShift.displayResults`
    own transition table prints K_ms and F the OPPOSITE way round, lower-index level minus higher-index level
    (so, for a ground/excited pair, ground minus excited) -- its own header's advice "just take the
    difference K_i - K_f" is for comparing TWO ISOTOPES of the SAME transition, not for fixing a transition's
    own internal direction, and the two are easy to conflate. A caller using that table's printed Kms, F here
    must NEGATE them first, or (equivalently, and clearer at the call site) form Kms = foutcome.Knms +
    foutcome.Ksms - ioutcome.Knms - ioutcome.Ksms and F = foutcome.Fme - ioutcome.Fme directly from the two
    `IsotopeShift.Outcome`s, with `foutcome` the upper (excited) level and `ioutcome` the lower one.

    Units follow this module's own `displayResults` convention otherwise: deltaNuMeasured in MHz, Kms in
    GHz*u, F in MHz/fm^2, massA and massAprime in atomic mass units (u).
    A value::Float64, in fm^2, is returned.
source
JenaAtomicCalculator.IsotopeShift.kingPlotFit — Method

IsotopeShift.kingPlotFit(xModifiedShifts::Array{Float64,1}, yModifiedShifts::Array{Float64,1}) ... to fit the standard King-plot straight line y = slopex + intercept by ordinary least squares, where x and y are the MODIFIED isotope shifts (see IsotopeShift.kingPlotModifiedShift) of a reference transition and of the transition of interest, respectively, each evaluated for the SAME set of isotope pairs; both arrays must therefore have one entry per isotope pair, in the same order. The slope is the ratio Fy/Fx of the two transitions' field-shift constants and the intercept is K_ms,y - slopeK_ms,x, which is the usual cross-check a King plot provides without needing either transition's F individually. A (slope, intercept)::Tuple{Float64,Float64} is returned.

source
JenaAtomicCalculator.IsotopeShift.kingPlotModifiedShift — Method

IsotopeShift.kingPlotModifiedShift(deltaNu::Float64, massA::Float64, massAprime::Float64) ... to compute the MODIFIED isotope shift deltaNu' = mu^(A,A') * deltaNu that a King plot is built from, with the reduced-mass factor mu^(A,A') = massA*massAprime/(massAprime-massA). This is a purely kinematic reweighting of a RAW isotope shift (measured or otherwise supplied by the caller in whatever frequency unit it is quoted in, e.g. MHz or GHz) by the two isotope masses (in atomic mass units, u); it carries no dependence on JAC's own internal atomic units and performs no unit conversion of its own, so the returned value is in the SAME frequency unit as deltaNu, times u. A value::Float64 is returned.

source

Lande factors and Zeeman splittings

JenaAtomicCalculator.LandeZeeman.AbstractZeemanKind — Type

abstract type LandeZeeman.AbstractZeemanKind ... defines an abstract and two singleton types to select the N^(1) or Delta N^(1) Zeeman amplitude.

+ ZeemanN1       ... non-relativistic Zeeman operator N^(1).
+ ZeemanDeltaN1  ... relativistic correction Delta N^(1) to the Zeeman operator.
source
JenaAtomicCalculator.LandeZeeman.Outcome — Type

struct LandeZeeman.Outcome ... defines a type to keep the Lande Factors and Zeeman spittling parameters of a fine-structure level.

+ Jlevel                 ::Level             ... Fine-structure levels to which the results refer to.
+ LandeJ                 ::Float64           ... Lande-J factor of this fine-structure level 
+ amplitudeN1            ::Complex{Float64}  ... N1 amplitude
+ amplitudeDeltaN1       ::Complex{Float64}  ... Delta-N1 amplitude
+ nuclearI               ::AngularJ64        ... nuclear spin
+ Jsublevels             ::Array{LandeZeeman.SublevelJ,1}   
    ... List of the magnetic fine-structure sublevels and data with well-defined J-value 
+ Fsublevels             ::Array{LandeZeeman.SublevelF,1}   
    ... List of the magnetic hyperfine sublevels and data with well-defined F-value
source
JenaAtomicCalculator.LandeZeeman.Settings — Type

struct LandeZeeman.Settings <: AbstractPropertySettings ... defines a type for the details and parameters of computing the Lande Factors and Zeeman spittling of fine-structure levels.

+ calcLandeJ             ::Bool              ... True if Lande-J factors are to be calculated.
+ calcLandeF             ::Bool              ... True if Lande-F factors are to be calculated.
+ calcZeeman             ::Bool              ... True if Zeeman splittings are to be calculated.
+ calcQZScoeff           ::Bool              ... True if the quadratic-Zeeman shift coefficients are to be calculated.
+ includeSchwinger       ::Bool              ... True if Schwinger's QED correction ``\Delta N^(1)`` is to be included, 
                                                    and false otherwise.
+ printBefore            ::Bool              ... True if a list of selected levels is printed before the actual computations start. 
+ BField                 ::Float64           ... Strength of the magnetic field in [Tesla]
+ levelSelection         ::LevelSelection    ... Specifies the selected levels, if any.
+ gMultiplet             ::Multiplet         ... Specifies the levels, used as intermediate levels for second-order coefficients.
source
JenaAtomicCalculator.LandeZeeman.Settings — Method

LandeZeeman.Settings(set::LandeZeeman.Settings; calcLandeJ::Union{Nothing,Bool}=nothing, calcLandeF::Union{Nothing,Bool}=nothing, calcZeeman::Union{Nothing,Bool}=nothing, calcQZScoeff::Union{Nothing,Bool}=nothing, includeSchwinger::Union{Nothing,Bool}=nothing, printBefore::Union{Nothing,Bool}=nothing, BField::Union{Nothing,Float64}=nothing, levelSelection::Union{Nothing,LevelSelection}=nothing, gMultiplet::Union{Nothing,Multiplet}=nothing) ... keyword constructor to modify selected fields of a LandeZeeman.Settings object; for fields not given, the values of set are used. A settings::LandeZeeman.Settings is returned.

source
JenaAtomicCalculator.LandeZeeman.SublevelF — Type

struct LandeZeeman.SublevelF ... defines a type to specify a magnetic hyperfine sublevel with well-defined F.

+ F                      ::AngularJ64        ... F-value
+ M                      ::AngularM64        ... M_F-value
+ energy                 ::Float64           ... energy of this sublevel
+ c2Coeff                ::Float64           ... quadratic-Zeeman shift C_2 coefficient of this level
source
JenaAtomicCalculator.LandeZeeman.SublevelJ — Type

struct LandeZeeman.SublevelJ ... defines a type to specify a magnetic sublevel with well-defined J.

+ M                      ::AngularM64        ... M_J-value
+ energy                 ::Float64           ... energy of this sublevel
+ c2Coeff                ::Float64           ... quadratic-Zeeman shift C_2 coefficient for this level
source
JenaAtomicCalculator.LandeZeeman.amplitude — Method

LandeZeeman.amplitude(::ZeemanDeltaN1, rLevel::Level, sLevel::Level, grid::Radial.Grid) ... to compute the Delta N^(1) Zeeman amplitude <alphar Jr || Delta N^(1) || alphas Js> for a given pair of levels. A value::ComplexF64 is returned.

source
JenaAtomicCalculator.LandeZeeman.amplitude — Method

LandeZeeman.amplitude(::ZeemanN1, rLevel::Level, sLevel::Level, grid::Radial.Grid) ... to compute the N^(1) Zeeman amplitude <alphar Jr || N^(1) || alphas Js> for a given pair of levels. A value::ComplexF64 is returned.

RESOLVED, 10-Aug-2026 (this block previously carried a KNOWN LIMITATION saying that any subshell with
kappa <= -3 gives a WRONG g_J). It was never a defect in this amplitude, nor in the angular machinery.
A one-electron scan on a matched radial box reproduces the exact Lande factor 2|kappa|/(2|kappa| -+ 1)
for EVERY kappa -- ratios 0.99867, 0.99947, 0.99961, 0.99975, 0.99980, 0.99985 for
kappa = +1, -2, +2, -3, +3, -4 -- so neither AngularMomentum.CL_reduced_me nor the Subshell(1,-ka)
construction in InteractionStrength.zeeman_n1 is at fault; both were named as suspects and both are
exonerated. The failing cases were run on a radial box far too wide for the orbitals involved, where the
SCF returns the WRONG STATE for the kappa < 0 partner: Ge II 4f on 614 a.u. gave E(4f_7/2) = -1.5758
with <r> = 5.20 against E(4f_5/2) = -0.0619 with <r> = 10.87, although the two partners of one 4f shell
must be nearly identical. That also explains why the wrong value was never stable against unrelated
changes in the basis machinery -- it was simply whichever wrong state the basis happened to return.
With the box matched (rbox = 30 a.u.) example-Cd.jl branch c reproduces Andersson & Jonsson to six
decimals on BOTH levels. Bsplines.checkOrbitalConsistency now stops this class of failure at its source.
source
JenaAtomicCalculator.LandeZeeman.computeAmplitudesProperties — Method

LandeZeeman.computeAmplitudesProperties(outcome::LandeZeeman.Outcome, grid::Radial.Grid, settings::LandeZeeman.Settings) ... to compute all amplitudes and properties of for a given level. The given gMultiplet in settings containes the intermediate levels used in the computation of second order coefficients. An outcome::LandeZeeman.Outcome is returned for which the amplitudes and all requested properties are now evaluated explicitly.

source
JenaAtomicCalculator.LandeZeeman.computeOutcomes — Method

LandeZeeman.computeOutcomes(multiplet::Multiplet, nm::Nuclear.Model, grid::Radial.Grid, settings::LandeZeeman.Settings; output=true) ... to compute (as selected) the Lande J or F factors for the levels of the given multiplet and as specified by the given settings. The results are printed in neat tables to screen but nothing is returned otherwise.

source
JenaAtomicCalculator.LandeZeeman.computeQuadraticZeemanC2 — Method

LandeZeeman.computeQuadraticZeemanC2(level::Level, Jsub::SublevelJ, grid::Radial.Grid, settings::LandeZeeman.Settings) ... to compute the quadratic-Zeeman shift coefficient C2 for the Zeeman sublevel Jsub by applyling a summation over all levels from gMultiplet, following the STRUCTURE of Gilles, Fritzsche, Spieß, Schmidt & Surzhykov, Phys. Rev. A 110, 052812 (2024), Eq. (33): C2 = sum{Gamma',J'} |<JM;10|J'M>|^2 / (E(GammaJ)-E(Gamma'J')) * |<Gamma'J'||mu^(1)+Delta mu^(1)||GammaJ>|^2. A value c2::Float64 is returned for the given level (level, Jsub).

    Note (31-Jul-2026): Eq. (33) as published includes an extra 1/(2J'+1) normalization factor, appropriate
    for a BARE Wigner-Eckart reduced matrix element <Gamma'J'||...||GammaJ>. Adding that factor here (it was
    present, disabled, as a commented-out line in the source, evidently an unfinished/unvalidated attempt to
    literally match Eq. (33)) was tried and found EMPIRICALLY WRONG: it makes every C_2 value too small by
    very close to a clean factor of (2J'+1) for whatever intermediate J' dominates the sum -- confirmed
    against examples/example-Cd.jl branches e/f (Al+, Ca^14+ vs the paper's own Tables III/V): with the extra
    factor, agreement was off by ~3x (J'=1 dominant) or ~5x (J'=2 dominant); WITHOUT it (as below, matching
    the code's original, never-quite-finished form once its debug prints are stripped out), 6 of 7 tested
    M-sublevels across both systems land within 1-7% of the literature values, consistent with the paper's
    own step-1 (no virtual excitations) accuracy. This means LandeZeeman.amplitude's own reduced-matrix-
    element convention already differs from Eq. (33)'s assumed bare normalization by exactly this (2J'+1)
    factor -- consistent with amplitude() never needing such a factor for the separately-validated diagonal
    (g_J) case either. The exact origin of that convention difference (presumably somewhere in
    SpinAngular's one-particle-operator coefficients) has not been independently re-derived from first
    principles here; this note records an empirical resolution, not a theoretical one.
source
JenaAtomicCalculator.LandeZeeman.computeQuadraticZeemanC2 — Method

LandeZeeman.computeQuadraticZeemanC2(multiplet::Multiplet, level::Level, Fsub::SublevelF, nm::Nuclear.Model, grid::Radial.Grid, settings::LandeZeeman.Settings) ... to compute all quadratic-Zeeman shift C2 coefficients; an c2::Float64 is returned for the given hyperfine level Fsub.

source
JenaAtomicCalculator.LandeZeeman.determineOutcomes — Method

LandeZeeman.determineOutcomes(multiplet::Multiplet, nm::Nuclear.Model, settings::LandeZeeman.Settings) ... to determine a list of Outcomes's for the computation of Lande factors and/or Zeeman splittings for levels from the given multiplet. It takes into account the particular selections and settings. An Array{LandeZeeman.Outcome,1} is returned. Apart from the level specification, all physical properties are still set to zero during the initialization process.

source
JenaAtomicCalculator.LandeZeeman.displayOutcomes — Method

LandeZeeman.displayOutcomes(outcomes::Array{LandeZeeman.Outcome,1}) ... to display a list of levels that have been selected for the computations. A small neat table of all selected levels and their energies is printed but nothing is returned otherwise.

source
JenaAtomicCalculator.LandeZeeman.displayResults — Method

LandeZeeman.displayResults(stream::IO, outcomes::Array{LandeZeeman.Outcome,1}, nm::Nuclear.Model, settings::LandeZeeman.Settings) ... to display the energies, Lande factors, Zeeman amplitudes etc. for the selected levels. A neat table is printed but nothing is returned otherwise.

source
JenaAtomicCalculator.LandeZeeman.landeFFactor — Method

LandeZeeman.landeFFactor(F::AngularJ64, J::AngularJ64, I::AngularJ64, gJ::Float64, gI::Float64) ... calculates the hyperfine Lande factor g_F of a hyperfine level |(I J) F>, i.e. the factor by which that level responds to an external magnetic field; a value::Float64 is returned.

    BOTH the electronic and the NUCLEAR magnetic moment are included:

        g_F  =  g_J [F(F+1) + J(J+1) - I(I+1)] / 2F(F+1)
              - g_I (mu_N/mu_B) [F(F+1) + I(I+1) - J(J+1)] / 2F(F+1)

    where g_I = mu_I / (I mu_N) is the dimensionless nuclear g factor and mu_N/mu_B = m_e/m_p.

    THE NUCLEAR TERM WAS MISSING UNTIL 30-Sep-2026 and is not negligible, which is why it has its own function
    rather than sitting inline in a display routine.  It is of relative order 1e-4 -- about m_e/m_p -- so it is
    a HUNDRED TIMES larger than the 1e-6 at which a quantum-logic experiment now reads a g factor.  Worse, the
    electronic projection VANISHES on particular hyperfine levels while the nuclear one does not, and there the
    omission was the entire answer: for I = 7/2 coupled to J = 3/2 at F = 3 the electronic bracket is identically
    zero and g_F is purely nuclear.  49Ti+ a^4F_(3/2), F = 3 returns +1.718e-04 where the old code returned 0.

    SIGN CONVENTION.  g_I carries the sign of the nuclear moment, and the nuclear term enters with a MINUS because
    the nucleus and the electron have opposite charge.  For a NEGATIVE moment -- as both odd titanium isotopes have
    -- the nuclear term is therefore POSITIVE.
source

Reduced density matrices and natural orbitals

JenaAtomicCalculator.ReducedDensityMatrix.Outcome — Type

struct ReducedDensityMatrix.Outcome ... defines a type to keep the outcome of a reduced density-matrix and natural-orbital computation.

+ level                     ::Level                 ... Atomic level to which the outcome refers to.
+ naturalSubshells          ::Array{Subshell,1}     ... List of natural orbitals (subshells).
+ naturalOccupation         ::Array{Float64,1}      ... Occupation numbers of natural orbitals.
+ naturalOrbitalExpansion   ::Dict{Subshell, Array{Float64,1}} 
    ... Dictionary of the expansion of (one-electron) natural orbitals in terms of the standard orbitals
        from the given basis.
+ naturalOrbitals           ::Dict{Subshell, Orbital} ... Dictionary of (one-electron) natural orbitals.
+ orbitalInteraction        ::Array{Float64,2}      ... Orbital interaction I_pq = I[ip,iq].
+ rho1p                     ::Array{Float64,2}      ... One-particle RDM rho^(1p) [ip,iq].
+ rho2p                     ::Array{Float64,4}      ... Two-particle RDM rho^(2p) [ip,iq,ir,is].
+ electronDensity           ::Radial.Density        ... Radial density distribution.
source
JenaAtomicCalculator.ReducedDensityMatrix.Outcome — Method

ReducedDensityMatrix.Outcome() ... constructor for an empty instance of ReducedDensityMatrix.Outcome, i.e. with the level and every derived quantity unset. An outcome::ReducedDensityMatrix.Outcome is returned.

source
JenaAtomicCalculator.ReducedDensityMatrix.Settings — Type

struct ReducedDensityMatrix.Settings <: AbstractPropertySettings ... defines a type for the parameters that control the computation of reduced density matrices and the quantities derived from them.

+ calcNatural              ::Bool             ... True if natural orbitals need to be calculated, and false otherwise.
+ calcDensity              ::Bool             ... True if the radial density need to be calculated, and false otherwise.
+ calcIpq                  ::Bool             ... True if orbital interaction I_pq need to be calculated, and false otherwise.
+ calc2pRDM                ::Bool             ... True if the 2p RDM need to be calculated, and false otherwise;
                                                    the 1pRDM is calculated by default.
+ printBefore              ::Bool             ... True if a list of selected levels is printed before the actual computations start. 
+ levelSelection           ::LevelSelection   ... Specifies the selected levels, if any.
source
JenaAtomicCalculator.ReducedDensityMatrix.Settings — Method

ReducedDensityMatrix.Settings(set::ReducedDensityMatrix.Settings; calcNatural::Union{Nothing,Bool} = nothing, calcDensity::Union{Nothing,Bool} = nothing, calcIpq::Union{Nothing,Bool} = nothing, calc2pRDM::Union{Nothing,Bool} = nothing, printBefore::Union{Nothing,Bool} = nothing, levelSelection::Union{Nothing,LevelSelection} = nothing )

... constructor for modifying the given ReducedDensityMatrix.Settings by 'overwriting' the previously selected parameters.
    A settings::ReducedDensityMatrix.Settings is returned.
source
JenaAtomicCalculator.ReducedDensityMatrix.Settings — Method

ReducedDensityMatrix.Settings(; calcNatural::Bool=true, calcDensity::Bool=true, calcIpq::Bool=false, calc2pRDM::Bool=false, printBefore::Bool=true, levelSelection::LevelSelection=LevelSelection()) ... keyword constructor to overwrite selected values of the reduced-density-matrix computations. A settings::ReducedDensityMatrix.Settings is returned.

source
Base.show — Method

Base.show(io::IO, outcome::ReducedDensityMatrix.Outcome) ... prepares a proper printout of the variable outcome::ReducedDensityMatrix.Outcome; nothing is returned.

source
Base.show — Method

Base.show(io::IO, settings::ReducedDensityMatrix.Settings) ... prepares a proper printout of the variable settings::ReducedDensityMatrix.Settings; nothing is returned.

source
JenaAtomicCalculator.ReducedDensityMatrix.compute1pRDMDirect — Method

ReducedDensityMatrix.compute1pRDMDirect(level::Level) ... to compute the 1p RDM directly from the CI mixing coefficients and CSF occupation numbers, following Eq. (7) of Ma et al., Atoms 12, 30 (2024), rho^kappann' = sumij ci v^ijnn' c_j – but derived here from elementary second quantization, independently of SpinAngular.computeCoefficients.

    Diagonal elements need no angular-momentum recoupling at all: the expectation value of a number operator in a normalized state is
    just the mc-weighted sum of that CSF's own occupation number.

    Off-diagonal elements are supported for the simplest, and here relevant, case only: two CSFs that differ by moving ONE electron
    between two subshells of the SAME kappa, each holding 0 or 1 electron (e.g. a single 2s->3s substitution), with all other subshells
    in identical coupling. For this case the transfer coefficient is the universal value sqrt(2), independent of kappa/j: writing the
    singly-occupied pair coupled to a scalar (J=0) as |ab;0> = (1/sqrt(2j+1)) sum_m (-1)^(j-m) a+_{am} a+_{b,-m} |0> (the standard
    pair-coupling identity) and the closed-shell pair as |aa;0> = (1/sqrt(2*(2j+1))) sum_m (-1)^(j-m) a+_{am} a+_{a,-m} |0> (note the
    extra factor of 2 under the root here, from the (m,-m) double counting that only affects the same-shell case), direct evaluation of
    N_ab = sum_m a+_{am} a_{bm} gives N_ab |ab;0> = sqrt(2) |aa;0> for ANY j. CSF pairs with a more general occupation pattern (more
    than one electron differing per subshell) are NOT handled and raise an error -- those need the full
    coefficient-of-fractional-parentage machinery in SpinAngularTables.
    A rho_pq::Array{Float64,2} is returned.
source
JenaAtomicCalculator.ReducedDensityMatrix.computeNaturalOrbitalExpansion — Method

ReducedDensityMatrix.computeNaturalOrbitalExpansion(rho1p::Array{Float64,2}, level::Level) ... to perform the expansion of the natural orbitals for the given level in terms of the standard orbitals as defined by the basis. A tuple (naturalOcc::Array{Float64,1}, naturalExp::Dict{Subshell, Array{Float64,1}}) is returned which provides the natural occpuation numbers and expansion coefficients with regard to the given list of natural orbitals. This method makes use of the 1-particle RDM to extract and diagonalize the expansion matrix. Since the (rank-0) 1p RDM has no matrix elements between subshells of different relativistic symmetry kappa, it is block-diagonal in kappa; each kappa-block is diagonalized separately (Eqs. 7-8 of Ma et al., Atoms 12, 30 (2024)) and the resulting natural orbitals (sorted by decreasing occupation within the block) are associated, in turn, with the standard subshells of that same kappa.

source
JenaAtomicCalculator.ReducedDensityMatrix.computeNaturalOrbitals — Method

ReducedDensityMatrix.computeNaturalOrbitals(naturalSubshells::Array{Subshell,1}, naturalExp::Dict{Subshell, Array{Float64,1}}, level::Level) ... to compute the natural orbitals as superposition of the standard orbitals; for each subshell in naturalExp, an orbital is computed, and naturalOrbitals::Dict{Subshell, Orbital} returned. Follows Eqs. 10-11 of Ma et al., Atoms 12, 30 (2024): P-tilden'kappa(r) = sumn u^kappa{n,n'} Pnkappa(r), and likewise for Q.

source
JenaAtomicCalculator.ReducedDensityMatrix.computeOrbitalInteractions — Method

ReducedDensityMatrix.computeOrbitalInteractions(naturalSubshells::Array{Subshell,1}, naturalOrbitals::Dict{Subshell, Orbital}, level::Level) ... to compute the orbital interaction I_pq between pairs of natural orbitals; a matrix orbitalInteraction::Array{Float64,2} is returned. Not yet implemented – this quantity is not part of the Ma et al. (2024) recipe used elsewhere in this module and still needs its own definition/derivation.

source
JenaAtomicCalculator.ReducedDensityMatrix.computeOutcomes — Method

ReducedDensityMatrix.computeOutcomes(multiplet::Multiplet, nm::Nuclear.Model, grid::Radial.Grid, settings::ReducedDensityMatrix.Settings; output=true) ... to compute (as selected) the 1-particle and 2-particle reduced density matrices, natural orbitals or other requested information for the levels of interest. This is the driver of the module: it determines the outcomes, computes the properties of each and displays the results to screen and to the summary file. A newOutcomes::Array{ReducedDensityMatrix.Outcome,1} is returned for output = true, and nothing otherwise.

source
JenaAtomicCalculator.ReducedDensityMatrix.computeProperties — Method

ReducedDensityMatrix.computeProperties(outcome::ReducedDensityMatrix.Outcome, nm::Nuclear.Model, grid::Radial.Grid, settings::ReducedDensityMatrix.Settings) ... to compute all properties for a given level; an outcome::ReducedDensityMatrix.Outcome is returned for which the properties are now evaluated explicitly.

source
JenaAtomicCalculator.ReducedDensityMatrix.computeRadialDistribution — Method

ReducedDensityMatrix.computeRadialDistribution(naturalOcc::Array{Float64,1}, naturalOrbitals::Dict{Subshell, Orbital}, naturalSubshells::Array{Subshell,1}, grid::Radial.Grid) ... to compute the total radial electron density from the (occupation-weighted) natural orbitals, D(r) = sum(n'kappa) occ(n'kappa) [ P-tilde(n'kappa)(r)^2 + Q-tilde(n'kappa)(r)^2 ]. A Radial.Density is returned w.r.t. the given grid.

source
JenaAtomicCalculator.ReducedDensityMatrix.determineOutcomes — Method

ReducedDensityMatrix.determineOutcomes(multiplet::Multiplet, settings::ReducedDensityMatrix.Settings) ... to determine a list of Outcomes's for the computation of reduced density matrices and other information for the given multiplet. It takes into account the particular selections and settings. An Array{ReducedDensityMatrix.Outcome,1} is returned. Apart from the level specification, all physical properties are set to zero during the initialization process.

source
JenaAtomicCalculator.ReducedDensityMatrix.displayOutcomes — Method

ReducedDensityMatrix.displayOutcomes(outcomes::Array{ReducedDensityMatrix.Outcome,1}, settings::ReducedDensityMatrix.Settings) ... to display a list of levels that have been selected for the computations. A small neat table of all selected levels and their energies is printed but nothing is returned otherwise. Moreover, the selected properties and information is printed as well, though not yet calculated.

source
JenaAtomicCalculator.ReducedDensityMatrix.displayResults — Method

ReducedDensityMatrix.displayResults(stream::IO, outcomes::Array{ReducedDensityMatrix.Outcome,1}, grid::Radial.Grid, settings::ReducedDensityMatrix.Settings) ... to display the computed results for all outcomes on the given stream. The selected levels and their energies are tabulated first, and then, for each level in turn, the 1-particle RDM, the natural occupation numbers and the natural orbital expansion; the natural orbitals, the radial electron density, the orbital interactions I_pq and the 2-particle RDM follow for whichever of them the settings requested. Nothing is returned.

source

Stark-Zeeman effect

JenaAtomicCalculator.StarkZeeman.Component — Type

struct StarkZeeman.Component ... one dominant (level,M) contribution to a field-dressed eigenstate.

+ level   ::Level        ... the zero-field level this component belongs to.
+ M       ::AngularM64   ... its M-sublevel.
+ weight  ::Float64      ... |eigenvector coefficient|^2 for this (level,M) basis component.
source
JenaAtomicCalculator.StarkZeeman.Outcome — Type

struct StarkZeeman.Outcome ... one field-dressed eigenstate of the (E,B)-field perturbation matrix.

+ energy      ::Float64                        ... field-dressed energy, in atomic units.
+ components  ::Array{StarkZeeman.Component,1}  ... the zero-field (level,M) components this
                                                      eigenstate is built from, sorted by
                                                      descending weight ("major level/symmetry"
                                                      first).
source
JenaAtomicCalculator.StarkZeeman.Settings — Type

struct StarkZeeman.Settings <: AbstractPropertySettings ... defines a type for the details and parameters of an exact (E,B)-field level-mixing/-splitting computation.

+ includeEField    ::Bool               ... True if the static electric-field (Stark) coupling is
                                             to be included.
+ includeBField    ::Bool               ... True if the static magnetic-field (Zeeman) coupling is
                                             to be included.
+ eField           ::Float64            ... Strength of the electric field, in V/cm (SAME unit
                                             convention as StarkShift.Settings.EField).
+ eDirection       ::NTuple{3,Float64}  ... Cartesian direction of the electric field (need not be
                                             normalized); default (0.,0.,1.), i.e. along the
                                             quantization axis.
+ bField           ::Float64            ... Strength of the magnetic field, in Tesla (SAME unit
                                             convention as LandeZeeman.Settings.BField).
+ bDirection       ::NTuple{3,Float64}  ... Cartesian direction of the magnetic field; default
                                             (0.,0.,1.).
+ includeSchwinger ::Bool               ... True if Schwinger's QED correction Delta-N1 is to be
                                             included in the magnetic-dipole coupling (SAME flag
                                             role as LandeZeeman.Settings.includeSchwinger).
+ printBefore      ::Bool               ... True if a list of selected levels is printed before
                                             the actual computation starts.
+ levelSelection   ::LevelSelection     ... Specifies the levels admitted into the (E,B)-field
                                             perturbation matrix -- see the module docstring.
source
JenaAtomicCalculator.StarkZeeman.Settings — Method

StarkZeeman.Settings(set::StarkZeeman.Settings; includeEField::Union{Nothing,Bool}=nothing, includeBField::Union{Nothing,Bool}=nothing, eField::Union{Nothing,Float64}=nothing, eDirection::Union{Nothing,NTuple{3,Float64}}=nothing, bField::Union{Nothing,Float64}=nothing, bDirection::Union{Nothing,NTuple{3,Float64}}=nothing, includeSchwinger::Union{Nothing,Bool}=nothing, printBefore::Union{Nothing,Bool}=nothing, levelSelection::Union{Nothing,LevelSelection}=nothing)

... keyword copy-constructor for re-defining selected values of a settings::StarkZeeman.Settings.
    A `settings::StarkZeeman.Settings` is returned.
source
JenaAtomicCalculator.StarkZeeman.computeOutcomes — Method

StarkZeeman.computeOutcomes(multiplet::Multiplet, nm::Nuclear.Model, grid::Radial.Grid, settings::StarkZeeman.Settings; output=true) ... to compute the field-dressed eigenenergies and mixing coefficients for the levels selected by settings.levelSelection from multiplet, in the given static electric and/or magnetic field(s). The results are printed in a neat table but nothing is returned otherwise.

source
JenaAtomicCalculator.StarkZeeman.computeStarkZeemanMatrix — Method

StarkZeeman.computeStarkZeemanMatrix(multiplet::Multiplet, grid::Radial.Grid, settings::StarkZeeman.Settings) ... builds and diagonalizes the (level,M)-basis (E,B)-field perturbation matrix for the levels selected by settings.levelSelection from multiplet – see the module docstring for the full construction. A tuple (eigenvalues::Array{Float64,1}, eigenvectors::Array{ComplexF64,2}, basisList::Array{StarkZeeman.SublevelBasis,1}) is returned.

source
JenaAtomicCalculator.StarkZeeman.determineOutcomes — Method

StarkZeeman.determineOutcomes(eigenvalues, eigenvectors, basisList::Array{StarkZeeman.SublevelBasis,1}) ... packages the raw diagonalization result into a sorted (by energy) array of StarkZeeman.Outcome, each carrying its dominant zero-field (level,M) components (weight > 1.0e-3, sorted by descending weight) – the "major level/symmetry" labeling. An Array{StarkZeeman.Outcome,1} is returned.

source
JenaAtomicCalculator.StarkZeeman.directionToAngles — Method

StarkZeeman.directionToAngles(direction::NTuple{3,Float64}) ... converts a (not necessarily normalized) Cartesian direction (dx,dy,dz) into the polar angles (theta,phi) relative to the SAME z quantization axis used throughout JAC's M-sublevel machinery. A tuple (theta::Float64, phi::Float64) is returned.

source
JenaAtomicCalculator.StarkZeeman.displayOutcomes — Method

StarkZeeman.displayOutcomes(selectedLevels::Array{Level,1}) ... to display the list of zero-field levels admitted into the (E,B)-field perturbation matrix. A small neat table is printed but nothing is returned otherwise.

source
JenaAtomicCalculator.StarkZeeman.displayResults — Method

StarkZeeman.displayResults(stream::IO, outcomes::Array{StarkZeeman.Outcome,1}) ... to display the field-dressed eigenenergies and their dominant zero-field (level,M) components. A neat table is printed but nothing is returned otherwise.

source
JenaAtomicCalculator.StarkZeeman.fieldWeight — Method

StarkZeeman.fieldWeight(q::Int64, theta::Float64, phi::Float64) ... the rank-1 spherical-tensor weight of a unit-vector direction (theta,phi) in component q, i.e. nhat . T^(1) = sumq StarkZeeman.fieldWeight(q,theta,phi) * T^(1)q, using the standard identity nhat <-> C^(1)(theta,phi) (Racah-normalized spherical harmonic, AngularMomentum.sphericalYlm) and the rank-1 spherical dot product A.B = sumq (-1)^q Aq B_{-q}. A value::ComplexF64 is returned.

source
JenaAtomicCalculator.StarkZeeman.mResolvedAmplitude — Method

StarkZeeman.mResolvedAmplitude(reducedAmplitude, Ji::AngularJ64, Mi::AngularM64, Jf::AngularJ64, Mf::AngularM64) ... converts a reduced matrix element <Jf||T^(1)||Ji> (as returned by MultipoleMoment.emmStaticAmplitude or LandeZeeman.amplitude) into the genuine M-resolved sublevel matrix element <Jf,Mf|T^(1)_q|Ji,Mi>, q = Mf-Mi, via ClebschGordan(Ji,Mi;1,q|Jf,Mf) * reducedAmplitude – deliberately WITHOUT an additional 1/sqrt(2Jf+1) factor; see the module docstring for how this convention was empirically calibrated (not assumed) against the exact hydrogen n=2 Stark coupling. A value is returned in the same (real or complex) type as reducedAmplitude, or exactly zero if q is not in {-1,0,1} or the Clebsch-Gordan coefficient vanishes.

source

Stark shift

JenaAtomicCalculator.StarkShift.MagicWavelength — Type

struct StarkShift.MagicWavelength ... one magic wavelength of a PAIR of levels, i.e. one zero of alpha0(omega, A) - alpha0(omega, B). At such a frequency the two levels are shifted EQUALLY, so the transition between them is untouched by the trapping light to first order in the intensity – which is what makes an optical trap compatible with a clock or a qubit. There are generically MANY of them, one or more between every pair of consecutive resonances, so StarkShift.magicWavelengths returns a list and never "the" magic wavelength.

+ omega          ::Float64   ... the frequency, in atomic units.
+ wavelength     ::Float64   ... the same frequency as a vacuum wavelength, in nm, which is how this quantity
                                   is universally quoted.
+ alphaCommon    ::Float64   ... the polarizability the two levels SHARE there, in a.u. IT IS THE TRAP DEPTH per
                                   unit intensity, and ITS SIGN DECIDES WHETHER THE TRAP TRAPS: a magic
                                   wavelength with alphaCommon < 0 shifts both levels UP and repels the atom
                                   from the focus, so it is magic and useless at the same time.
+ slope          ::Float64   ... d(alpha_A - alpha_B)/d omega at the zero, in a.u. per a.u. It says how
                                   SHARP the magic wavelength is: a small slope means a wide tolerance on the
                                   laser frequency, a large one means the differential shift returns at once.
+ aboveResonance ::Bool      ... true if omega lies at or above the lowest excitation energy of either level,
                                   where the true polarizability is COMPLEX and this real sum is a
                                   principal-value-like part with no width. Such a zero is still a real
                                   crossing of the two real parts, but it is not a usable magic wavelength
                                   without the widths.
source
JenaAtomicCalculator.StarkShift.Outcome — Type

struct StarkShift.Outcome ... defines a type to keep the Stark shift and electric-quadrupole-moment parameters of a fine-structure level.

+ Jlevel                 ::Level             ... Fine-structure levels to which the results refer to.
+ Theta1                 ::Float64           ... Electric-dipole moment of the atom in this level.
+ Theta2                 ::Float64           ... Electric-quadrupole moment of the atom in this level.
+ alpha0                 ::EmProperty        ... Static scalar (rank 0) E1 polarizability alpha_0(J), in
                                                   a.u., that the Stark shift below was computed from
                                                   (see module docstring); EmProperty(0.) if calcStarkshifts
                                                   was not requested.
+ alpha2                 ::EmProperty        ... Static tensor (rank 2) E1 polarizability alpha_2(J), in
                                                   a.u.; identically 0. for J<1 (see module docstring).
+ Jsublevels              ::Array{StarkShift.SublevelJ,1}
    ... List of the Stark-shifted fine-structure sublevels and data with well-defined J-value
+ bbrShift               ::EmProperty        ... Black-body radiation shift of the level at
                                                   Settings.temperature, in a.u.; 0. if no temperature was
                                                   given. It carries NO M-dependence, by the isotropy
                                                   argument in the module docstring.
+ magicWavelengths       ::Array{StarkShift.MagicWavelength,1}
                                             ... The magic wavelengths of THIS level paired with
                                                   settings.magicPartnerIndex, empty unless
                                                   settings.calcMagicWavelengths. A magic wavelength belongs
                                                   to the PAIR, so it is stored on the outcome of the first
                                                   of the two and the partner's own outcome carries the same
                                                   list;  which is which is in the printed table.
+ bbrEta                 ::Float64           ... The dynamic correction eta of that shift, i.e. how far
                                                   alpha_0(omega) departs from alpha_0(0) across the Planck
                                                   spectrum. A small eta says the static polarizability was
                                                   sufficient; a large one says the spectrum reaches the
                                                   level's own excitation energies.
source
JenaAtomicCalculator.StarkShift.Settings — Type

struct StarkShift.Settings <: AbstractPropertySettings ... defines a type for the details and parameters of computing the Stark shift and electric-quadrupole-moments of fine-structure levels.

+ calcEDM                ::Bool              ... True if the EDM of selected levels is to be calculated.
+ calcEQM                ::Bool              ... True if the EQM of selected levels is to be calculated.
+ calcStarkshifts        ::Bool              ... True if the Stark energy shifts are to be computed.
+ calcMagicWavelengths   ::Bool              ... True if the MAGIC WAVELENGTHS of a PAIR of levels are to be
                                                   computed, i.e. the frequencies at which the two levels are
                                                   shifted equally and the transition between them is
                                                   insensitive to the trapping field. Needs gMultiplet and
                                                   magicPartnerIndex;  both are checked.
+ gMultiplet              ::Multiplet         ... A local, approximate Green multiplet of intermediate
                                                   (opposite-parity) ASF that the underlying alpha_0/alpha_2
                                                   sum-over-states runs over -- generated INDEPENDENTLY,
                                                   ahead of time, by the caller (see the module docstring
                                                   and examples/example-Cl.jl); only used if calcStarkshifts.
+ printBefore             ::Bool              ... True if a list of selected levels is printed before the actual computations start.
+ EField                 ::Float64           ... Strength of the electric field in [V/cm]: the CONSTANT
                                                   field if omega = 0., the PEAK amplitude E_0 otherwise
                                                   (see the module docstring on the factor of two).
+ omega                  ::Float64           ... Angular frequency of the driving field, in atomic units.
                                                   0., the default, means a STATIC field and leaves that
                                                   path bit-identical to what it was.
+ temperature            ::Float64           ... Temperature of a black-body radiation field, in KELVIN (the
                                                   same user-facing convention as EField in V/cm). 0., the
                                                   default, means no black-body shift is computed. It is
                                                   INDEPENDENT of EField and omega: a black-body shift is an
                                                   average over the whole Planck spectrum and does not read
                                                   either of them.
+ magicPartnerIndex      ::Int64             ... Index, IN THE COMPUTED MULTIPLET, of the level each selected
                                                   level is paired with for a magic wavelength. A magic
                                                   wavelength belongs to a PAIR and not to a level, and the
                                                   partner is always another level of the same atom, so an
                                                   index into the same multiplet names it -- the same
                                                   vocabulary levelSelection already uses. 0 means none.
+ magicOmegas            ::Array{Float64,1}  ... The frequency window [omegaMin, omegaMax] in atomic units
                                                   within which magic wavelengths are searched. EMPTY means
                                                   the documented defaults of StarkShift.magicWavelengths
                                                   (0.01 to 0.25 a.u.); any other length than 0 or 2 raises.
+ levelSelection         ::LevelSelection    ... Specifies the selected levels, if any.
source
JenaAtomicCalculator.StarkShift.Settings — Method

StarkShift.Settings(set::StarkShift.Settings; calcEDM::Union{Nothing,Bool}=nothing, calcEQM::Union{Nothing,Bool}=nothing, calcStarkshifts::Union{Nothing,Bool}=nothing, calcMagicWavelengths::Union{Nothing,Bool}=nothing, gMultiplet::Union{Nothing,Multiplet}=nothing, printBefore::Union{Nothing,Bool}=nothing, EField::Union{Nothing,Float64}=nothing, omega::Union{Nothing,Float64}=nothing, temperature::Union{Nothing,Float64}=nothing, magicPartnerIndex::Union{Nothing,Int64}=nothing, magicOmegas::Union{Nothing,Array{Float64,1}}=nothing, levelSelection::Union{Nothing,LevelSelection}=nothing)

... keyword copy-constructor for re-defining selected values of a settings::StarkShift.Settings.
    A `settings::StarkShift.Settings` is returned.
source
JenaAtomicCalculator.StarkShift.SublevelJ — Type

struct StarkShift.SublevelJ ... defines a type to specify a Stark-shifted sublevel with well-defined J.

+ M                      ::AngularM64        ... M_J-value
+ energy                 ::EmProperty        ... Stark energy shift of this sublevel, in both the
                                                   Coulomb and Babushkin gauge (see module docstring).
source
JenaAtomicCalculator.StarkShift.addMagicWavelengths — Method

StarkShift.addMagicWavelengths(outcomes::Array{StarkShift.Outcome,1}, multiplet::Multiplet, grid::Radial.Grid, settings::StarkShift.Settings) ... returns the given outcomes with their magicWavelengths filled in, each selected level paired with the level settings.magicPartnerIndex of the SAME multiplet. This exists separately from StarkShift.computeAmplitudesProperties for one reason: a magic wavelength is a property of a PAIR of levels, so it cannot be formed from a single outcome, and the partner has to be looked up where the multiplet is in hand. An Array{StarkShift.Outcome,1} is returned.

    THREE THINGS ARE REFUSED RATHER THAN RETURNED EMPTY, because an empty list reads as "this pair has no
    magic wavelength" -- a physical statement -- where the truth is that the computation was not set up:
    a `gMultiplet` with no levels (the sum-over-states has nothing to run over), a `magicPartnerIndex` that
    names no level of the multiplet, and a `magicOmegas` of any length other than 0 or 2.

+ outcomes    ::Array{StarkShift.Outcome,1}  ... the outcomes whose amplitudes are already computed.
+ multiplet   ::Multiplet                    ... the multiplet the partner level is taken from.
+ grid        ::Radial.Grid                  ... the radial grid.
+ settings    ::StarkShift.Settings          ... carries magicPartnerIndex and magicOmegas.
source
JenaAtomicCalculator.StarkShift.blackbodyFieldSquare — Method

StarkShift.blackbodyFieldSquare(temperature::Float64) ... returns the mean-square electric field <E^2> of an isotropic black-body radiation field at temperature, given in KELVIN as StarkShift.Settings.temperature is, in ATOMIC UNITS. It is four pi times the Stefan-Boltzmann energy density u = (pi^2/15) alpha_fs^3 T^4, since u = <E^2>/(4 pi) for a field with <E^2> = <B^2>, so

        <E^2>  =  (4 pi^3/15) alpha_fs^3 T^4

    with T the temperature in Hartree. A value::Float64 is returned, and 0. for a non-positive temperature.

    THIS IS A COMPLETE EXTERNAL ANCHOR AND COSTS NOTHING TO CHECK, because no atomic quantity enters it: only
    the fine-structure constant does. At 300 K it gives E_rms = 831.945 V/m against the textbook 831.9 V/m,
    and the leading shift it implies for a level of alpha_0 = 1 a.u. is -0.008611 Hz. The same number by
    QUADRATURE over JAC's own `Distribution.photonNumberDensity(Distribution.PhotonPlanck(T), omega)` agrees
    to 1.3e-10, which is how the Planck normalisation used in StarkShift.computeBlackbodyShift was checked;
    that module is deliberately not a dependency here, since the closed form is exact and the spectral weight
    is one expression.
source
JenaAtomicCalculator.StarkShift.checkBlackbodyResonance — Method

StarkShift.checkBlackbodyResonance(temperature::Float64, energies::Array{Float64,1}, nPoints::Int64, xMax::Float64) ... inspects whether the Planck spectrum at temperature reaches the level's own excitation energies and WARNS LOUDLY, to stdout, when it does – which is the one way a black-body shift comes out wrong while looking perfectly reasonable. It measures the FRACTION of the Planck weight x^3/(exp(x)-1) lying ABOVE the lowest excitation energy, since that is the part of the spectrum for which alpha_0(omega) is not a polarizability at all, and warns when that fraction exceeds 1e-3. Nothing is returned.

    WHY A FRACTION RATHER THAN A RULE OF THUMB. The weight peaks at x = 2.82 and is spent by x = 15, so
    "kT well below the first excitation energy" is the usual statement; but what decides whether a number is
    usable is how much weight actually sits above it, and that is one integral. For a low-lying level at
    room temperature the fraction is utterly negligible and nothing is printed. For a RYDBERG level the
    excitation energies fall as 1/n^3 and the fraction approaches one.

    WHAT IS WRONG IN THAT REGIME IS NOT PRECISION BUT THE QUANTITY. Above the lowest excitation energy the
    true alpha_0(omega) is COMPLEX, so the integral is a PRINCIPAL VALUE and its imaginary part is the
    BBR-INDUCED TRANSITION RATE -- a real, separate observable. A plain quadrature gives neither: it returns
    whatever the point nearest a pole happened to contribute, so the distance from the nearest quadrature
    point to the lowest excitation energy is reported too.
source
JenaAtomicCalculator.StarkShift.computeAmplitudesProperties — Method

StarkShift.computeAmplitudesProperties(outcome::StarkShift.Outcome, grid::Radial.Grid, settings::StarkShift.Settings) ... to compute all amplitudes and properties of for a given level. An outcome::StarkShift.Outcome is returned for which the amplitudes and all requested properties are now evaluated explicitly.

source
JenaAtomicCalculator.StarkShift.computeBlackbodyShift — Method

StarkShift.computeBlackbodyShift(level::Level, gMultiplet::Multiplet, grid::Radial.Grid, temperature::Float64; nPoints::Int64=400, xMax::Float64=40.0) ... computes the black-body radiation shift of level at temperature (in Kelvin) by averaging the rank-0 E1 polarizability over the Planck spectrum,

        DeltaE_BBR = -(1/2) <E^2> alpha_eff      alpha_eff = int x^3 alpha_0(Tx)/(e^x-1) dx / int x^3/(e^x-1) dx

    where x = omega/T and BOTH integrals are taken by the SAME quadrature on the SAME nodes -- see the comment
    at the loop, which is the one thing here that must not be tidied -- so that alpha_eff -> alpha_0(0) for a
    flat polarizability to machine precision rather than to the quadrature error, and the leading term is the
    universally quoted -(2/15)(alpha_fs pi)^3 T^4 alpha_0. There is NO second factor of two here, unlike the
    ac Stark shift: <E^2> is already a mean square. Only the RANK-0 polarizability enters, because thermal
    radiation is isotropic and unpolarized -- see the module docstring. A tuple
    (bbrShift::EmProperty, eta::Float64) is returned, with eta = alpha_eff/alpha_0(0) - 1.

    THE SUM OVER STATES IS EVALUATED ONCE, AT omega = 0, and the quadrature over omega is then arithmetic on
    its own stored terms -- the reduced matrix elements and energies that MultipolePolarizibility.Contribution
    carries -- recombined through MultipolePolarizibility.rankCoefficient and .frequencyFactor. That is the
    idiom module-DispersionCoefficient.jl uses for its Casimir-Polder integral, and it matters twice here: a
    few hundred quadrature points would otherwise mean a few hundred sum-over-states evaluations, and
    MultipolePolarizibility.checkFrequency would fire once per point, which is a guard that gets scrolled past.

    eta IS SMALL FOR A LOW-LYING LEVEL AND GROWS AS T^2, being first order in <omega^2>/dE^2 with <omega^2>
    proportional to T^2. Measured on the approved H 1s case: +1.15e-04 at 300 K, +1.28e-03 at 1000 K and
    +1.18e-02 at 3000 K. The law is far sharper on H 2p, whose smaller gap makes eta bigger, and that is the
    case the test suite asserts: the successive ratios at 1, 3, 10, 30, 100 and 300 K come out 9.000, 11.111,
    9.001, 11.120 and 9.062 against the exact (T2/T1)^2 of 9, 11.111, 9, 11.111 and 9 -- holding from
    eta = 3.8e-08 upwards, over two and a half decades. Where eta is NOT small the spectrum has reached the
    level's own excitation energies and StarkShift.checkBlackbodyResonance says so.
source
JenaAtomicCalculator.StarkShift.computeOutcomes — Method

StarkShift.computeOutcomes(multiplet::Multiplet, nm::Nuclear.Model, grid::Radial.Grid, settings::StarkShift.Settings; output=true) ... to compute (as selected) the EDM and EQM factors for the levels of the given multiplet and as specified by the given settings. The results are returned in table (if required) or nothing is returned otherwise. The nuclear model is not used at present.

source
JenaAtomicCalculator.StarkShift.computeStarkShifts — Method

StarkShift.computeStarkShifts(level::Level, gMultiplet::Multiplet, grid::Radial.Grid, settings::StarkShift.Settings) ... computes the Stark shift of every M-sublevel of level in a field of strength settings.EField [V/cm] and angular frequency settings.omega [a.u.], from the level's own E1 scalar/tensor polarizability (taken from MultipolePolarizibility rather than re-derived here – see module docstring):

        DeltaE(J,M) = - c alpha_0(omega) E^2  -  c alpha_2(omega) E^2 [3M^2-J(J+1)] / [J(2J-1)]

    with c = 1/2 for a STATIC field (omega = 0.) and c = 1/4 for a field oscillating at omega, where the
    second case is averaged over the cycle and E is then the PEAK amplitude.  The tensor term is undefined
    and set to 0. for J < 1, matching MultipolePolarizibility's own alpha_2 guard.  A tuple
    (alpha0::EmProperty, alpha2::EmProperty, Jsublevels::Array{StarkShift.SublevelJ,1}) is returned.

    AT omega = 0. THE STATIC ENTRY POINT IS CALLED, not the general one with omega = 0. passed through.  The
    two agree bit for bit -- that is asserted in `testModule_MultipolePolarizibility` -- but keeping the
    static call makes it visible here that adding the dynamic case moved no static number.
source
JenaAtomicCalculator.StarkShift.computeTheta2 — Method

StarkShift.computeTheta2(level::Level, grid::Radial.Grid) ... to compute the electric-quadrupole-moment [Theta^(2)] for the given level; an eqm::Float64 is returned. Until July 2024, it remains unclear why the Clebsch-Gordan coefficient does not give a proper result

source
JenaAtomicCalculator.StarkShift.determineOutcomes — Method

StarkShift.determineOutcomes(multiplet::Multiplet, settings::StarkShift.Settings) ... to determine a list of Outcomes's for the computation of electric-multipole-moments and energy shifts for levels from the given multiplet. It takes into account the particular selections and settings. An Array{StarkShift.Outcome,1} is returned. Apart from the level specification, all physical properties are still set to zero during the initialization process.

source
JenaAtomicCalculator.StarkShift.displayOutcomes — Method

StarkShift.displayOutcomes(outcomes::Array{StarkShift.Outcome,1}) ... to display a list of levels that have been selected for the computations. A small neat table of all selected levels and their energies is printed but nothing is returned otherwise.

source
JenaAtomicCalculator.StarkShift.displayResults — Method

StarkShift.displayResults(stream::IO, outcomes::Array{StarkShift.Outcome,1}, settings::StarkShift.Settings) ... to display the energies, Lande factors, Zeeman amplitudes etc. for the selected levels. A neat table is printed but nothing is returned otherwise.

source
JenaAtomicCalculator.StarkShift.magicWavelengths — Method

StarkShift.magicWavelengths(levelA::Level, levelB::Level, gMultiplet::Multiplet, grid::Radial.Grid; omegaMin::Float64=0.01, omegaMax::Float64=0.25, nSamples::Int64=40, tolerance::Float64=1.0e-12, residualTolerance::Float64=1.0e-6) ... finds every magic wavelength of the pair (levelA, levelB) between omegaMin and omegaMax, i.e. every zero of alpha0(omega, A) - alpha0(omega, B), and returns them as an Array{StarkShift.MagicWavelength,1} in ascending frequency – empty if the range holds none. At such a frequency the trapping light shifts both levels equally, so the TRANSITION between them is untouched to first order in the intensity, which is what lets an optical trap coexist with a clock or a qubit. One gMultiplet serves both levels: each one's own selection rules decide which perturbers it reaches, so unreachable ones drop out on their own.

    A SIGN CHANGE IS NOT A ZERO, AND THAT IS THE WHOLE DIFFICULTY. alpha_0(omega) runs to +infinity as omega
    approaches an excitation energy from below and comes back from -infinity above it, so the difference jumps
    sign across EVERY resonance of EITHER level. A bisection let loose on such a sign change converges
    contentedly onto the POLE and reports a resonance as a magic wavelength -- which is the one error that
    looks entirely plausible, since the answer is a sharp, reproducible frequency.

    THE FIRST HALF OF THE REMEDY IS THAT THE POLES ARE KNOWN EXACTLY: they are the excitation energies that
    StarkShift.polarizabilityTerms returns. The range is CUT at every one of them, and each bracket is taken
    strictly inside a pole-free subinterval.

    AND THAT IS NECESSARY BUT NOT SUFFICIENT, which was MEASURED rather than foreseen -- the first version of
    this function did only the partition and returned two poles as magic wavelengths. THE POLES COME IN
    NEAR-DEGENERATE PAIRS: in hydrogen 2p -> 3s and 2p -> 3d sit 1e-7 apart, and the fine-structure partners of
    any subshell closer still. The sliver between such a pair is below numerical resolution, so the sign change
    inside it is the PAIR OF POLES and not a zero, and bisection converges onto one of them. Measured on
    H 1s against H 2p: the two spurious roots came back with |alpha_A - alpha_B|/alpha of 1.2e+01 and 1.1e+01
    and slopes of 1e12 and 1e13, against 3.5e-09 and 7.8e+04 for the one genuine root.

    SO EVERY CANDIDATE IS VERIFIED by its residual: |alpha_A - alpha_B| must be below `residualTolerance` times
    the scale of the two polarizabilities there, or it is discarded and counted. The two populations are seven
    orders apart, so the default 1e-6 is nowhere near either of them.

    AND EACH SUBINTERVAL IS SAMPLED RATHER THAN MERELY TESTED AT ITS ENDS. Between a pole of A and a pole of B
    the difference runs from -infinity to -infinity, so it holds an EVEN number of zeros -- commonly two, and
    an end-point test finds neither. `nSamples` points per subinterval is the resolution at which two zeros
    can still be separated; raise it if a known magic wavelength is missed.

    WHAT COMES BACK IS NOT AUTOMATICALLY USABLE, and MagicWavelength carries the two reasons why: a zero with
    `alphaCommon` negative is a trap that REPELS, and one with `aboveResonance` true sits where the true
    polarizability is complex and this real sum has no width.
source
JenaAtomicCalculator.StarkShift.makeMagicWavelength — Method

StarkShift.makeMagicWavelength(omega::Float64, strengths::Array{Float64,1}, energies::Array{Float64,1}, dAlpha::Function, lowest::Float64) ... assembles the StarkShift.MagicWavelength record for a zero already located at omega: it converts the frequency to a vacuum wavelength in nm, reads off the polarizability the two levels share there from strengths/energies (either level will do, since that is what a zero of the difference means), takes d(alphaA - alphaB)/d omega by a central difference on dAlpha, and compares omega with lowest, the lowest excitation energy of either level. A mw::StarkShift.MagicWavelength is returned.

source
JenaAtomicCalculator.StarkShift.polarizabilityTerms — Method

StarkShift.polarizabilityTerms(level::Level, gMultiplet::Multiplet, grid::Radial.Grid) ... returns the per-perturber pieces from which the rank-0 E1 polarizability of level can be rebuilt at ANY frequency by arithmetic alone,

        alpha_0(omega) = sum_a strengths[a] * MultipolePolarizibility.frequencyFactor(energies[a], omega, false)

    with strengths[a] = c(L=1, K=0, J, J_a) |<J_a||O^(E1)||J>|^2 and energies[a] = W_a - W_J. The sum over states
    is therefore evaluated ONCE, and that is what makes a frequency quadrature or a root search affordable: a few
    hundred frequencies would otherwise be a few hundred sum-over-states evaluations, each rebuilding subshell
    unions and reduced matrix elements. A tuple (strengths::Array{Float64,1}, energies::Array{Float64,1}) is
    returned, both empty if no perturber of gMultiplet can be reached at all.

    AND THE ENERGIES ARE ALSO THE POLE POSITIONS, which is the second reason this function exists: a root search
    on a difference of polarizabilities has to know where the poles are, because a sign change ACROSS one is not
    a zero -- see StarkShift.magicWavelengths.

    THE REBUILD IS EXACT RATHER THAN AN APPROXIMATION, and that is measured instead of asserted: against a full
    sum-over-states evaluation it is BIT-IDENTICAL at omega = 0, 1e-3, 1e-2, 0.1 and 0.3 a.u. on the approved
    H 1s case (tools/probe-blackbodyShift.jl), the last being a frequency at which alpha_0 has already grown
    from 3.49 to 9.18 a.u.
source
JenaAtomicCalculator.StarkShift.rebuiltPolarizability — Method

StarkShift.rebuiltPolarizability(strengths::Array{Float64,1}, energies::Array{Float64,1}, omega::Float64) ... returns the rank-0 E1 polarizability alpha_0(omega), in a.u., from the pieces that StarkShift.polarizabilityTerms extracted once, on the REAL frequency axis. It is the one place where those pieces are recombined, so that a quadrature and a root search cannot drift apart in how they do it. A value::Float64 is returned, and 0. for an empty set of terms.

source

Muonic atoms

JenaAtomicCalculator.MuonicAtom.computeOrbitals — Method

MuonicAtom.computeOrbitals(subshells::Array{Subshell,1}, nm::Nuclear.Model, grid::Radial.Grid; electronPotential::Union{Nothing,Radial.Potential}=nothing, printout::Bool=false) ... solves the one-particle Dirac equation for a MUON in the potential of the nucleus nm, optionally with the mean field of the electrons added. A dictionary orbitals::Dict{Subshell,Orbital} is returned.

    `electronPotential` is the electrons' contribution in the Zr convention of Radial.Potential and is simply
    ADDED to the nuclear one; passing `nothing` leaves the muon in the bare nuclear field.  The screening it
    provides is small -- the muon sits far inside the electron cloud and sees almost the whole nuclear charge
    -- but it is what makes the muon levels depend on the charge state of the ion.
source
JenaAtomicCalculator.MuonicAtom.displayLevels — Method

MuonicAtom.displayLevels(stream::IO, orbitals::Dict{Subshell,Orbital}, nm::Nuclear.Model) ... displays the muon binding energies of the given orbitals, beside the point-nucleus values they would have if the nuclear charge were concentrated at the origin. Nothing is returned.

source
JenaAtomicCalculator.MuonicAtom.displayTransitions — Method

MuonicAtom.displayTransitions(stream::IO, orbitals::Dict{Subshell,Orbital}) ... displays the muonic X-ray energies, i.e. the differences of the muon binding energies, for every pair of the given subshells with a lower final level. Nothing is returned.

    ENERGIES ONLY.  No rate or intensity is formed, so nothing here says which of these lines is strong; the
    multipole selection rules are not applied either, and a pair that E1 cannot connect is still listed.
source
JenaAtomicCalculator.MuonicAtom.recommendedGrid — Method

MuonicAtom.recommendedGrid(Z::Float64, nMax::Int64) ... returns a Radial.Grid suited to the MUON's orbitals of an atom with nuclear charge Z, up to principal quantum number nMax. A grid::Radial.Grid is returned.

    This exists because Rule 12 -- the box must be matched to the orbitals -- bites twice as hard for a muon.
    A muon orbit is ~207 times smaller than the corresponding electron orbit, so an electron grid is both far
    too coarse near the nucleus and enormously too wide; the B-spline basis then spends its splines on empty
    space and misrepresents exactly the innermost orbital one is after.  The outer turning point of a
    hydrogenic (n,l) orbit is r+ = (n^2/Z)(1 + sqrt(1 - l(l+1)/n^2)) / m, and the box is taken as 2.5 r+ for
    the l = n-1 member of the highest shell requested.
source
JenaAtomicCalculator.MuonicAtom.screeningPotential — Method

MuonicAtom.screeningPotential(orbital::Orbital, grid::Radial.Grid) ... forms the potential that the bound MUON presents to the electrons, in the Zr convention of Radial.Potential. A potential::Radial.Potential is returned, to be ADDED to the nuclear one when the electronic structure of a muonic atom is computed.

    The classical statement about muonic atoms falls out of this: because the muon orbits some two hundred
    times closer than any electron, the electrons cannot resolve it from the nucleus and see one unit of
    charge glued on.  Zr tends to 1 at electron distances, so a muonic atom of charge Z behaves chemically
    like an ordinary atom of charge Z-1 -- and that limit is the natural check on this function.
source

Weak-interaction moments

JenaAtomicCalculator.WeakInteractionMoment.anapoleAmplitude — Method

WeakInteractionMoment.anapoleAmplitude(finalLevel::Level, initialLevel::Level, nm::Nuclear.Model, grid::Radial.Grid; kappaAnapole::Float64=1.0, display::Bool=false)

... to compute the anapole-moment amplitude <alpha_f J_f || H^(anapole) || alpha_i J_i> for the given final and initial level and for
    the nuclear density of the given nuclear model.  The operator is `(G_F/sqrt2) kappa_anapole alpha.I rho(r)`, of rank 1 and odd
    parity.  A value::ComplexF64 is returned, purely imaginary for real radial orbitals.

    THE ANGULAR STRUCTURE IS NOT THE MAGNETIC-MULTIPOLE ONE, and a first implementation that assumed it was had to be withdrawn: the
    template <-kappa_a||C^1||kappa_b> (kappa_a + kappa_b) is parity-EVEN, so it survived for p_1/2 <- p_3/2 and vanished for BOTH
    s_1/2 <- p_1/2 and s_1/2 <- p_3/2 -- exactly backwards for a P-odd operator, and it forbade precisely the s_1/2 <-> p_1/2 mixing
    through which an anapole moment reaches a measured PNC transition.  Branch a of `examples/example-Bb.jl` caught it as a column of
    sixteen identical zeros.

    What is correct follows from alpha = [[0, sigma], [sigma, 0]], which connects the LARGE component of one orbital with the SMALL
    component of the other.  With `Omega_(-kappa) = -(sigma.rhat) Omega_(kappa)` the two cross terms combine, and

        <kappa_a || alpha rho || kappa_b>  =  i [ <Omega_(kappa_a)||sigma||Omega_(-kappa_b)>  INT rho P_a Q_b dr
                                                - <Omega_(-kappa_a)||sigma||Omega_(kappa_b)>  INT rho Q_a P_b dr ] .

    Since sigma acts only on spin it cannot change the orbital angular momentum, so a term vanishes unless the two kappa it couples
    share the same l -- which is what makes the operator parity-odd, Omega_(-kappa) carrying orbital parity l+-1.

    THE TWO CROSS TERMS MUST BE KEPT APART.  A first version combined them into the symmetric P_a Q_b + Q_a P_b, assuming their angular
    factors differ only by a sign.  That is true for gamma_5, whose angular factors are both simply delta(kappa_a, -kappa_b), and FALSE
    here: for s_1/2 <-> p_1/2 the two are <s||sigma||s> = sqrt(6) and <p_1/2||sigma||p_1/2> = -sqrt(6)/3, a ratio of -3 and not -1.  The
    error was invisible in the selection rules and in the reality of the amplitude, and showed up only in the HERMITICITY check, where
    exchanging the two levels multiplied the amplitude by -3 instead of -1.

    `kappaAnapole` is the dimensionless nuclear anapole constant, left at 1.0 so that the amplitude may be scaled by whatever value the
    user adopts.
source
JenaAtomicCalculator.WeakInteractionMoment.displayAmplitude — Method

WeakInteractionMoment.displayAmplitude(label::String, opName::String, nm::Nuclear.Model, finalLevel::Level, initialLevel::Level, amplitude::ComplexF64) ... to print one amplitude to screen and, if it is open, to the summary stream; nothing is returned.

    The two parts are printed with a separator between them: without it the real and imaginary parts run together into one unparsable
    token, and `TestFrames.testCompareLines` can then only compare that token as a STRING, so that a change in the last digit fails the
    test outright instead of being weighed against its tolerance.
source
JenaAtomicCalculator.WeakInteractionMoment.nuclearDensity — Method

WeakInteractionMoment.nuclearDensity(nm::Nuclear.Model, grid::Radial.Grid) ... to compute the NORMALIZED nuclear density rho(r) on the given grid, i.e. with INT rho(r) 4 pi r^2 dr = 1, so that the nuclear charge or weak charge enters only through the prefactor of an operator and never through the density. An Array{Float64,1} over the grid points is returned.

    `Nuclear.fermiDistributedNucleus` cannot serve here: it returns the effective charge Z(r) of the POTENTIAL, not a density, and its
    Fermi shape is a local closure that cannot be reused.  A point nucleus is rejected rather than approximated, since a delta density
    would have every one of these amplitudes depend on the orbital exactly at the origin, where a finite grid says least.
source
JenaAtomicCalculator.WeakInteractionMoment.oneParticleAmplitude — Method

WeakInteractionMoment.oneParticleAmplitude(rank::Int64, kernel::Function, finalLevel::Level, initialLevel::Level) ... to contract a one-electron kernel with the spin-angular coefficients of the two levels and with their mixing coefficients, giving the many-electron REDUCED matrix element <alphaf Jf || H || alphai Ji>. A value::ComplexF64 is returned.

    `SpinAngularGaigalas.computeCoefficients` does NOT return its coefficients in one normalization, and the difference is exactly what this
    function has to absorb.  For rank >= 1 (`computeCoefficientsNonScalar`) the contraction yields the reduced matrix element up to a
    factor sqrt(2J_f+1); for rank 0 (`computeCoefficientsScalar`) it yields the ORDINARY matrix element, as it must, since its main
    client is the one-body Hamiltonian -- and the reduced one then follows from the Wigner-Eckart theorem as sqrt(2J_f+1) times it.
    Both factors were measured against exact one-electron reduced matrix elements rather than assumed; see the module's example branch.
source
JenaAtomicCalculator.WeakInteractionMoment.radialDerivative — Method

WeakInteractionMoment.radialDerivative(f::Array{Float64,1}, grid::Radial.Grid) ... to compute df/dr on the given grid by central differences, with one-sided differences at the two ends; an Array{Float64,1} is returned. The grid is not uniform in r, so the spacing is taken from grid.r itself rather than assumed.

source
JenaAtomicCalculator.WeakInteractionMoment.radialIntegralPPplus — Method

WeakInteractionMoment.radialIntegralPPplus(weight::Array{Float64,1}, a::Orbital, b::Orbital, grid::Radial.Grid) ... to compute INT weight(r) [Pa Pb + Qa Qb] dr, the combination of an operator that does not mix the large and small components; a value::Float64 is returned.

source
JenaAtomicCalculator.WeakInteractionMoment.radialIntegralPQ — Method

WeakInteractionMoment.radialIntegralPQ(weight::Array{Float64,1}, a::Orbital, b::Orbital, grid::Radial.Grid) ... to compute INT weight(r) Pa(r) Qb(r) dr, i.e. the LARGE component of the first orbital against the SMALL component of the second; a value::Float64 is returned. It is the same shape as RadialIntegrals.GrantIL0, with a nuclear density in place of a spherical Bessel function.

    This deliberately does NOT symmetrize.  An operator built from the Dirac alpha matrix produces two cross terms, P_a Q_b and Q_a P_b,
    and they carry DIFFERENT angular factors; combining them into P_a Q_b + Q_a P_b is legitimate only when those factors happen to be
    equal up to a sign, which is true for gamma_5 but false for alpha.  Assuming it for the anapole cost a factor of -3 in the
    Hermiticity check.  The caller therefore weights the two terms itself; `radialIntegralPQ(w, b, a, grid)` supplies the second.
source
JenaAtomicCalculator.WeakInteractionMoment.radialIntegralPQminus — Method

WeakInteractionMoment.radialIntegralPQminus(weight::Array{Float64,1}, a::Orbital, b::Orbital, grid::Radial.Grid) ... to compute INT weight(r) [Pa Qb - Qa Pb] dr, the antisymmetric large/small combination that gamma_5 produces; a value::Float64 is returned. It is the same shape as RadialIntegrals.GrantILminus, with a nuclear density in place of a spherical Bessel function.

source
JenaAtomicCalculator.WeakInteractionMoment.schiffMomentAmplitude — Method

WeakInteractionMoment.schiffMomentAmplitude(finalLevel::Level, initialLevel::Level, nm::Nuclear.Model, grid::Radial.Grid; display::Bool=false)

... to compute the Schiff-moment amplitude <alpha_f J_f || H^(Schiff) || alpha_i J_i> for the given final and initial level and for the
    nuclear density of the given nuclear model.  The operator is `4 pi S . grad rho(r)`, of rank 1 and odd parity, and -- being a
    function of position rather than a Dirac matrix -- it carries the ELECTRIC-multipole structure, i.e. <kappa_a||C^1||kappa_b> and the
    P*P + Q*Q radial combination, with the density GRADIENT as the radial weight.  A value::ComplexF64 is returned.

    The amplitude is returned for a unit Schiff moment, so that it may be scaled by whatever nuclear value is adopted.
source
JenaAtomicCalculator.WeakInteractionMoment.sigmaReducedMe — Method

WeakInteractionMoment.sigmaReducedMe(kappaA::Int64, kappaB::Int64) ... to compute the reduced matrix element <Omega(kappaA) || sigma || Omega(kappaB)> of the Pauli spin operator between two spin-angular functions; a value::Float64 is returned.

    sigma acts on the spin alone, so it cannot change the orbital angular momentum and the result vanishes unless l_A = l_B.  With that
    understood, the two functions are just |(l 1/2) j> couplings and the Wigner-Eckart theorem for an operator acting on the second
    factor gives

        <(l 1/2)j_A || sigma || (l 1/2)j_B> = (-1)^(l + 1/2 + j_B + 1) sqrt((2j_A+1)(2j_B+1)) {1/2  j_A  l ; j_B  1/2  1} sqrt(6),

    the sqrt(6) being <1/2||sigma||1/2>.  Note that j_A and j_B need NOT be equal: for a given l the two values l +- 1/2 are connected,
    which is why the anapole amplitude reaches p_1/2 <-> d_3/2 as well as s_1/2 <-> p_1/2 once the -kappa_B of the small component is
    taken into account.
source
JenaAtomicCalculator.WeakInteractionMoment.weakCharge — Method

WeakInteractionMoment.weakCharge(nm::Nuclear.Model) ... to compute the nuclear weak charge QW = -N + Z(1 - 4 sin^2 thetaW) from the given nuclear model, with the neutron number taken as N = round(mass) - Z; a value::Float64 is returned.

    `Nuclear.Model` carries no neutron number and no weak charge, so both are derived here rather than by extending that struct, whose
    eight-field constructor is called positionally throughout src/ and examples/.
source
JenaAtomicCalculator.WeakInteractionMoment.weakChargeAmplitude — Method

WeakInteractionMoment.weakChargeAmplitude(finalLevel::Level, initialLevel::Level, nm::Nuclear.Model, grid::Radial.Grid; display::Bool=false)

... to compute the weak-charge amplitude <alpha_f J_f || H^(weak-charge) || alpha_i J_i> for the given final and initial level and for
    the nuclear density of the given nuclear model.  A value::ComplexF64 is returned.

    The operator `(G_F/2sqrt2) Q_W rho(r) gamma_5` is a PSEUDOSCALAR: rank 0 and odd parity.  It therefore connects only levels of the
    SAME total angular momentum and OPPOSITE parity, and its one-electron matrix element vanishes unless kappa_b = -kappa_a, i.e.
    between the two orbitals of equal j and opposite parity such as s_1/2 and p_1/2.  All three conditions are enforced here rather
    than left to cancel numerically.

    The result is PURELY IMAGINARY for real radial orbitals, since gamma_5 produces the antisymmetric P_a Q_b - Q_a P_b combination.
source

Weak-interaction enhancement factors

JenaAtomicCalculator.WeakInteractionEnhancement.Outcome — Type

struct WeakInteractionEnhancement.Outcome ... defines a type to keep the outcome of a weak-interaction-enhancement computation for ONE level.

+ level                     ::Level                            ... Atomic level to which the outcome refers to.
+ edmEnhancement            ::Float64                          ... R = d_atom/d_e for this level, from the truncated sum over
                                                                    gMultiplet; UNCONVERGED rather than an estimate, and of an
                                                                    operator whose absolute scale is unverified -- see the module
                                                                    docstring before quoting it.
+ pncAmplitudes             ::Array{Tuple{Level,ComplexF64},1} ... List of (partner level, E1_PNC) pairs, in which the amplitude
                                                                    <level || D_PNC || partner> is given in atomic units (e a_0) and is
                                                                    purely imaginary for real orbitals.
source
JenaAtomicCalculator.WeakInteractionEnhancement.Settings — Type

struct WeakInteractionEnhancement.Settings <: AbstractPropertySettings ... defines a type for the details and parameters of computing the parity-non-conserving E1 amplitude and the electron-EDM enhancement factor.

+ calcPncE1                ::Bool             ... True if the PNC E1 amplitudes between the selected levels are to be computed.
+ calcEdmEnhancement       ::Bool             ... True if the electron-EDM enhancement factor R = d_atom/d_e is to be computed; see the
                                                    module docstring for why R from a truncated sum is reported as unconverged.
+ gMultiplet               ::Multiplet        ... The intermediate levels of the sum over states, supplied by the caller; only those of
                                                    parity opposite to the level in question contribute, and the others are ignored.
+ printBefore              ::Bool             ... True if a list of selected levels is printed before the actual computations start.
+ levelSelection           ::LevelSelection   ... Specifies the selected levels, if any.
source
JenaAtomicCalculator.WeakInteractionEnhancement.Settings — Method

WeakInteractionEnhancement.Settings(set::WeakInteractionEnhancement.Settings; calcPncE1::Union{Nothing,Bool}=nothing, calcEdmEnhancement::Union{Nothing,Bool}=nothing, gMultiplet::Union{Nothing,Multiplet}=nothing, printBefore::Union{Nothing,Bool}=nothing, levelSelection::Union{Nothing,LevelSelection}=nothing)

... keyword copy-constructor for re-defining selected values of a settings::WeakInteractionEnhancement.Settings; a
    settings::WeakInteractionEnhancement.Settings is returned.
source
JenaAtomicCalculator.WeakInteractionEnhancement.Settings — Method

WeakInteractionEnhancement.Settings() ... constructor for an empty instance of WeakInteractionEnhancement.Settings; a settings::WeakInteractionEnhancement.Settings is returned. The empty gMultiplet must be replaced before anything can be computed, since the sum over states has no intermediates without it.

source
JenaAtomicCalculator.WeakInteractionEnhancement.computeEdmEnhancement — Method

WeakInteractionEnhancement.computeEdmEnhancement(level::Level, gMultiplet::Multiplet, nm::Nuclear.Model, grid::Radial.Grid) ... to compute the enhancement factor R = datom/de of an electron electric-dipole moment in the given level, from the sum over the opposite-parity intermediate levels of gMultiplet. A value::Float64 is returned.

    The atomic moment is the expectation of D_z in the perturbed state of the stretched magnetic substate M = J,

        d_atom = 2 SUM_n <0|D_z|n> <n|H_EDM|0> / (E_0 - E_n),

    in which H_EDM is a scalar, so that only intermediates of the same J and opposite parity contribute.  Using the projection
    <j j|T^1_0|j j> = sqrt( j / ((j+1)(2j+1)) ) <j||T^1||j> the whole sum reduces to reduced matrix elements.  R is returned for a unit
    electron EDM and is therefore dimensionless.  Read the module docstring before using the number: Schiff's theorem makes this a
    CANCELLING sum, which converges more slowly than E1_PNC does over the same intermediate sets, and in a hydrogen-like ion it is
    dominated by the 2s-2p_1/2 denominator that a calculation without QED gets wrong by some two orders of magnitude.
source
JenaAtomicCalculator.WeakInteractionEnhancement.computeOutcomes — Method

WeakInteractionEnhancement.computeOutcomes(multiplet::Multiplet, nm::Nuclear.Model, grid::Radial.Grid, settings::WeakInteractionEnhancement.Settings; output=true) ... to compute (as selected) the parity-non-conserving E1 amplitudes and the electron-EDM enhancement factors for the levels of the given multiplet. The intermediate states of both sums are taken from settings.gMultiplet. The results are printed in neat tables to screen and, if output, an Array{WeakInteractionEnhancement.Outcome,1} is returned; nothing otherwise.

source
JenaAtomicCalculator.WeakInteractionEnhancement.computePncE1Amplitude — Method

WeakInteractionEnhancement.computePncE1Amplitude(finalLevel::Level, initialLevel::Level, gMultiplet::Multiplet, nm::Nuclear.Model, grid::Radial.Grid) ... to compute the parity-non-conserving electric-dipole amplitude <finalLevel || DPNC || initialLevel> between two levels of the SAME parity, from the sum over the opposite-parity intermediate levels of gMultiplet. A value::ComplexF64 is returned, in atomic units (e a0).

    The weak-charge Hamiltonian is a scalar and so admixes opposite-parity states without altering the angular structure; the amplitude
    therefore remains an ordinary rank-1 reduced matrix element,

        <f||D_PNC||i> = SUM_n [ <f||D||n> <n|H_W|i>/(E_i - E_n)  +  <f|H_W|n> <n||D||i>/(E_f - E_n) ],

    in which <n|H_W|i> is the ORDINARY matrix element, i.e. the reduced one divided by sqrt(2J+1), and is nonzero only for J_n = J_i.
    The result is purely imaginary for real radial orbitals, since the weak-charge amplitude is.
source
JenaAtomicCalculator.WeakInteractionEnhancement.computePncE1AmplitudeNsd — Method

WeakInteractionEnhancement.computePncE1AmplitudeNsd(finalLevel::Level, Ff::AngularJ64, initialLevel::Level, Fi::AngularJ64, gMultiplet::Multiplet, nm::Nuclear.Model, grid::Radial.Grid; kappaAnapole::Float64=1.0) ... to compute the NUCLEAR-SPIN-DEPENDENT parity-non-conserving electric-dipole amplitude <f Jf I Ff || DPNC || i Ji I Fi> between two HYPERFINE levels of the same electronic parity, from the sum over the opposite-parity intermediate levels of gMultiplet. A value::ComplexF64 is returned, in atomic units (e a0).

    THIS IS A DIFFERENT OBSERVABLE FROM `computePncE1Amplitude` AND NOT A REFINEMENT OF IT.  The weak charge is a scalar, so the
    amplitude it drives is an ordinary rank-1 reduced matrix element between FINE-STRUCTURE levels and the hyperfine structure only
    re-couples it.  The anapole moment is not: its operator is the scalar product `alpha.I rho(r)` of an electronic rank-1 tensor with
    the nuclear spin, so it is a scalar only in the COUPLED electron-plus-nucleus space, and the amplitude it drives exists only between
    hyperfine levels.  A nucleus of spin zero has no anapole amplitude at all, and this function returns zero for one.

    The consequence that matters for an experiment is a selection rule.  Because the weak charge cannot change J, the intermediate level
    must carry J_n = J_i on one side and J_n = J_f on the other, and a transition such as barium 6s_1/2 - 5d_5/2 then has NO
    nuclear-spin-independent amplitude whatever: no single E1 step reaches from J = 1/2 to J = 5/2.  The anapole operator obeys only the
    triangle |J_n - J_i| <= 1, so p_3/2 intermediates open and the amplitude is non-zero.  Such a transition is therefore a CLEAN
    anapole probe rather than a weak-charge measurement with a small spin-dependent correction, which is the reverse of the caesium
    6s-7s situation.

    The two geometrical factors are `hyperfineMultipoleFactor` and `hyperfineScalarFactor`; the electronic reduced matrix element of the
    anapole operator is `WeakInteractionMoment.anapoleAmplitude`, which already carries the `G_F/sqrt(2) kappa` prefactor.  Since the
    anapole Hamiltonian is diagonal in F, the admixture on the initial side carries F_i and that on the final side F_f.

    + kappaAnapole  ::Float64   ... the dimensionless nuclear anapole constant, left at 1.0 so that the returned amplitude is the
                                    coefficient OF kappa and may be scaled by whatever value the user adopts.  The convention is the one
                                    of Flambaum and Khriplovich, `H = (G_F/sqrt2) kappa (alpha.I/I) rho(r)`, i.e. with the 1/I that
                                    makes kappa comparable with the caesium value 0.112(16) of Wood et al., Science 275, 1759 (1997).
source
JenaAtomicCalculator.WeakInteractionEnhancement.computePncE1AmplitudeNsi — Method

WeakInteractionEnhancement.computePncE1AmplitudeNsi(finalLevel::Level, Ff::AngularJ64, initialLevel::Level, Fi::AngularJ64, gMultiplet::Multiplet, nm::Nuclear.Model, grid::Radial.Grid) ... to re-couple the nuclear-spin-independent amplitude of computePncE1Amplitude into the hyperfine basis, giving <f Jf I Ff || DPNC || i Ji I Fi>. A value::ComplexF64 is returned, in atomic units (e a0).

    It carries no physics of its own: the weak charge is a purely electronic scalar, so the F-dependence is the single geometrical
    factor `hyperfineMultipoleFactor` and nothing else. The function exists so that the two contributions to one measured hyperfine line
    can be added, which is what an experiment sees, and so that their RATIO can be formed on the same footing -- the caesium anapole
    moment was extracted from exactly that ratio, as the small difference between the F = 3 -> 4 and F = 4 -> 3 components of one line.
source
JenaAtomicCalculator.WeakInteractionEnhancement.determineOutcomes — Method

WeakInteractionEnhancement.determineOutcomes(multiplet::Multiplet, settings::WeakInteractionEnhancement.Settings) ... to determine a list of Outcome's for the computation of the enhancement properties for the given multiplet, taking the level selection of the settings into account. An Array{WeakInteractionEnhancement.Outcome,1} is returned, in which all physical properties are still set to zero.

source
JenaAtomicCalculator.WeakInteractionEnhancement.dipoleReducedMe — Method

WeakInteractionEnhancement.dipoleReducedMe(finalLevel::Level, initialLevel::Level, grid::Radial.Grid) ... to compute the reduced electric-dipole matrix element <alphaf Jf || D || alphai Ji> in the LENGTH form and in atomic units (e a_0). A value::ComplexF64 is returned.

    It is deliberately built from `WeakInteractionMoment.oneParticleAmplitude`, the same contraction that produces the weak-charge
    amplitude, rather than from `MultipoleMoment.dipoleAmplitude`.  The two observables of this module are PRODUCTS of a dipole and a
    weak matrix element, so what matters is that both factors carry the same normalization; routing them through one contraction makes
    that automatic and leaves only an overall constant that the example branch measures.
source
JenaAtomicCalculator.WeakInteractionEnhancement.displayOutcomes — Method

WeakInteractionEnhancement.displayOutcomes(stream::IO, outcomes::Array{WeakInteractionEnhancement.Outcome,1}, settings::WeakInteractionEnhancement.Settings) ... to display the levels that have been selected, together with the size of the intermediate multiplet, before the computation starts. Nothing is returned.

source
JenaAtomicCalculator.WeakInteractionEnhancement.displayResults — Method

WeakInteractionEnhancement.displayResults(stream::IO, outcomes::Array{WeakInteractionEnhancement.Outcome,1}, settings::WeakInteractionEnhancement.Settings) ... to display the PNC E1 amplitudes and the EDM enhancement factors that have been computed, each in its own table. Nothing is returned.

source
JenaAtomicCalculator.WeakInteractionEnhancement.edmAmplitude — Method

WeakInteractionEnhancement.edmAmplitude(finalLevel::Level, initialLevel::Level, nm::Nuclear.Model, grid::Radial.Grid; display::Bool=false)

... to compute the electron-EDM amplitude <alpha_f J_f || H^(EDM) || alpha_i J_i> for a UNIT electron electric-dipole moment, in the
    nuclear field of the given model.  A value::ComplexF64 is returned.

    The operator is `H_EDM = -d_e beta Sigma.E` with `E = -grad phi` the internal electric field.  Sigma is an axial vector and E a
    polar one, so their contraction is a PSEUDOSCALAR: rank 0, P-odd and, since Sigma changes sign under time reversal while E does not,
    also T-odd.  It therefore obeys the same selection rules as the weak charge -- equal J, opposite parity, kappa_b = -kappa_a -- but a
    different radial structure, because beta Sigma.r does not mix the large and small components and instead weights them with opposite
    signs:

        <a|H_EDM|b>  =  d_e  INT E_r(r) [P_a P_b - Q_a Q_b] dr ,    kappa_b = -kappa_a

    using  <Om(kappa_a)|sigma.r|Om(kappa_b)> = -delta(kappa_a, -kappa_b)  for both the upper and the lower pair.  The amplitude is REAL
    for real radial orbitals, in contrast to the weak charge, whose gamma_5 supplies an explicit factor of i.
source
JenaAtomicCalculator.WeakInteractionEnhancement.hyperfineMultipoleFactor — Method

WeakInteractionEnhancement.hyperfineMultipoleFactor(rank::Int64, Ja::AngularJ64, Fa::AngularJ64, Jb::AngularJ64, Fb::AngularJ64, spinI::AngularJ64) ... to compute the geometrical factor that turns a purely ELECTRONIC reduced matrix element <a Ja || T^(rank) || b Jb> into the reduced matrix element <a Ja I Fa || T^(rank) || b Jb I Fb> of the same operator in the coupled hyperfine basis. A value::Float64 is returned, and it is zero whenever the momenta cannot be coupled.

    THE FORMULA IS NOT REPEATED HERE.  It is `Hfs.recouplingElectronicOperator`, which carries it and was verified over 454
    combinations of I, J_a, J_b, F_a and rank; this method only adds the guards that let it be called from inside a loop over
    intermediate levels.  Those guards are the reason it exists at all: the recoupling routine reaches `AngularMomentum.phaseFactor`,
    which RAISES for momenta that cannot be coupled, whereas a sum over states must simply skip such a level.  Keeping a second copy of
    the algebra was tried and rejected on 5-Sep-2026 -- the two agreed to 0.0 over 497 combinations, which is exactly the situation in
    which one of them later drifts.

    `rank` is 1 for the electric dipole and for the nuclear-spin-independent PNC amplitude, 2 for an electric quadrupole; any rank the
    underlying reduced matrix element is defined for may be used.
source
JenaAtomicCalculator.WeakInteractionEnhancement.hyperfineScalarFactor — Method

WeakInteractionEnhancement.hyperfineScalarFactor(Ja::AngularJ64, Jb::AngularJ64, F::AngularJ64, spinI::AngularJ64) ... to compute the geometrical factor that turns the ELECTRONIC rank-1 reduced matrix element <a Ja || alpha rho || b Jb> of the anapole operator into the matrix element of the full scalar Hamiltonian H = (G_F/sqrt2) kappa (alpha.I/I) rho(r) between the hyperfine states |a Ja I F> and |b Jb I F>. A value::Float64 is returned; it is zero for a nucleus of spin zero.

        factor = (-1)^(I + J_b + F) { F  J_a  I ; 1  I  J_b }  sqrt( I(I+1)(2I+1) ) / I

    The first three factors are the reduction of a scalar product of two commuting tensors (Edmonds, Eq. 7.1.6), in the SAME form and
    with the same phase convention as `Hfs.computeHyperfineRepresentation` uses for the hyperfine matrix itself, which was verified
    there against the Casimir formula.  The last factor is the nuclear reduced matrix element <I||I||I> = sqrt(I(I+1)(2I+1)), divided by
    I because the anapole constant kappa is conventionally defined with the unit vector I/I; carrying that 1/I here is what makes a
    kappa extracted from a computed amplitude comparable with the published caesium value.

    Note that the operator is diagonal in F but NOT in J: the triangle |J_a - J_b| <= 1 is what lets the anapole reach intermediate
    levels that the weak charge cannot, and is the whole reason a spin-dependent amplitude survives where the spin-independent one
    vanishes.
source
JenaAtomicCalculator.WeakInteractionEnhancement.radialIntegralPPminus — Method

WeakInteractionEnhancement.radialIntegralPPminus(weight::Array{Float64,1}, a::Orbital, b::Orbital, grid::Radial.Grid) ... to compute INT weight(r) [Pa Pb - Qa Qb] dr, the combination that the Dirac matrix beta produces by weighting the large and the small components with opposite signs; a value::Float64 is returned.

    It completes the family of `WeakInteractionMoment.radialIntegralPPplus`, `radialIntegralPQminus` and `radialIntegralPQ`, and belongs
    beside them; it sits here only because the EDM operator does, see the module docstring.
source

Multipole polarizibilities

JenaAtomicCalculator.MultipolePolarizibility.Contribution — Type

struct MultipolePolarizibility.Contribution ... defines a type to keep the individual contribution of ONE intermediate (perturber) ASF from gMultiplet to the static multipole polarizability alpha^(Mp,K) of some other (fixed) level. One such term is built per perturber AND per multipole, and it carries the multipole it belongs to in its own multipole field, so that the contributions of several requested multipoles can be told apart in one Outcome.

+ nuLevel        ::Level        ... The intermediate (perturber) level nuLevel = J' from gMultiplet.
+ deltaE         ::Float64      ... Energy denominator W_J - W_J' (atomic units) entering this term.
+ contribAlpha0  ::EmProperty   ... This perturber's own additive contribution to alpha_0(J), in a.u.,
                                    in both the Coulomb and Babushkin gauge (see module docstring).
+ contribAlpha2  ::EmProperty   ... This perturber's own additive contribution to alpha_2(J), in a.u.,
                                    in both gauges; identically 0. for J<1, where the tensor
                                    polarizability does not exist.
+ multipole      ::EmMultipole  ... The multipole Mp whose polarizability this term contributes to; E1 for
                                    every term built by computeScalarTensorPolarizability.
+ reducedMe      ::Float64      ... The static reduced matrix element <J' || O^(Mp) || J> ITSELF, kept
                                    because the whole frequency dependence of a polarizability sits in the
                                    denominator: with reducedMe and deltaE stored, alpha^(Mp,K) at any real
                                    or imaginary frequency -- and hence any dispersion coefficient -- is a
                                    re-summation of these same terms and needs no new structure calculation.
+ contribAlphas  ::Array{Tuple{Int64,EmProperty},1}
                                ... (K, contribution) for EVERY rank K this perturber feeds, in ascending K;
                                    contribAlpha0/contribAlpha2 are the K = 0 and K = 2 members of it.
+ omega          ::Float64      ... The frequency at which this term was evaluated; 0. for a static one. A
                                    Contribution belongs to ONE (multipole, frequency) evaluation, so a caller
                                    that asked for several frequencies can tell the terms apart by this field.
+ imaginaryOmega ::Bool         ... True if `omega` is to be read as the IMAGINARY frequency i*omega, which is
                                    what a dispersion coefficient needs and where the sum has no poles at all.
source
JenaAtomicCalculator.MultipolePolarizibility.Outcome — Type

struct MultipolePolarizibility.Outcome ... defines a type to keep the outcome of a static-polarizability computation.

+ level          ::Level                                 ... Atomic level to which the outcome refers to.
+ alpha0         ::EmProperty                             ... static scalar (rank 0) electric-dipole
                                                                polarizability alpha_0(J), in atomic units,
                                                                in both the Coulomb and Babushkin gauge.
+ alpha2         ::EmProperty                             ... static tensor (rank 2) electric-dipole
                                                                polarizability alpha_2(J), in atomic units,
                                                                in both gauges; identically 0. for J<1,
                                                                where the tensor polarizability does not exist.
+ contributions  ::Array{MultipolePolarizibility.Contribution,1}
                                                            ... individual, additive contribution of every
                                                                intermediate ASF in gMultiplet that the requested
                                                                multipoles can reach from level; each term names
                                                                its own multipole (see module docstring).
+ alphas         ::Array{Tuple{EmMultipole,Int64,Float64,EmProperty},1}
                                                            ... (Mp, K, omega, alpha^(Mp,K)(omega)) for every
                                                                multipole requested, every rank K this level can
                                                                carry and every frequency in Settings.omegas,
                                                                in the order computed; omega = 0. is ALWAYS
                                                                present, and alpha0/alpha2 above are its (E1,0)
                                                                and (E1,2) members. These frequencies are REAL;
                                                                the imaginary axis is reached by calling
                                                                computeMultipolePolarizabilities directly, since
                                                                i*omega is an internal device for dispersion
                                                                coefficients rather than a property anyone asks
                                                                for on its own.
+ alphaCore      ::Array{Tuple{Float64,Float64},1}          ... (omega, alpha_core(omega)) for every frequency, when
                                                                Settings.calcCore is true, and empty otherwise. This
                                                                is the CLOSED subshells' polarizability from a
                                                                complete basis, so it is ADDITIVE to the alphas above
                                                                and deliberately kept apart from them rather than
                                                                summed in: the two are computed by different routes
                                                                with different accuracies, and adding them silently
                                                                would hide which.
source
JenaAtomicCalculator.MultipolePolarizibility.Settings — Type

struct MultipolePolarizibility.Settings <: AbstractPropertySettings ... defines a type for the details and parameters of computing multipolar polarizibilities.

+ multipoles                ::Array{EmMultipole,1}  ... Multipoles to be considered for the polarity. Stage 1
                                                          only supports E1 (the classic scalar/tensor
                                                          polarizability); any other multipole present in the
                                                          list is skipped with a warning.
+ gMultiplet                ::Multiplet             ... A local, approximate Green multiplet of intermediate
                                                          (opposite-parity) ASF that the sum-over-states runs
                                                          over -- generated INDEPENDENTLY, ahead of time, by the
                                                          caller (e.g. via AtomicState.GreenExpansion/generate(),
                                                          see examples/example-Aj.jl) and simply consumed here;
                                                          mirrors MultiPhotonTransition.Settings.gMultiplet.
+ omegas                    ::Array{Float64,1}      ... List of REAL frequencies (in atomic units) at which the
                                                          dynamic polarizability is wanted, beside the static
                                                          case. omega = 0. is always computed whether or not it
                                                          appears here, so alpha0/alpha2 of the Outcome keep
                                                          their meaning; duplicates are dropped. A frequency at
                                                          or above the lowest excitation energy is WARNED about
                                                          rather than refused -- see
                                                          MultipolePolarizibility.checkFrequency.
+ helicity                  ::Int64                 ... Helicity of the field: 0 for a linearly polarized or static
                                                          field, which is the default and carries only the EVEN
                                                          ranks K = 0, 2, ... as this module always has, and +-1 for
                                                          a circularly polarized one, which carries every K and so
                                                          opens the ODD ranks -- K = 1 being the vector
                                                          polarizability alpha_1. An odd rank is purely dynamic and
                                                          comes back as zero unless a frequency is given in omegas.
+ printBefore               ::Bool                  ... True if a list of selected levels is printed before the
                                                        actual computations start.
+ levelSelection            ::LevelSelection        ... Specifies the selected levels, if any.
+ calcCore                  ::Bool                  ... True if the CORE polarizability of the level's CLOSED
                                                          subshells is to be computed as well, from a COMPLETE
                                                          B-spline basis rather than from gMultiplet -- see
                                                          MultipolePolarizibility.computeCorePolarizability for
                                                          why that is a different calculation and not a better
                                                          perturber list. It needs no gMultiplet, it is reported
                                                          in its own table, and it is evaluated at every
                                                          frequency in omegas as well as at omega = 0.
source
JenaAtomicCalculator.MultipolePolarizibility.Settings — Method

MultipolePolarizibility.Settings(set::MultipolePolarizibility.Settings; multipoles::Union{Nothing,Array{EmMultipole,1}}=nothing, gMultiplet::Union{Nothing,Multiplet}=nothing, omegas::Union{Nothing,Array{Float64,1}}=nothing, helicity::Union{Nothing,Int64}=nothing, printBefore::Union{Nothing,Bool}=nothing, levelSelection::Union{Nothing,LevelSelection}=nothing, calcCore::Union{Nothing,Bool}=nothing)

... keyword copy-constructor for re-defining selected values of a settings::MultipolePolarizibility.Settings.
    A `settings::MultipolePolarizibility.Settings` is returned.
source
JenaAtomicCalculator.MultipolePolarizibility.allowedRanks — Method

MultipolePolarizibility.allowedRanks(multipole::EmMultipole, J::AngularJ64; helicity::Int64=0) ... returns the ranks K for which a level of angular momentum J can carry a non-vanishing multipole polarizability alpha^(Mp,K) in the field of the given 2^L-pole multipole and of the given helicity. Two rules always act: K <= 2L, because the rank-K component is built by coupling the two 2^L-pole operators of the second-order expression, and K <= 2J, by the Wigner-Eckart theorem applied between the substates of one level. THE THIRD RULE IS THE HELICITY, and it is what decides the parity of K: a linearly polarized or static field, helicity = 0, carries only EVEN K, because its two coupled operators are identical and the 3-j symbol of MultipolePolarizibility.rankCoefficient then vanishes; a circularly polarized field, helicity = +-1, carries EVERY K <= min(2L, 2J), the odd members being the axial polarizabilities of which K = 1 is the one the literature calls the vector polarizability alpha_1. A ranks::Array{Int64,1} is returned, in ascending order; it always contains K = 0.

    AN ODD RANK IS PURELY DYNAMIC. It is returned here whenever the helicity allows it, but it comes back as a clean
    zero from a static computation, because its energy denominator is proportional to omega -- see
    MultipolePolarizibility.frequencyFactorOdd. That is physics and not a missing case: a static field has no handedness.
source
JenaAtomicCalculator.MultipolePolarizibility.checkFrequency — Method

MultipolePolarizibility.checkFrequency(multipole::EmMultipole, level::Level, omega::Float64, imaginaryOmega::Bool, contributions::Array{MultipolePolarizibility.Contribution,1}) ... inspects the frequency a dynamic polarizability was asked for and WARNS LOUDLY, to stdout, about the two ways it goes wrong while still returning a finite, plausible-looking number. Both concern the REAL axis only; on the imaginary axis the denominator is dE^2 + omega^2, which cannot vanish, and that is precisely why a dispersion coefficient is evaluated there. Nothing is returned.

    THE FIRST IS THAT THE TRUE POLARIZABILITY IS COMPLEX AND THIS SUM IS REAL. Above the lowest excitation energy
    the atom absorbs, alpha(omega) acquires an imaginary part, and a sum over a DISCRETE perturber set cannot
    represent it -- what comes back is a principal-value-like real part with no width. The number is not a
    polarizability there, however reasonable it looks.

    THE SECOND IS A POLE. As omega approaches a perturber's excitation energy the factor dE/(dE^2 - omega^2)
    diverges, so the result is carried by ONE term and is only as accurate as that ONE energy. For a genuine
    low-lying perturber that is a real resonance; for a high-n pseudo-state standing in for the continuum -- which
    is most of the set, and whose energy means nothing individually -- it is an artefact of the discretisation.
source
JenaAtomicCalculator.MultipolePolarizibility.checkPerturberSet — Method

MultipolePolarizibility.checkPerturberSet(multipole::EmMultipole, level::Level, gMultiplet::Multiplet, grid::Radial.Grid, contributions::Array{MultipolePolarizibility.Contribution,1}, alphaScalar::Float64) ... inspects the perturber set that was actually used and WARNS LOUDLY, to stdout, about the two conditions under which a multipole polarizability comes out wrong while looking perfectly reasonable. The first is that NO level of gMultiplet can be reached at all: a 2^L-pole operator needs perturbers of its own parity and within its own triangle, so a set of np levels – right for E1 – reaches NOTHING for E2, and the sum then returns a clean zero rather than an error. The second is that the sum HAS NOT SATURATED: the discrete perturber series stands in for the continuum, so the highest-lying member must already contribute negligibly, and where it does not the result is a lower bound of unknown quality rather than a polarizability. The third, for L >= 2 only, re-runs Bsplines.checkOrbitalConsistency on the perturber orbitals, because an ill-matched radial box is far more dangerous for a high multipole than for E1 – see the measured figures in the module docstring. Nothing is returned.

    NO FOURTH GUARD IS OFFERED, AND THAT IS DELIBERATE. Two candidate detectors for a box-corrupted sum were
    built and MEASURED on one healthy and two catastrophic E4 cases, and NEITHER discriminates: where the largest
    contribution sits in the energy-ordered series put the healthy case FURTHER up (78 % of the way) than either
    corrupted one (43 %, 37 %), and box/<r> of the dominant perturber ran 1.67/1.45 for the healthy cases against
    1.33/1.27 for the corrupted ones -- overlapping, and in the wrong direction. An uncalibrated guard here would
    be worse than none, since it would be read as a clean bill of health.
source
JenaAtomicCalculator.MultipolePolarizibility.closedSubshells — Method

MultipolePolarizibility.closedSubshells(level::Level) ... returns those subshells of the given level whose occupation is FULL, i.e. 2j+1, together with that occupation, as the pairs a core polarizability is to be summed over. The occupations are read from the level's LEADING CSF, which is sufficient because a subshell that is closed in one CSF of a bound level is closed in all of them; the subshell list is taken from the BASIS or from the CSF according to that CSF's own useStandardSubshells flag, which is what the field means and cannot be guessed from the CSF alone. A PARTIALLY FILLED SUBSHELL IS DELIBERATELY EXCLUDED, and that is the physics rather than a limitation: its response is the valence excitation the sum-over-states route computes from Settings.gMultiplet, where the individual perturber levels and their energies are what matter. A Dict{Subshell,Float64} is returned, empty for a level with no closed subshell at all.

source
JenaAtomicCalculator.MultipolePolarizibility.computeAmplitudesProperties — Method

MultipolePolarizibility.computeAmplitudesProperties(outcome::MultipolePolarizibility.Outcome, gMultiplet::Multiplet, nm::Nuclear.Model, grid::Radial.Grid, primitives::Union{Nothing,Bsplines.Primitives}, settings::MultipolePolarizibility.Settings) ... to compute the static scalar/tensor E1 polarizabilities for a given level; an outcome::MultipolePolarizibility.Outcome is returned for which alpha0/alpha2/contributions are now evaluated explicitly. If E1 is not among settings.multipoles (or gMultiplet is empty), alpha0=alpha2=0. is returned without further computation.

source
JenaAtomicCalculator.MultipolePolarizibility.computeCorePolarizability — Method

MultipolePolarizibility.computeCorePolarizability(level::Level, nm::Nuclear.Model, grid::Radial.Grid, primitives::Bsplines.Primitives, omega::Float64; scField::Basics.AbstractScField = Basics.DFSField()) ... computes the dipole polarizability of the level's CLOSED subshells from a COMPLETE B-spline basis, by solving the Dalgarno-Lewis equation in each channel the rank-1 operator reaches instead of summing over a perturber list. A value::Float64 is returned, in atomic units, together with the largest orbital-energy inconsistency found (see below) as the second member of a tuple.

    **WHY THIS IS A DIFFERENT CALCULATION AND NOT A BETTER PERTURBER LIST.** For a closed shell the CONTINUUM
    carries about 35 % of the polarizability (18.6 % for hydrogen's 1s), so a sum over bound perturbers cannot
    converge to it: measured on Na+ with 2p^5 ns + 2p^5 nd, n <= 8, the sum gives 1.1213 / 0.8719 / 0.6861 / 0.6135
    at rbox = 12 / 20 / 32 / 50 a.u., a monotone slide in which the box has become a fitted parameter. The chi
    solved here saturates each channel, so there is no perturber set to choose: the same quantity comes out as
    1.277625 / 1.277776 / 1.277831 / 1.277876 over rbox = 40 to 200 a.u., a spread of 2.0e-4 across a fivefold
    change of box.

    **THE FREQUENCY NEEDS TWO SOLVES, which is the only thing that differs from the static case.** The two energy
    denominators dE - omega and dE + omega no longer coincide, so chi is solved at targetEnergy = E_a +- omega and
    each contraction carries 1/3; at omega = 0 the two solves are identical and the 1/3 + 1/3 reproduces the
    static 2/3 exactly, which is the calibration of this prefactor (measured: identical to the last bit).

    **THE CONSISTENCY GUARD, and it is returned rather than printed, so a caller can act on it.** The chi equation's
    Hamiltonian must be the operator its source orbital is an eigenfunction of, so the core orbitals are
    REGENERATED here in the DFS potential built from the level's own basis rather than taken from that basis. The
    second member of the returned tuple is the largest |eps(regenerated) - eps(stored)| over the closed subshells;
    a value that is not small says the level was optimized by a route this potential does not reproduce, and the
    core number should not be trusted. `scField` names the mean field to regenerate them in and must be the one
    the level itself was computed with -- `Basics.NuclearField()` builds the bare nuclear potential, which is what
    makes a hydrogenic closed subshell an EXACT test of this routine: a 1s^2 shell at charge Z then has
    alpha = 2 * 9/(2 Z^4) with no screening and no literature in it.

    **WHAT LIMITS THE RESULT IS NOT THE BASIS BUT THE MEAN FIELD.** The induced field of the other core electrons
    is absent here, so the number is the UNSCREENED one -- 1.351 times the RRPA value for Na+. Screening is
    `RandomPhase`'s business and its exchange half is not yet wired, so this routine deliberately reports the
    unscreened polarizability rather than a partially screened one.
source
JenaAtomicCalculator.MultipolePolarizibility.computeMultipolePolarizabilities — Method

MultipolePolarizibility.computeMultipolePolarizabilities(multipole::EmMultipole, level::Level, gMultiplet::Multiplet, grid::Radial.Grid; omega::Float64=0.0, imaginaryOmega::Bool=false, helicity::Int64=0) ... computes the static multipole polarizabilities alpha^(Mp,K)(level) of level for the 2^L-pole multipole and for EVERY rank K that the level can carry (MultipolePolarizibility.allowedRanks), by summing the static reduced matrix elements <J' || O^(Mp) || J> = MultipoleMoment.emmStaticAmplitude(L, ...) over every level of gMultiplet. The convention is the one fixed in the module docstring: alpha^(Mp,K) is the coefficient of the angular shape AK(J,M) = C^(JM)(JM,K0) / C^(JJ)_(JJ,K0) in the substate polarizability alpha(J,M), so that alpha^(Mp,0) is the scalar polarizability and alpha^(Mp,K>0) is the anisotropy carried by the M = J substate. A static polarizability has no gauge freedom, so both components of every EmProperty hold the same number. The perturber set is checked and warned about (MultipolePolarizibility.checkPerturberSet). A tuple (alphas::Array{Tuple{Int64,EmProperty},1}, contributions::Array{MultipolePolarizibility.Contribution,1}) is returned, the latter giving each perturber's own additive share of every rank.

    THE FREQUENCY ENTERS ONLY THROUGH THE DENOMINATOR, which is why the dynamic case costs nothing beyond the
    static one: `omega` (real, atomic units) or, with `imaginaryOmega = true`, the imaginary frequency i*omega
    replaces 1/dE by MultipolePolarizibility.frequencyFactor and NOTHING else changes -- the same reduced matrix
    elements, the same angular coefficients, the same perturber set. A caller sweeping many frequencies therefore
    pays for one structure calculation, and `Contribution.reducedMe` is stored so that even that can be reused.
    The frequency is checked and warned about by MultipolePolarizibility.checkFrequency, which matters on the real
    axis only.
source
JenaAtomicCalculator.MultipolePolarizibility.computeOutcomes — Method

MultipolePolarizibility.computeOutcomes(multiplet::Multiplet, nm::Nuclear.Model, grid::Radial.Grid, settings::MultipolePolarizibility.Settings; output=true) ... to compute (as selected) the static E1 scalar/tensor polarizabilities for the levels of the given multiplet and as specified by the given settings. The intermediate (perturber) ASF are taken directly from settings.gMultiplet, which the caller must generate independently, ahead of time (see the module docstring and examples/example-Aj.jl/example-Cj.jl). The results are printed in neat tables to screen but nothing is returned otherwise.

source
JenaAtomicCalculator.MultipolePolarizibility.computeScalarTensorPolarizability — Method

MultipolePolarizibility.computeScalarTensorPolarizability(level::Level, gMultiplet::Multiplet, grid::Radial.Grid) ... computes the static E1 scalar and tensor polarizabilities of level, i.e. alpha^(E1,0) and alpha^(E1,2) in the notation of the module docstring, which the Stark-shift literature writes alpha0 and alpha2 (Angel & Sandars 1968). This is the E1 rank-0/rank-2 FACE of MultipolePolarizibility.computeMultipolePolarizabilities and adds nothing of its own: it is kept because it is the entry point that module-StarkShift.jl and several examples call, and because those two ranks are what a Stark shift of a linearly polarized field needs. A static polarizability carries no gauge freedom, so both components of each EmProperty hold the same number. A tuple (alpha0::EmProperty, alpha2::EmProperty, contributions::Array{MultipolePolarizibility.Contribution,1}) is returned, the latter giving each perturber level's own additive share of alpha0/alpha2 in both gauges.

    UNTIL 19-Oct-2026 THIS FUNCTION CARRIED ITS OWN LOOP, with the two Angel & Sandars prefactors written out. The
    general function reproduces that loop EXACTLY -- 0.0e+00 relative difference on the total and 3.2e-16 on the
    worst of its eight perturber terms, on the H 1s case of test/approved -- which is what made it safe to have
    one implementation instead of two that can drift apart.
source
JenaAtomicCalculator.MultipolePolarizibility.determineOutcomes — Method

MultipolePolarizibility.determineOutcomes(multiplet::Multiplet, settings::MultipolePolarizibility.Settings) ... to determine a list of Outcomes's for the computation of the multipole polarizibilities for the given multiplet. It takes into account the particular selections and settings. An Array{MultipolePolarizibility.Outcome,1} is returned. Apart from the level specification, all physical properties are set to zero during the initialization process.

source
JenaAtomicCalculator.MultipolePolarizibility.displayContributions — Method

MultipolePolarizibility.displayContributions(stream::IO, outcome::MultipolePolarizibility.Outcome) ... to display, for the single level outcome.level, the individual (additive) contribution of every intermediate ASF in gMultiplet that couples to it via E1, sorted by descending |contribAlpha0| so that the dominant perturber levels (e.g. 2p1/2, 2p3/2 for an ns ground level) appear first. A neat table is printed but nothing is returned otherwise. Nothing is printed if outcome.contributions is empty.

source
JenaAtomicCalculator.MultipolePolarizibility.displayCorePolarizabilities — Method

MultipolePolarizibility.displayCorePolarizabilities(stream::IO, outcomes::Array{MultipolePolarizibility.Outcome,1}) ... prints the CLOSED subshells' dipole polarizability of every outcome that carries one, at each frequency it was computed for, together with the fractional change from the static value. It is a table of its OWN rather than a column of MultipolePolarizibility.displayResults, for two reasons: the quantity comes from a complete-basis route with a different accuracy from the sum over states beside it, and adding a column there would alter printed output that approved test references already hold. Nothing is returned.

source
JenaAtomicCalculator.MultipolePolarizibility.displayOutcomes — Method

MultipolePolarizibility.displayOutcomes(outcomes::Array{MultipolePolarizibility.Outcome,1}) ... to display a list of levels that have been selected for the computations. A small neat table of all selected levels and their energies is printed but nothing is returned otherwise.

source
JenaAtomicCalculator.MultipolePolarizibility.displayResults — Method

MultipolePolarizibility.displayResults(stream::IO, outcomes::Array{MultipolePolarizibility.Outcome,1}) ... to display the energies and static scalar/tensor E1 polarizabilities for the selected levels. A neat table is printed but nothing is returned otherwise.

source
JenaAtomicCalculator.MultipolePolarizibility.frequencyFactor — Method

MultipolePolarizibility.frequencyFactor(dE::Float64, omega::Float64, imaginaryOmega::Bool) ... returns the energy-denominator factor which carries the WHOLE frequency dependence of a multipole polarizability, so that alpha^(Mp,K)(omega) = sumJ' c(L,K,J,J') |<J'||O^(Mp)||J>|^2 * this factor, with dE = WJ' - W_J:

        omega = 0           1 / dE
        real omega          dE / (dE^2 - omega^2)
        imaginary i*omega   dE / (dE^2 + omega^2)

    All three agree at omega = 0. THE IMAGINARY AXIS HAS NO POLES -- dE^2 + omega^2 cannot vanish -- which is why
    a dispersion coefficient is built there and why alpha(i*omega) is numerically the EASIER quantity, despite
    having no direct physical meaning of its own. On the real axis the factor diverges whenever omega meets an
    excitation energy; MultipolePolarizibility.checkFrequency warns about that. A value::Float64 is returned.

    For an EXCITED level of interest some perturbers lie BELOW it, dE < 0, and the same expressions hold: such a
    term contributes with the opposite sign, which is the de-excitation channel and not an error.
source
JenaAtomicCalculator.MultipolePolarizibility.frequencyFactorOdd — Method

MultipolePolarizibility.frequencyFactorOdd(dE::Float64, omega::Float64, imaginaryOmega::Bool) ... returns the energy-denominator factor of an ODD-rank multipole polarizability, omega / (dE^2 - omega^2), which is what MultipolePolarizibility.frequencyFactor is to an even one. The two differ because the two second-order terms of a field of helicity q carry the polarization vectors eps and eps*, hence the operator components q and -q: the part of the angular factor SYMMETRIC in q goes with the sum of the two denominators, dE/(dE^2 - omega^2), and the part ANTISYMMETRIC in q – which is the whole of odd K – goes with their difference, omega/(dE^2 - omega^2).

    SO AN ODD RANK VANISHES IDENTICALLY AT omega = 0, and 0.0 is returned there: a static field has no handedness, and
    the rank-1 polarizability is a purely dynamic quantity proportional to omega at small omega. This was MEASURED
    rather than assumed -- see tools/probe-rank1Polarizability.jl, where the ratio of the extracted alpha^(E1,1) to
    this factor is 1.0000000000 at every frequency while the even factor gives 0.057 ... 0.431.

    ON THE IMAGINARY AXIS AN ODD RANK HAS NO REAL VALUE -- the factor becomes i*omega/(dE^2 + omega^2), purely
    imaginary -- so this RAISES rather than return a plausible-looking real number. A dispersion coefficient needs
    only K = 0 and must therefore be asked for at helicity = 0. A value::Float64 is returned.
source
JenaAtomicCalculator.MultipolePolarizibility.isReachable — Method

MultipolePolarizibility.isReachable(multipole::EmMultipole, level::Level, nuLevel::Level) ... returns true if the static 2^L-pole operator of multipole can connect level to the perturber nuLevel at all, i.e. if the two angular momenta satisfy the triangle |J - L| <= J' <= J + L AND the two parities match the parity of the operator, which is (-1)^L for an electric and (-1)^(L+1) for a magnetic multipole. This is the selection rule that decides whether a given gMultiplet is of any use for a given multipole – an np set serves E1 and reaches nothing at all for E2. A value::Bool is returned.

source
JenaAtomicCalculator.MultipolePolarizibility.polarizationFactor — Method

MultipolePolarizibility.polarizationFactor(L::Int64, K::Int64, helicity::Int64) ... returns the factor P(L,K,q) by which the rank-K polarizability of a 2^L-pole field of helicity q = helicity enters the substate shift, so that the shift of one magnetic substate reads

        alpha(J,M; q)  =  sum_K  P(L,K,q) * MultipolePolarizibility.rankShape(J,K,M) * alpha^(Mp,K)

    The normalisation is the one that leaves each alpha^(Mp,K) an ATOMIC quantity, independent of the field:
    P(L,K,q) = 1 at the REFERENCE helicity of that rank, which is q = 0 for even K -- so that alpha^(Mp,0) and
    alpha^(Mp,2) keep exactly the meaning they have always had here, the scalar and tensor polarizabilities of a
    linearly polarized field -- and q = +1 for odd K, which has no q = 0 value to be normalised against.

    FOR E1 THE TABLE IS THE FAMILIAR ONE and is worth quoting, since it is the one external check this machinery
    has that needed no literature value to be looked up: P(1,0,q) = 1 at every helicity, so the scalar shift does
    not care about polarization; P(1,1,q) = q, so the vector shift reverses with the handedness and vanishes for
    linear light; and P(1,2,0) = 1 against P(1,2,+-1) = -1/2, which is the textbook statement that circular
    polarization gives MINUS ONE HALF of the linear tensor shift. For E2 the same formula gives P(2,2,+-1) = +1/2
    and P(2,4,+-1) = -2/3. A value::Float64 is returned.
source
JenaAtomicCalculator.MultipolePolarizibility.radialDrive — Method

MultipolePolarizibility.radialDrive(aSub::Subshell, tSub::Subshell, orbitals::Dict{Subshell,Orbital}, primitives::Bsplines.Primitives, grid::Radial.Grid) ... returns the correction vector that turns DalgarnoLewis.solve's own static drive into the PURE RADIAL drive r, as an Array{Float64,1} to be handed to that function's extraSource. It is needed because solve with staticDrive = true builds its source from InteractionStrength.eMultipole, which carries the angular reduction, whereas the assembly below wants the bare radial operator with the angular factor applied separately and visibly – the discipline Rule 18 asks for. The vector is therefore Ri - bi, the difference of the two drives over the B-spline basis. An Array{Float64,1} of length nsL+nsS is returned.

    A future `drive = :radial` option in `DalgarnoLewis.solve` would make this helper unnecessary; it lives here
    rather than there so that this change touches one module.
source
JenaAtomicCalculator.MultipolePolarizibility.rankCoefficient — Method

MultipolePolarizibility.rankCoefficient(L::Int64, K::Int64, J::AngularJ64, Jnu::AngularJ64; helicity::Int64=0) ... returns the angular coefficient c(L,K,J,J') which multiplies |<J' || O^(Mp) || J>|^2 / (EJ' - EJ) in the rank-K static multipole polarizability alpha^(Mp,K)(J) of the module docstring, i.e.

        c(L,K,J,J')  =  2 (-1)^(J+J'+q) C^(JJ)_(JJ,K0) (2K+1) / sqrt(2J+1) * (L L K; q -q 0) * {J J' L; L K J}

    with a Wigner 3-j and a Wigner 6-j symbol and q = `helicity`. The three selection rules are carried by the
    formula itself rather than imposed on it: the 3-j symbol vanishes for K > 2L, and at q = 0 also for odd K, and
    the Clebsch-Gordan coefficient vanishes for K > 2J. For K = 0 the expression collapses analytically to
    2 / ((2J+1)(2L+1)) at every helicity, which for L = 1 is the scalar prefactor of Angel & Sandars (1968) that
    this module has always used. A value::Float64 is returned.

    THE HELICITY IS THE ONLY THING ADDED ON 20-Oct-2026, and q = 0 is the default, so every caller written before
    that date gets BIT-IDENTICALLY what it got: at q = 0 the factor (-1)^q is 1.0 and (L L K; 0 0 0) is the symbol
    that was there. What q = +-1 opens is ODD K, and K = 1 in particular -- the vector polarizability alpha_1 of
    the Stark-shift and optical-tweezer literature -- which is unreachable at q = 0 because the 3-j symbol with
    three zero projections vanishes whenever L + L + K is odd. That vanishing is not a convention: it says that the
    SYMMETRIC product of two identical multipole operators has no odd rank, and a circular field is precisely what
    makes the product unsymmetric, since its two second-order terms carry eps and eps*, i.e. q and -q.

    THE FORMULA WAS SETTLED NUMERICALLY RATHER THAN BY HAND, 19-Oct-2026, because a factor of this shape is exactly
    what gets written with the wrong phase and then compensated elsewhere (Rule 18). The substate polarizability
    alpha(J,M) was built directly from the Clebsch-Gordan coefficients, decomposed in the A_K shapes, and the
    coefficient read off: the decomposition residual is <= 1.7e-16 over 70 (J,L) combinations, which proves the
    rank set complete, and the ratio of the extracted coefficient to (-1)^(J+J') {J J' L; L K J} is INDEPENDENT of
    J' to <= 9.1e-15, which proves the 6-j structure. The remaining normalisation came out as 2 sqrt(2J+1) times
    the Clebsch-Gordan/3-j product above, and the phase as (-1)^(J+J') with ZERO mismatches over 421 samples.
source
JenaAtomicCalculator.MultipolePolarizibility.rankShape — Method

MultipolePolarizibility.rankShape(J::AngularJ64, K::Int64, M::AngularM64) ... returns the angular shape AK(J,M) = C^(JM)(JM,K0) / C^(JJ)(JJ,K0) in which the substate polarizability of a level is expanded, alpha(J,M) = sumK AK(J,M) alpha^(Mp,K)(J). The normalisation is fixed by A0 = 1 and A_K(J,J) = 1, so that alpha^(Mp,0) is the usual scalar polarizability and every alpha^(Mp,K>0) is the anisotropy carried by the stretched M = J substate – which is what makes the number directly readable. For K = 2 the shape is the familiar [3M^2 - J(J+1)] / [J(2J-1)] of the Stark-shift literature. A value::Float64 is returned.

source

Long-range dispersion coefficients

JenaAtomicCalculator.DispersionCoefficient.Coefficient — Type

struct DispersionCoefficient.Coefficient ... defines a type to keep ONE atom-atom dispersion coefficient C_n together with the (l1,l2) pieces it was built from, because the pieces are what a reader needs: they say which multipole response the coefficient actually rests on, and hence which one has to be converged.

+ n           ::Int64                                     ... The order, i.e. the n of C_n in -C_n/R^n; even and
                                                              at least 6.
+ value       ::Float64                                   ... The coefficient itself, in atomic units.
+ pieces      ::Array{Tuple{Int64,Int64,Float64},1}       ... (l1, l2, contribution) for every ordered multipole
                                                              pair with l1 + l2 = n/2 - 1, in the order computed.
+ complete    ::Bool                                      ... False if some (l1,l2) pair was skipped because a
                                                              partner carried no terms for that multipole, in
                                                              which case `value` is a LOWER bound and nothing
                                                              more.
source
JenaAtomicCalculator.DispersionCoefficient.MultipoleTerms — Type

struct DispersionCoefficient.MultipoleTerms ... defines a type to keep ONE atom's complete 2^L-pole response as the list of single poles it is made of, which is the only input any dispersion coefficient needs. The scalar polarizability at imaginary frequency is alpha^(E L,0)(i w) = suma strengths[a] * energies[a] / (energies[a]^2 + w^2), and the static value is alpha^(E L,0)(0) = suma strengths[a] / energies[a].

+ multipole   ::EmMultipole        ... The multipole E L whose response these terms carry.
+ strengths   ::Array{Float64,1}   ... The weights A_a = c(L,0,J,J_a) |<J_a || O^(E L) || J>|^2 of each perturber,
                                       with c the rank-0 angular coefficient `MultipolePolarizibility.rankCoefficient`.
+ energies    ::Array{Float64,1}   ... The excitation energies dE_a = W_a - W_level (atomic units), all POSITIVE
                                       for a lowest level, which is what the Casimir-Polder form requires.
source
JenaAtomicCalculator.DispersionCoefficient.Outcome — Type

struct DispersionCoefficient.Outcome ... defines a type to keep the outcome of one dispersion-coefficient computation, i.e. of ONE pair of partners.

+ partnerA        ::DispersionCoefficient.Partner               ... The first atom.
+ partnerB        ::DispersionCoefficient.Partner               ... The second atom; identical to partnerA for a
                                                                    homonuclear pair.
+ coefficients    ::Array{DispersionCoefficient.Coefficient,1}  ... The atom-atom coefficients C_n requested, in
                                                                    ascending order of n.
+ atomWallC3      ::Float64                                     ... The atom-wall coefficient C_3 of partnerA in
                                                                    atomic units, or 0. if it was not requested.
+ wallDielectric  ::Float64                                     ... The STATIC dielectric constant the wall was
                                                                    given; Inf for a perfect conductor.
+ wallResonance   ::Float64                                     ... The resonance omega_0 of that wall's Lorentz
                                                                    oscillator, in atomic units; Inf for the
                                                                    instantaneous-response limit, in which the
                                                                    constant-eps reflection factor is exact.
source
JenaAtomicCalculator.DispersionCoefficient.Partner — Type

struct DispersionCoefficient.Partner ... defines a type to keep one of the two atoms (or the single atom, for an atom-wall coefficient) of a dispersion calculation, together with its multipole response. A Partner is the unit that is checked by DispersionCoefficient.checkGroundLevel, since the Casimir-Polder form is valid only if its level is the lowest one its own perturber set can see.

+ name        ::String                           ... A label for the printout, e.g. "H(1s)"; it carries no physics.
+ level       ::Level                            ... The level whose dispersion coefficients are wanted.
+ terms       ::Array{DispersionCoefficient.MultipoleTerms,1}
                                                 ... One entry per multipole available for this atom; a C_n that
                                                     needs a multipole absent from this list is reported as
                                                     INCOMPLETE rather than silently computed too small.
source
JenaAtomicCalculator.DispersionCoefficient.Partner — Method

DispersionCoefficient.Partner(name::String, level::Level, gMultiplet::Multiplet, grid::Radial.Grid, multipoles::Array{EmMultipole,1}) ... constructor that builds a partner::DispersionCoefficient.Partner directly from a level and a perturber multiplet, by asking MultipolePolarizibility for the terms of each requested multipole in turn; a partner::DispersionCoefficient.Partner is returned. This is the convenient path and uses ONE perturber set for every multipole. Where the multipoles need different sets – and they do, since the discrete series saturates the more slowly the higher the multipole, and the radial box that suits one may ruin another – build each MultipoleTerms separately with DispersionCoefficient.multipoleTerms and use the plain constructor above.

source
JenaAtomicCalculator.DispersionCoefficient.Partner — Method

DispersionCoefficient.Partner() ... constructor for an empty instance of DispersionCoefficient.Partner. It carries no multipole response at all, and is the value that tells DispersionCoefficient.computeOutcomes to treat the pair as HOMONUCLEAR; a partner::DispersionCoefficient.Partner is returned.

source
JenaAtomicCalculator.DispersionCoefficient.Settings — Type

struct DispersionCoefficient.Settings ... defines a type for the details and parameters of computing long-range dispersion coefficients. It IS an AbstractPropertySettings, so the module is reached through propertySettings of an Atomic.Computation exactly as every other property module is, and the module's own functions remain available for the cases the property route cannot express. A dispersion coefficient is a property of a PAIR of atoms, and perform(::Atomic.Computation) carries only ONE multiplet – so the computed atom is partner A, taken level by level from that multiplet, while partner B is carried IN THESE SETTINGS, already built. Leaving partnerB empty asks for a HOMONUCLEAR pair, which is what a published C_n of a single species means.

+ orders            ::Array{Int64,1}        ... The orders n of the atom-atom coefficients C_n wanted; even and at
                                                  least 6. The default [6, 8, 10] is what the literature quotes.
+ multipoles        ::Array{EmMultipole,1}  ... The multipoles whose response is to be built when a Partner is
                                                  constructed from a level and a perturber multiplet. C_6 needs
                                                  E1, C_8 needs E1 and E2, and C_10 needs E1, E2 and E3.
+ calcAtomWall      ::Bool                  ... True if the atom-wall coefficient C_3 of partnerA is wanted
                                                  beside the atom-atom ones.
+ wallDielectric    ::Float64               ... The STATIC dielectric constant eps(0) of that wall; Inf, the
                                                  default, is a perfect conductor at every frequency.
+ wallResonance     ::Float64               ... The resonance omega_0 of the wall's one Lorentz oscillator, in
                                                  atomic units, which fixes eps(i omega) = 1 + omega_p^2 /
                                                  (omega_0^2 + omega^2) together with wallDielectric. Inf, the
                                                  default, is the instantaneous-response limit, where the
                                                  constant-eps reflection factor (eps-1)/(eps+1) is exact; a
                                                  FINITE omega_0 reduces C_3 by 1 + dE_a/Omega per perturber,
                                                  which is not a small factor for a real wall -- see the module
                                                  docstring.
+ gMultiplet        ::Multiplet             ... The perturber multiplet of the atom whose levels are computed,
                                                  i.e. the intermediate ASF over which the response is summed.
                                                  As in `MultipolePolarizibility`, the caller generates it ahead
                                                  of time; see the module docstring.
+ partnerB          ::DispersionCoefficient.Partner
                                            ... The SECOND atom, fully built by the caller, including its own
                                                  perturber response. An empty partner -- the default -- means a
                                                  HOMONUCLEAR pair, and partner B is then taken to be partner A
                                                  itself, which is the common case and the one every published
                                                  C_n of a single species refers to.
+ printBefore       ::Bool                  ... True if the partners and their response are printed before the
                                                  coefficients are computed.
+ levelSelection    ::LevelSelection        ... Specifies the levels to be computed. The Casimir-Polder form
                                                  holds only for the LOWEST level a perturber set can see, so a
                                                  selection that admits an excited level makes
                                                  `DispersionCoefficient.checkGroundLevel` raise rather than
                                                  return a plausible number.
source
JenaAtomicCalculator.DispersionCoefficient.Settings — Method

DispersionCoefficient.Settings(set::DispersionCoefficient.Settings; orders::Union{Nothing,Array{Int64,1}}=nothing, multipoles::Union{Nothing,Array{EmMultipole,1}}=nothing, calcAtomWall::Union{Nothing,Bool}=nothing, wallDielectric::Union{Nothing,Float64}=nothing, wallResonance::Union{Nothing,Float64}=nothing, gMultiplet::Union{Nothing,Multiplet}=nothing, partnerB::Union{Nothing,DispersionCoefficient.Partner}=nothing, printBefore::Union{Nothing,Bool}=nothing, levelSelection::Union{Nothing,LevelSelection}=nothing)

... keyword copy-constructor for re-defining selected values of a settings::DispersionCoefficient.Settings.
    A `settings::DispersionCoefficient.Settings` is returned.
source
JenaAtomicCalculator.DispersionCoefficient.casimirPolderPrefactor — Method

DispersionCoefficient.casimirPolderPrefactor(l1::Int64, l2::Int64) ... returns the weight with which the overlap integral of a 2^l1-pole and a 2^l2-pole polarizability enters the dispersion coefficient of order n = 2(l1 + l2 + 1), i.e. binomial(2 l1 + 2 l2, 2 l1)/(2 pi); a prefactor::Float64 is returned. This single expression is the whole of the Casimir-Polder combinatorics and reproduces every prefactor the literature writes out: summed over ORDERED pairs it gives 3/pi for C6, 15/2 pi for each of the two C8 terms, and 28/pi (l1,l2 = 1,3 and 3,1 together) and 35/pi (2,2) for C_10.

source
JenaAtomicCalculator.DispersionCoefficient.checkGroundLevel — Method

DispersionCoefficient.checkGroundLevel(partner::DispersionCoefficient.Partner) ... verifies that partner's level is the LOWEST one its own perturber set can reach, which is the condition the whole Casimir-Polder construction rests on, and RAISES an informative error if it is not; nothing is returned.

    THIS IS THE ONE GUARD THAT IS NOT OPTIONAL, and it refuses rather than warns because the number it would
    otherwise return is finite, smooth and wrong. The imaginary-frequency representation is reached by a contour
    argument that needs every excitation energy dE_a = W_a - W_level to have the SAME sign. For an excited level at
    least one perturber lies BELOW it, that dE_a is negative, and two things happen at once: the integrand acquires
    a pole on the contour, and the true interaction gains an additional REAL-frequency (resonant) term that no
    imaginary-axis integral contains -- Lepers & Dulieu, arXiv:1703.02833, Eq. (75). Since excited levels are
    exactly what JAC is for, this is the common case here and not an edge one.
source
JenaAtomicCalculator.DispersionCoefficient.checkSaturation — Method

DispersionCoefficient.checkSaturation(partner::DispersionCoefficient.Partner) ... inspects whether each of partner's multipole responses rests on a perturber set that reaches into the CONTINUUM, and WARNS LOUDLY, to stdout, where it does not; nothing is returned.

    THE CONDITION BEING TESTED IS THE ONE THAT MAKES A SUM A LOWER BOUND. A bound Rydberg series accumulates at
    the ionization threshold, so its excitation energies crowd into a narrow band and its highest member lies
    barely above its lowest; a set that continues into the continuum, as a box-confined pseudo-state series does,
    spreads over orders of magnitude. The span max(dE_a)/min(dE_a) therefore separates the two without needing the
    threshold, the box or anything else from outside. Calibrated on one H(1s) np n = 2..16 set at four boxes:

        span 54.6 (64 a.u.)    alpha^(E1,0) 1.00000 of reference,   C_3 0.99995 of exact
        span  6.7 (200 a.u.)                0.99992                     0.99908
        span  2.2 (400 a.u.)                0.98888                     0.96403
        span  1.4 (775 a.u.)                0.86054                     0.77026

    and on nd n = 3..16, where a span of 1.15 goes with alpha^(E2,0) at 0.443 of reference. A span below 3 is
    therefore warned about, and the warning names C_3 because that is the quantity which suffers most.

    WHAT THIS GUARD DOES NOT CATCH, said here so that it is not relied upon for it: a box that is far too LARGE
    inflates a high multipole rather than starving it, and the span is then huge while the number is wrong -- E3
    on a 775 a.u. box gives a span of 10.4 and 1.275 of its reference. That failure belongs to
    `MultipolePolarizibility.checkPerturberSet` and `Bsplines.checkOrbitalConsistency`, which are run when the
    polarizability itself is computed.

    ONE CANDIDATE DETECTOR WAS MEASURED AND REJECTED, and its numbers are kept so that it is not rebuilt: the
    SHARE of sum_a A_a carried by the highest-lying pole runs 0.0000 on the perfect E1 set and 0.0306 on the
    23 %-short one -- discriminating in the wrong direction and by far too little -- and it is 0.0000 for E3 in
    every box, good and bad alike.
source
JenaAtomicCalculator.DispersionCoefficient.checkWall — Method

DispersionCoefficient.checkWall(settings::DispersionCoefficient.Settings) ... refuses a wall that is not a dielectric BEFORE any perturber set is built; nothing is returned. Neither eps(0) < 1, which has no reflection factor on the imaginary axis, nor omega_0 <= 0, which has no pole, is an extreme case to be clamped; both are typing errors. WHAT THIS BUYS IS THE TIMING, since the wall enters only at the END of DispersionCoefficient.computeOutcome: a mistyped eps(0) was discovered after the multipole sums of the first selected level had been assembled, and the remaining levels never ran at all. The algebra is DispersionCoefficient.wallReflectionPole and costs nothing, so it is done once here as well. A perfect conductor reflects fully at every frequency and so carries no resonance to check.

source
JenaAtomicCalculator.DispersionCoefficient.computeAtomWallCoefficient — Method

DispersionCoefficient.computeAtomWallCoefficient(partner::DispersionCoefficient.Partner, wallDielectric::Float64, wallResonance::Float64) ... computes the non-retarded atom-wall coefficient C3 of partner in U(z) = - C3/z^3, for a wall of STATIC dielectric constant wallDielectric (Inf for a perfect conductor) whose one Lorentz oscillator sits at wallResonance (Inf for the instantaneous-response limit); a C3::Float64 in atomic units is returned, and 0. if the partner carries no E1 response.

    The Lennard-Jones form C_3 = (1/4 pi) int_0^inf alpha^(E1,0)(i w) dw collapses on a discrete spectrum to
    C_3 = (1/8) sum_a A_a, since int_0^inf dE/(dE^2 + w^2) dw = pi/2 for every pole alike. The wall enters as the
    reflection factor r(i w), which for one oscillator is itself a single pole R/(Omega^2 + w^2) -- see
    `DispersionCoefficient.wallReflectionPole` -- so the integral stays closed and

    C_3 = (R/8) sum_a A_a / [Omega (dE_a + Omega)],   collapsing to (eps-1)/(eps+1) times (1/8) sum_a A_a as
    Omega >> dE_a.

    SO THE CONSTANT-eps ANSWER IS A LIMIT AND NOT A SEPARATE MODEL, and its error is one factor per pole,
    exactly 1 + dE_a/Omega. For a silica-like wall (eps(0) = 3.9, omega_0 = 10 eV, Omega = 0.575 a.u.) against
    H(1s) that is 65 % on the 2p pole alone and 81 % measured over the np n = 2..16 set, so a real dielectric is
    NOT well described by its static constant alone. A perfect conductor reflects fully at every frequency and
    ignores `wallResonance` altogether.

    The perfectly conducting closed form is exactly checkable: with A_a = (2/3) |<a|d|0>|^2 the dipole sum rule
    gives C_3 = <d^2>/12, which is what an electrostatic image dipole yields, so C_3(H 1s) = 1/4 exactly.

    BEWARE THAT A POOR PERTURBER SET DAMAGES THIS BEFORE ANYTHING ELSE, because sum_a A_a carries no energy
    denominator while alpha(0) and every C_n suppress the high poles: measured on one H(1s) np n = 2..16 set,
    moving the radial box from 64 to 775 a.u. costs alpha^(E1,0) 14 % and C_3 23 %. See
    `DispersionCoefficient.checkSaturation`.
source
JenaAtomicCalculator.DispersionCoefficient.computeAtomWallCoefficient — Method

DispersionCoefficient.computeAtomWallCoefficient(partner::DispersionCoefficient.Partner, wallDielectric::Float64) ... computes the non-retarded atom-wall coefficient C3 of partner against a wall that responds INSTANTANEOUSLY on the atom's own frequency scale, i.e. in the limit omega0 >> dE_a; a C3::Float64 in atomic units is returned. It is DispersionCoefficient.computeAtomWallCoefficient(partner, wallDielectric, Inf) and is kept as its own method because that limit is the only wall most callers want.

source
JenaAtomicCalculator.DispersionCoefficient.computeCoefficient — Method

DispersionCoefficient.computeCoefficient(n::Int64, partnerA::DispersionCoefficient.Partner, partnerB::DispersionCoefficient.Partner) ... computes the atom-atom dispersion coefficient Cn of the pair (partnerA, partnerB) in V(R) = - ... - Cn/R^n - ..., by summing the Casimir-Polder weight times the polarizability overlap integral over every ORDERED multipole pair (l1,l2) with l1 + l2 = n/2 - 1; a coefficient::DispersionCoefficient.Coefficient in atomic units is returned, carrying its own (l1,l2) pieces. Both partners are first checked by DispersionCoefficient.checkGroundLevel, which raises for an excited level. A pair whose multipole either partner does not carry is SKIPPED with a warning and marks the result incomplete, so that a coefficient missing a term is never mistaken for a converged one.

source
JenaAtomicCalculator.DispersionCoefficient.computeOutcome — Method

DispersionCoefficient.computeOutcome(partnerA::DispersionCoefficient.Partner, partnerB::DispersionCoefficient.Partner, settings::DispersionCoefficient.Settings) ... computes every dispersion coefficient asked for in settings for the pair (partnerA, partnerB), i.e. the atom-atom Cn of settings.orders and, if requested, the atom-wall C3 of partnerA; an outcome::DispersionCoefficient.Outcome is returned. The saturation of both partners is reported first, since a coefficient is only as good as the perturber set under it.

source
JenaAtomicCalculator.DispersionCoefficient.computeOutcomes — Method

DispersionCoefficient.computeOutcomes(multiplet::Multiplet, nm::Nuclear.Model, grid::Radial.Grid, settings::DispersionCoefficient.Settings; output=true) ... computes the dispersion coefficients for the selected levels of the given multiplet, which is the entry point perform(::Atomic.Computation) uses, so that the module is reached exactly as every other property module is; an outcomes::Array{DispersionCoefficient.Outcome,1} is returned. The computed atom is partner A and its response is built from settings.gMultiplet; partner B is settings.partnerB where the caller supplied one and partner A itself otherwise, which is the homonuclear case every published C_n of a single species means. Each selected level passes DispersionCoefficient.checkGroundLevel FIRST, so a selection that admits an excited level raises here rather than returning a number the Casimir-Polder form cannot support.

source
JenaAtomicCalculator.DispersionCoefficient.displayResults — Method

DispersionCoefficient.displayResults(stream::IO, outcome::DispersionCoefficient.Outcome) ... prints the dispersion coefficients of outcome in a neat table, each with the (l1,l2) multipole pairs it is built from and the static polarizabilities that carry it, so that a reader can see at once which response would have to be improved; nothing is returned.

source
JenaAtomicCalculator.DispersionCoefficient.multipoleTerms — Method

DispersionCoefficient.multipoleTerms(multipole::EmMultipole, level::Level, gMultiplet::Multiplet, grid::Radial.Grid) ... builds the single-pole representation of level's 2^L-pole response from the perturbers of gMultiplet, by asking MultipolePolarizibility.computeMultipolePolarizabilities for its per-perturber contributions and keeping, for each, the rank-0 strength Aa = c(L,0,J,Ja) |<Ja || O^(E L) || J>|^2 and the excitation energy dEa = Wa - Wlevel; a terms::DispersionCoefficient.MultipoleTerms is returned. Poles of vanishing strength – a perturber the multipole cannot reach, or one outside the rank-0 triangle – are dropped, so the returned lists hold only terms that contribute.

    NO NEW STRUCTURE CALCULATION HAPPENS HERE, and that is the point of taking this route rather than evaluating
    polarizabilities at many frequencies: the stored reduced matrix element and energy denominator are all a
    dispersion coefficient ever needs, so one pass over the perturbers serves every C_n and the atom-wall C_3 at
    once.
source
JenaAtomicCalculator.DispersionCoefficient.overlapIntegral — Method

DispersionCoefficient.overlapIntegral(termsA::DispersionCoefficient.MultipoleTerms, termsB::DispersionCoefficient.MultipoleTerms) ... computes the imaginary-frequency overlap integral int0^inf alphaA(i w) alpha_B(i w) dw of two multipole responses in CLOSED FORM; an integral::Float64 in atomic units is returned.

    No quadrature is involved and none is wanted: on a discrete spectrum each polarizability is a sum of single
    poles, and int_0^inf [a/(a^2+w^2)] [b/(b^2+w^2)] dw = pi/(2(a+b)) exactly, so the integral is the double sum
    (pi/2) sum_ab A_a A_b/(dE_a + dE_b) -- Dalgarno's oscillator-strength form. Reading the weight 1/(dE_a + dE_b)
    is also how one sees which perturbers a dispersion coefficient actually rests on: the low-lying ones, though
    less exclusively so than for alpha(0), whose weight is 1/dE_a.
source
JenaAtomicCalculator.DispersionCoefficient.polarizability — Method

DispersionCoefficient.polarizability(terms::DispersionCoefficient.MultipoleTerms, omega::Float64) ... returns the scalar multipole polarizability alpha^(E L,0)(i omega) of terms at the IMAGINARY frequency i*omega, i.e. suma Aa dEa/(dEa^2 + omega^2); an alpha::Float64 in atomic units is returned. It is provided because it is what a user plots and what makes this module's closed-form integrals checkable by quadrature, not because any coefficient here needs it: the imaginary axis has no poles, so this function is finite, positive and monotone decreasing for every omega.

source
JenaAtomicCalculator.DispersionCoefficient.selectTerms — Method

DispersionCoefficient.selectTerms(partner::DispersionCoefficient.Partner, L::Int64) ... picks out partner's electric 2^L-pole response; a terms::DispersionCoefficient.MultipoleTerms is returned, or nothing if the partner carries no response for that multipole, which the callers report as an incomplete coefficient rather than treat as zero.

source
JenaAtomicCalculator.DispersionCoefficient.staticPolarizability — Method

DispersionCoefficient.staticPolarizability(terms::DispersionCoefficient.MultipoleTerms) ... returns the static scalar multipole polarizability alpha^(E L,0)(0) = suma Aa/dE_a of terms; an alpha::Float64 in atomic units is returned. It is the omega = 0 member of DispersionCoefficient.polarizability and is given its own method because it is the number a reader compares against the literature to judge whether a dispersion coefficient rests on anything.

source
JenaAtomicCalculator.DispersionCoefficient.wallReflectionPole — Method

DispersionCoefficient.wallReflectionPole(wallDielectric::Float64, wallResonance::Float64) ... writes the imaginary-frequency reflection factor of a wall with one undamped Lorentz oscillator as a SINGLE POLE, which is what keeps the atom-wall integral closed; a (strength, energy)::Tuple{Float64,Float64} in atomic units is returned, meaning r(i w) = strength/(energy^2 + w^2).

    With eps(i w) = 1 + omega_p^2/(omega_0^2 + w^2) the factor (eps-1)/(eps+1) is omega_p^2 / (omega_p^2 +
    2 omega_0^2 + 2 w^2), hence strength = omega_p^2/2 and energy^2 = omega_0^2 + omega_p^2/2. Expressed through
    the STATIC constant eps(0) = 1 + omega_p^2/omega_0^2, which is what a wall is tabulated by,

        strength = (eps(0) - 1) omega_0^2 / 2,     energy = omega_0 sqrt( (eps(0) + 1) / 2 )

    and the three limits are worth knowing because each is a physical wall: energy >> dE returns the constant
    (eps(0)-1)/(eps(0)+1), eps(0) -> Inf returns 1 at every frequency (a perfect conductor), and omega_0 -> 0
    returns 0 -- a wall whose charges are too slow to follow the atom does not reflect at the frequencies that
    carry C_3. The function RAISES for eps(0) < 1 or omega_0 <= 0, neither of which is a dielectric.
source

Nuclear magnetic shielding

JenaAtomicCalculator.NuclearShielding.AbstractFieldModel — Type

abstract type NuclearShielding.AbstractFieldModel ... defines an abstract type to specify WHAT is applied to the ion from outside, and hence what the returned factor means. The choice is not a numerical parameter: it changes the physical content of the answer.

+ UniformField()          ... a strictly uniform external field gradient, i.e. the sources are infinitely far away.
                              This returns the transferable, tabulated coefficient gamma_inf.
+ NeighbourField(charges) ... the exact rank-2 potential of point charges at finite distances, which falls off as
                              R^2/r^3 outside each neighbour instead of growing as r^2.  This returns the EFFECTIVE
                              factor for that particular arrangement, which is smaller in magnitude.
source
JenaAtomicCalculator.NuclearShielding.Contribution — Type

struct NuclearShielding.Contribution ... keeps what one occupied subshell contributes through one excitation channel, so that a total can be read rather than merely trusted. This breakdown is the reason a sum-over-states formulation was chosen.

+ subshell     ::Subshell   ... the occupied subshell that is distorted.
+ kappaP       ::Int64      ... the kappa of the states it is distorted into.
+ value        ::Float64    ... its contribution to gamma_inf.
+ nStates      ::Int64      ... how many intermediate states entered the sum.
+ nOccupied    ::Int64      ... how many were excluded because they are occupied (Pauli).
source
JenaAtomicCalculator.NuclearShielding.NeighbourField — Type

struct NuclearShielding.NeighbourField <: AbstractFieldModel ... the potential of point charges at FINITE distance, whose rank-2 part is q * r<^2 / r>^3 with r< and r> the smaller and larger of (r, R). Only the distances matter for the radial response, since the angular placement of the neighbours affects the LATTICE gradient and not the ion's response to it.

+ charges  ::Array{Tuple{Float64,Float64},1}  ... list of (charge [e], distance [a.u.]) of the neighbours.
source
JenaAtomicCalculator.NuclearShielding.Outcome — Type

struct NuclearShielding.Outcome ... defines a type to keep the outcome of a nuclear-shielding computation.

+ level          ::Level                       ... Atomic level to which the outcome refers to.
+ gammaE2        ::Float64                     ... the quadrupole antishielding factor gamma_inf.
+ sigmaM1        ::Float64                     ... the magnetic-dipole shielding sigma; 0. while unimplemented.
+ fieldModel     ::AbstractFieldModel          ... what was applied, kept WITH the number so that a later script
                                                   cannot separate a value from its meaning.
+ contributions  ::Array{Contribution,1}       ... the per-subshell, per-channel breakdown.
source
JenaAtomicCalculator.NuclearShielding.Settings — Type

struct NuclearShielding.Settings <: AbstractPropertySettings ... defines a type for the details and parameters of computing nuclear shielding factors.

+ calcE2        ::Bool               ... True if the electric-quadrupole antishielding factor gamma_inf is wanted.
+ calcM1        ::Bool               ... True if the magnetic-dipole shielding sigma is wanted; NOT YET IMPLEMENTED.
+ fieldModel    ::AbstractFieldModel ... what is applied from outside; see AbstractFieldModel.  This decides what
                                         the returned number MEANS and is echoed in the output for that reason.
+ nVirtualMax   ::Int64              ... maximum number of intermediate states per channel, ordered by |contribution|;
                                         0 keeps all of them.  Only for convergence studies -- the default keeps all.
+ selfConsistent::Bool               ... True if the induced field is allowed to act back on the electrons, i.e. if the
                                         response is iterated to convergence.  DEFAULT FALSE, so that the uncoupled
                                         number every earlier result was computed with stays what the module returns
                                         unless it is asked for otherwise.  See `computeInducedPotential` for what the
                                         feedback contains and, just as important, for what it does NOT.
+ scfIterations ::Int64              ... iterations of that loop.  The undamped iteration OSCILLATES, so this is used
                                         with `scfMixing` below; 16 is ample for the ions measured so far.
+ scfMixing     ::Float64            ... linear mixing of the new driving term into the old, in (0,1].  1.0 is no
                                         damping and oscillates; 0.5 converges to a spread of 0.002 in 16 steps.
+ printBefore   ::Bool               ... True if a list of selected levels is printed before the computations start.
+ levelSelection::LevelSelection     ... Specifies the selected levels, if any.
source
JenaAtomicCalculator.NuclearShielding.Settings — Method

NuclearShielding.Settings(set::NuclearShielding.Settings; calcE2::Union{Nothing,Bool}=nothing, calcM1::Union{Nothing,Bool}=nothing, fieldModel::Union{Nothing,AbstractFieldModel}=nothing, nVirtualMax::Union{Nothing,Int64}=nothing, selfConsistent::Union{Nothing,Bool}=nothing, scfIterations::Union{Nothing,Int64}=nothing, scfMixing::Union{Nothing,Float64}=nothing, printBefore::Union{Nothing,Bool}=nothing, levelSelection::Union{Nothing,LevelSelection}=nothing)

... keyword copy-constructor for re-defining selected values of a settings::NuclearShielding.Settings.
    A `settings::NuclearShielding.Settings` is returned.
source
JenaAtomicCalculator.NuclearShielding.allowedKappas — Method

NuclearShielding.allowedKappas(kappa::Int64) ... returns every kappa' that a RANK-2 operator can reach from the given kappa, i.e. those for which the reduced matrix element <kappa || C^(2) || kappa'> does not vanish by the triangle and parity rules; this is the list of channels through which a shell can be distorted. An array::Array{Int64,1} is returned.

source
JenaAtomicCalculator.NuclearShielding.appliedGradient — Method

NuclearShielding.appliedGradient(model::NuclearShielding.NeighbourField) ... returns the field gradient Vzz produced at the nucleus by the given point charges, sumk 2 qk / Rk^3, which is the quantity a lattice sum reports; a value::Float64 is returned.

source
JenaAtomicCalculator.NuclearShielding.appliedGradient — Method

NuclearShielding.appliedGradient(model::NuclearShielding.UniformField) ... returns the field gradient V_zz that the driving function of this model produces at the nucleus, so that the computed response can be divided by it; a value::Float64 is returned. For f(r) = r^2 it is 2.

source
JenaAtomicCalculator.NuclearShielding.checkCancellation — Method

NuclearShielding.checkCancellation(contributions::Array{Contribution,1}, gamma::Float64) ... warns when the channel sum that produced gamma shows the signature of a radial box the response is not converged in; nothing::Nothing is returned.

    WHY A CHECK OF THIS KIND IS NEEDED AT ALL.  gamma_inf is a signed sum over channels, and a sum whose
    terms are individually larger than their total has lost its leading figures to cancellation; whatever
    else is true of such a number, it is not one to quote.

    AND ON THE GRIDS A USER ACTUALLY GETS, IT IS WELL CALIBRATED.  Measured 04-Oct-2026 on the four ions'
    own `Basics.recommendedGrid` grids, against values converged by halving hp four times:

        Y(3+)    A1 = 0.33     -36.18  against  -36.14 converged      0.1 % out
        Ba(2+)   A1 = 0.35    -101.83  against -102.86                1.0 % out
        Th(4+)   A1 = 0.44    -184.96  against -189.72                2.5 % out
        Hg(2+)   A1 = 1.82     -21.49  against  -62.00            a FACTOR OF 2.9 out

    So the one default grid that was grossly wrong is the one this check flags, and it flags no other.  The
    Hg(2+) ratio falls to 0.38 at the first refinement and sits at 0.36 once the number has settled, so the
    quantity tracks the error rather than merely correlating with it.

    WHAT IS TESTED, AND WHY THESE TWO.  Both are pure cancellation measures of the channel sum:

        A1 = max |contribution| / |gamma|       one channel larger than the answer it helped produce
        A2 = sum |contribution| / |gamma|       the usual cancellation factor of a signed sum

    A1 is the one that gates; A2 follows it (1.1 where A1 is healthy, 6.6 at Hg(2+)) and is reported in the
    warning because it says how much of the sum cancelled, but it adds no discrimination of its own.

    IT IS A FLOOR AND NOT A SUFFICIENT TEST, and this must be said plainly because the first version of this
    docstring claimed a clean separation that does not exist.  A DELIBERATELY STARVED B-SPLINE BASIS need not
    cancel at all: Y(3+) in a 93 a.u. box on the default hp, 1.07 splines per a.u., is 16 % wrong with
    A1 = 0.29 -- as healthy-looking as its own correct answer.  Those cases are caught instead by
    `checkGridDensity`, which tests the knot sequence and runs before any orbital exists.  Worse, one
    measured case defeats both: Hg(2+) at 4.70 splines per a.u. in a 30 a.u. box returns -2.6e+07 with
    A1 = 0.55.  The two checks are therefore complementary, and not even together are they sufficient -- only
    the refinement test is, and `checkGridDensity` names it.

    ONE CANDIDATE WAS TRIED AND REJECTED, recorded so it is not retried: the LOCALITY ratio, the energy
    denominator of the dominant term over the outermost binding energy.  It looks compelling -- a healthy
    response is dominated by LOW-lying excitations of the OUTER shells, and in the bad cases the dominant
    channel moves to a deep inner s shell at tens of Hartree.  But Ba(2+) in a 30 a.u. box gives a locality
    ratio of 55 while its gamma is unmoved to five figures, so it cries wolf.  Cancellation gates; locality
    only describes.

    IT WARNS AND DOES NOT REFUSE.  The remedy is cheap and certain, so a warning that names it costs the user
    one run; a refusal would stop a calculation whose default grid is, for three ions in four, good to 2.5 %.
source
JenaAtomicCalculator.NuclearShielding.checkGridDensity — Method

NuclearShielding.checkGridDensity(grid::Radial.Grid) ... tests, BEFORE any orbital is generated, whether the given grid carries enough B-splines to represent the Sternheimer response at all, and warns naming the remedy if it does not; nothing is returned.

    WHAT IS TESTED, AND WHY IT CAN BE TESTED THIS EARLY.  The number tested is the SPLINE DENSITY,
    nsL / r_box, the number of large-component splines per Bohr radius of box.  It is a property of the KNOT
    SEQUENCE alone, so it is known the moment the grid exists -- no orbital, no SCF and no response is needed
    to evaluate it, which is what makes it usable as an entry condition.

    THIS IS A FLOOR AND NOT A CRITERION, AND THE DISTINCTION IS THE WHOLE POINT.  No grid measured below 4
    splines per a.u. has returned a sound gamma_inf, so a grid below that is rejected cheaply.  But PASSING
    establishes nothing whatever, and two measurements of 04-Oct-2026 say so in the strongest terms.  The
    approach to the converged value is GRADUAL rather than a threshold -- Th(4+) in a 62 a.u. box gives
    -48.1, -135.6, -167.2 and -185.0 at 1.78, 2.32, 2.93 and 4.02 splines per a.u. -- and the density a given
    ion NEEDS is a property of the ion, not of the grid: Y(3+) [Kr] is converged at 10.7 splines per a.u. to
    0.1 %, while Hg(2+) [Xe] 4f^14 5d^10 at 6.4 is a FACTOR OF 2.9 out (-21.49 against -62.00) and needs 27
    before it settles.  And at 4.70 per a.u. in a 30 a.u. box Hg(2+) returns -2.6e+07, seven orders of
    magnitude wrong, with this check and `checkCancellation` BOTH silent.

    THE PRESCRIPTION IS THEREFORE A REFINEMENT TEST, NOT A THRESHOLD.  Keep the box `Basics.recommendedGrid`
    chooses, then recompute with hp HALVED and compare.  If gamma_inf moves by more than the accuracy wanted,
    halve again; when two successive densities agree, the number is converged in the mesh, and -- this being
    the useful part -- it is then also independent of the box, so no separate box study is needed.  Measured
    04-Oct-2026 with hp halved four times, the four reference ions converge to

        Y(3+)   -36.14      Ba(2+)  -102.86      Th(4+)  -189.72      Hg(2+)  -62.00

    and their recommended grids are 0.1 %, 1.0 %, 2.5 % and 190 % away from those.  It is the only test here
    that caught every bad case.  `tools/probe-nuclearShieldingDensity.jl` performs it.

    WHAT THIS CORRECTS, worth stating because the opposite was believed for a day.  gamma_inf is NOT
    box-dependent, and the apparent box dependence that made Th(4+) run -185 -> -136 -> +30 -> +287 over
    r_box = 14 to 91 was an artefact of ONE line: `Basics.recommendedGrid` sets hp = r_box/300, which holds
    the number of points in the outer region roughly FIXED however large the box, so the spline basis does
    not grow with it and each spline is asked to cover more space.  Hold hp fixed instead -- pass it
    explicitly -- and the box may be enlarged freely: Y(3+) gives -36.18 at r_box = 8.7 and -36.18 at 92.3, a
    tenfold box, and Th(4+) -184.98 at 13.7 against -184.96 at 62.2.  The same mechanism is documented at the
    point where it is caused, in `Basics.recommendedGrid`, where it was measured on continuum normalization
    on 01-Sep-2026; this is the bound-response face of it.

    AND IT IS COMPLEMENTARY TO `checkCancellation`, NOT REDUNDANT WITH IT.  The two catch disjoint failures.
    A starved basis need not cancel: Y(3+) at 1.07 splines per a.u. is 16 % wrong with a cancellation ratio
    of 0.29, as healthy-looking as its own correct answer, so cancellation misses it completely.  Conversely
    Hg(2+) on its own default grid cancels at 2.24 on a density this check passes.  Both are kept; neither is
    sufficient, and as the Hg(2+) 30 a.u. case shows, not even both together are.
source
JenaAtomicCalculator.NuclearShielding.computeAmplitudesProperties — Method

NuclearShielding.computeAmplitudesProperties(outcome::NuclearShielding.Outcome, nm::Nuclear.Model, grid::Radial.Grid, settings::NuclearShielding.Settings) ... computes the shielding factor of the given level by summing, over every occupied subshell and every rank-2 excitation channel, the response of the electron cloud to the external field. The angular weight of a channel is |<kappaa || C^(2) || kappa'>|^2 and the overall constant is `GAMMAPREFACTOR, which is DERIVED -- see its own docstring for the four factors -- and checked against Sternheimer's closed-shell coefficients 48/25 (p->p), 16/7 (d->d) and 224/75 (f->f). NOTE thatfObservebelow is 1/r^3 and NOT the full 2/r^3 of the gradient operator; that factor of two sits inGAMMA_PREFACTOR`. A new outcome::NuclearShielding.Outcome is returned.

source
JenaAtomicCalculator.NuclearShielding.computeChannelResponse — Method

NuclearShielding.computeChannelResponse(orb::Radial.Orbital, kappaP::Int64, bDrive::Array{Float64,1}, bObserve::Array{Float64,1}, pot::Radial.Potential, primitives::Bsplines.Primitives, occupiedEnergies::Array{Float64,1}, storage::Dict{String,Array{Float64,2}}, overlap::Array{Float64,2}, nVirtualMax::Int64) ... performs the sum over intermediate states of one excitation channel: the occupied orbital is pushed by the external field into the states of symmetry kappaP, and each of them produces a field gradient back at the nucleus. States that are themselves OCCUPIED are excluded, since a rotation among occupied orbitals is not a physical excitation. A tuple tpl(value::Float64, nStates::Int64, nOccupied::Int64, dvector::Array{Float64,1}) is returned, the last being the B-spline expansion of the PERTURBED orbital of this channel, sumv |v> <v|fdrive|a>/(epsa - epsv). It is what the self-consistent loop needs and it costs nothing extra to accumulate, since every term of it is already formed for the scalar.

source
JenaAtomicCalculator.NuclearShielding.computeInducedPotential — Method

NuclearShielding.computeInducedPotential(density::Array{Float64,1}, rhoTotal::Array{Float64,1}, grid::Radial.Grid) ... returns the radial factor of the rank-2 potential that the induced electron density makes, i.e. the term that turns a first-order response into a self-consistent one; an array::Array{Float64,1} is returned.

    TWO PIECES, AND THE SECOND IS OFTEN LEFT OUT.
    (i)  THE DIRECT (HARTREE) TERM, `INDUCED_SCALE` times the rank-2 potential of the induced density.  The scale is
         not fitted: the gradient that Y_2[density] makes at the nucleus was measured against the gradient the module
         computes directly, and the ratio came out as 5/2 EXACTLY on three ions spanning Z = 39 to 90 and gamma from
         -27 to -185.  A constant rational across that range is bookkeeping, not physics -- it is the same 1/5 and 2
         that `GAMMA_PREFACTOR` carries, met once more on the way back from density to potential.
    (ii) THE EXCHANGE RESPONSE, the local derivative of the SAME Slater term the DFS mean field is built with:
         V_x = -(3 rho_t/(4 pi^2 r^2))^(1/3) goes as rho_t^(1/3), so dV_x = (1/3)(V_x/rho_t) drho_2.  No new
         functional and no new parameter.  Measured, it is a correction of about 1.5 percentage points on the
         self-consistent shift and it does NOT change its sign anywhere.

    WHAT IS STILL MISSING, stated because it bounds what the self-consistent number means: the exchange response is
    LOCAL, as the mean field it derives from is; a non-local (Dirac-Fock) exchange response is a different and larger
    calculation.  And the response remains that of a free, spherical, closed-shell ion.
source
JenaAtomicCalculator.NuclearShielding.computeOutcomes — Method

NuclearShielding.computeOutcomes(multiplet::Multiplet, nm::Nuclear.Model, grid::Radial.Grid, settings::NuclearShielding.Settings; output=true) ... computes the nuclear shielding factors for the selected levels of the given multiplet. The ion must be CLOSED SHELL: the response of an open-shell ion is not a scalar and the factorisation this module rests on does not apply, so such a case is refused rather than approximated. An array of outcomes::Array{Outcome,1} is returned if output = true, and nothing otherwise.

source
JenaAtomicCalculator.NuclearShielding.determineOutcomes — Method

NuclearShielding.determineOutcomes(multiplet::Multiplet, settings::NuclearShielding.Settings) ... determines which levels of the given multiplet should be considered; an array of outcomes::Array{Outcome,1} is returned, one for each selected level, with the shielding factors still unset.

source
JenaAtomicCalculator.NuclearShielding.displayOutcomes — Method

NuclearShielding.displayOutcomes(outcomes::Array{NuclearShielding.Outcome,1}) ... lists the selected levels before the computation starts, so that a long run can be interrupted early if the wrong levels were picked; nothing is returned.

source
JenaAtomicCalculator.NuclearShielding.displayResults — Method

NuclearShielding.displayResults(stream::IO, outcomes::Array{NuclearShielding.Outcome,1}, settings::NuclearShielding.Settings) ... prints the shielding factors together with the STATEMENT OF WHAT THEY MEAN, which is not decoration: a shielding factor is a conditional quantity and a number quoted without its field model and its free-ion caveat invites exactly the misuse this module exists to prevent. Both gammainf and (1 - gammainf) are printed because the published sign conventions for this quantity disagree with one another. Nothing is returned.

source
JenaAtomicCalculator.NuclearShielding.drivingFunction — Method

NuclearShielding.drivingFunction(model::NuclearShielding.NeighbourField, r::Float64) ... returns the radial factor f(r) = sumk qk r<^2 / r>^3 of the EXACT rank-2 potential of point charges at finite distance, the standard r<^L / r>^(L+1) kernel with one coordinate frozen at the neighbour's distance. It grows as r^2 only INSIDE the nearest neighbour and falls as 1/r^3 outside it, which is the whole difference between an effective and a far-field shielding factor; a value::Float64 is returned.

source
JenaAtomicCalculator.NuclearShielding.drivingFunction — Method

NuclearShielding.drivingFunction(model::NuclearShielding.UniformField, r::Float64) ... returns the radial factor f(r) = r^2 of a strictly uniform external field gradient, whose rank-2 potential grows as r^2 everywhere; a value::Float64 is returned.

source
JenaAtomicCalculator.NuclearShielding.multipolePotential — Method

NuclearShielding.multipolePotential(density::Array{Float64,1}, grid::Radial.Grid) ... returns the rank-2 potential of a radial density, Y_2[f](r) = (1/r^3) int_0^r r'^2 f dr' + r^2 int_r^inf f/r'^3 dr', tabulated on the grid; an array::Array{Float64,1} is returned.

    THE SECOND TERM IS WHY THIS FUNCTION IS WORTH ITS OWN NAME.  Its coefficient, int_0^inf f/r'^3 dr', is the
    gradient-carrying part: as r -> 0 the first term goes to a constant and only the second behaves as r^2.  That is
    what lets the induced potential be checked against the gradient the module computes directly -- see
    `computeInducedPotential`.
source
JenaAtomicCalculator.NuclearShielding.projectOperator — Method

NuclearShielding.projectOperator(f::Function, orb::Radial.Orbital, primitives::Bsplines.Primitives, grid::Radial.Grid) ... returns the vector <B_i | f(r) | orb> of the given radial operator acting on an orbital and projected onto the B-spline primitives, large and small component alike, since f(r) is multiplicative and acts on both the same way. An array::Array{Float64,1} of length nsL+nsS is returned.

source