`qlat.propagator` — Propagator Types and Utilities¶

Source: qlat/qlat/propagator.pyx

Note: Update this document when updating the source file.

Overview¶

propagator defines the primary propagator container types used in domain-wall fermion lattice QCD calculations and provides functions for source construction, inversion, and format conversion.

The five propagator/field types are:

Type	Element Type	Description
`Prop`	`WilsonMatrix` (12x12)	Full-volume propagator field
`SelProp`	`WilsonMatrix`	Propagator on a `FieldSelection` subset of sites
`PselProp`	`WilsonMatrix`	Propagator on a `PointsSelection` subset of sites
`SpinProp`	`SpinMatrix` (4x4)	Full-volume spin propagator (no colour index)
`FermionField4d`	`WilsonVector` (12-component)	Single fermion field

Each class enforces multiplicity == 1 — there is exactly one matrix or vector element per site.

Prop stores a 12x12 complex matrix (4 spin x 3 colour) at every lattice site. SelProp and PselProp are selected-site variants used for point-source solves and measurements. SpinProp is the spin-only (4x4) counterpart used in QED corrections. FermionField4d is a single 12-component Wilson vector field.

Propagator Classes¶

`Prop`¶

class Prop(FieldWilsonMatrix)

Full-volume propagator. Each site stores one WilsonMatrix (12x12 complex matrix, multiplicity = 1).

Constructors¶

Signature	Description
`Prop()`	Uninitialized propagator
`Prop(geo: Geometry)`	Allocate on the given geometry

Methods¶

Method	Description
`get_elem_wm(index, m=0) -> WilsonMatrix`	Return the Wilson matrix at site `index`
`glb_sum_tslice(t_dir=3) -> PselProp`	Sum propagator over each time slice, returning a `PselProp`
`__getstate__` / `__setstate__`	Pickle support (single-node only)

`SelProp`¶

class SelProp(SelectedFieldWilsonMatrix)

Propagator defined on a field selection (a subset of lattice sites).

Constructors¶

Signature	Description
`SelProp()`	Uninitialized
`SelProp(fsel: FieldSelection)`	Allocate on the selected sites

Methods¶

Method	Description
`get_elem_wm(idx, m=0) -> WilsonMatrix`	Return the Wilson matrix at selected-site index `idx`
`__getstate__` / `__setstate__`	Pickle support (single-node only)

`PselProp`¶

class PselProp(SelectedPointsWilsonMatrix)

Propagator defined on a points selection (an ordered list of sites).

Constructors¶

Signature	Description
`PselProp()`	Uninitialized
`PselProp(psel: PointsSelection)`	Allocate for the given point set
`PselProp(psel, multiplicity)`	Must have `multiplicity == 1`
`PselProp(sel_prop: SelProp)`	Copy selected sites from a `SelProp`

Methods¶

Method	Description
`get_elem_wm(idx, m=0) -> WilsonMatrix`	Return the Wilson matrix at point index `idx`
`__getstate__` / `__setstate__`	Pickle support (single-node only)

`SpinProp`¶

class SpinProp(FieldSpinMatrix)

Full-volume spin propagator (4x4 complex matrix, no colour index). Used for QED corrections.

Constructors¶

Signature	Description
`SpinProp()`	Uninitialized
`SpinProp(geo: Geometry)`	Allocate on the given geometry

Methods¶

Method	Description
`get_elem_sm(index, m=0) -> SpinMatrix`	Return the spin matrix at site `index`
`glb_sum_tslice(t_dir=3) -> SelectedPointsSpinMatrix`	Sum over each time slice
`__getstate__` / `__setstate__`	Pickle support (single-node only)

`FermionField4d`¶

class FermionField4d(FieldWilsonVector)

A single 12-component fermion field (one WilsonVector per site).

Constructors¶

Signature	Description
`FermionField4d()`	Uninitialized
`FermionField4d(geo: Geometry)`	Allocate on the given geometry

Source Construction¶

`set_point_src`¶

set_point_src(prop_src: Prop, geo: Geometry, xg: Coordinate,
              value: complex = 1.0) -> None

Set prop_src to a point source at global coordinate xg with the given colour-spin amplitude.

