dgamore.local_four_point

Local (momentum-independent) four-point objects. LocalFourPoint wraps a single array carrying four orbital indices and a variable number of bosonic/fermionic Matsubara axes, e.g. the generalized susceptibility \(\chi_{abcd}^{\omega\nu\nu'}\), the vertex \(F\), the irreducible vertex \(\Gamma\), and the physical susceptibility \(\chi\). It adds channel-/notation-aware arithmetic (+, -, *, @, inversion, integer powers), orbital and frequency contractions, and conversions to/from the compound-index matrix layout used for inversion and matrix products. Notation mirrors the thesis (Chapters 3 & 4).

class dgamore.local_four_point.LocalFourPoint(mat: ndarray, channel: SpinChannel = SpinChannel.NONE, num_wn_dimensions: int = 1, num_vn_dimensions: int = 2, full_niw_range: bool = True, full_niv_range: bool = True, frequency_notation: FrequencyNotation = FrequencyNotation.PH)

Bases: LocalNPoint, IHaveChannel

This class is used to represent a local four-point object in a given channel with four orbital dimensions and a variable number of bosonic and fermionic frequency dimensions.

Parameters:

• mat (ndarray)

• channel (SpinChannel)

• num_wn_dimensions (int)

• num_vn_dimensions (int)

• full_niw_range (bool)

• full_niv_range (bool)

• frequency_notation (FrequencyNotation)

add(other)

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

Parameters:

other – A LocalFourPoint, LocalInteraction, numpy array, or number.

Returns:

The sum (a new LocalFourPoint, or a raw numpy array for a non-local Interaction).

change_frequency_notation_ph_to_pp_w0()

Converts the frequency notation from ph to pp at the bosonic frequency \(\omega' = 0\), returning a copy. The frequency map is \((\omega, \nu_1, \nu_2) \to (\omega', \nu_1', \nu_2') = (\nu_1 + \nu_2 - \omega, \nu_1, \nu_2)\). A pp object is returned unchanged.

Returns:

A new LocalFourPoint in pp notation at \(\omega' = 0\).

Raises:

ValueError – If the object does not have one bosonic and one or two fermionic frequency dimensions.

contract_legs(beta: float)

Contracts the outer legs of a four-point vertex: sums over both fermionic frequency axes (with the \(1/\beta^2\) prefactor) and traces the inner two orbitals (abcd->ad). Used e.g. to obtain the physical susceptibility \(\chi_{ad}^{\omega}\) from a generalized susceptibility.

Parameters:

beta (float) – Inverse temperature \(\beta\).

Returns:

A new LocalFourPoint with two orbital indices and no fermionic frequency axes.

Raises:

ValueError – If the object does not have exactly two fermionic frequency dimensions.

create_wn_dimension()

Adds a single-point bosonic frequency axis (niw=0) immediately before the fermionic axes, returning a copy.

Returns:

A new LocalFourPoint with one bosonic frequency dimension.

Raises:

ValueError – If the object already has a bosonic frequency dimension.

static from_constant(n_bands: int, niw: int, niv: int, num_wn_dimensions: int = 1, num_vn_dimensions: int = 2, channel: SpinChannel = SpinChannel.NONE, frequency_notation: FrequencyNotation = FrequencyNotation.PH, value: float = 0.0) → LocalFourPoint

Creates a LocalFourPoint filled with a constant value.

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.

• num_wn_dimensions (int) – Number of bosonic frequency axes (0–1).

• num_vn_dimensions (int) – Number of fermionic frequency axes (0–2).

• channel (SpinChannel) – Spin channel of the object (see SpinChannel).

• frequency_notation (FrequencyNotation) – Frequency convention (see FrequencyNotation).

• value (float) – Constant fill value.

Returns:

The constant LocalFourPoint (in the full niw/niv range).

Return type:

LocalFourPoint

static identity(n_bands: int, niw: int, niv: int, num_vn_dimensions: int = 2, full_niw_range: bool = False, frequency_notation: FrequencyNotation = FrequencyNotation.PH) → LocalFourPoint

Creates a LocalFourPoint that is the identity in compound-index (matrix) space.

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.

• num_vn_dimensions (int) – Number of fermionic frequency axes (1 or 2).

• full_niw_range (bool) – Whether the object spans the full (signed) bosonic range or only \(\omega \geq 0\).

• frequency_notation (FrequencyNotation) – Frequency convention (see FrequencyNotation).

Returns:

The identity LocalFourPoint.

Raises:

ValueError – If num_vn_dimensions is not 1 or 2.

Return type:

LocalFourPoint

static identity_like(other: LocalFourPoint) → LocalFourPoint

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

Parameters:

other (LocalFourPoint) – The LocalFourPoint whose shape/attributes the identity should match.

Returns:

The matching identity LocalFourPoint.

Return type:

LocalFourPoint

invert(copy: bool = True)

Inverts the object in compound-index (matrix) space. The result is always returned in the half bosonic frequency range to save memory.

Parameters:

copy (bool) – If True, operate on and return a deep copy; if False, mutate and return self in place.

Returns:

The inverted LocalFourPoint in the half niw range.

is_orbitally_symmetrized(orbitals: list | ndarray) → bool

Checks whether the object is already symmetric under all permutations of the given orbitals.

Parameters:

orbitals (list | ndarray) – 1-based orbital indices to test for equivalence.

Returns:

True if the object is invariant under permutations of those orbitals.

Return type:

bool

static load(filename: str, channel: SpinChannel = SpinChannel.NONE, num_wn_dimensions: int = 1, num_vn_dimensions: int = 2, full_niw_range: bool = False, full_niv_range: bool = True, frequency_notation: FrequencyNotation = FrequencyNotation.PH) → LocalFourPoint

Loads a LocalFourPoint 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).

• 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\).

