pythtb.WFArray#

class WFArray(lattice, mesh, nstates=None, spinful=False)[source]#

Wavefunction container defined on a sampling mesh.

A WFArray stores states on a discrete mesh of k-points and/or adiabatic parameters \(\lambda\). Once populated, it can be queried for Berry connections, Berry curvature, Chern numbers, and other derived quantities, or passed to Wannier when constructing Wannier functions or obtaining smooth gauges from the projection method.

The underlying Mesh may represent a full Monkhorst-Pack grid, a lower-dimensional path, or even a mesh that contains only parameter axes. In every case, WFArray tracks the mesh layout, the stored states, and the necessary phase conventions so downstream utilities can consume the data consistently.

Wavefunctions stored in a WFArray can be the Hamiltonian eigenstates generated by solve_model(), or any other Mesh-defined states in the orbital basis of the underlying Lattice that match spinful setting. Use set_states() for bulk assignments, or the [...] indexer to update the states at an individual mesh point. Periodic boundary conditions are enforced automatically on assignment.

Parameters:

latticeLattice: Lattice structure with orbital positions, periodic directions, and lattice vectors. Use model.lattice to keep it consistent with a TBModel.
meshMesh: Sampling grid in k/parameter space. Build it before constructing the WFArray. Its axes set the topology for enforcing periodic boundary conditions.
spinfulbool, optional: Whether the model includes spin degrees of freedom (defaults to False). If True, each orbital stores two spin components. This affects the shape of the stored wavefunction array.
nstatesint, optional: Number of bands per mesh point to store (defaults to WFArray.norb * WFArray.nspin).

See also

pythtb.TBModel
pythtb.Mesh
pythtb.Wannier
Formalism
Berry phase and curvature in the Haldane model: For an example of using WFArray on a regular grid of points in k-space.
Graphene Dirac cone Berry phase: For an example of using WFArray on a non-regular grid of points in k-space.
Three-site Thouless pump: For an example of using Mesh with an adiabatic dimension. This example shows how one of the directions of WFArray object need not be a k-vector direction, but can instead be a Hamiltonian parameter \(\lambda\). See also discussion after equation 4.1 in Formalism.
Hybrid Wannier functions in cubic slab: For an example of using WFArray to store hybrid Wannier functions.

Notes

Wavefunctions are always stored with mesh axes leading, followed by bands, orbital, and (if present) spin indices. When setting the wavefunctions manually, ensure the input array matches this convention.
WFArray cooperates with Wannier to construct smooth Wannier gauges: pass the populated array to Wannier(wfarray) and use Wannier.single_shot_projection().
Some features are only defined for regular grids and/or in the energy eigenstate gauge. Check the documentation of individual methods for details.

Examples

Populate Mesh with a uniform Monkhorst-Pack grid of k-points

>>> mesh = Mesh(['k', 'k'])
>>> mesh.build_grid(shape=(20, 20), gamma_centered=True)
>>> wfa = WFArray(lattice, mesh, spinful=True, nstates=4)
>>> wfa.shape
(20, 20, ...)

The WFArray is initially empty

>>> wfa.filled
False

Solve a TBModel on the mesh and store the eigenstates

>>> wfa.solve_model(tb_model)
>>> wfa.energies.shape
(20, 20, ...)

Now we can use downstream functions, such as computing the Berry curvature on the grid

>>> curv = wfa.berry_curvature(non_abelian=False)

We can also store states from a finite model on a parameter sweep (no k-axes)

>>> mesh = Mesh(['l'])
>>> mesh.build_grid(shape=(101,), lambda_start=0.0, lambda_stop=2*np.pi)

If the parameter points in the mesh are adiabatic cycles, ensure the boundary conditions are set correctly in the Mesh

>>> mesh.loop(axis_idx=0, loop_idx=0)
>>> wfa = WFArray(lattice, mesh)
>>> wfa.set_states(eigenvectors_lambda, is_cell_periodic=False)
>>> np.allclose(wfa[0], wfa[-1])
True  # states at the endpoints match due to adiabatic cycle

Even if we set the states manually with the indexer, periodic boundary conditions are still enforced automatically using the topology of the Mesh

