elfes.io.abacus

Read supported ABACUS calculations and numerical-orbital files.

AbacusReader accepts the directory of one completed ABACUS calculation, or the calculation's top-level INPUT file. The calculation must be a converged, periodic, single-point SCF. The reader resolves OUT.<suffix> from the top-level INPUT, then interprets the unique completed INPUT or INPUT.info snapshot and running_scf.log in that output directory. Compatibility is determined from the required file contents, not an ABACUS version string.

Calculation files

<calculation>/
├── INPUT
├── STRU
└── OUT.<suffix>/
    ├── INPUT or INPUT.info
    ├── running_scf.log
    ├── Hamiltonian CSR files          # requested by read_hamiltonian()
    ├── overlap CSR file               # requested by read_overlap()
    └── charge-density cube files      # requested by read_density()

read_geometry() uses INPUT spin settings together with STRU. Its optional magmoms contains the species defaults and per-atom overrides as collinear scalars or noncollinear Cartesian vectors in μB; nspin=1 omits it. These are the values declared by STRU, before any ABACUS internal all-zero autoset. read_ao_basis() requires basis_type=lcao and uses the shell layout reported by running_scf.log together with species information from STRU. The matrix methods additionally require gamma_only=0 and the real-space CSR files generated by out_mat_hs2:

data-HR-sparse_SPIN*.csr, data-SR-sparse_SPIN0.csr
hrs*_nao.csr, srs1_nao.csr

Each matrix method requires only its own files. Spinless, collinear, and noncollinear calculations with nspin=1, 2, and 4 are supported, including SOC Hamiltonians. The reader converts ABACUS units, AO ordering, real spherical harmonics, and spin packing into ELFES conventions. Hamiltonian and overlap are returned as Hermitian-half periodic HermBlockSparseOrbMatrix objects with their source cell shifts preserved.

read_density() accepts either PW or LCAO calculations and reads the final uniform-grid cube files. Depending on nspin, exactly one complete set must exist: SPIN1_CHG.cube through SPIN4_CHG.cube, or chg.cube and chgs1.cube through chgs4.cube. It returns positive electron density and, when present, Cartesian magnetization in electron Å\(^{-3}\) with 0, 0z, or 0xyz Pauli labels. Density trajectories and relax or MD output are not supported.

Standalone numerical orbitals

read_abacus_orbital() converts one ABACUS .orb file into a UniformNumericalAtomicBasis. The file must contain the standard uniform radial grid, shell multiplicities, and (l, n)-ordered radial blocks with exact zero tails. Radii and radial values are converted from Bohr-based units to ELFES Å units. Their source scale is preserved; the reader does not reproduce ABACUS's post-read normalization. An even active mesh receives one trailing zero knot for Simpson quadrature, matching ABACUS's own parity treatment while preserving the physical cutoff.

read_abacus_upf_soc() converts the separable spin-traceless part of a fully relativistic norm-conserving UPF into a uniform numerical spin-orbit potential. The initial implementation accepts the uniform radial meshes used by the SG15 fully relativistic library.

AbacusReader(path: StrPath)

read_hamiltonian() -> HermBlockSparseOrbMatrix

read_overlap() -> HermBlockSparseOrbMatrix

read_abacus_orbital(path: StrPath) -> UniformNumericalAtomicBasis

read_abacus_upf_soc(path: StrPath) -> UniformNumericalSpinOrbitPotential