Electronic Structure Properties¶

Purpose: Electronic eigenvalues, band structures, DOS, band gaps, molecular orbitals, occupancies, and Fermi surfaces

Relationship map¶

Hold "Alt" / "Option" to enable pan & zoom

classDiagram
    class BaseElectronicEigenvalues
    class DOSProfile
    class ElectronicBandGap
    class ElectronicBandStructure
    class ElectronicDensityOfStates
    class ElectronicEigenvalues
    class Energy2
    class FermiSurface
    class MolecularOrbitals
    class Occupancy
    ElectronicEigenvalues <|-- ElectronicBandStructure
    DOSProfile <|-- ElectronicDensityOfStates
    BaseElectronicEigenvalues <|-- ElectronicEigenvalues
    DOSProfile *-- Energy2 : energies
    ElectronicDensityOfStates *-- DOSProfile : projected_dos
    ElectronicDensityOfStates *-- Energy2 : energies
    ElectronicEigenvalues *-- BaseElectronicEigenvalues : contributions

Legend

inheritance (is-a)

composition (has-a)

Quantities by Key Sections¶

`BaseElectronicEigenvalues`¶

Section	Description	MetaInfo
`BaseElectronicEigenvalues`	A base section used to define basic quantities for the `ElectronicEigenvalues` and `ElectronicBandStructure` properties.	Open in MetaInfo browser

Quantity	Type	Description
`n_levels`	m_int32(int32)	Number of energy levels per sampling point. Number of energy levels per sampling point. In periodic systems these correspond to electronic bands; in molecular calculations they correspond to (spin-resolved) molecular orbitals or similar one-particle states.
`value`	m_float64(float64) (shape: ['', ''])	Value of the electronic eigenvalues.

`ElectronicEigenvalues`¶

Section	Description	MetaInfo
`ElectronicEigenvalues`		Open in MetaInfo browser

Quantity	Type	Description
`spin_channel`	m_int32(int32)	Spin channel of the corresponding electronic eigenvalues. It can take values of 0 or 1.
`occupation`	m_float64(float64) (shape: ['*', 'n_levels'])	Occupation of the electronic eigenvalues. Occupation of the electronic eigenvalues. This is a number depending whether the `spin_channel` has been set or not. If `spin_channel` is set, then this number is between 0 and 1, where 0 means that the state is unoccupied and 1 means that the state is fully occupied; if `spin_channel` is not set, then this number is between 0 and 2. The shape of this quantity is defined as `[K.n_points, K.dimensionality, n_levels]`, where `K` is a `variable` which can be `KMesh` or `KLinePath`, depending whether the simulation mapped the whole Brillouin zone or just a specific path.
`highest_occupied`	m_float64(float64)	Highest occupied electronic eigenvalue. Together with `lowest_unoccupied`, it defines the electronic band gap.
`lowest_unoccupied`	m_float64(float64)	Lowest unoccupied electronic eigenvalue. Together with `highest_occupied`, it defines the electronic band gap.

`ElectronicBandStructure`¶

Section	Description	MetaInfo
`ElectronicBandStructure`	Accessible energies by the charges (electrons and holes) in the reciprocal space.	Open in MetaInfo browser

Quantity	Type	Description
`reciprocal_cell`	QuantityReference	Reciprocal lattice vectors associated with the k-space sampling used for these eigenvalues, taken from the corresponding `KSpace` numerical settings.

`MolecularOrbitals`¶

Section	Description	MetaInfo
`MolecularOrbitals`	Molecular-orbital eigenstates in an atom-centered AO basis.	Open in MetaInfo browser