>>> wfa[-1] = eigvecs  # shape (nstates, norb[, nspin])
>>> np.allclose(wfa[0], wfa[-1])
True  # states at the endpoints still match due to adiabatic cycle

Methods#

`pythtb.WFArray.berry_connection`	Berry connection from parallel-transport links.
`pythtb.WFArray.berry_curvature`	Berry curvature tensor using the Fukui-Hatsugai-Suzuki plaquette method.
`pythtb.WFArray.berry_flux`	Berry flux tensor using the Fukui-Hatsugai-Suzuki plaquette method.
`pythtb.WFArray.berry_phase`	Berry phase accumulated along a specified mesh axis.
`pythtb.WFArray.chern_number`	Computes the Chern number in the specified plane.
`pythtb.WFArray.choose_states`	Keep only the specified states in the `WFArray`.
`pythtb.WFArray.copy`	Create a copy of the current `WFArray` object.
`pythtb.WFArray.empty_like`	Create a new `WFArray` object with the same `Lattice` and `Mesh`.
`pythtb.WFArray.impose_loop`
`pythtb.WFArray.impose_pbc`
`pythtb.WFArray.links`	Compute unitary link matrices for specified axis directions.
`pythtb.WFArray.overlap_matrix`	Compute the overlap matrix of the cell periodic eigenstates on nearest neighbor k-shell.
`pythtb.WFArray.position_expectation`	Position expectation value for a given k-point and set of states.
`pythtb.WFArray.position_hwf`	Eigenvalues and eigenvectors of the position operator in a given basis.
`pythtb.WFArray.position_matrix`	Position matrix for a given k-point and set of states.
`pythtb.WFArray.projectors`	Returns the band projectors associated with the states in the WFArray.
`pythtb.WFArray.remove_states`	Remove specified states from the `WFArray`.
`pythtb.WFArray.roll_states_with_pbc`	Roll states with periodic boundary conditions.
`pythtb.WFArray.set_states`	Populate the wavefunction array.
`pythtb.WFArray.solve_model`	Diagonalizes `model` on every point of the internal `Mesh`.
`pythtb.WFArray.solve_on_grid`
`pythtb.WFArray.solve_on_one_point`
`pythtb.WFArray.states`	Return states stored in the WFArray object.
`pythtb.WFArray.wilson_loop`	Wilson loop along a specified mesh axis.

Attributes#

`pythtb.WFArray.Mmn`	The overlap matrix of the wavefunctions.
`pythtb.WFArray.dim_k`	The dimension of k-space in the `Mesh`.
`pythtb.WFArray.dim_lambda`	The dimension of lambda-space in the `Mesh`.
`pythtb.WFArray.energies`	The energies of the `TBModel`.
`pythtb.WFArray.filled`	Whether the wavefunction array has been initialized.
`pythtb.WFArray.hamiltonian`	The Hamiltonian defined on the `Mesh`.
`pythtb.WFArray.k_points`	The k-points in the `Mesh`.
`pythtb.WFArray.lattice`	The `Lattice` associated with the `WFArray`.
`pythtb.WFArray.mesh`	The `Mesh` associated with the `WFArray`.
`pythtb.WFArray.model`	The `TBModel` associated with the `WFArray`.
`pythtb.WFArray.naxes`	The number of axes in the `Mesh`.
`pythtb.WFArray.norb`	The number of orbitals defined in the `Lattice`.
`pythtb.WFArray.nspin`	The number of spin components.
`pythtb.WFArray.nstates`	The number of states (or bands) in the state array.
`pythtb.WFArray.param_points`	The parameter points in the `Mesh`.
`pythtb.WFArray.psi_nk`	The Bloch wavefunctions.
`pythtb.WFArray.shape`	The shape of the state array.
`pythtb.WFArray.shape_mesh`	The shape of the axes of `Mesh`.
`pythtb.WFArray.spinful`	Whether the `WFArray` includes spin degrees of freedom.
`pythtb.WFArray.u_nk`	The cell-periodic wavefunctions.
`pythtb.WFArray.wfs`	The stored wavefunctions.