# 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](../../contributor_guides/overview.md).
