GitHub

API Reference

Complete index of all exported symbols.

Internal Types

AtomicAndPhysicalConstants.SubatomicSpecies — Type
SubatomicSpecies

Internal struct storing intrinsic data for a single subatomic particle. Instances are stored in SUBATOMIC_SPECIES.

Fields

  • speciesname::String — openPMD particle identifier.
  • charge::Float64 — charge in units of e.
  • mass::Float64 — mass in eV/c².
  • moment::Float64 — magnetic dipole moment in eV/T.
  • spin::Float64 — spin in ħ.
  • gspin::Float64 — spin g-factor.
source
AtomicAndPhysicalConstants.AtomicSpecies — Type
AtomicSpecies

Internal struct storing isotope data for a chemical element. Instances are stored in ATOMIC_SPECIES.

Fields

  • Z::Int — atomic number (number of protons).
  • speciesname::String — standard atomic symbol (e.g. "Fe").
  • mass::Dict{Int,Float64} — isotope masses in atomic mass units (u), keyed by mass number. The special key −1 holds the abundance-averaged atomic mass.
  • spin::Dict{Int,Float64} — ground-state nuclear spins in units of ħ, keyed by mass number, taken from NUBASE2020. NaN marks an isotope to which NUBASE assigns no unambiguous spin. There is deliberately no −1 key: the abundance average has no meaningful spin, because different isotopes of an element have different ones.
source
AtomicAndPhysicalConstants.CODATA_release — Type
CODATA_release

Keyword-argument struct holding all fundamental constants from one CODATA release year. Fields mirror the exported scalar constants (M_ELECTRON, C_LIGHT, etc.) but are grouped together so that multiple release years can coexist in memory simultaneously.

Pre-built instances are exported as CODATA2002, CODATA2006, CODATA2010, CODATA2014, CODATA2018, and CODATA2022.

CODATA2018.M_ELECTRON   # electron mass from the 2018 release
CODATA2014.C_LIGHT      # speed of light from the 2014 release
source

Species type and constructor

AtomicAndPhysicalConstants.Species — Type
Species(speciesname::String)
Species()

Construct a particle species by name, or a null placeholder with no arguments.

The string format encodes particle identity, isotope (for atoms), and charge state in one expression: [mass_number] symbol [charge].

Subatomic particles

Pass the openPMD name exactly:

NameParticle
"electron" / "positron"electron / positron
"proton" / "anti-proton"proton / antiproton
"neutron" / "anti-neutron"neutron / antineutron
"muon" / "anti-muon"muon / antimuon
"pion0" / "pion+" / "pion-"pions
"deuteron" / "anti-deuteron"deuteron / antideuteron
"triton" / "anti-triton"triton / antitriton
"helion" / "anti-helion"helion / antihelion
"photon"photon

Atomic species

Atomic symbols "H" (Z=1) through "Og" (Z=118) are supported.

Mass number — There are two ways to include the mass number: Before the atomic symbol, either prefix with a pound symbol # followed by the mass number or, prefix with a Unicode superscript(s). A bare ASCII mass number (e.g. "4He") is not accepted. Correct would be "#4He" or "⁴He".

Charge state — append after the symbol. Repeated signs ("++", "---") or "+n" / "-n" notation are both accepted.

Species("#4He")     # helium-4, neutral (# prefix required for ASCII digits)
Species("⁴He")      # same, Unicode superscript
Species("Li+3")     # lithium, charge +3
Species("Li+++")    # same
Species("K-2")      # potassium, charge −2

Anti-atoms: prepend "anti-" to any atomic symbol.

Species("anti-H")   # antihydrogen

Null species: Species(), or names "Null", "null", "".

Fields

FieldTypeDescription
nameStringParticle name or atomic symbol
chargeFloat64Net charge in units of e
massFloat64Rest mass in eV/c²
spinFloat64Spin in ħ; for an atom the nuclear spin, NaN if undefined
gspinFloat64Spin g-factor (0 for atoms)
momentFloat64Magnetic dipole moment in eV/T (0 for atoms)
isoIntMass number; −1 for abundance average; 0 for subatomic particles
kindKind.TLEPTON, HADRON, PHOTON, ATOM, or NULL

Direct field access is disabled. Use chargeof, massof, spinof, g_spin, momentof, iso_of, atomicnumberof, kindof, isnullspecies, Base.nameof.

source

Accessor functions

The Species page describes the unit conventions these follow and what each one returns for a species that does not carry the property.

Base.nameof — Method
nameof(species::Species) -> String

Return the canonical name of species.

For subatomic particles the openPMD name is returned unchanged. For atomic species the name is assembled from the atomic symbol, mass number (if a specific isotope was requested), and charge state, using the #mAS±c convention:

nameof(Species("electron"))   # "electron"
nameof(Species("Fe"))         # "Fe"
nameof(Species("#4He+2"))     # "#4He+2"
nameof(Species("Li+"))        # "Li+1"
nameof(Species("anti-#4He"))  # "anti-#4He"
source
AtomicAndPhysicalConstants.chargeof — Function
chargeof(species::Species; C::Bool = false) -> Float64

