qlat.propagator — Propagator Types and Utilities¶
Source: qlat/qlat/propagator.pyx
Note: Update this document when updating the source file.
Outline¶
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 |
|---|---|---|
|
|
Full-volume propagator field |
|
|
Propagator on a |
|
|
Propagator on a |
|
|
Full-volume spin propagator (no colour index) |
|
|
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 |
|---|---|
|
Uninitialized propagator |
|
Allocate on the given geometry |
Methods¶
Method |
Description |
|---|---|
|
Return the Wilson matrix at site |
|
Sum propagator over each time slice, returning a |
|
Pickle support (single-node only) |
SelProp¶
class SelProp(SelectedFieldWilsonMatrix)
Propagator defined on a field selection (a subset of lattice sites).
Constructors¶
Signature |
Description |
|---|---|
|
Uninitialized |
|
Allocate on the selected sites |
Methods¶
Method |
Description |
|---|---|
|
Return the Wilson matrix at selected-site index |
|
Pickle support (single-node only) |
PselProp¶
class PselProp(SelectedPointsWilsonMatrix)
Propagator defined on a points selection (an ordered list of sites).
Constructors¶
Signature |
Description |
|---|---|
|
Uninitialized |
|
Allocate for the given point set |
|
Must have |
|
Copy selected sites from a |
Methods¶
Method |
Description |
|---|---|
|
Return the Wilson matrix at point index |
|
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 |
|---|---|
|
Uninitialized |
|
Allocate on the given geometry |
Methods¶
Method |
Description |
|---|---|
|
Return the spin matrix at site |
|
Sum over each time slice |
|
Pickle support (single-node only) |
FermionField4d¶
class FermionField4d(FieldWilsonVector)
A single 12-component fermion field (one WilsonVector per site).
Constructors¶
Signature |
Description |
|---|---|
|
Uninitialized |
|
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 |
|---|---|---|---|
|
|
— |
Source field |
|
|
— |
Fermion mass |
|
|
|
Fifth-dimensional mass for DWF |
|
|
|
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 |
|---|---|---|---|
|
|
— |
Source field, in momentum space |
|
|
— |
Fermion mass |
|
|
|
Fifth-dimensional mass for DWF |
|
|
|
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 |
|---|---|---|---|
|
|
— |
Spin-propagator source |
|
|
— |
Left-expanded QED gauge field |
|
|
— |
Fermion mass |
|
|
— |
DWF fifth-dimensional mass |
|
|
— |
Fifth-dimensional extent |
|
array-like |
|
Optional Wick rotation phase factors per time slice |
|
|
|
Whether to use the conjugate operator |
|
|
|
Stopping residual |
|
|
|
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) -> 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, and the field is multiplied by
prod_mu ( 2 i sin(k_mu / 2) )^{deriv[mu]}, 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; this matters here because
2 i sin(k_mu / 2) is odd in k_mu.
At the self-conjugate momentum k_mu = pi (smod(n_mu, L_mu) + momtwist_mu = +- L_mu / 2) the two branches of 2 i sin(k_mu / 2) under k_mu -> k_mu + 2 pi differ by a sign. For an odd deriv[mu] that sign is ambiguous, so
the mode is dropped (d_mu = 0); for an even deriv[mu] the sign squares
out and 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. Note
d_mu^2 = -4 sin^2(k_mu / 2), i.e. minus the mu term of the D(k) used by
free_scalar_mom_invert, so deriv[mu] = 2 gives minus that Laplacian term.
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) -> 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:
sol = q.free_scalar_invert_deriv(src, mass, deriv=[1, 0, 0, 0], momtwist=t)
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()