PAOFLOW.transport.grid.kpoints#

Classes#

KpointsData

Encapsulates all k-point and R-point related arrays and computes memory usage.

Functions#

`kpoints_mask`(vect, init, transport_direction)	Embed a 2D vector into 3D space by inserting a value along the transport direction.
`kpoints_equivalent`(v1, v2[, tol])	Check if two 2D k-points are equivalent under time-reversal symmetry (modulo 1).
`initialize_meshsize`(nr_full, transport_direction[, ...])	Extract the 2D R-vector mesh (nr_par) orthogonal to the transport direction
`initialize_kpoints`(nk_par, s_par, transport_direction)	Generate 3D k-points and weights on a uniform 2D mesh orthogonal to the transport direction.
`compute_fourier_phase_table`(vkpts, ivr_par)	Compute Fourier phase factors exp(i 2π k · R) for each pair of k-point and R-vector.
`initialize_r_vectors`(nr_par, transport_direction)	Generate 3D R-vectors and weights based on a uniform 2D integer grid orthogonal to the transport direction.
`compute_ivr_par`(nr_par)	Generate a 2D mesh of integer real-space vectors and associated weights

Module Contents#

PAOFLOW.transport.grid.kpoints.kpoints_mask(vect, init, transport_direction)[source]#

Embed a 2D vector into 3D space by inserting a value along the transport direction.

Parameters:

vect (Tuple[int, int] or (2,) ndarray) – A 2D vector to embed into 3D. Can represent: - Integer grid descriptors like mesh sizes or shift values (e.g., nk, s, nr) - Floating-point physical vectors like k-points or R-vectors in reciprocal space
init (int or float) – Value to insert along the transport direction: - Use 1 for mesh dimensions - Use 0 for shift vectors or physical coordinates
transport_direction ({'x', 'y', 'z'}) – Direction of transport. This direction will receive the init value, and vect will fill the two orthogonal directions.

Returns:

`out` – A 3D vector with init inserted along the transport direction, and the 2D input vect placed in the remaining two directions.

Return type:

(3,) ndarray

Notes

This function is a general-purpose utility for constructing 3D vectors that respect the geometry of transport problems, where a 2D grid or vector lies perpendicular to the specified transport direction.

It applies to both grid descriptors (like number of points or shifts) and to physical vectors (like k-points or R-vectors in fractional coordinates).

Mapping logic:

If transport_direction == ‘x’:: out = [init, vect[0], vect[1]]
If transport_direction == ‘y’:: out = [vect[0], init, vect[1]]
If transport_direction == ‘z’:: out = [vect[0], vect[1], init]

PAOFLOW.transport.grid.kpoints.kpoints_equivalent(v1, v2, tol=1e-06)[source]#

Check if two 2D k-points are equivalent under time-reversal symmetry (modulo 1).

Parameters:

v1 ((2,) ndarray) – 2D k-point vectors in reciprocal lattice units (fractional coordinates).
v2 ((2,) ndarray) – 2D k-point vectors in reciprocal lattice units (fractional coordinates).
tol (float) – Tolerance for equality check.

Returns:

`is_equiv` – True if v1 ≈ -v2 (mod 1), i.e., they are time-reversal partners.

Return type:

bool

Notes

In a time-reversal symmetric system, a k-point k is equivalent to -k (modulo the reciprocal lattice). This function checks:

(v1 + v2) % 1 ≈ 0

For example:

v1 = (0.25, 0.5), v2 = (-0.25, -0.5) -> equivalent v1 = (0.25, 0.5), v2 = (0.25, 0.5) -> not equivalent (unless v1 == 0)

This is essential for symmetrizing the k-point mesh and avoiding double counting.

PAOFLOW.transport.grid.kpoints.initialize_meshsize(nr_full, transport_direction, nk_par=None, use_safe_kmesh=False)[source]#

Extract the 2D R-vector mesh (nr_par) orthogonal to the transport direction and validate or infer the corresponding k-point mesh (nk_par).

Parameters:

nr_full ((3,) ndarray of int) – Full 3D R-vector mesh sizes along (x, y, z) directions. For example: array([2, 2, 3])
transport_direction ({'x', 'y', 'z'}) – Transport direction.
nk_par (Optional[(2,) ndarray of int]) – User-specified number of k-points in the 2D plane orthogonal to transport. If None or [0, 0], it will be inferred from nr_par.
use_safe_kmesh (bool) – If True, enforces nk_par[i] >= nr_par[i] to guarantee sufficient resolution for Fourier-based methods.

Returns:

`nk_par` ((2,) ndarray of int) – Validated number of k-points in the orthogonal directions.
`nr_par` ((2,) ndarray of int) – Number of R-vectors in directions orthogonal to transport.

Notes

Example:: nr_full = np.array([2, 2, 3]) transport_direction = 3

