PAOFLOW.hamiltonian.sparse_hamiltonian#

Sparse real-space PAO Hamiltonian: truncation, storage and restoration.

After the projection step the real-space Hamiltonian HRs is a dense array of shape (nawf, nawf, nk1, nk2, nk3, nspin). Most of its content is numerical noise: the PAO Hamiltonian decays quickly with the bond length, so only matrix elements connecting orbitals on atoms that are close neighbours carry physical weight.

This module truncates HRs to a sparse bond list using a star (neighbour shell) criterion, stores it together with everything needed to reproduce a PAOFLOW run, and rebuilds the dense array on load.

The bond that carries the matrix element \(H_{\mu\nu}(\mathbf{R})\) is

\[\mathbf{d} = \boldsymbol{\tau}_B - \mathbf{R} - \boldsymbol{\tau}_A\]

where \(\mu\) sits on atom \(A\) and \(\nu\) on atom \(B\). The sign of \(\mathbf{R}\) follows PAOFLOW’s own transform \(H(\mathbf{k}) = \sum_R H(\mathbf{R})\, e^{-2\pi i \mathbf{k}\cdot\mathbf{R}}\) (Hks = fftn(HRs)). A bond is retained when \(|\mathbf{d}|\) lies within the requested neighbour shell.

Every stored matrix element is tagged with the atoms, species and orbital labels it connects, so the saved bundle doubles as a labelled dataset for fitting Hamiltonian matrix elements directly.

The storage layout (flat COO arrays of row, column, lattice translation and value) mirrors PAOFLOW.spectrum.sparse_bands.SparseEDTB. Note that SparseEDTB assembles \(H(\mathbf{k})\) with \(e^{+2\pi i \mathbf{k}\cdot\mathbf{R}}\), so reusing these bonds there requires negating bond_translation.

Attributes#

Functions#

build_orbital_basis_table(data_controller)

Map every PAO basis index onto the atom and orbital it represents.

aliasing_safe_radius(lattice_vectors, grid_shape)

Largest bond length representable on the FFT supercell without wrapping.

detect_bond_sign(hamiltonian_real_space, ...)

Infer the sign of R in the bond vector from the Hamiltonian itself.

compute_star_shells(atomic_positions, lattice_vectors, ...)

Collect the distinct neighbour-shell distances (the star) of the lattice.

sparsify_real_space_hamiltonian(data_controller[, ...])

Truncate HRs to the bonds inside a neighbour-shell cutoff.

write_sparse_hamiltonian(data_controller, bundle, fname)

Write a truncated Hamiltonian bundle to a compressed .npz archive.

read_sparse_hamiltonian(fname)

Read a bundle written by write_sparse_hamiltonian().

rebuild_HRs_from_sparse(bundle)

Scatter a sparse bond list back onto the dense FFT real-space grid.

restore_data_controller(data_controller, bundle)

Repopulate a DataController so the standard pipeline can run.

bond_table(bundle)

Expand the stored bonds into fully labelled records.

Module Contents#

PAOFLOW.hamiltonian.sparse_hamiltonian.SPARSE_HAMILTONIAN_FORMAT_VERSION = 1[source]#
PAOFLOW.hamiltonian.sparse_hamiltonian.QE_ORBITAL_LABELS_BY_L[source]#
PAOFLOW.hamiltonian.sparse_hamiltonian.build_orbital_basis_table(data_controller)[source]#

Map every PAO basis index onto the atom and orbital it represents.

Targets the QE-PAOFLOW projection pipeline, where arry['basis'] carries the authoritative per-orbital records (both projections and read_atomic_proj_QE populate it). Orbital names follow the Quantum-ESPRESSO real-harmonic order, QE_ORBITAL_LABELS_BY_L.

Parameters:

data_controller (DataController) – Must carry nawf and tau. The orbital identity is read from basis, falling back to a species-keyed shells dictionary.

Returns:

orbital_atom (int, atom index), orbital_species (str), orbital_l (int), orbital_m (int, 1-based within the shell), orbital_label (str, e.g. 'px') and orbital_shell (str, e.g. '3P') — each of length nawf — plus atom_block_start and orbitals_per_atom.

Return type:

dict

Raises:

RuntimeError – If the controller holds a tight-binding model rather than a QE projection, or if no description expands to exactly nawf orbitals.

PAOFLOW.hamiltonian.sparse_hamiltonian.aliasing_safe_radius(lattice_vectors, grid_shape)[source]#

Largest bond length representable on the FFT supercell without wrapping.

Parameters:
  • lattice_vectors (np.ndarray, shape (3, 3)) – Primitive lattice vectors in Bohr (rows).

  • grid_shape (sequence of int) – The (nk1, nk2, nk3) Monkhorst-Pack grid, i.e. the supercell repeat.

Returns:

Inradius of the supercell in Bohr. Bonds longer than this fold back onto the same FFT cell as a shorter bond and cannot be distinguished.

Return type:

float

PAOFLOW.hamiltonian.sparse_hamiltonian.detect_bond_sign(hamiltonian_real_space, atomic_positions, lattice_vectors, orbital_atom)[source]#

Infer the sign of R in the bond vector from the Hamiltonian itself.

A physical hopping decays with the bond length, so the correct sign is the one that concentrates the weight of \(|H(\mathbf{R})|\) at short bonds.

