dgamore.n_point_base#

Foundational mixins for every physical quantity in the code. IHaveMat owns the underlying numpy array (stored in the global precision DTYPE) and the memory-management/arithmetic helpers; IHaveChannel adds the spin channel and frequency notation; IAmNonLocal adds a single momentum dimension with the compressed/decompressed and irreducible/full-BZ bookkeeping. Concrete classes (Green’s function, self-energy, vertices, interaction, gap function) compose these mixins.

class dgamore.n_point_base.FrequencyNotation(*values)[source]#

Bases: Enum

Enum for the different frequency notations. Is interchangeable with the channel reducibility.

Variables:

PH – Particle-hole notation.
PH_BAR – Transverse (crossed) particle-hole notation.
PP – Particle-particle notation.

class dgamore.n_point_base.IAmNonLocal(mat: ndarray, nq: tuple[int, int, int], has_compressed_q_dimension: bool = False)[source]#

Bases: IHaveMat, ABC

Abstract interface for objects that are momentum dependent. Since we focus on ladder objects, we do not need more than one momentum dimension for one- and two-particle quantities.

Parameters:

mat (ndarray)
nq (tuple[int, int, int])
has_compressed_q_dimension (bool)

compress_q_dimension()[source]#

Converts the object from [qx,qy,qz,…] to [q,…], where len(q) = qx*qy*qz.

Returns:: self with a compressed momentum dimension (a no-op if already compressed).

decompress_q_dimension()[source]#

Converts the object from [q,…] to [qx,qy,qz,…], where len(q) = qx*qy*qz.

Returns:: self with a decompressed momentum dimension (a no-op if already decompressed).

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

Performs a discrete forward Fourier transform over the momentum dimension and returns a copy if specified.

Parameters:: copy (bool) – If True, operate on and return a deep copy; if False, mutate and return self in place.
Returns:: The Fourier-transformed object, in the same momentum-compression state as the input.

filter_q_index(index: int = 0)[source]#

Filters the object to the given index of the momentum dimension and returns a copy. Acts like a filter. Makes it possible to use e.g. only the n-th q-component of a non-local object.

Parameters:: index (int) – The position along the compressed momentum axis to keep.
Returns:: A compressed copy containing only that single momentum (nq = (1, 1, 1)).

find_q(q: tuple[int, int, int] = (0, 0, 0))[source]#

Finds the matrix element for a single momentum \(\vec{q}\) and returns a compressed copy.

Parameters:: q (tuple[int, int, int]) – The momentum grid index (qx, qy, qz) to select.
Returns:: A compressed copy containing only the requested momentum (nq = (1, 1, 1)).
Raises:: ValueError – If no matrix element is found for the given momentum.

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

Flips the momentum axis \(F^{q}\to F^{-q}\) of the object and returns a copy if specified.

Parameters:: copy (bool) – If True, operate on and return a deep copy; if False, mutate and return self in place.
Returns:: The momentum-flipped object, in the same momentum-compression state as the input.

property has_compressed_q_dimension: bool#

Returns whether the underlying matrix has a compressed momentum dimension [q,…] or not [qx,qy,qz,…].

Returns:: True if the momentum is stored as a single compressed axis.

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

Performs a discrete inverse Fourier transform over the momentum dimension and returns a copy if specified.

Parameters:: copy (bool) – If True, operate on and return a deep copy; if False, mutate and return self in place.
Returns:: The inverse-Fourier-transformed object, in the same momentum-compression state as the input.

interpolate_q_grid(nq_new: tuple[int, int, int], copy: bool = True)[source]#

Re-samples the object onto a new Gamma-centered momentum grid (\(\Gamma\) at index 0) and returns a copy if specified. Up- and downsampling are both supported, per axis and in any combination. Returns in the same momentum compression state as the input.

For each axis the method chooses automatically:

if the target is a sub-lattice of the source (n_new divides n_old), the exact \(\Sigma(\vec{q})\) at the retained points is obtained by striding – no band-limiting;
otherwise (upsampling or incommensurate downsampling) a band-limited Fourier interpolation (FFT -> pad/truncate spectrum -> iFFT, with symmetric Nyquist handling) is used.

Requires a full-BZ object. A compressed dimension that is not the full BZ (e.g. IBZ-reduced) is rejected.

Parameters:

nq_new (tuple[int, int, int]) – Target number of momenta per spatial direction (nqx, nqy, nqz).
copy (bool) – If True, operate on and return a deep copy; if False, mutate and return self in place.

Returns:

The re-gridded object in the same momentum-compression state as the input.

Raises:

ValueError – If a target size is not a positive integer, or the object is compressed but not full-BZ.

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

Maps to full BZ using k_grid’s inverse map and precomputed orbital rotation tensors.

Parameters:

k_grid (KGrid) – The momentum grid carrying the irreducible-to-full-BZ map and per-k orbital rotations.
nq (tuple) – Optional override for the number of momenta; if None the object’s own nq is used.

Returns:

self expanded to the full BZ (four orbital dimensions transformed).

property n_bands: int#

Returns the number of bands in the nonlocal two- or four-point object. If the object has a compressed momentum dimension, the array has dimension [q, o1, o2, … ], otherwise it has dimension [qx, qy, qz, o1, o2, … ].

Returns:: The number of bands (orbitals).

property nq: tuple[int, int, int]#

Returns the number of momenta in the object. This should always be equal to the k- or q-point grid of the lattice.

Returns:: The number of momenta per spatial direction (nqx, nqy, nqz).

property nq_tot: int#

Returns the total number of momenta in the object. This might be lower than np.prod(self.nq) if the object is currently saved in the irreducible Brillouin zone.

Returns:: The total number of stored momenta.

