PAOFLOW.pyskeaf.io_bxsf

BXSF (XCrysDen Band-XSF) file reader for PAOFLOW.pyskeaf.

Implements the validation rules of the Fortran subroutine preadbxsf in skeaf_v1p3p0_r149.F90 (lines 2873–3067):

• Single-band files only (multi-band BXSFs must be split first).

• Reciprocal-lattice origin must be (0, 0, 0).

• Number of energies in the data block must equal nx * ny * nz.

• Reject obvious “periodic-grid” BXSFs (ELK / exciting style) where the energy at the corner E[nx,ny,nz] equals E[1,1,1]; these need to be converted to the General Grid before SKEAF can consume them.

Reciprocal-lattice vectors in BXSF files are in units of (atomic units)^-1 without the factor of 2π. We expose two views:

• recip_au — exactly as read from the file, units of a.u.^-1.

• recip_ang — converted to Å^-1 with the 2π factor included, i.e. recip_ang = 2π · recip_au / CONV_AU_TO_ANG. This matches the plr* arrays in the Fortran source and is the form used by all downstream SKEAF computations (areas in Å^-2 → frequencies in kT).

Exceptions

BXSFError

Raised when a BXSF file fails SKEAF's validation rules.

Classes

BXSFData

Parsed contents of a BXSF (XCrysDen Band-XSF) file.

Functions

read_bxsf(path)	Read a single-band BXSF file and return a BXSFData.
write_bxsf(path, data, *[, fermi_energy, band_label])	Write data back to a BXSF file (round-trip helper for tests).

Module Contents

exception PAOFLOW.pyskeaf.io_bxsf.BXSFError

Bases: ValueError

Raised when a BXSF file fails SKEAF’s validation rules.

class PAOFLOW.pyskeaf.io_bxsf.BXSFData

Parsed contents of a BXSF (XCrysDen Band-XSF) file.

Variables:

• filename (str) – Path the data was read from (informational; used in output headers).

• fermi_energy (float) – Fermi energy in Rydbergs, as written in the file’s BEGIN_INFO block.

• nz (nx, ny,) – Grid dimensions (number of k-points along each reciprocal lattice direction). Indexing in this package is 0-based; the Fortran code uses 1-based indexing.

• recip_au (np.ndarray, shape (3, 3)) – Reciprocal lattice vectors as stored in the BXSF file (a.u.^-1, no 2π factor). recip_au[i] is the i-th vector.

• recip_ang (np.ndarray, shape (3, 3)) – Reciprocal lattice vectors converted to Å^-1, with the 2π factor. Computed as 2π · recip_au / CONV_AU_TO_ANG — matches the Fortran plrx*/plry*/plrz* variables that drive the area→frequency conversion.

• energies (np.ndarray, shape (nx, ny, nz)) – Band energies in Rydbergs. Stored in C-contiguous order with the third index varying fastest (the BXSF “General Grid” convention, matching masterkarray(i,j,k) in Fortran).

filename: str

fermi_energy: float

nx: int

ny: int

nz: int

recip_au: numpy.ndarray

recip_ang: numpy.ndarray

energies: numpy.ndarray

origin_au: numpy.ndarray

property num_kpoints: int

PAOFLOW.pyskeaf.io_bxsf.read_bxsf(path)

Read a single-band BXSF file and return a BXSFData.

Parameters:

path (str or Path) – Path to the BXSF file.

Raises:

• BXSFError – If the file fails any of the validation checks copied from preadbxsf (multi-band, non-zero origin, count mismatch, periodic-grid layout, grid too small, etc.).

• FileNotFoundError – If path does not exist.

PAOFLOW.pyskeaf.io_bxsf.write_bxsf(path, data, *, fermi_energy=None, band_label='band_energies')

Write data back to a BXSF file (round-trip helper for tests).

The output format mirrors the Fortran-generated style (six energies per line, %.6E formatting). Mainly intended for round-trip tests; the SKEAF Python port itself never needs to produce BXSFs.