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
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#
|
Map every PAO basis index onto the atom and orbital it represents. |
|
Largest bond length representable on the FFT supercell without wrapping. |
|
Infer the sign of |
|
Collect the distinct neighbour-shell distances (the star) of the lattice. |
|
Truncate |
|
Write a truncated Hamiltonian bundle to a compressed |
|
Read a bundle written by |
|
Scatter a sparse bond list back onto the dense FFT real-space grid. |
|
Repopulate a |
|
Expand the stored bonds into fully labelled records. |
Module Contents#
- 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 (bothprojectionsandread_atomic_proj_QEpopulate it). Orbital names follow the Quantum-ESPRESSO real-harmonic order,QE_ORBITAL_LABELS_BY_L.- Parameters:
data_controller (DataController) – Must carry
nawfandtau. The orbital identity is read frombasis, falling back to a species-keyedshellsdictionary.- 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') andorbital_shell(str, e.g.'3P') — each of lengthnawf— plusatom_block_startandorbitals_per_atom.- Return type:
- Raises:
RuntimeError – If the controller holds a tight-binding model rather than a QE projection, or if no description expands to exactly
nawforbitals.
- 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:
- PAOFLOW.hamiltonian.sparse_hamiltonian.detect_bond_sign(hamiltonian_real_space, atomic_positions, lattice_vectors, orbital_atom)[source]#
Infer the sign of
Rin 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) –
HRswith 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:
+1or-1: the value ofsind = tau_B + s*R - tau_A.- Return type:
- 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
HRsto the bonds inside a neighbour-shell cutoff.- Parameters:
data_controller (DataController) – Must carry
HRs(i.e.pao_hamiltonianhas run), plus the geometry arraysa_vectors,tauandatoms.bond_order (int) – Keep bonds up to and including this neighbour shell.
1is nearest neighbours. Ignored whenr_cutis 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
0to 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
Rin the bond vectortau_B + s*R - tau_A.'auto'infers it withdetect_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 arraysbond_row,bond_col,bond_translation,bond_value,bond_distanceandbond_shell.- Return type:
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
.npzarchive.- Parameters:
data_controller (DataController) – Source of the run metadata stored alongside the bonds.
bundle (dict) – Output of
sparsify_real_space_hamiltonian().fname (str) – Destination path. Relative names resolve inside the output directory.
- Returns:
The path that was written.
- Return type:
Notes
Metadata is stored as JSON text rather than a pickled object so that loading never needs
allow_pickleand 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
.npzarchive.- Returns:
Arrays as stored, plus the decoded
metadatadictionary and the scalars promoted to top level (nawf,nspin,alat, …).- Return type:
- 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()orsparsify_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
DataControllerso the standard pipeline can run.- Parameters:
data_controller (DataController) – Target container; its arrays and attributes are overwritten with the saved run metadata and the rebuilt
HRs.bundle (dict) – Output of
read_sparse_hamiltonian().
- 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()orsparsify_real_space_hamiltonian().- Returns:
Column-oriented table of length
n_bondswith keysatom_i,atom_j,species_i,species_j,orbital_i,orbital_j,l_i,l_j,translation,bond_vector(Bohr),distance(Bohr),shellandvalue(shape(n_bonds, nspin)).- Return type:
dict of np.ndarray