→ nr_par = array([2, 2]) # selects x and y directions → nk_par = array([2, 2]) if not provided

PAOFLOW.transport.grid.kpoints.initialize_kpoints(nk_par, s_par, transport_direction, use_sym=True)[source]#

Generate 3D k-points and weights on a uniform 2D mesh orthogonal to the transport direction.

Parameters:

nk_par ((2,) ndarray of int) – Number of k-points along the two non-transport directions.
s_par ((2,) ndarray of int) – Shifts (in fractional units) for the mesh in the two non-transport directions.
transport_direction ({'x', 'y', 'z'}) – Transport direction.
use_sym (bool) – Whether to symmetrize the mesh under time-reversal (k ≡ -k).

Returns:

`vkpt_par3D` ((nkpnts, 3) ndarray) – Generated 3D k-points in fractional coordinates.
`wk_par` ((nkpnts,) ndarray) – Normalized weights for each unique k-point.

Notes

Example:

If nk_par = [2, 2], s_par = [0, 0], transport_direction = 3

kx(i) = (i - 1) / 2 ky(j) = (j - 1) / 2 → yields 2×2 mesh in xy-plane, mapped to 3D with z = 0

Time-reversal symmetry is enforced as:

k1 ≡ -k2 (mod 1) ⇒ count only one of them, with doubled weight.

PAOFLOW.transport.grid.kpoints.compute_fourier_phase_table(vkpts, ivr_par)[source]#

Compute Fourier phase factors exp(i 2π k · R) for each pair of k-point and R-vector.

Parameters:

vkpts ((nkpnts, 2) or (nkpnts, 3) ndarray) – k-point vectors in fractional reciprocal lattice units.
ivr_par ((nR, 2) or (nR, 3) ndarray) – R-vectors in fractional crystal units (integer multiples of lattice vectors).

Returns:

`table_par` – Phase factors e^{i 2π k · R} used for Fourier transforms or interpolation.

Return type:

(nR, nkpnts) ndarray of complex128

Notes

This computes the plane-wave phase factors:: table_par[ir, ik] = exp(i * 2π * (k · R))
where:: k : reciprocal vector (fractional units) R : real-space vector (fractional units)

These factors are essential for transforming quantities between real and reciprocal space. For example, they are used in evaluating Fourier series expansions, computing Green’s functions or self-energies in k-space, and constructing Hamiltonians or overlaps in different representations.

The 2π factor comes from the convention of expressing k and R in fractional units:: k = k_cartesian / (2π) -> k_cartesian = 2π * k_fractional

PAOFLOW.transport.grid.kpoints.initialize_r_vectors(nr_par, transport_direction)[source]#

Generate 3D R-vectors and weights based on a uniform 2D integer grid orthogonal to the transport direction.

Parameters:

nr_par (Tuple[int, int]) – 2D mesh sizes for R-vectors in the directions orthogonal to transport.
transport_direction ({'x', 'y', 'z'}) – Direction of transport.

Returns:

`ivr_par3D` ((nR, 3) ndarray of int) – 3D integer R-vectors in crystal coordinates.
`wr_par` ((nR,) ndarray of float) – Weights for each R-vector (normalized to match Fortran behavior).

Notes

The 2D R-vectors are generated as:

R_i = i - (nr_x + 1) // 2 R_j = j - (nr_y + 1) // 2

for i in [1, nr_x], j in [1, nr_y].

Hermitian symmetry is enforced by ensuring that for each R, -R is present. If a corresponding -R is not found, it is added, and the weights of both R and -R are halved.

The 2D vectors are then expanded to 3D using:: if transport_direction == ‘x’: (0, R1, R2) if transport_direction == ‘y’: (R1, 0, R2) if transport_direction == ‘z’: (R1, R2, 0)

PAOFLOW.transport.grid.kpoints.compute_ivr_par(nr_par)[source]#

Generate a 2D mesh of integer real-space vectors and associated weights for use in constructing operator blocks in reciprocal space.

This function produces a grid of R-vectors on a uniform mesh centered around the origin, spanning the two directions orthogonal to the transport axis. Each R-vector is a pair of integers (Rx, Ry), symmetrically distributed about zero to preserve hermiticity in subsequent Fourier transforms.

For each generated R-vector, its negative counterpart is also ensured to exist in the final set. If a negative is not initially present, it is added, and both the original and its negative are assigned half the original weight.

Parameters:

nr_par (Tuple[int, int]) – Size of the uniform mesh in the two directions orthogonal to the transport axis. Each component specifies the number of grid points along one axis.

Returns:

`ivr_par` ((2, nR) ndarray of int) – Array of 2D integer real-space vectors.
`wr_par` ((nR,) ndarray of float) – Associated weights for each R-vector, normalized by symmetry.

Notes

The R-vectors are centered about the origin using the rule: