Electronic States and Quantum Number Representation

Introduction

The representation of electronic states in the NOMAD simulations schema follows a two-level architecture that separates the organizational aspects of electronic structure from the quantum mechanical description of individual states. At the top level, the ElectronicState class provides a hierarchical navigation structure for organizing electronic configurations. The actual quantum mechanical information resides in instances of BaseSpinOrbitalState subclasses, most commonly SphericalSymmetryState, which use quantum numbers to precisely define states.

This design emphasizes semantic organization over numerical representation. The ElectronicState hierarchy labels and organizes which orbitals participate in a calculation, providing reference points for projection operations in density of states, band structure, or Green's function calculations. The numerical details of how these states are represented computationally reside elsewhere in the schema: basis set definitions live in the numerical_settings module, while expansion coefficients and eigenvalues appear in property sections like BandStructure or DOSElectronic. This separation allows the same electronic state labels to apply across different numerical treatments, whether plane-wave, localized orbital, or other basis set approaches.

The semantic focus proves essential when complex electronic structures require multiple decomposition views. The same d-electrons in a transition metal atom can be organized by orbital angular momentum (L-S coupling), by total angular momentum (j-j coupling), or by crystal field symmetry labels. The ElectronicState hierarchy accommodates all these perspectives while the underlying quantum numbers remain consistently defined.

The ElectronicState Container

Each ElectronicState instance contains a spin_orbit_state field referencing a BaseSpinOrbitalState that describes the quantum state at that hierarchy level. The sub_states field enables recursive decomposition, building complex electronic structures from progressively finer-grained components. This recursive structure naturally expresses manifolds decomposing into individual orbitals, which further split into spin components.

For systems where electronic states arise from linear combinations of simpler basis functions, the basis_orbitals field holds a list of BaseSpinOrbitalState objects representing the constituent orbitals. This pattern applies to hybrid orbitals like sp³, molecular orbitals constructed via LCAO methods, or Wannier functions expressed as linear combinations of Bloch states. The actual expansion coefficients belong in the relevant electronic eigenvalue sections rather than being duplicated in the state definition.

The container also tracks occupation numbers and degeneracy. For non-interacting systems, occupations follow integer values or Fermi-Dirac distributions. In strongly correlated systems described by many-body methods like DMFT, fractional occupations reflect the quantum nature of the many-body state rather than partial filling of individual orbitals. The degeneracy can be computed automatically from quantum numbers or set explicitly for symmetry-adapted states.

Quantum State Description with SphericalSymmetryState

The SphericalSymmetryState class provides quantum mechanical descriptions using spherical symmetry quantum numbers. The principal quantum number n_quantum_number identifies the shell, while l_quantum_number specifies the orbital angular momentum with values 0, 1, 2, 3 corresponding to s, p, d, f orbitals. The azimuthal projection ml_quantum_number must satisfy -l ≤ ml ≤ l and determines the orbital's directional character.

For systems with significant spin-orbit coupling, the total angular momentum quantum number j_quantum_number becomes relevant. The relationship j = |l - s|, |l - s| + 1, ..., l + s follows from Russell-Saunders coupling theory. The projection mj_quantum_number ranges from -j to j in integer steps. Similarly, the spin projection ms_quantum_number relates to the spin quantum number s_quantum_number, which defaults to 0.5 for electrons.

In relativistic calculations, the kappa_quantum_number provides an alternative labeling scheme. The relationship j = |κ| - 0.5 connects κ to the total angular momentum, while the sign of κ encodes information about the orbital angular momentum. Specifically, l = |κ| - 1 for negative κ and l = κ for positive κ. However, the schema deliberately avoids automatic conversion between κ and (j, l) during normalization to prevent baking relativistic assumptions into the data representation.

Derived Properties and Recent Changes

Recent refactoring converted the quantum number symbols from stored quantities to computed properties. The symbols l_quantum_symbol, ml_quantum_symbol, and ms_quantum_symbol now derive automatically from their corresponding quantum numbers. Setting l_quantum_number = 1 causes l_quantum_symbol to return 'p', while l_quantum_number = 2 yields 'd'. The ml symbols map to directional labels like 'x', 'y', 'z' for p-orbitals or 'xy', 'xz', 'z^2', 'yz', 'x^2-y^2' for d-orbitals.