Parameters:
  • hamiltonian_real_space (np.ndarray) – HRs with shape (nawf, nawf, nk1, nk2, nk3, nspin).

  • atomic_positions (np.ndarray, shape (natoms, 3)) – Cartesian positions in Bohr.

  • lattice_vectors (np.ndarray, shape (3, 3)) – Primitive lattice vectors in Bohr (rows).

  • orbital_atom (np.ndarray, shape (nawf,)) – Atom index of each orbital.

Returns:

+1 or -1: the value of s in d = tau_B + s*R - tau_A.

Return type:

int

PAOFLOW.hamiltonian.sparse_hamiltonian.compute_star_shells(atomic_positions, lattice_vectors, grid_shape, max_radius=None, distance_tol=0.001)[source]#

Collect the distinct neighbour-shell distances (the star) of the lattice.

Only distances that the FFT supercell can represent unambiguously are considered, so the returned shells are exactly those addressable in HRs.

Parameters:
  • atomic_positions (np.ndarray, shape (natoms, 3)) – Cartesian atomic positions in Bohr.

  • lattice_vectors (np.ndarray, shape (3, 3)) – Primitive lattice vectors in Bohr (rows).

  • grid_shape (sequence of int) – (nk1, nk2, nk3).

  • max_radius (float, optional) – Search cutoff in Bohr. Defaults to aliasing_safe_radius().

  • distance_tol (float) – Distances closer than this are merged into a single shell (Bohr).

Returns:

Sorted shell distances, excluding the on-site distance (zero).

Return type:

np.ndarray, 1-D, float

PAOFLOW.hamiltonian.sparse_hamiltonian.sparsify_real_space_hamiltonian(data_controller, bond_order=3, r_cut=None, magnitude_tol=1e-08, distance_tol=0.001, bond_sign='auto', verbose=False)[source]#

Truncate HRs to the bonds inside a neighbour-shell cutoff.

Parameters:
  • data_controller (DataController) – Must carry HRs (i.e. pao_hamiltonian has run), plus the geometry arrays a_vectors, tau and atoms.

  • bond_order (int) – Keep bonds up to and including this neighbour shell. 1 is nearest neighbours. Ignored when r_cut is given.

  • r_cut (float, optional) – Explicit bond-length cutoff in Bohr, overriding bond_order.

  • magnitude_tol (float) – Drop matrix elements whose magnitude is below this value in every spin channel. Set to 0 to keep the full blocks.

  • distance_tol (float) – Tolerance used to merge neighbour shells and to detect on-site terms.

  • bond_sign ({'auto', 1, -1}) – Sign of R in the bond vector tau_B + s*R - tau_A. 'auto' infers it with detect_bond_sign(), which is the safe choice: the projection path and the model builders disagree on this convention.

  • verbose (bool) – Report the retained fraction.

Returns:

The bundle consumed by write_sparse_hamiltonian(). Bond data is held in the flat COO arrays bond_row, bond_col, bond_translation, bond_value, bond_distance and bond_shell.

Return type:

dict

Notes

A bond longer than aliasing_safe_radius() cannot be distinguished from its periodic image on the (nk1, nk2, nk3) grid; requesting such a cutoff raises rather than silently storing an aliased Hamiltonian.

PAOFLOW.hamiltonian.sparse_hamiltonian.write_sparse_hamiltonian(data_controller, bundle, fname)[source]#

Write a truncated Hamiltonian bundle to a compressed .npz archive.

Parameters:
Returns:

The path that was written.

Return type:

str

Notes

Metadata is stored as JSON text rather than a pickled object so that loading never needs allow_pickle and cannot execute code from an untrusted file.

PAOFLOW.hamiltonian.sparse_hamiltonian.read_sparse_hamiltonian(fname)[source]#

Read a bundle written by write_sparse_hamiltonian().

Parameters:

fname (str) – Path to the .npz archive.

Returns:

Arrays as stored, plus the decoded metadata dictionary and the scalars promoted to top level (nawf, nspin, alat, …).

Return type:

dict

Raises:

ValueError – If the archive was written by an incompatible format version.

PAOFLOW.hamiltonian.sparse_hamiltonian.rebuild_HRs_from_sparse(bundle)[source]#

Scatter a sparse bond list back onto the dense FFT real-space grid.

Parameters:

bundle (dict) – Output of read_sparse_hamiltonian() or sparsify_real_space_hamiltonian().

Returns:

The truncated real-space Hamiltonian. Elements outside the stored bonds are exactly zero.

Return type:

np.ndarray, shape (nawf, nawf, nk1, nk2, nk3, nspin), complex

PAOFLOW.hamiltonian.sparse_hamiltonian.restore_data_controller(data_controller, bundle)[source]#

Repopulate a DataController so the standard pipeline can run.

Parameters:
Returns:

Populates HRs, the geometry arrays, the orbital map and the real- and k-space FFT grids.

Return type:

None

Notes

Attributes describing where this session runs (working and output paths, pool count, verbosity) are kept from the live controller when present, so a restored run writes to its own output directory rather than the one recorded in the archive.

PAOFLOW.hamiltonian.sparse_hamiltonian.bond_table(bundle)[source]#

Expand the stored bonds into fully labelled records.

Every retained matrix element becomes one row carrying the atoms, species and orbital names it connects — the form consumed by a matrix-element fit.

Parameters:

bundle (dict) – Output of read_sparse_hamiltonian() or sparsify_real_space_hamiltonian().

Returns:

Column-oriented table of length n_bonds with keys atom_i, atom_j, species_i, species_j, orbital_i, orbital_j, l_i, l_j, translation, bond_vector (Bohr), distance (Bohr), shell and value (shape (n_bonds, nspin)).

Return type:

dict of np.ndarray