`set_wall_src`¶

set_wall_src(prop_src: Prop, geo: Geometry, tslice: int,
             lmom: CoordinateD = None) -> None

Set prop_src to a wall source at time slice tslice with optional spatial momentum lmom. If lmom is None, zero momentum is used.

`mk_point_src`¶

mk_point_src(geo: Geometry, xg: Coordinate,
             value: complex = 1.0) -> Prop

Create and return a new Prop with a point source. Convenience wrapper around set_point_src.

`mk_wall_src`¶

mk_wall_src(geo: Geometry, tslice: int,
            lmom: CoordinateD = None) -> Prop

Create and return a new Prop with a wall source. Convenience wrapper around set_wall_src.

`set_rand_vol_u1` / `mk_rand_vol_u1`¶

set_rand_vol_u1(fu1: FieldComplexD, geo: Geometry,
                multiplicity: int, rs: RngState) -> None

mk_rand_vol_u1(geo: Geometry, multiplicity: int,
               rs: RngState) -> FieldComplexD

Generate a volume-filling random U(1) field. mk_rand_vol_u1 creates and returns the field; set_rand_vol_u1 fills an existing one.

`set_rand_vol_u1_src` / `mk_rand_vol_u1_src`¶

set_rand_vol_u1_src(prop_src: Prop, fu1: FieldComplexD) -> None

mk_rand_vol_u1_src(fu1: FieldComplexD) -> Prop

Construct a random-U1 volume source from a U(1) field fu1. The source propagator is proportional to fu1.

`mk_rand_u1_src`¶

mk_rand_u1_src(sel, rs: RngState) -> tuple[Prop, FieldComplexD]

Create a random-U1 source on selected sites. sel can be a FieldSelection or a PointsSelection.

Returns (prop_src, fu1) where fu1 stores the random U(1) numbers.

`get_rand_u1_sol`¶

get_rand_u1_sol(prop_sol: Prop, fu1: FieldComplexD,
                sel) -> SelProp | PselProp

Extract the solution on selected sites after solving with a random-U1 source. sel can be a FieldSelection (returns SelProp) or a PointsSelection (returns PselProp).

`mk_rand_u1_prop`¶

mk_rand_u1_prop(inv, sel, rs: RngState) -> SelProp | PselProp

High-level interface: generate a random-U1 source, invert, and return the solution on selected sites. inv is an inverter object (supports inv * prop_src). sel can be a FieldSelection or PointsSelection.

Inversion Functions¶

`free_invert`¶

free_invert(prop_src, mass: float, m5: float = 1.0,
            momtwist: CoordinateD = None) -> Prop | SpinProp

Compute the free (gauge-field-independent) inverse of a propagator source. Supports both Prop and SpinProp input; returns the same type.

Parameter	Type	Default	Description
`prop_src`	`Prop` or `SpinProp`	—	Source field
`mass`	`float`	—	Fermion mass
`m5`	`float`	`1.0`	Fifth-dimensional mass for DWF
`momtwist`	`CoordinateD`	`[0,0,0,0]`	Twist angles for twisted-boundary conditions

`free_mom_invert`¶

free_mom_invert(prop_src, mass: float, m5: float = 1.0,
                momtwist: CoordinateD = None) -> Prop | SpinProp

Apply the free DWF inverse in momentum space. Unlike free_invert, no Fourier transform is performed, so prop_src must already be in momentum space (e.g. the output of a normalizing forward FFT). All parameters of the underlying C++ kernel are exposed. Supports both Prop and SpinProp input; returns the same type.

Equivalently, for a normalizing FFT pair fft_f / fft_b:

sol = fft_b * q.free_mom_invert(fft_f * src, mass=m, m5=m5, momtwist=t)
# equals q.free_invert(src, mass=m, m5=m5, momtwist=t)

Parameter	Type	Default	Description
`prop_src`	`Prop` or `SpinProp`	—	Source field, in momentum space
`mass`	`float`	—	Fermion mass
`m5`	`float`	`1.0`	Fifth-dimensional mass for DWF
`momtwist`	`CoordinateD`	`[0,0,0,0]`	Twist angles for twisted-boundary conditions

`invert_qed`¶

invert_qed(sp_src: SpinProp, gf1: FieldComplexD,
           mass: float, m5: float, ls: int, *,
           t_wick_phase_factor_arr=None,
           is_dagger: bool = False,
           stop_rsd: float = 1e-8,
           max_num_iter: int = 50000) -> SpinProp

Invert the Dirac operator in the presence of a QED gauge field for spin-propagator sources. Used for electromagnetic corrections.

Parameter	Type	Default	Description
`sp_src`	`SpinProp`	—	Spin-propagator source
`gf1`	`FieldComplexD`	—	Left-expanded QED gauge field
`mass`	`float`	—	Fermion mass
`m5`	`float`	—	DWF fifth-dimensional mass
`ls`	`int`	—	Fifth-dimensional extent
`t_wick_phase_factor_arr`	array-like	`None`	Optional Wick rotation phase factors per time slice
`is_dagger`	`bool`	`False`	Whether to use the conjugate operator
`stop_rsd`	`float`	`1e-8`	Stopping residual
`max_num_iter`	`int`	`50000`	Maximum CG iterations

Format Conversion¶

`convert_mspincolor_from_wm`¶

convert_mspincolor_from_wm(prop_wm) -> Prop | SelProp | PselProp

Convert a propagator from Wilson-matrix layout (spin-colour interleaved as a 12x12 matrix) to m-spin-colour layout. Accepts Prop, SelProp, or PselProp; returns the same type.

`convert_wm_from_mspincolor`¶

convert_wm_from_mspincolor(prop_msc) -> Prop | SelProp | PselProp

Convert from m-spin-colour layout back to Wilson-matrix layout. Inverse of convert_mspincolor_from_wm.

Fermion Field Utilities¶

`mk_ff_list_from_prop`¶

mk_ff_list_from_prop(prop: Prop) -> list[FermionField4d]

Split a Prop into a list of 12 FermionField4d objects (one per colour-spin column of the Wilson matrix).

`mk_prop_from_ff_list`¶

mk_prop_from_ff_list(ff_list: list[FermionField4d]) -> Prop

Reassemble a Prop from a list of 12 FermionField4d objects. Inverse of mk_ff_list_from_prop.

Miscellaneous¶

`flip_tpbc_with_tslice`¶

flip_tpbc_with_tslice(prop, tslice_flip_tpbc) -> None

Flip the temporal boundary condition at tslice_flip_tpbc for a SelProp or PselProp.

`free_scalar_mom_invert`¶

free_scalar_mom_invert(f: FieldComplexD, mass: float,
                       momtwist: CoordinateD = None) -> None

Apply the free-scalar inverse in momentum space to a complex field f (modified in place). momtwist is passed through to the C++ kernel and defaults to zero when None.

`free_scalar_deriv_mom`¶

free_scalar_deriv_mom(f: FieldComplexD, deriv, momtwist: CoordinateD = None, *,
                      even_deriv_kernel: str = None) -> None

Apply a lattice derivative in momentum space to a complex field f (modified in place). f must already be in momentum space (e.g. the output of a normalizing forward FFT). deriv gives the derivative order for each direction x, y, z, t. Writing deriv[mu] = 2 m + e with e in {0, 1}, the field is multiplied by

prod_mu [ d_even(k_mu)^m ( i sin(k_mu) )^e ],
k_mu = 2 pi ( smod(n_mu, L_mu) + momtwist_mu ) / L_mu

smod is the signed momentum index (folded to [-L/2, L/2)), matching the convention used by free_scalar_mom_invert.

The leftover odd factor i sin(k_mu) is the symmetric (central) difference factor, so deriv = [1, 0, 0, 0] is the central difference in the x direction. even_deriv_kernel selects the even kernel d_even:

"central" (the default, also None): d_even = ( i sin(k_mu) )^2 = -sin^2(k_mu), the square of the odd kernel, so every order is a power of the symmetric difference factor i sin(k_mu). With this choice deriv[mu] = 2 is the square of the central difference, (f(x+2) - 2 f(x) + f(x-2)) / 4, and it does not match the D(k) of free_scalar_mom_invert.
"half": d_even = ( 2 i sin(k_mu / 2) )^2 = -4 sin^2(k_mu / 2). This is the lattice laplacian factor: it is minus the mu term of the D(k) used by free_scalar_mom_invert, so even derivative orders are the laplacian powers — in particular deriv[mu] = 2 is exactly minus the mu term of the laplacian.

At the self-conjugate momentum k_mu = pi (smod(n_mu, L_mu) + momtwist_mu = +- L_mu / 2) the odd factor i sin(k_mu) vanishes; it is set to exactly 0 there, so that mode is dropped for an odd deriv[mu]. With even_deriv_kernel="central" the even kernel is its square, so the mode is dropped for an even deriv[mu] as well; with "half" the mode is kept.

This is the bare derivative factor: it contains no mass and no 1 / D(k). Compose it with free_scalar_mom_invert to differentiate the free scalar inverse — the two factors commute, so the order does not matter:

f = q.mk_fft(is_forward=True, is_normalizing=True) * src
q.free_scalar_deriv_mom(f, [1, 0, 0, 0], momtwist)
q.free_scalar_mom_invert(f, mass, momtwist)
sol = q.mk_fft(is_forward=False, is_normalizing=True) * f

deriv=None is equivalent to [0, 0, 0, 0] and leaves f unchanged.

`free_scalar_invert`¶

free_scalar_invert(src: FieldComplexD, mass: float, *,
                   momtwist: CoordinateD = None,
                   mode_fft: int = 1) -> FieldComplexD

Compute the free-scalar inverse of a complex field in position space. Transforms to momentum space, applies the inverse, and transforms back. momtwist is passed through to free_scalar_mom_invert.

`free_scalar_invert_deriv`¶

free_scalar_invert_deriv(src: FieldComplexD, mass: float, *,
                         momtwist: CoordinateD = None,
                         mode_fft: int = 1,
                         deriv=None,
                         even_deriv_kernel: str = None) -> FieldComplexD

Position-space entry point for the derivative of the free scalar inverse. Transforms src to momentum space, applies free_scalar_deriv_mom with the orders deriv, applies free_scalar_mom_invert, and transforms back. The derivative and the inverse commute, so this equals the free scalar inverse of the derivative source as well. Each order is split into an even power of d_even(k_mu) and, for an odd order, one symmetric (central) difference factor i sin(k_mu); even_deriv_kernel selects d_even ("central", the default, or "half" — see free_scalar_deriv_mom). So deriv=[1, 0, 0, 0] is the central difference in the x direction, while deriv=[2, 0, 0, 0] is the square of the central difference with "central" and minus the x term of the laplacian with "half":

sol = q.free_scalar_invert_deriv(src, mass, deriv=[1, 0, 0, 0], momtwist=t)
sol2 = q.free_scalar_invert_deriv(
    src, mass, deriv=[2, 0, 0, 0], even_deriv_kernel="half"
)

deriv=None is equivalent to [0, 0, 0, 0], in which case the result equals free_scalar_invert(src, mass, ...).

Examples¶

Point Source and Free Inversion¶

import qlat as q
import numpy as np

size_node_list = [[1, 1, 1, 1]]

q.begin_with_mpi(size_node_list)

total_site = q.Coordinate([4, 4, 4, 8])
geo = q.Geometry(total_site)
xg = q.Coordinate([0, 0, 0, 0])

prop_src = q.mk_point_src(geo, xg)
prop_sol = q.free_invert(prop_src, mass=0.1)

wm = prop_sol.get_elem_wm(0)
print("Wilson matrix at site 0 shape:", np.asarray(wm).shape)

q.end_with_mpi()

Wall Source with Momentum¶

import qlat as q

size_node_list = [[1, 1, 1, 1]]

q.begin_with_mpi(size_node_list)

total_site = q.Coordinate([4, 4, 4, 8])
geo = q.Geometry(total_site)

lmom = q.CoordinateD([0.0, 0.0, 0.0, 0.0])
prop_src = q.mk_wall_src(geo, tslice=0, lmom=lmom)

print("Wall source created on geometry:", geo)

q.end_with_mpi()

Random U1 Source with Selection¶

import qlat as q

size_node_list = [[1, 1, 1, 1]]

q.begin_with_mpi(size_node_list)

total_site = q.Coordinate([4, 4, 4, 8])
geo = q.Geometry(total_site)

# Create a points selection
n_points = 8
psel = q.PointsSelection(total_site, [q.Coordinate([0, 0, 0, i]) for i in range(n_points)])

rs = q.RngState("test-seed")
prop_src, fu1 = q.mk_rand_u1_src(psel, rs)

print("Source prop type:", type(prop_src).__name__)
print("U1 field type:", type(fu1).__name__)

q.end_with_mpi()

Splitting and Reassembling a Propagator¶

import qlat as q

size_node_list = [[1, 1, 1, 1]]

q.begin_with_mpi(size_node_list)

total_site = q.Coordinate([4, 4, 4, 8])
geo = q.Geometry(total_site)

prop_src = q.mk_point_src(geo, q.Coordinate([0, 0, 0, 0]))
prop_sol = q.free_invert(prop_src, mass=0.1)

# Split into 12 fermion fields
ff_list = q.mk_ff_list_from_prop(prop_sol)
print(f"Number of fermion fields: {len(ff_list)}")

# Reassemble
prop_rebuilt = q.mk_prop_from_ff_list(ff_list)

q.end_with_mpi()

Pickle Round-Trip¶

import qlat as q
import pickle

size_node_list = [[1, 1, 1, 1]]

q.begin_with_mpi(size_node_list)

total_site = q.Coordinate([4, 4, 4, 8])
geo = q.Geometry(total_site)

prop = q.mk_point_src(geo, q.Coordinate([0, 0, 0, 0]))

data = pickle.dumps(prop)
prop2 = pickle.loads(data)

print("Pickle round-trip succeeded")

q.end_with_mpi()

qlat.propagator — Propagator Types and Utilities¶

Outline¶

Overview¶

Propagator Classes¶

Prop¶

Constructors¶

Methods¶

SelProp¶

Constructors¶

Methods¶

PselProp¶

Constructors¶

Methods¶

SpinProp¶

Constructors¶

Methods¶

FermionField4d¶

Constructors¶

Source Construction¶

set_point_src¶

set_wall_src¶

mk_point_src¶

mk_wall_src¶

set_rand_vol_u1 / mk_rand_vol_u1¶

set_rand_vol_u1_src / mk_rand_vol_u1_src¶

mk_rand_u1_src¶

get_rand_u1_sol¶

mk_rand_u1_prop¶

Inversion Functions¶

free_invert¶

free_mom_invert¶

invert_qed¶

Format Conversion¶

convert_mspincolor_from_wm¶

convert_wm_from_mspincolor¶

Fermion Field Utilities¶

mk_ff_list_from_prop¶

mk_prop_from_ff_list¶

Miscellaneous¶

flip_tpbc_with_tslice¶

free_scalar_mom_invert¶

free_scalar_deriv_mom¶

free_scalar_invert¶

free_scalar_invert_deriv¶

Examples¶

Point Source and Free Inversion¶

Wall Source with Momentum¶

Random U1 Source with Selection¶

Splitting and Reassembling a Propagator¶

Pickle Round-Trip¶

`qlat.propagator` — Propagator Types and Utilities¶

`Prop`¶

`SelProp`¶

`PselProp`¶

`SpinProp`¶

`FermionField4d`¶

`set_point_src`¶

`set_wall_src`¶

`mk_point_src`¶

`mk_wall_src`¶

`set_rand_vol_u1` / `mk_rand_vol_u1`¶

`set_rand_vol_u1_src` / `mk_rand_vol_u1_src`¶

`mk_rand_u1_src`¶

`get_rand_u1_sol`¶

`mk_rand_u1_prop`¶

`free_invert`¶

`free_mom_invert`¶

`invert_qed`¶

`convert_mspincolor_from_wm`¶

`convert_wm_from_mspincolor`¶

`mk_ff_list_from_prop`¶

`mk_prop_from_ff_list`¶

`flip_tpbc_with_tslice`¶

`free_scalar_mom_invert`¶

`free_scalar_deriv_mom`¶

`free_scalar_invert`¶

`free_scalar_invert_deriv`¶