PAOFLOW.DataController

Classes

DataController

Central data store and I/O manager for a PAOFLOW run.

Module Contents

class PAOFLOW.DataController.DataController(workpath, outputdir, inputfile, model, savedir, npool, smearing, save_overlaps, acbn0, sparse, sparse_threshold, verbose, restart, dft)

Central data store and I/O manager for a PAOFLOW run.

DataController owns every piece of data that flows through a PAOFLOW calculation. It is created once by PAOFLOW.PAOFLOW during initialisation and is passed by reference to every physics kernel. The class is responsible for four distinct concerns:

1. Data storage — two flat dictionaries, data_arrays and data_attributes, hold all intermediate results and configuration scalars respectively. Physics modules read and write these dicts directly via data_dicts().

2. Initialisation and DFT ingestion — reads the DFT output (QE data-file-schema.xml / data-file.xml or VASP vasprun.xml), optionally reads a PAOFLOW XML input file, or constructs a Hamiltonian from a tight-binding model. All data is populated on rank 0 and then broadcast to every MPI rank.

3. MPI communication — thin wrappers around mpi4py primitives for broadcasting arrays, lists, and scalar attributes from one rank to all others, and for scattering / gathering distributed arrays across the k-point pool decomposition.

4. File I/O — writes band structures, Hamiltonians, Fermi-surface files, k-point paths, and two-column data files to the output directory.

Data dictionaries

data_arraysdict

NumPy array payloads. Common keys (populated progressively as the calculation advances):

Key	Content
kpnts	k-points from the DFT calculation
kpnts_wght	BZ integration weights
a_vectors	Lattice vectors (rows, in units of alat)
tau	Atomic positions (crystal coordinates)
atoms	Atom species labels
species	(label, pseudopotential) pairs
shells	Angular-momentum shell list per species
U	PAO projection matrix ⟨φ|ψ_nk⟩
Sks	Overlap matrix S(k) (if save_overlaps=True)
Hks	k-space PAO Hamiltonian H(k)
HRs	Real-space PAO Hamiltonian H(R)
Hksp	Fourier-interpolated H(k) on the dense grid
E_k	Band eigenvalues (scattered across k-pool)
v_k	Band eigenvectors (scattered across k-pool)
pksp	Momentum matrix elements p(k)
dHksp	Gradient ∇_k H(k)
Sj	Spin operator matrix (3, nawf, nawf)
Efield	External electric field (3,) — default zeros
Bfield	External magnetic field (3,) — default zeros
HubbardU	On-site Hubbard-U corrections — default zeros
d_tensor	Dielectric tensor component indices
t_tensor	Transport tensor component indices
a_tensor	Anomalous Hall tensor component indices
s_tensor	Spin Hall tensor component indices

data_attributesdict

Scalar configuration values. Common keys:

Key	Content
nawf	Number of PAO basis functions
nbnds	Number of DFT bands
nspin	Number of spin channels (1 or 2)
nkpnts	Total number of k-points
nk1,nk2,nk3	k-grid dimensions
nelec	Number of electrons
natoms	Number of atoms in the unit cell
alat	Lattice parameter (Bohr)
omega	Unit-cell volume
npool	Number of k-point pools
smearing	Smearing type (None, 'm-p', 'gauss')
acbn0	Whether ACBN0 orthogonalisation is active
verbose	Verbosity flag
opath	Absolute path to the output directory
fpath	Absolute path to the DFT .save directory
abort_on_exception	Re-raise exceptions immediately if True

Parameters (constructor)

workpathstr

Path to the working directory.

outputdirstr

Name of the output sub-directory (created under workpath).

inputfilestr or None

Optional PAOFLOW XML input file.

modeldict or None

Tight-binding model specification; if provided, DFT input is ignored.

savedirstr or None

Path to the QE .save directory.

npoolint

Number of k-point pools for distributed memory execution.

smearingstr or None

BZ integration smearing type.

save_overlapsbool

Keep the overlap matrices Sks after Hamiltonian construction.

acbn0bool

Activate ACBN0 orthogonalisation.

verbosebool

Enable debugging output.

restartbool

Skip initialisation (data will be loaded from a dump file).

dftstr

DFT back-end: 'QE' or 'VASP'.

Methods — data access

data_dicts()

Return (data_arrays, data_attributes) as a 2-tuple.

print_data()

Print all keys in both data dictionaries (rank 0 only).

Methods — initialisation helpers

add_default_arrays()

Pre-populate data_arrays with zero-valued field arrays and full-tensor component index arrays.

read_pao_inputfile()

Parse a PAOFLOW XML input file into data_attributes.

read_qe_output()