This change means that code attempting to set these symbol properties will fail silently. The constructor will accept them as keyword arguments but they have no effect. Users must instead set the quantum number values directly. The refactoring also converted j_quantum_number and mj_quantum_number from arrays to scalar values, eliminating the need for array indexing when accessing these quantities.

The _name property generates human-readable orbital labels by combining available quantum number information. A state with n=2 and l=1 produces "2p", while specifying ml=-1 yields "2px". When j is provided without ml, the format uses parentheses as in "2p(j=0.5)". This automatic naming proves useful for visualization and debugging but can be overridden by explicitly setting the name field on the parent ElectronicState.

Design Patterns and Usage Guidelines

The fundamental rule governing usage is that SphericalSymmetryState instances should never appear standalone at the atom level. They must always be wrapped in an ElectronicState container. At the AtomsState level, assign a single ElectronicState instance to the electronic_state field. This container then holds either a single quantum state descriptor in spin_orbit_state, a list of basis functions in basis_orbitals, or a hierarchy of finer-grained states in sub_states.

For a simple hydrogen atom, create an ElectronicState with a SphericalSymmetryState in its basis_orbitals list. For a transition metal with multiple d-orbitals, create a parent ElectronicState describing the d-manifold and populate its sub_states with child states for each orbital component. Each child inherits context from the parent, so specifying n=3 and l=2 at the parent level means children need only specify their ml values.

When dealing with correlated systems, the hierarchy may be minimal or absent entirely. A DMFT calculation of 3d electrons cannot decompose the many-body state into single-particle orbitals, so the electronic structure consists of a single ElectronicState with the manifold's quantum numbers and a fractional occupation reflecting the correlated nature. The absence of sub_states signals that further decomposition is not physically meaningful.

Validation and Normalization Behavior

The schema validates quantum number relationships during normalization. Setting ml outside the range [-l, l] triggers an error and prevents normalization from completing. Similarly, mj must satisfy -j ≤ mj ≤ j. The validation for κ and j consistency checks that j = |κ| - 0.5 within numerical tolerance, logging errors when this relationship fails.

However, normalization deliberately avoids automatic derivation of quantum numbers from relationships. A state with κ defined but j undefined will not populate j automatically. This design choice prevents the schema from imposing physical assumptions about relativistic effects or coupling schemes. Users requiring such conversions must call normalize_kappa_j_consistency() explicitly, typically in parser logic or analysis code rather than during standard normalization.

When name or degeneracy remain unset, normalization computes them from available quantum information. The degeneracy calculation considers whether projection quantum numbers are specified. For j without mj, the degeneracy equals 2j+1. For l without ml and no j information, the orbital degeneracy is 2l+1, optionally multiplied by spin degeneracy if ms is unspecified. When both ml and ms are defined, the degeneracy becomes 1 since the state is fully specified.

Hierarchical Decomposition Examples

Consider a copper atom's 3d electrons in a DFT calculation. Create an ElectronicState with n=3 and l=2 in its spin_orbit_state to represent the d-manifold. Add five child states for ml values -2, -1, 0, 1, 2, each labeled with the conventional d-orbital names dxy, dxz, dz², dyz, dx²-y². Each of these can further split into spin-up and spin-down components by adding children with ms=±0.5. This three-level hierarchy from manifold to orbital to spin matches the decomposition in typical DFT+U implementations.

For a system in an octahedral crystal field, the decomposition follows symmetry rather than pure angular momentum. Create child states labeled t2g and eg with appropriate symmetry labels and point group information. The t2g state has degeneracy 6 (three orbitals times two spins) while eg has degeneracy 4. This symmetry-adapted decomposition coexists with the angular momentum decomposition as alternative views of the same electronic structure, selected based on the physical question being addressed.

When parsing Wannier function output, create ElectronicState instances with the basis_orbitals field populated by the atomic orbitals used in the Wannierization. Each basis orbital is a SphericalSymmetryState with specific n, l, ml values. The expansion coefficients connecting Bloch states to Wannier functions reside in the band structure eigenvector arrays rather than in the state definition, maintaining clean separation between basis set definition and wavefunction coefficients.

Developer Notes

Additional contributor guidance is available under Contributor Guides > Overview.