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.

Migration from Earlier Schema Versions

Earlier versions of the schema allowed direct assignment of SphericalSymmetryState lists to a field called orbitals_state on AtomsState. This pattern is deprecated. The modern approach requires wrapping those states in an ElectronicState container and assigning to the electronic_state field instead. Parsers and analysis code using the old pattern must update to the new hierarchy.

The symbol-to-number conversion also requires attention during migration. Code that previously set l_quantum_symbol='p' must change to l_quantum_number=1. The symbol properties now serve only as read-only accessors for display and verification purposes. Any logic depending on symbols should be revised to work with quantum numbers directly.

Array-based quantum number access also breaks with recent changes. Code indexing into j_quantum_number[0] fails because the field is now scalar. Simply remove the indexing operation to access the value directly. Similarly, mj_quantum_number changed from variable-length array to scalar, eliminating the need to iterate over multiple mj values for a single state.

Technical Considerations

The quantization axis for ml symbols currently assumes a default Cartesian coordinate frame. The symbols 'x', 'y', 'z' for p-orbitals or 'xy', 'xz' for d-orbitals imply specific alignments with coordinate axes. In magnetic field or crystal field contexts, this axis should align with the field direction or principal crystal symmetry axes. Future development will add an explicit quantization_axis quantity similar to the axis field in NonCollinearSpinState, along with documentation clarifying that ml=0 corresponds to the z-direction while ml=±1 span the xy-plane.

The coupling scheme methods like _russell_saunders_j_values() and _jj_coupling() exist in the codebase but are not invoked during normalization. These helper functions support future search and matching operations where users might want to find all states compatible with specific coupling schemes. Calling them requires explicit invocation in analysis scripts rather than relying on automatic execution during data ingestion.

Projection quantum numbers cannot exist independently of their parent quantum numbers. While j, l, and s can be set independently when the others are unknown or not applicable, ml requires l to be defined, mj requires j, and ms requires s. This reflects the physical reality that projections are meaningless without the corresponding total angular momentum being specified first. Attempting to set only ml without l will pass validation at construction but fail during normalization with appropriate error messages.

Further Information

The complete implementation resides in atoms_state.py within the nomad_simulations.schema_packages module. Test cases in test_atoms_state.py demonstrate construction patterns and validation behavior. Integration with the tight-binding model method appears in model_method.py, where the TB.resolve_orbital_references() method shows how to extract orbital information from model systems. Property calculations reference electronic states through entity/orbital reference fields (like entity_ref or orbitals_state_ref) that point to ElectronicState instances. To access the parent AtomsState, use the get_parent_entity() helper method. This Pattern A architecture eliminates circular references while maintaining clean navigation through the hierarchy.

Users encountering issues or seeking clarification should consult the NOMAD forum at matsci.org, open issues on the GitHub repository, or refer to the main NOMAD documentation for broader context on schema design principles and the normalization system.