dgamore.four_point#

Momentum-dependent four-point objects. FourPoint extends LocalFourPoint with one momentum axis (see IAmNonLocal) to represent quantities such as the ladder susceptibility \(\chi_{abcd}^{q\omega\nu\nu'}\) and vertex \(F^{q}\) over the (irreducible) BZ. The arithmetic and compound-index machinery mirrors LocalFourPoint but accounts for the extra momentum dimension; these operations are the performance and memory bottleneck of the non-local ladder DGA step, so several variants are provided that trade speed for footprint. Notation mirrors the thesis (Chapters 3 & 4).

class dgamore.four_point.FourPoint(mat: ndarray, channel: SpinChannel = SpinChannel.NONE, nq: tuple[int, int, int] = (1, 1, 1), num_wn_dimensions: int = 1, num_vn_dimensions: int = 2, full_niw_range: bool = True, full_niv_range: bool = True, has_compressed_q_dimension: bool = False, frequency_notation: FrequencyNotation = FrequencyNotation.PH)[source]#

Bases: IAmNonLocal, LocalFourPoint

This class is used to represent a non-local four-point object in a given channel with one momentum dimension, four orbital dimensions and variable bosonic and fermionic frequency dimensions. Calculations using these objects are the bottleneck of the DGA algorithm and need to be optimized for performance and memory usage.

Parameters:

mat (ndarray)
channel (SpinChannel)
nq (tuple[int, int, int])
num_wn_dimensions (int)
num_vn_dimensions (int)
full_niw_range (bool)
full_niv_range (bool)
has_compressed_q_dimension (bool)
frequency_notation (FrequencyNotation)

add(other) → FourPoint[source]#

Adds other to this object (operator +); see _add() for the accepted operands and the niw-range handling.

Parameters:: other – A FourPoint, LocalFourPoint, Interaction, LocalInteraction, numpy array, or number.
Returns:: A new FourPoint holding the sum.
Return type:: FourPoint

static identity(n_bands: int, niw: int, niv: int, nq_tot: int = 1, nq: tuple[int, int, int] = (1, 1, 1), num_vn_dimensions: int = 2, frequency_notation: FrequencyNotation = FrequencyNotation.PH) → FourPoint[source]#

Creates a FourPoint that is the identity in compound-index (matrix) space at each momentum, returned in the half bosonic frequency range.

Parameters:

n_bands (int) – Number of orbitals/bands per orbital axis.
niw (int) – Number of positive bosonic frequencies.
niv (int) – Number of positive fermionic frequencies.
nq_tot (int) – Total number of momenta (product over directions).
nq (tuple[int, int, int]) – Number of momenta per spatial direction.
num_vn_dimensions (int) – Number of fermionic frequency axes (1 or 2).
frequency_notation (FrequencyNotation) – Frequency convention (see FrequencyNotation).

Returns:

The identity FourPoint (compressed momentum, half niw range).

Raises:

ValueError – If num_vn_dimensions is not 1 or 2.

Return type:

FourPoint

static identity_like(other: FourPoint) → FourPoint[source]#

Creates a compound-index identity matching the bands, frequency box, momenta, fermionic-axis count and frequency notation of other (see identity()).

Parameters:: other (FourPoint) – The FourPoint whose shape/attributes the identity should match.
Returns:: The matching identity FourPoint.
Return type:: FourPoint

invert(copy: bool = True)[source]#

Inverts the object in compound-index (matrix) space, per momentum. The single-fermionic-frequency case is handled by a dedicated block-diagonal reshape; otherwise each momentum slice is inverted in a loop to keep intermediate arrays small. The result is always returned in the half bosonic frequency range.

Parameters:: copy (bool) – If True, operate on and return a deep copy; if False, mutate and return self in place.
Returns:: The inverted FourPoint in the half niw range.

invert_and_sum_over_last_vn(beta: float)[source]#

Inverts the object in compound-index space per momentum and bosonic frequency, then sums over the last fermionic frequency axis (with the \(1/\beta\) prefactor). This computes the auxiliary susceptibility used in the ladder construction in a single fused pass. Mutates self in place.

Parameters:: beta (float) – Inverse temperature \(\beta\).
Returns:: self with the last fermionic axis summed out (num_vn_dimensions reduced to 1).
Raises:: NotImplementedError – If the object does not have exactly two fermionic frequency dimensions.

invert_and_sum_over_last_vn_v2(beta: float)[source]#

Helper method that explicitly handles the calculation of the sum over the auxiliary susceptibility while being highly memory-efficient. Does not invert the matrix directly but uses a linear solver to avoid the creation of large intermediate arrays. This is especially important for objects with a large number of orbital degrees of freedom, where the matrix in compound index space can become very large. Is up to numerical precision the same as invert_and_sum_over_last_vn().

Parameters:: beta (float) – Inverse temperature \(\beta\).
Returns:: self with the last fermionic axis summed out (num_vn_dimensions reduced to 1).

static load(filename: str, channel: SpinChannel = SpinChannel.NONE, nq: tuple[int, int, int] = (1, 1, 1), num_wn_dimensions: int = 1, num_vn_dimensions: int = 2, full_niw_range: bool = False, full_niv_range: bool = True, has_compressed_q_dimension: bool = True, frequency_notation: FrequencyNotation = FrequencyNotation.PH) → FourPoint[source]#

Loads a FourPoint from a .npy file.

Parameters:

filename (str) – Path to the .npy file (loaded with allow_pickle=False).
channel (SpinChannel) – Spin channel of the object (see SpinChannel).
nq (tuple[int, int, int]) – Number of momenta per spatial direction.
num_wn_dimensions (int) – Number of bosonic frequency axes (0–1).
num_vn_dimensions (int) – Number of fermionic frequency axes (0–2).
full_niw_range (bool) – Whether the stored array spans the full (signed) bosonic range or only \(\omega \geq 0\).
full_niv_range (bool) – Whether the stored array spans the full (signed) fermionic range or only \(\nu \geq 0\).
has_compressed_q_dimension (bool) – Whether the momentum is stored as a single compressed axis (True) or as [qx, qy, qz, ...] (False).
frequency_notation (FrequencyNotation) – Frequency convention (see FrequencyNotation).

Returns:

The loaded FourPoint.

Return type:

FourPoint

map_to_full_bz(grid: KGrid, nq: tuple = None)[source]#

Unfolds the object from the irreducible BZ to the full BZ using the grid’s symmetry index map (see IAmNonLocal._map_to_full_bz()), with four orbital dimensions.

Parameters:

grid (KGrid) – The KGrid providing the irreducible-to-full BZ index mapping.
nq (tuple) – Optional number of momenta per direction for the unfolded grid; defaults to the object’s nq.

Returns:

self defined on the full BZ.

matmul(other, left_hand_side: bool = True) → FourPoint[source]#

Helper method that allows for a matrix multiplication between FourPoint and FourPoint, LocalFourPoint, Interaction and LocalInteraction objects. Depending on the number of frequency and momentum dimensions, the objects have to be multiplied differently. The use of einsum is very crucial for memory efficiency here, as a regular matrix multiplication in compound index space would create large intermediate arrays if one of both partaking objects has less than two fermionic frequency dimensions. Result objects will always be returned in half of their niw range to save memory.

Parameters:

other – A FourPoint, LocalFourPoint, Interaction, or LocalInteraction. Local operands are broadcast over the momentum axis.
left_hand_side (bool) – If True, compute self @ other; if False, compute other @ self.

Returns:

A new FourPoint in the half bosonic frequency range, carrying the non-NONE channel.

Raises:

ValueError – If other has an unsupported type.

Return type:

FourPoint

mul(other) → FourPoint[source]#

Allows for the multiplication with a number, a numpy array or another FourPoint object. This is different from the matmul() method, which is used for matrix multiplication. In the case the other object is a FourPoint object, we require that both objects have only one fermionic frequency dimension, such that \(A_{abcd}^{qv} * B_{dcef}^{qv'} = C_{abef}^{qvv'}\). This is needed to construct the full vertex, see Eq. (3.139) in my thesis. Returns the object in the half niw range.

Parameters:: other – A number, numpy array, or FourPoint.
Returns:: A new FourPoint (in the half niw range for the four-point case).
Raises:: ValueError – If other has an unsupported type, or either four-point operand does not have exactly one fermionic frequency dimension.
Return type:: FourPoint

permute_orbitals(permutation: str = 'abcd->abcd', copy: bool = True) → FourPoint[source]#

Permutes the four orbital axes according to an einsum-style string (the momentum and frequency axes are kept fixed). Summing over orbitals is not allowed (both sides must list all four orbitals).

Parameters:

permutation (str) – A permutation of the form "abcd->..." using exactly the four orbital labels.
copy (bool) – If True, operate on and return a deep copy; if False, mutate and return self in place.

Returns:

The orbital-permuted FourPoint (self unchanged if the permutation is the identity).

Raises:

ValueError – If the permutation is malformed or does not list all four orbitals on both sides.

Return type:

FourPoint

sub(other) → FourPoint[source]#

Helper method that allows for subtraction of FourPoint objects and other FourPoint, LocalFourPoint, Interaction or LocalInteraction objects. Subtractions with numpy arrays, floats, ints or complex numbers are also supported. Depending on the number of frequency and momentum dimensions, the vertices have to be subtracted slightly different. If the objects have different niw ranges, they will be converted to the half niw range before the subtraction. Objects will always be returned in the half niw range to save memory.

Parameters:: other – A FourPoint, LocalFourPoint, Interaction, LocalInteraction, numpy array, or number.
Returns:: The difference, implemented as self._add(other, subtract=True) (see _add()).
Raises:: ValueError – Propagated from _add() for unsupported operands.
Return type:: FourPoint

sum_over_orbitals(orbital_contraction: str = 'abcd->ad') → FourPoint[source]#

Sums over orbital indices according to an einsum-style contraction on the four orbital axes (the leading momentum axis and trailing frequency axes are preserved automatically). Mutates self in place.

Parameters:: orbital_contraction (str) – Contraction of the form "abcd->..." whose target side is a subset of abcd.
Returns:: self, with the summed orbital axes removed.
Raises:: ValueError – If the left side does not have four orbitals or the right side has more indices than the left.
Return type:: FourPoint

sum_over_vn(beta: float, axis: tuple = (-1,), copy: bool = True) → FourPoint[source]#

Sums over the given fermionic frequency axes and applies the Matsubara prefactor \(1/\beta^{n}\) (with \(n\) the number of summed axes). The in-place branch frees the old array before allocating the result to cap peak memory.

Parameters:

beta (float) – Inverse temperature \(\beta\).
axis (tuple) – Fermionic axes to sum over (negative indices into the frequency tail).
copy (bool) – If True, operate on and return a deep copy; if False, mutate and return self in place.

Returns:

A FourPoint with the summed axes removed and num_vn_dimensions reduced accordingly.

Raises:

ValueError – If more axes are requested than the object has fermionic frequency dimensions.

Return type:

FourPoint

to_compound_indices() → FourPoint[source]#

Converts the indices of the FourPoint object \(F^{wvv'}_{lmm'l'}\) to compound indices \(F^{w}_{c_1, c_2}\) by transposing the object to [q, w, o1, o2, v, o4, o3, v’] (if the object has any fermionic frequency dimension, otherwise the compound indices are built from orbital dimensions only) and grouping {o1, o2, v} and {o4, o3, v’} to the new compound index. Always returns the object with a compressed momentum dimension and in the same niw range as the original object.

Returns:: self with shape [q, w, c1, c2] (compound indices, compressed momentum).
Raises:: NotImplementedError – If the frequency notation is neither ph nor pp.
Return type:: FourPoint

to_full_indices(shape: tuple = None) → FourPoint[source]#

Converts an object stored with compound indices to an object that has unraveled momentum, orbital and frequency axes. Always returns the object with a compressed momentum dimension. This is the inverse transformation of to_compound_indices(). Will make use of the original_shape the object was created or last modified with. If the original_shape is not set or is hard to obtain, the shape argument can be used to specify the original shape of the object.

Parameters:: shape (tuple) – Optional override for the stored original_shape used to unravel the compound axes.
Returns:: self with unraveled orbital and frequency axes (compressed momentum).
Raises:: NotImplementedError – If the frequency notation is neither ph nor pp.
Return type:: FourPoint