Parse data-file-schema.xml or data-file.xml from a QE .save directory.

read_vasp_output(symprec)

Parse vasprun.xml from a VASP calculation.

build_arrays_adhoc_soc()

Construct naw (orbital counts per atom) and orb_pseudo (orbital character labels) required for the ad-hoc spin-orbit coupling routines.

Methods — MPI communication

broadcast_single_array(key, dtype, root)

Broadcast a NumPy array stored at data_arrays[key] from root to all ranks using MPI.Bcast.

broadcast_single_list(key, root)

Broadcast a Python list stored at data_arrays[key].

broadcast_attribute(key, root)

Broadcast a scalar stored at data_attributes[key].

scatter_data_array(key)

Scatter data_arrays[key] across ranks along the first axis.

gather_data_array(key)

Gather a distributed array back to rank 0.

Methods — file output

write_bands(fname, bands)

Write per-spin band structure files <fname>_<ispin>.dat.

write_bxsf(fname, bands, nbnd, indices)

Write Fermi-surface data in .bxsf format (for XCrysDen / SKEAF).

write_HRs(fname)

Write the real-space Hamiltonian in the Wannier90 / Z2Pack _hr.dat format.

write_Hk_acbn0()

Write H(k), S(k), k-points, and weights to files for ACBN0 post-processing (binary .npy or plain text).

write_file_row_col(fname, col1, col2)

Write a two-column plain-text data file.

write_kpnts_path(fname, path, kpnts, b_vectors)

Write the k-point path in Cartesian reciprocal coordinates.

Notes

• Only rank 0 reads and populates the dictionaries; all other ranks receive the data via MPI.bcast at the end of __init__.

• The error_handler attribute holds an ErrorHandler instance; report_exception is a convenience alias for its report_exception method, used throughout the PAOFLOW codebase to format and print stack traces without aborting unless abort_on_exception is set.

comm

rank

size

error_handler

report_exception

data_dicts()

Get the data dictionaries

Arguments:

None

Returns:

(arrays, attributes): Tuple of two dictionaries, data_arrays and data_attributes

print_data()

Print the data dictionary keys

Arguments:

None

Returns:

None

build_arrays_adhoc_soc()

Construc arrays needed for the adhoc_spin_orbit routine

Arguments:

None

Returns:

None

add_default_arrays()

read_pao_inputfile()

read_qe_output()

read_vasp_output(symprec)

write_file_row_col(fname, col1, col2)

Write a file with 2 columns

Arguments:

fname (str): Name of the file (written to outputdir) col1 (ndarray): 1D array of values for the rightmost column col2 (ndarray): 1D array of values for the leftmost column

Returns:

None

write_bxsf(fname, bands, nbnd, indices=None)

Write a file in the bxsf format

Arguments:

fname (str): Name of the file (written to outputdir) bands (ndarray): The data array of values to be written nbnd (int): Number of values from array to write

Returns:

None

write_bands(fname, bands)

Write electronic band structure file

Arguments:

fname (str): Name of the file (written to outputdir) bands (ndarray): Band data array (shape: (nk,nbnd,nspin))

Returns:

None

write_kpnts_path(fname, path, kpnts, b_vectors)

Write the k-path through the BZ

Arguments:

fname (str): Name of the file (written to outputdir) kpnts (ndarray): k-point path (shape: (3,nk))

Returns:

None

write_Hk_acbn0()

write_HRs(fname)

Write HRs in the Z2 Pack format

Arguments:

fname (str): Name of the file (written to outputdir)

Returns:

None

broadcast_single_list(key, root=0)

Broadcast list from ‘data_array’ with ‘key’ from ‘root’ to all other ranks

Arguments:

key (str): The key for the attribute to broadcast (key must exist in dictionary ‘data_attributes’) root (int): The rank which is the source of the broadcasted attribut

Returns:

None

broadcast_attribute(key, root=0)

Broadcast attribute from ‘data_attributes’ with ‘key’ from ‘root’ to all other ranks

Arguments:

key (str): The key for the attribute to broadcast (key must exist in dictionary ‘data_attributes’) root (int): The rank which is the source of the broadcasted attribut

Returns:

None

broadcast_single_array(key, dtype=complex, root=0)

Broadcast array from ‘data_arrays’ with ‘key’ from ‘root’ to all other ranks

Arguments:

key (str): The key for the array to broadcast (key must exist in dictionary ‘data_arrays’) dtype (dtype): The data type of the array to broadcast root (int): The rank which is the source of the broadcasted array

Returns:

None

broadcast_data_attributes()

broadcast_data_arrays()

scatter_data_array(key)

gather_data_array(key)