Quantity	Type	Description
`n_mo`	m_int_bounded(int)	Number of molecular orbitals.
`value`	m_float64(float64) (shape: ['n_mo'])	Orbital energies (eigenvalues) for each molecular orbital, mirroring `ElectronicEigenvalues.value`. Defined only for `kind=canonical`; may be absent for natural/localized orbitals.
`occupations`	m_float_bounded(float64) (shape: ['n_mo'])	Occupation number for each molecular orbital. Occupation number for each molecular orbital. Expected in [0, 2] (spin-summed; [0, 1] for spin orbitals). Occupation numbers from approximate methods (e.g. MP2/CC natural orbitals) can fall slightly outside; values beyond the `mo_occupation_slack` tolerance are logged, and out-of-[0, 2] values are clamped into [0, 2].
`spin_channel`	m_int32(int32)	Spin channel of the molecular orbitals: 0 for α-spin, 1 for β-spin.
`n_ao`	m_int_bounded(int)	Number of atomic orbitals (size of the AO basis).
`basis_set_ref`	Reference	Reference to the atom-centered basis set used to expand these orbitals.
`coefficients`	HDF5Dataset	The AO→MO coefficient matrix C, such that The AO→MO coefficient matrix C, such that ψ_i(r) = ∑_μ C[i,μ] φ_μ(r). Row index i runs over MOs (`n_mo`), column index μ runs over AOs (`n_ao`). Expected dataset shape: [`n_mo`, `n_ao`].
`coefficients_im`	HDF5Dataset	Imaginary component of the AO→MO coefficient matrix. Imaginary component of the AO→MO coefficient matrix. Combine with `coefficients` to obtain the full complex matrix: C_complex = coefficients + 1j * coefficients_im Omit for strictly real wave functions (non-relativistic calculations without complex basis functions). Expected dataset shape: [`n_mo`, `n_ao`].
`role`	Enum (shape: ['n_mo'])	Role of each MO within a correlated calculation or active-space protocol: Role of each MO within a correlated calculation or active-space protocol: core: fully occupied, energy-frozen, excluded from correlation. inactive: fully occupied, variationally optimized, outside the active space. active: in the active space. virtual: unoccupied correlated orbital. * deleted: pruned for technical reasons (e.g. linear dependence). `role` is the active-space/correlation classification, orthogonal to `occupations`.
`symmetry`	m_str(str) (shape: ['n_mo'])	Symmetry label of each MO in the molecule's point group (e.g. a₁, b₂u, π_g). Leave empty for systems with no detected symmetry.
`kind`	Enum	Classification of the orbital set by the transformation that defines it: Classification of the orbital set by the transformation that defines it: canonical : standard SCF eigenfunctions (Fock/Kohn-Sham diagonal) natural : eigenfunctions of the 1-RDM * localized : after a localization transform (Boys, Pipek-Mezey, …) For MCSCF/CASSCF outputs, tag the reported set as `canonical` or `natural` (whichever it is); the active-space partition is captured by `role`.
`homo_parsed`	m_float64(float64)	Highest occupied molecular orbital (HOMO) energy as reported by the code.
`lumo_parsed`	m_float64(float64)	Lowest unoccupied molecular orbital (LUMO) energy as reported by the code.
`homo_lumo_gap_parsed`	m_float64(float64)	HOMO-LUMO gap as directly reported by the code. Strictly a parsed value, not derived from `homo_parsed`/`lumo_parsed`. Leave unset if the code reports no gap directly.
`homo_normalized`	m_float64(float64)	Highest occupied molecular orbital (HOMO) energy, derived purely from `value` and `occupations` for `kind=canonical`. Left unset when the occupied/unoccupied boundary cannot be resolved; does not fall back to `homo_parsed`.
`lumo_normalized`	m_float64(float64)	Lowest unoccupied molecular orbital (LUMO) energy, derived purely from `value` and `occupations` for `kind=canonical`. Left unset when the occupied/unoccupied boundary cannot be resolved; does not fall back to `lumo_parsed`.
`homo_lumo_gap_normalized`	m_float64(float64)	HOMO-LUMO gap of the derived frontier pair, taken as `lumo_normalized - homo_normalized`. Left unset when that pair is unavailable; does not fall back to `homo_lumo_gap_parsed`.

`ElectronicBandGap`¶

Section	Description	MetaInfo
`ElectronicBandGap`	Energy difference between the highest occupied electronic state and the lowest unoccupied electronic state.	Open in MetaInfo browser