• frequency_notation (FrequencyNotation) – Frequency convention (see FrequencyNotation).

Returns:

The loaded LocalFourPoint.

Return type:

LocalFourPoint

matmul(other, left_hand_side: bool = True) → LocalFourPoint

Helper method that allows for a matrix multiplication between LocalFourPoint and LocalFourPoint 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 – The right/left operand, a LocalFourPoint or LocalInteraction.

• left_hand_side (bool) – If True, compute self @ other; if False, compute other @ self.

Returns:

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

Raises:

ValueError – If other is neither a LocalFourPoint nor a LocalInteraction.

Return type:

LocalFourPoint

mul(other)

Multiplies the object by a scalar/array (element-wise) or by another LocalFourPoint. Note this is not a matrix product (see matmul()): for two four-point operands, each with a single fermionic frequency, it forms \(A_{abcd}^{\omega\nu} \, B_{dcef}^{\omega\nu'} = C_{abef}^{\omega\nu\nu'}\), contracting the inner orbitals while keeping both fermionic frequencies as separate axes.

Parameters:

other – A number, numpy array, or LocalFourPoint.

Returns:

A new LocalFourPoint (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.

pad_with_u(u: LocalInteraction, niv_pad: int)

Extends the fermionic frequency range to niv_pad by filling the shell (outside the core region) with the bare interaction u, returning a copy. Mainly used to add the constant asymptotic value \(U\) to the irreducible vertex \(\Gamma\) beyond the core frequency box. A no-op (returns a copy) if niv_pad <= self.niv.

Parameters:

• u (LocalInteraction) – The bare local interaction to fill the frequency shell with.

• niv_pad (int) – Target number of positive fermionic frequencies.

Returns:

A new LocalFourPoint padded to niv_pad.

permute_orbitals(permutation: str = 'abcd->abcd', copy: bool = True) → LocalFourPoint

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

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 LocalFourPoint.

Raises:

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

Return type:

LocalFourPoint

pow(power: int, identity)

Raises the object to an integer power using exponentiation by squaring (in compound-index matrix space). For \(n < 0\) the inverse is exponentiated, i.e. \(A^{-n} = (A^{-1})^{n}\).

Parameters:

• power (int) – Integer exponent \(n\).

• identity – Identity object matching self (see identity_like()), returned for \(n = 0\).

Returns:

The exponentiated LocalFourPoint.

Raises:

ValueError – If power is not an integer.

sub(other)

Helper method that allows for subtraction of LocalFourPoint objects and other LocalFourPoint 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 LocalFourPoint, 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.

sum_over_all_vn(beta: float)

Sums over all fermionic frequency axes and applies the prefactor \(1/\beta^{n}\) (with \(n\) the number of fermionic axes). A no-op (returns self) if there are no fermionic frequency dimensions.

Parameters:

beta (float) – Inverse temperature \(\beta\).

Returns:

A new LocalFourPoint without fermionic frequency axes (or self if there were none).

Raises:

ValueError – If the object has more than two fermionic frequency dimensions.

sum_over_orbitals(orbital_contraction: str = 'abcd->ad')

Sums over orbital indices according to an einsum-style contraction acting on the four orbital axes (the frequency axes are appended automatically). Mutates self in place and updates the orbital-dimension count.

Parameters:

orbital_contraction (str) – Contraction of the form "abcd->..." whose target side is a subset of abcd, e.g. "abcd->ad" to trace over the inner orbitals.

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.

sum_over_vn(beta: float, axis: tuple = (-1,))

Sums over the given fermionic frequency axes and applies the Matsubara prefactor \(1/\beta^{n}\), where \(n\) is the number of summed axes.

Parameters:

• beta (float) – Inverse temperature \(\beta\).

• axis (tuple) – Fermionic axes to sum over (negative indices into the frequency tail).

Returns:

A new LocalFourPoint 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.

symmetrize_orbitals(orbitals: list | ndarray) → LocalFourPoint

Symmetrizes the object with respect to the given (equivalent) orbitals by averaging over all permutations of those orbitals applied to the four orbital axes. The orbital labels are 1-based, ranging from 1 to the number of bands; e.g. for a 3-band object orbitals=[1, 3] symmetrizes the first and third orbital.

Parameters:

orbitals (list | ndarray) – 1-based orbital indices to treat as equivalent.

Returns:

The symmetrized LocalFourPoint (self unchanged if already symmetrized).

Return type:

LocalFourPoint

symmetrize_v_vp()

Symmetrizes the vertex with respect to \((\nu, \nu')\) via time-reversal symmetry: \(G_{abcd}(\nu, \nu', \omega) = G_{dcba}(\nu', \nu, \omega)\). Valid for TR-symmetric (real-hopping, paramagnetic) systems with SU(2) symmetry. Mutates self in place.

Returns:

self, symmetrized in \((\nu, \nu')\).

Raises:

ValueError – If the object does not have exactly two fermionic frequency dimensions.

take_first_wn()

Selects the first entry along the bosonic frequency axis, removing that axis, and returns a copy.

Returns:

A new LocalFourPoint without a bosonic frequency dimension.

Raises:

ValueError – If the object does not have exactly one bosonic frequency dimension.

to_compound_indices() → LocalFourPoint

Converts the indices of the LocalFourPoint object \(F^{wvv'}_{lmm'l'}\) to compound indices \(F^{w}_{c_1, c_2}\) by transposing the object to [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 in the same niw range as the original object.

Returns:

self with shape [w, c1, c2] (compound indices).

Raises:

NotImplementedError – If the frequency notation is neither ph nor pp.

Return type:

LocalFourPoint

to_full_indices(shape: tuple = None) → LocalFourPoint

Converts an object stored with compound indices to an object that has unraveled orbital and frequency axes. 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.

Raises:

NotImplementedError – If the frequency notation is neither ph nor pp.

Return type:

LocalFourPoint