q_mean()[source]#

Averages over the momentum dimension and returns a copy of the object with nq = (1,1,1).

Returns:: A copy holding the momentum average (nq = (1, 1, 1)).

reduce_q(q_list: ndarray)[source]#

Reduces the object to the given list of momenta and returns a copy with a compressed momentum dimension. Acts like a filter. Makes it possible to use e.g. only the \(\vec{q}=0\) component of a non-local object or filter the irreducible Brillouin zone from an object in the full Brillouin zone.

Parameters:: q_list (ndarray) – Array of momentum grid indices to keep, shape [3, n_q] (one column per momentum).
Returns:: A copy reduced to q_list, with a compressed momentum dimension.

shift_k_by_pi()[source]#

Shifts all momenta by \(\pi\) and returns the object with a decompressed momentum dimension.

Returns:: A copy shifted by \(\pi\) along every momentum axis, in the same compression state as self.

shift_k_by_q(q: tuple | list[int] = (0, 0, 0))[source]#

Shifts all momenta by the given values and returns a copy of the object with a decompressed momentum dimension.

Parameters:: q (tuple | list[int]) – The momentum shift \(\vec{q}\) as integer grid offsets (qx, qy, qz).
Returns:: A copy shifted by \(\vec{q}\), in the same momentum-compression state as self.

class dgamore.n_point_base.IHaveChannel(channel: SpinChannel = SpinChannel.NONE, frequency_notation: FrequencyNotation = FrequencyNotation.PH)[source]#

Bases: ABC

Abstract interface for classes that have a channel attribute. Adds a property for the spin channel and the frequency notation.

Parameters:

channel (SpinChannel)
frequency_notation (FrequencyNotation)

property channel: SpinChannel#

Returns the spin channel of the object. For a set of available channels, see the enum SpinChannel.

Returns:: The current spin channel.

property frequency_notation: FrequencyNotation#

Returns the frequency notation (not the channel reducibility) of the object. For a set of available frequency notations, see the enum FrequencyNotation.

Returns:: The current frequency notation.

set_channel(channel: SpinChannel)[source]#

Sets the spin channel of the object (chainable). For a set of available channels, see the enum SpinChannel.

Parameters:: channel (SpinChannel) – The spin channel to set.
Returns:: self (for chaining).

set_frequency_notation(value: FrequencyNotation)[source]#

Sets the frequency notation of the object (chainable). For a set of available frequency notations, see the enum FrequencyNotation.

Parameters:: value (FrequencyNotation) – The frequency notation to set.
Returns:: self (for chaining).

class dgamore.n_point_base.IHaveMat(mat: ndarray)[source]#

Bases: ABC

Abstract interface for classes that have a mat attribute. Adds a couple of convenience methods for matrix operations. Also adds a way to easily delete the underlying matrix to free memory.

Parameters:: mat (ndarray)

property current_shape: tuple#

Keeps track of the current shape of the underlying numpy array.

Returns:: The current shape of mat.

filter_small_values(threshold: float = 1e-12)[source]#

Sets all values in the underlying matrix to zero which are smaller than the given threshold in absolute value. This can be used to save memory and speed up calculations by setting very small values to zero.

The mask is evaluated in chunks so the full-size |real|/|imag| and boolean temporaries (~0.75x the array) are never materialized all at once – on a very large array that transient spike would otherwise dominate the footprint right when mat is at its largest. Chunking is also faster (cache-resident temporaries, fewer page faults). A small array is filtered in a single pass to avoid the per-chunk overhead.

Parameters:: threshold (float) – Values whose real and imaginary parts are both below this magnitude are zeroed (in place).
Returns:: self (for chaining).

free(trim: bool = False)[source]#

Explicitly releases the underlying numpy array. If True and running on Linux, attempts to return freed heap memory back to the OS using malloc_trim.

trim defaults to False on purpose: malloc_trim walks the entire heap, so it should be requested only at coarse, heavy boundaries (e.g. after a large object is released at the end of a self-consistency iteration), never on every release in a hot loop.

Parameters:: trim (bool) – If True, additionally attempt to return freed heap memory to the OS (Linux only).

property mat: ndarray#

Returns the underlying matrix, i.e. the numpy array.

Returns:: The underlying numpy array (or None if it has been freed).

property memory_usage_in_gb: float#

Returns the memory usage of the numpy array in GigaBytes (GB).

Returns:: Memory footprint of mat in GB.

property original_shape: tuple#

Keeps track of the previous shape of the underlying numpy array for any reshaping process. E.g., it is needed when reshaping it to compound indices where the original shape would have been lost otherwise.

Returns:: The stored original (pre-reshape) shape.

times(contraction: str, *args) → ndarray[source]#

Multiplies the matrices of multiple objects with the contraction specified and returns the result as a numpy array.

Parameters:

contraction (str) – An einsum contraction string applied to self.mat and the operands in args.
args – Further operands, each either an IHaveMat or a numpy array.

Returns:

The contracted numpy array.

Raises:

ValueError – If any operand is neither an IHaveMat nor a numpy array.

Return type:

ndarray

update_original_shape()[source]#: Updates the original shape of the numpy array to the current array. This is often needed when the matrix is reshaped.

class dgamore.n_point_base.SpinChannel(*values)[source]#

Bases: Enum

Enum for the different spin combinations.

Variables:

DENS – Density (charge) channel.
MAGN – Magnetic (spin) channel.
SING – Singlet pairing channel.
TRIP – Triplet pairing channel.
UU – Up-up spin combination.
UD – Up-down spin combination.
UD_BAR – Crossed (transverse) up-down spin combination.
NONE – No / unspecified channel (e.g. a bare, not-yet-projected quantity).