Quantity	Type	Description
`type`	Enum	Type categorization of the electronic band gap. This quantity is directly related with `momentum_transfer` as by definition, the electronic band gap is `'direct'` for zero momentum transfer (or if `momentum_transfer` is `None`) and `'indirect'` for finite momentum transfer.
`momentum_transfer`	m_float64(float64) (shape: [2, 3])	If the electronic band gap is `'indirect'`, the reciprocal momentum transfer for... If the electronic band gap is `'indirect'`, the reciprocal momentum transfer for which the band gap is defined in units of the `reciprocal_lattice_vectors`. The initial and final momentum 3D vectors are given in the first and second element. Example, the momentum transfer in bulk Si2 happens between the Γ and the (approximately) X points in the Brillouin zone; thus: `momentum_transfer = [[0, 0, 0], [0.5, 0.5, 0]]`. Note: this quantity only refers to scalar `value`, not to arrays of `value`.
`spin_channel`	m_int32(int32)	Spin channel of the corresponding electronic band gap. It can take values of 0 or 1.
`value`	m_float_bounded(float)	The value of the electronic band gap. This value must be positive.

`DOSProfile`¶

Section	Description	MetaInfo
`DOSProfile`	A base section used to define the `value` of the `ElectronicDensityOfState` property.	Open in MetaInfo browser

Quantity	Type	Description
`value`	m_float_bounded(float) (shape: ['*'])	The value of the electronic DOS. Must be positive.

`ElectronicDensityOfStates`¶

Section	Description	MetaInfo
`ElectronicDensityOfStates`	Number of electronic states accessible for the charges per energy and per volume.	Open in MetaInfo browser

Quantity	Type	Description
`spin_channel`	m_int32(int32)	Spin channel of the corresponding electronic DOS. It can take values of 0 or 1.
`energies_origin`	m_float64(float64)	Energy level denoting the origin along the energy axis, used for comparison and visualization. Energy level denoting the origin along the energy axis, used for comparison and visualization. This value is fully derived during normalization from the sibling `ElectronicEigenvalues.highest_occupied` (when a resolvable reference is available), so parsers are recommended NOT to populate it directly: any manually set value is recomputed and overwritten on normalization without any logging. Provide `ElectronicEigenvalues.highest_occupied` instead.
`normalization_factor`	m_float64(float64)	Normalization factor for electronic DOS to get a cell-independent intensive DOS. The cell-independent intensive DOS is as the integral from the lowest (most negative) energy to the Fermi level for a neutrally charged system (i.e., the sum of `AtomsState.charge` is zero).

`Occupancy`¶

Section	Description	MetaInfo
`Occupancy`	Electrons occupancy of an atom per orbital and spin.	Open in MetaInfo browser

Quantity	Type	Description
`orbitals_state_ref`	Reference	Reference to the `ElectronicState` section in which the occupancy is calculated. This can reference individual orbitals, orbital manifolds, or hybrid/molecular orbitals. The parent AtomsState can be accessed via `orbitals_state_ref.get_parent_entity()`.
`spin_channel`	m_int32(int32)	Spin channel of the corresponding electronic property. It can take values of 0 and 1.
`value`	m_float64(float64)	Value of the electronic occupancy for the orbital defined by `orbitals_state_ref`. Value of the electronic occupancy for the orbital defined by `orbitals_state_ref`. If `spin_channel` is set, then this number is between 0 and 1, where 0 means that the state is unoccupied and 1 means that the state is fully occupied; if `spin_channel` is not set, then this number is between 0 and 2.

`FermiSurface`¶

Section	Description	MetaInfo
`FermiSurface`	Energy boundary in reciprocal space that separates the filled and empty electronic states in a metal.	Open in MetaInfo browser

Quantity	Type	Description
`n_bands`	m_int32(int32)	Number of bands / eigenvalues.

Electronic Structure Properties¶

Relationship map¶

Quantities by Key Sections¶

BaseElectronicEigenvalues¶

ElectronicEigenvalues¶

ElectronicBandStructure¶

MolecularOrbitals¶

ElectronicBandGap¶

DOSProfile¶

ElectronicDensityOfStates¶

Occupancy¶

FermiSurface¶