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.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.
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.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.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.
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.
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.
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.
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.
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.
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.JenaAtomicCalculator.FormFactor.Outcome — Method
FormFactor.Outcome() ... constructor for an empty instance of FormFactor.Outcome for the computation of atomic form factors. A outcome::FormFactor.Outcome is returned.
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.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.JenaAtomicCalculator.FormFactor.Settings — Method
FormFactor.Settings() ... constructor for an empty instance of FormFactor.Settings for the computation of atomic form factors. A settings::FormFactor.Settings is returned.
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.
JenaAtomicCalculator.FormFactor.computeAmplitudesProperties — Method
FormFactor.computeAmplitudesProperties(outcome::FormFactor.Outcome, nm::Nuclear.Model, grid::Radial.Grid, settings::FormFactor.Settings) ... to compute all form factors, etc. for the given outcome; a newOutcome::FormFactor.Outcome is returned.
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.
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.
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.
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.
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.
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.
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.
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.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).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.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.JenaAtomicCalculator.CrystalField.Lattice — Method
CrystalField.Lattice() ... constructor for an empty lattice (no external field). A lattice::CrystalField.Lattice is returned.
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.JenaAtomicCalculator.CrystalField.Outcome — Method
CrystalField.Outcome() ... constructor for an empty instance of CrystalField.Outcome. A outcome::CrystalField.Outcome is returned.
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.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.JenaAtomicCalculator.CrystalField.PointChargeModel — Method
CrystalField.PointChargeModel() ... constructor for the unscaled (scaleField = 1.0) point-charge model. A pointChargeModel::CrystalField.PointChargeModel is returned.
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.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.JenaAtomicCalculator.CrystalField.Settings — Method
CrystalField.Settings() ... constructor for a Settings with an empty lattice and otherwise default values. A settings::CrystalField.Settings is returned.
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.JenaAtomicCalculator.CrystalField.characteristicSplitting — Method
CrystalField.characteristicSplitting(outcome::CrystalField.Outcome) ... convenience method, equivalent to CrystalField.characteristicSplitting(outcome.cfMultiplet).
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.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.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.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.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.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.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.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.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.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.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.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.
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.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.JenaAtomicCalculator.Einstein.Settings — Method
Einstein.Settings() ... constructor for the default values of Einstein line computations. A settings::Einstein.Settings is returned.
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.
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.
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.
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.
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.
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.
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.
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 allJenaAtomicCalculator.Hfs.HfBasisVector — Method
Hfs.HfBasisVector() ... constructor for an empty instance of HfBasisVector. AhfBasisVector::Hfs.HfBasisVector` is returned.
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.JenaAtomicCalculator.Hfs.HfLevel — Method
Hfs.HfLevel() ... constructor for an empty instance of HfLevel. A hfLevel::Hfs.HfLevel is returned.
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)JenaAtomicCalculator.Hfs.HfMultiplet — Method
Hfs.HfMultiplet() ... constructor for an empty instance of Hfs.HfMultiplet. A hfMultiplet::Hfs.HfMultiplet is returned.
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 matrixJenaAtomicCalculator.Hfs.InteractionMatrix — Method
Hfs.InteractionMatrix() ... constructor for an empty instance of InteractionMatrix. A interactionMatrix::Hfs.InteractionMatrix is returned.
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.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.
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.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.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.
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.
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.
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.
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.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.
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.
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.
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.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.
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`.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).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.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.
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.
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.
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.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.
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.
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.
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.
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.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.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.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.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.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.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.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.JenaAtomicCalculator.HfsPaschenBack.Settings — Method
HfsPaschenBack.Settings() ... constructor for an empty instance of HfsPaschenBack.Settings. A settings::HfsPaschenBack.Settings is returned.
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.
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.
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.
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.
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.
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).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).
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.
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).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 amplitudeJenaAtomicCalculator.IsotopeShift.Outcome — Method
IsotopeShift.Outcome() ... constructor for an empty instance of Hfs.Outcome for the computation of isotope-shift properties. A outcome::IsotopeShift.Outcome is returned.
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.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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.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.
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.
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.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-valueJenaAtomicCalculator.LandeZeeman.Outcome — Method
LandeZeeman.Outcome() ... constructor for an empty instance of LandeZeeman.Outcome. A outcome::LandeZeeman.Outcome is returned.
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.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.
JenaAtomicCalculator.LandeZeeman.Settings — Method
LandeZeeman.Settings() ... constructor for an empty instance of ZeemanSettings for the computation of isotope M and F parameters. A settings::LandeZeeman.Settings is returned.
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 levelJenaAtomicCalculator.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 levelJenaAtomicCalculator.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.
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.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.
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.
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.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.
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.
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.
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.
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.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.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.
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.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.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.
JenaAtomicCalculator.ReducedDensityMatrix.compute1pRDM — Method
ReducedDensityMatrix.compute1pRDM(level::Level) ... to compute 1p RDM; a rdm::Array{Float64,2} is returned.
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.JenaAtomicCalculator.ReducedDensityMatrix.compute2pRDM — Method
ReducedDensityMatrix.compute2pRDM(level::Level) ... to compute 2p RDM for all pairs (p,q;r,s) of subshells; a rdm::Array{Float64,4} is returned.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.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).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.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.JenaAtomicCalculator.StarkZeeman.Settings — Method
StarkZeeman.Settings() ... constructor for an empty instance of StarkZeeman.Settings. A settings::StarkZeeman.Settings is returned.
JenaAtomicCalculator.StarkZeeman.SublevelBasis — Type
struct StarkZeeman.SublevelBasis ... one (level,M) entry of the perturbation-matrix basis.
+ level ::Level ... the zero-field level.
+ M ::AngularM64 ... the M-sublevel of that level.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.
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.
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.
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.
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.
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.
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.
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.
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.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.JenaAtomicCalculator.StarkShift.Outcome — Method
StarkShift.Outcome() ... constructor for an empty instance of StarkShift.Outcome. A outcome::StarkShift.Outcome is returned.
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.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.JenaAtomicCalculator.StarkShift.Settings — Method
StarkShift.Settings() ... constructor for an empty instance of StarkShift.Settings. A settings::StarkShift.Settings is returned.
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).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.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.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.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.
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.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.
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.JenaAtomicCalculator.StarkShift.computeTheta1 — Method
StarkShift.computeTheta1(level::Level, grid::Radial.Grid) ... to compute the electric-dipole-moment [Theta^(1)] for the given level; an edm::Float64 is returned.
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
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.
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.
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.
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.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.
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.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.
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.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.
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.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.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.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.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.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.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.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.
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.
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.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.
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.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.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/.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.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.JenaAtomicCalculator.WeakInteractionEnhancement.Outcome — Method
WeakInteractionEnhancement.Outcome() ... constructor for an empty instance of WeakInteractionEnhancement.Outcome; an outcome::WeakInteractionEnhancement.Outcome is returned.
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.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.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.
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.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.
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.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).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.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.
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.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.
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.
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.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.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.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.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.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.JenaAtomicCalculator.MultipolePolarizibility.Outcome — Method
MultipolePolarizibility.Outcome() ... constructor for an empty instance of MultipolePolarizibility.Outcome for the computation of static polarizibilities. A outcome::MultipolePolarizibility.Outcome is returned.
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.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.JenaAtomicCalculator.MultipolePolarizibility.Settings — Method
MultipolePolarizibility.Settings() ... constructor for an empty instance of MultipolePolarizibility.Settings for the computation dynamic polarizibilities. A settings::MultipolePolarizibility.Settings is returned.
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.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.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.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.
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.
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.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.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.
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.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.
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.
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.
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.
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.
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.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.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.
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.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.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.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.
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.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.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.JenaAtomicCalculator.DispersionCoefficient.Outcome — Method
DispersionCoefficient.Outcome() ... constructor for an empty instance of DispersionCoefficient.Outcome. A outcome::DispersionCoefficient.Outcome is returned.
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.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.
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.
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.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.JenaAtomicCalculator.DispersionCoefficient.Settings — Method
DispersionCoefficient.Settings() ... constructor for an empty instance of DispersionCoefficient.Settings. A settings::DispersionCoefficient.Settings is returned.
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.
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.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.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.
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`.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.
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.
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.
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.
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.
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.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.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.
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.
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.
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.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.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).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.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.JenaAtomicCalculator.NuclearShielding.Outcome — Method
NuclearShielding.Outcome() ... constructor for an empty instance of NuclearShielding.Outcome. A outcome::NuclearShielding.Outcome is returned.
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.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.JenaAtomicCalculator.NuclearShielding.Settings — Method
NuclearShielding.Settings() ... constructor for an empty instance of NuclearShielding.Settings. A settings::NuclearShielding.Settings is returned.
JenaAtomicCalculator.NuclearShielding.UniformField — Type
struct NuclearShielding.UniformField <: AbstractFieldModel ... the far-field limit; the perturbation grows as r^2 everywhere and the returned factor is the tabulated gamma_inf.
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.
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.
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.
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 %.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.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.
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.
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.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.
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.
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.
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.
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.
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.
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`.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.