Return the net charge of species.

By default the charge is returned as a (whole-numbered) multiple of the elementary charge e. Pass C = true to convert to coulombs using the active E_CHARGE constant.

Examples

chargeof(Species("proton"))       # 1.0
chargeof(Species("electron"))     # -1.0
chargeof(Species("Li+3"))         # 3.0
chargeof(Species("proton"), C=true)   # ≈ 1.602176634e-19
source
AtomicAndPhysicalConstants.massof — Function
massof(species::Species; AMU::Bool = false) -> Float64

Return the rest mass of species.

By default the mass is returned in eV/c². Pass AMU = true to return the mass in atomic mass units (daltons), which is particularly convenient for atomic species.

Examples

massof(Species("electron"))              # 510998.95069  eV/c²
massof(Species("proton"))               # 9.38272089430e8  eV/c²
massof(Species("H"), AMU = true)        # ≈ 1.00794  u
massof(Species("#4He"), AMU = true)     # ≈ 4.0026  u
source
AtomicAndPhysicalConstants.spinof — Function
spinof(species::Species) -> Float64

Return the spin of species in units of the reduced Planck constant ħ.

For an atomic species this is the nuclear spin, taken from the tabulated NUBASE2020 ground-state values. Electron spin is not included: the total angular momentum of an atom depends on its electronic state, which Species does not model. Ionisation therefore does not change the result, and an anti-nucleus has the same spin as its mirror.

Returns NaN when no spin is defined:

  • for an atom given without a mass number (e.g. Species("He")), because the abundance average runs over isotopes with differing spins;
  • for the handful of exotic isotopes to which NUBASE assigns no unambiguous ground-state spin.

Note that spin is not a function of the mass number — nucleons pair off with opposite spins, so every even-even nucleus has spin 0.

Examples

spinof(Species("electron"))    # 0.5
spinof(Species("proton"))      # 0.5
spinof(Species("photon"))      # 1.0
spinof(Species("#4He"))        # 0.0   even-even nucleus
spinof(Species("#3He"))        # 0.5
spinof(Species("#3He+2"))      # 0.5   ionisation does not change the nucleus
spinof(Species("He"))          # NaN   abundance average, no single value
source
AtomicAndPhysicalConstants.momentof — Function
momentof(species::Species) -> Float64

Return the magnetic dipole moment of species in eV/T.

Returns 0 for atomic species and the null species (no moment is stored for these types).

Examples

momentof(Species("electron"))   # ≈ -5.795094307320036e-5  eV/T
momentof(Species("proton"))     # ≈  8.8043151136e-8  eV/T
momentof(Species("H"))          # 0.0
source
AtomicAndPhysicalConstants.g_spin — Function
g_spin(species::Species; signed::Bool = false) -> Float64

Return the spin g-factor of species.

By default the absolute value is returned. Pass signed = true to get the signed g-factor (negative for particles with a negative gyromagnetic ratio, such as the electron).

Returns 0 for atomic species, for which no g-factor is stored.

gyromagnetic_anomaly is built on the default, unsigned value.

Examples

g_spin(Species("electron"))               # 2.00231930436092
g_spin(Species("electron"), signed=true)  # -2.00231930436092
g_spin(Species("proton"))                 # 5.5856946893
g_spin(Species("H"))                      # 0.0
source
AtomicAndPhysicalConstants.gyromagnetic_anomaly — Function
gyromagnetic_anomaly(species::Species) -> Float64

Compute and return the gyromagnetic anomaly

\[a = \frac{|g| - 2}{2}\]

for leptons and hadrons. Returns NaN for photons, atoms, and null species, since the gyromagnetic anomaly is not defined for them.

The unsigned g-factor is used, i.e. g_spin is called with its default signed = false. The sign of the stored g-factor records the orientation of the magnetic moment relative to the spin, not the size of the anomaly, so species whose g-factor is negative (electron, muon, neutron, helion) still get the conventional positive anomaly: the electron gives +0.00115965…, not -2.0011….

The stored g-factors are all in the convention mu = g * (e / 2m) * S, where the particle's own mass sets the magneton, so this formula applies uniformly. For the deuteron, helion, and triton this required renormalizing the NIST values, which are tabulated against the nuclear magneton e*hbar/(2*M_PROTON); G_DEUTERON, G_HELION, and G_TRITON carry the renormalized values (see the Physical Constants manual page).

Examples

gyromagnetic_anomaly(Species("electron"))   # ≈  0.00115965218046
gyromagnetic_anomaly(Species("muon"))       # ≈  0.00116592062
gyromagnetic_anomaly(Species("neutron"))    # ≈  0.91304276
gyromagnetic_anomaly(Species("deuteron"))   # ≈ -0.1429872697
gyromagnetic_anomaly(Species("H"))          # NaN
source
AtomicAndPhysicalConstants.iso_of — Function
iso_of(species::Species) -> Int

Return the mass number (isotope) of species.

  • For atomic species: the mass number of the requested isotope, or −1 if the abundance-averaged atomic mass was used.
  • For subatomic particles: always 0.

Examples

iso_of(Species("#3He"))         # 3
iso_of(Species("He"))           # -1  (abundance average)
iso_of(Species("electron"))     # 0
source
AtomicAndPhysicalConstants.atomicnumberof — Function
atomicnumberof(species::Species) -> Int

Return the atomic number (number of protons) of species.

For an anti-atom, returns the negative of the atomic number (-Z), to distinguish it from the matter atom of the same symbol.

Throws an error if species is not of kind ATOM.

Examples

atomicnumberof(Species("Fe"))       # 26
atomicnumberof(Species("H+"))       # 1
atomicnumberof(Species("anti-H"))   # -1
atomicnumberof(Species("electron")) # ERROR
source
AtomicAndPhysicalConstants.kindof — Function
kindof(species::Species) -> Kind.T

Return the particle classification of species as a Kind.T enum value.

Possible values: Kind.LEPTON, Kind.HADRON, Kind.PHOTON, Kind.ATOM, Kind.NULL.

Examples

kindof(Species("electron"))    # Kind.LEPTON
kindof(Species("proton"))      # Kind.HADRON
kindof(Species("H"))           # Kind.ATOM
kindof(Species("photon"))      # Kind.PHOTON
kindof(Species())              # Kind.NULL
source
AtomicAndPhysicalConstants.isnullspecies — Function
isnullspecies(species::Species) -> Bool

Return true if species is a null (placeholder) species, false otherwise.

isnullspecies(Species())           # true
isnullspecies(Species("null"))     # true
isnullspecies(Species("proton"))   # false
source

Configuration

AtomicAndPhysicalConstants.set_release — Function
set_release(; year::String = "2022")

Persistently set the CODATA release year used by AtomicAndPhysicalConstants.jl.

The setting is stored via Preferences.jl in the active Julia environment and survives across sessions. A Julia restart is required for the new constants to take effect.

Valid values for year: "2002", "2006", "2010", "2014", "2018", "2022". Calling with no arguments resets to the default ("2022").

Examples

set_release(year = "2014")
# [ Info: The default CODATA release is now 2014.
#         Restart your Julia session for this change to take effect.

set_release()   # revert to 2022

See also: RELEASE_YEAR.

source

Particle kind enum

AtomicAndPhysicalConstants.Kind — Module
Kind

Classification of a particle species.

ValueMeaning
Kind.LEPTONleptons: electron, positron, muon, anti-muon
Kind.HADRONhadrons: proton, neutron, pions, deuteron, …
Kind.PHOTONphoton
Kind.ATOMany atomic or ionic species
Kind.NULLnull placeholder species

The kind of a species is queried with kindof.

source

Particle data dictionaries

AtomicAndPhysicalConstants.SUBATOMIC_SPECIES — Constant
SUBATOMIC_SPECIES :: Dict{String, SubatomicSpecies}

Dictionary of all supported subatomic particles, keyed by openPMD name.

Supported keys: "electron", "positron", "proton", "anti-proton", "neutron", "anti-neutron", "muon", "anti-muon", "pion0", "pion+", "pion-", "deuteron", "anti-deuteron", "triton", "anti-triton", "helion", "anti-helion", "photon".

source
AtomicAndPhysicalConstants.ATOMIC_SPECIES — Constant
ATOMIC_SPECIES :: Dict{String, AtomicSpecies}

Dictionary of all supported atomic elements (Z = 1 … 118), keyed by atomic symbol (e.g. "H", "Fe", "Og"). Each value is an AtomicSpecies struct containing the atomic number, symbol, a dictionary of isotope masses in atomic mass units, and a dictionary of ground-state nuclear spins in units of ħ.

Isotope masses come from NIST; nuclear spins come from NUBASE2020. Regenerate them with update/update_isos.jl and update/update_spins.jl respectively.

source

CODATA release structs

Physical constants

AtomicAndPhysicalConstants.G_DEUTERON — Constant

GDEUTERON::Float64 - The deuteron spin g-factor renormalized to the deuteron magneton `ehbar/(2MDEUTERON), the convention in which the gyromagnetic anomalya = (|g|-2)/2` holds.

source
AtomicAndPhysicalConstants.G_HELION — Constant

GHELION::Float64 - The helion spin g-factor renormalized to the helion magneton `ehbar/(2MHELION), the convention in which the gyromagnetic anomalya = (|g|-2)/2` holds.

source
AtomicAndPhysicalConstants.G_TRITON — Constant

GTRITON::Float64 - The triton spin g-factor renormalized to the triton magneton `ehbar/(2MTRITON), the convention in which the gyromagnetic anomalya = (|g|-2)/2` holds.

source