`qlat.qlat_gpt` — GPT–Qlattice Interoperability¶

Source: qlat/qlat_gpt.py

Note: Update this document when updating the source file.

Overview¶

qlat_gpt bridges the GPT (Grid) lattice framework and Qlattice’s field types. It provides:

MPI initialization that coordinates GPT’s Grid layout with Qlattice’s node geometry.
Zero-copy-style field conversion between GPT lattice objects and Qlattice Field / GaugeField / Prop / FermionField4d / FieldComplexD via cached g.copy_plan objects.
Inverter and eigensystem wrappers (InverterGPT, EigSystemGPT, EigSystemCompressedGPT) that adapt GPT’s linear-algebra solvers to Qlattice’s Inverter / EigSystem interfaces.
Coulomb gauge fixing (gauge_fix_coulomb) built on GPT’s Landau fixing with split-grid acceleration and a custom non-linear CG optimizer.
NERSC gauge field I/O via GPT’s format support.

Initialization¶

`begin_with_gpt()`¶

Initialize both GPT and Qlattice runtimes. Must be called before any other Qlattice or GPT operation.

Creates a GPT grid (from --grid argument or a default 288×288×288×576 lattice).
Derives size_node, coor_node, and id_node from the GPT grid’s MPI layout.
Calls q.begin() and q.set_comm() with the appropriate MPI communicator.

`end_with_gpt()`¶

Tear down both runtimes. Frees the Qlattice communicator and calls q.end().

import qlat_gpt as qg
qg.begin_with_gpt()
# ... work ...
qg.end_with_gpt()

Field Conversion¶

Generic Converters¶

`qlat_from_gpt(gpt_obj) → object`¶

Auto-detect the GPT object type and convert it to the corresponding Qlattice type:

GPT type	Qlattice type
`list[4]` of `mcolor`	`GaugeField`
`mcolor` (single)	`GaugeTransform`
`mspincolor`	`Prop`
`vspincolor`	`FermionField4d`
`list` of `complex`	`FieldComplexD`
`list` of any above	`list` of converted elements

Raises Exception for unrecognized types.

`gpt_from_qlat(obj) → object`¶

Reverse of qlat_from_gpt. Auto-detects Qlattice types (Prop, GaugeTransform, GaugeField, FermionField4d, FieldComplexD) and converts to the GPT equivalent. Lists are converted element-wise.

Gauge Fields¶

`qlat_from_gpt_gauge_field(gpt_gf) → GaugeField`¶

Convert a list of 4 GPT mcolor fields (one per direction μ=0,1,2,3) into a single Qlattice GaugeField with multiplicity 4. Each direction is converted individually via a cached copy plan, then merged with q.merge_fields.

`gpt_from_qlat_gauge_field(gf) → list[mcolor]`¶

Split a Qlattice GaugeField into 4 single-direction FieldColorMatrix objects, then convert each to a GPT mcolor field.

Gauge Transforms¶

`qlat_from_gpt_gauge_transform(gpt_gt) → GaugeTransform`¶

Convert a single GPT mcolor field into a Qlattice GaugeTransform.

`gpt_from_qlat_gauge_transform(gt) → mcolor`¶

Convert a Qlattice GaugeTransform into a GPT mcolor field.

Propagators¶

`qlat_from_gpt_prop(gpt_prop) → Prop`¶

Convert a GPT mspincolor propagator to a Qlattice Prop (WilsonMatrix). Internally converts through mspincolor → WilsonMatrix via q.convert_wm_from_mspincolor.

`gpt_from_qlat_prop(prop_wm) → mspincolor`¶

Convert a Qlattice Prop to a GPT mspincolor. Uses q.convert_mspincolor_from_wm before the copy plan.

Fermion Fields¶

`qlat_from_gpt_ff4d(gpt_ff) → FermionField4d`¶

Convert a GPT vspincolor field to a Qlattice FermionField4d.

`gpt_from_qlat_ff4d(ff) → vspincolor`¶

Convert a Qlattice FermionField4d to a GPT vspincolor.

Complex Fields¶

`qlat_from_gpt_complex(gpt_fcs) → FieldComplexD`¶

Convert a list of GPT complex fields into a single Qlattice FieldComplexD. If the list has one element, returns a multiplicity-1 field. Otherwise, converts each element separately and merges into a higher-multiplicity field.

`gpt_from_qlat_complex(fc) → list[complex]`¶

Split a Qlattice FieldComplexD (possibly multi-multiplicity) into individual GPT complex fields.

Copy Plans¶

The conversion functions all use GPT’s g.copy_plan mechanism for efficient data transfer. Plans are created once and cached.

`mk_qlat_gpt_copy_plan_key(ctype, total_site, multiplicity, tag) → str`¶

Build a cache key string from element type name, total site, multiplicity, and direction tag ("qlat_from_gpt" or "gpt_from_qlat").

`mk_qlat_gpt_copy_plan(ctype, total_site, multiplicity, tag) → copy_plan`¶

Create a GPT copy_plan that maps between a GPT lattice field (in lexicographic order) and a Qlattice memoryview buffer. The plan is built by:

Creating temporary GPT and Qlattice fields.
Collecting lexicographic coordinates from GPT.
Setting up global_memory_view on the Qlattice buffer side.
Associating source/destination views.
Finalizing with local_only=True.

`get_qlat_gpt_copy_plan(ctype, total_site, multiplicity, tag) → copy_plan`¶

Retrieve a cached plan or create and cache a new one.

`mk_gpt_field(ctype, geo) → lattice`¶

Create a GPT lattice field matching the given Qlattice element type:

`ctype`	GPT type
`ElemTypeColorMatrix`	`g.mcolor(grid)`
`ElemTypeWilsonMatrix`	`g.mspincolor(grid)`
`ElemTypeWilsonVector`	`g.vspincolor(grid)`
`ElemTypeComplexD`	`g.complex(grid)`

Type Predicates¶

Functions to identify GPT object types by inspecting describe() strings.

Function	Matches
`is_gpt_prop(obj)`	`ot_matrix_spin_color(4,3);none`
`is_gpt_ff4d(obj)`	`ot_vector_spin_color(4,3);none`
`is_gpt_gauge_field(obj)`	`list[4]` of `ot_matrix_su_n_fundamental_group(3);none`
`is_gpt_gauge_transform(obj)`	`ot_matrix_su_n_fundamental_group(3);none` (single)
`is_gpt_complex(obj)`	`list` of `ot_complex_additive_group;none`

Inverter and Eigensystem¶

InverterGPT¶

class InverterGPT(q.Inverter):
    def __init__(self, *, inverter, qtimer=..., gpt_qtimer=...)

Wraps a GPT inverter (e.g. g.algorithms.inverter) as a Qlattice Inverter. Supports the inv * prop_src syntax:

Converts the Qlattice source to GPT format via gpt_from_qlat.
Applies the GPT inverter: g.eval(inverter * src).
Converts the result back via qlat_from_gpt.

Accepts Prop, FermionField4d, or list as the source operand.

Parameters:

Name	Type	Description
`inverter`	GPT inverter	The GPT linear solver object
`qtimer`	`q.Timer` / `q.TimerNone`	Timer for the full conversion+solve cycle
`gpt_qtimer`	`q.Timer` / `q.TimerNone`	Timer for the GPT solve step only

EigSystemGPT¶

class EigSystemGPT(q.EigSystem):
    def __init__(self, *, evec=None, evals=None)

Stores and I/Os a full eigensystem (eigenvectors + eigenvalues) using GPT’s serialization.

Methods:

Method	Description
`load(path)`	Load eigenvectors and eigenvalues from a GPT file
`save(path)`	Save to a GPT file (no-op if `path` is `None`)

EigSystemCompressedGPT¶

class EigSystemCompressedGPT(q.EigSystem):
    def __init__(self, *, basis=None, cevec=None, evals=None)

Stores a compressed eigensystem (basis + compressed eigenvectors + eigenvalues).

Methods:

Method	Description
`load(path, *, total_site, fermion_params)`	Load with grid reconstruction from fermion parameters
`save(path, *, nsingle, mpi)`	Save with `g.format.cevec` compression

load requires total_site and fermion_params to reconstruct the fermion grid (calls get_fgrid). save takes nsingle (number of single-precision components) and mpi (MPI layout for the format).

Gauge Fixing¶

`gauge_fix_coulomb`¶

def gauge_fix_coulomb(
    gf,
    *,
    gt=None,
    mpi_split=None,
    maxiter_gd=10,
    maxiter_cg=200,
    maxcycle_cg=50000,
    log_every=1,
    eps=1e-12,
    step=0.3,
    step_gd=0.1,
    rng_seed=None,
) -> GaugeTransform

Fix a gauge field to Coulomb gauge using split-grid optimization.

Algorithm:

Convert the Qlattice GaugeField to GPT and separate into time slices.
Split time slices across MPI ranks using g.split with configurable mpi_split.
For each local time slice, run a two-stage optimizer:
- Gradient descent (maxiter_gd iterations) for initial convergence.
- Non-linear CG (maxiter_cg iterations per cycle, up to maxcycle_cg cycles) for refinement.
Use Fourier-accelerated gradients (inverse_phat_square).
Unsplit, project to SU(3), and verify convergence.
Return the gauge transformation as a Qlattice GaugeTransform.

Parameters:

Name	Type	Default	Description
`gf`	`GaugeField`	—	Input gauge field
`gt`	`GaugeTransform`	`None`	Initial guess (unit if `None`)
`mpi_split`	`list[int]`	`[1,1,1]`	Spatial MPI split for the sub-grid
`maxiter_gd`	`int`	`10`	Max gradient descent iterations
`maxiter_cg`	`int`	`200`	Max CG iterations per cycle
`maxcycle_cg`	`int`	`50000`	Max CG restart cycles
`log_every`	`int`	`1`	Log functional every N iterations
`eps`	`float`	`1e-12`	Convergence threshold
`step`	`float`	`0.3`	CG step size
`step_gd`	`float`	`0.1`	Gradient descent step size
`rng_seed`	`str`	`None`	Random seed (no randomization if `None`)

`check_gauge_fix_coulomb`¶

def check_gauge_fix_coulomb(gf, gt, eps=1e-12) -> bool

Verify that a gauge transformation gt fixes gf to Coulomb gauge. Computes the average θ (gradient norm squared per site per color) over all time slices. Returns True if θ < eps.

`non_linear_cg`¶

class non_linear_cg(g.algorithms.base_iterative):
    def __init__(self, params)

Non-linear conjugate gradient optimizer built on GPT’s optimization framework. Used internally by gauge_fix_coulomb.

Parameters:

Name	Type	Default	Description
`eps`	`float`	`1e-8`	Convergence threshold on
`maxiter`	`int`	`1000`	Maximum iterations
`step`	`float`	`1e-3`	Base step size for line search
`log_functional_every`	`int`	`10`	Log interval
`line_search`	callable	`line_search_quadratic`	Line search function
`beta`	callable	`fletcher_reeves`	CG β formula (default Fletcher–Reeves; `gauge_fix_coulomb` uses Polak–Ribière)
`max_c`	`int`	`3`	Maximum line search step multiplier

Returns a callable opt(x, dx) that minimizes f over group-valued x.

`line_search_quadratic`¶

def line_search_quadratic(s, x, dx, dv0, df, step, *, max_c=3)

Quadratic line search used by non_linear_cg. Fits f(x) = a + b*(x-c)^2 from directional derivative sign changes to estimate the minimizer along direction s. Returns the step multiplier c (or None on failure).

Utilities¶

`mk_grid(geo=None) → g.grid`¶

Create a GPT grid object. If geo is provided, uses its total_site. Otherwise reads --grid from command-line arguments, falling back to a default 288×288×288×576 lattice.

`get_fgrid(total_site, fermion_params) → grid`¶

Reconstruct a GPT fermion grid (possibly even-odd) from Qlattice geometry and GPT fermion parameters. Supports both mobius and zmobius (detected by the presence of "omega" in fermion_params).

`save_gauge_field(gf, path)`¶

Save a Qlattice GaugeField to disk in NERSC format via GPT.

`load_gauge_field(path) → GaugeField`¶

Load a gauge field from a NERSC-format file via GPT and return as a Qlattice GaugeField.

Examples¶

Basic setup and field conversion¶

import qlat_gpt as qg
qg.begin_with_gpt()

import qlat as q
import gpt as g

# Load a gauge field from disk
gf = qg.load_gauge_field("config.nersc")

# Convert to GPT for analysis
gpt_gf = qg.gpt_from_qlat(gf)

# ... do GPT-level operations ...

# Convert back to Qlattice
gf2 = qg.qlat_from_gpt(gpt_gf)

qg.end_with_gpt()

Using InverterGPT¶

import qlat_gpt as qg
qg.begin_with_gpt()

import qlat as q
import gpt as g

# Set up a GPT inverter
gpt_gf = qg.gpt_from_qlat(gf)
q = g.qcd.fermion.mobius(gpt_gf, params)
inv = g.algorithms.inverter.cg({"eps": 1e-8, "maxiter": 1000})
prop_sol = g.eval(inv * q.propagator(prop_src))

# Or wrap as Qlattice inverter
qlat_inv = qg.InverterGPT(inverter=inv * q.propagator)
prop_src_qlat = q.Prop(gf.geo)
# ... set up source ...
prop_sol_qlat = qlat_inv * prop_src_qlat

qg.end_with_gpt()

Coulomb gauge fixing¶

import qlat_gpt as qg
qg.begin_with_gpt()

import qlat as q

gf = qg.load_gauge_field("config.nersc")

# Fix to Coulomb gauge
gt = qg.gauge_fix_coulomb(gf, maxiter_cg=200, eps=1e-12)

# Verify
assert qg.check_gauge_fix_coulomb(gf, gt, eps=1e-12)

qg.end_with_gpt()

qlat.qlat_gpt — GPT–Qlattice Interoperability¶

Outline¶

Overview¶

Initialization¶

begin_with_gpt()¶

end_with_gpt()¶

Field Conversion¶

Generic Converters¶

qlat_from_gpt(gpt_obj) → object¶

gpt_from_qlat(obj) → object¶

Gauge Fields¶

qlat_from_gpt_gauge_field(gpt_gf) → GaugeField¶

gpt_from_qlat_gauge_field(gf) → list[mcolor]¶

Gauge Transforms¶

qlat_from_gpt_gauge_transform(gpt_gt) → GaugeTransform¶

gpt_from_qlat_gauge_transform(gt) → mcolor¶

Propagators¶

qlat_from_gpt_prop(gpt_prop) → Prop¶

gpt_from_qlat_prop(prop_wm) → mspincolor¶

Fermion Fields¶

qlat_from_gpt_ff4d(gpt_ff) → FermionField4d¶

gpt_from_qlat_ff4d(ff) → vspincolor¶

Complex Fields¶

qlat_from_gpt_complex(gpt_fcs) → FieldComplexD¶

gpt_from_qlat_complex(fc) → list[complex]¶

Copy Plans¶

mk_qlat_gpt_copy_plan_key(ctype, total_site, multiplicity, tag) → str¶

mk_qlat_gpt_copy_plan(ctype, total_site, multiplicity, tag) → copy_plan¶

get_qlat_gpt_copy_plan(ctype, total_site, multiplicity, tag) → copy_plan¶

mk_gpt_field(ctype, geo) → lattice¶

Type Predicates¶

Inverter and Eigensystem¶

InverterGPT¶

EigSystemGPT¶

EigSystemCompressedGPT¶

Gauge Fixing¶

gauge_fix_coulomb¶

check_gauge_fix_coulomb¶

non_linear_cg¶

line_search_quadratic¶

Utilities¶

mk_grid(geo=None) → g.grid¶

get_fgrid(total_site, fermion_params) → grid¶

save_gauge_field(gf, path)¶

load_gauge_field(path) → GaugeField¶

Examples¶

Basic setup and field conversion¶

Using InverterGPT¶

Coulomb gauge fixing¶

`qlat.qlat_gpt` — GPT–Qlattice Interoperability¶

`begin_with_gpt()`¶

`end_with_gpt()`¶

`qlat_from_gpt(gpt_obj) → object`¶

`gpt_from_qlat(obj) → object`¶

`qlat_from_gpt_gauge_field(gpt_gf) → GaugeField`¶

`gpt_from_qlat_gauge_field(gf) → list[mcolor]`¶

`qlat_from_gpt_gauge_transform(gpt_gt) → GaugeTransform`¶

`gpt_from_qlat_gauge_transform(gt) → mcolor`¶

`qlat_from_gpt_prop(gpt_prop) → Prop`¶

`gpt_from_qlat_prop(prop_wm) → mspincolor`¶

`qlat_from_gpt_ff4d(gpt_ff) → FermionField4d`¶

`gpt_from_qlat_ff4d(ff) → vspincolor`¶

`qlat_from_gpt_complex(gpt_fcs) → FieldComplexD`¶

`gpt_from_qlat_complex(fc) → list[complex]`¶

`mk_qlat_gpt_copy_plan_key(ctype, total_site, multiplicity, tag) → str`¶

`mk_qlat_gpt_copy_plan(ctype, total_site, multiplicity, tag) → copy_plan`¶

`get_qlat_gpt_copy_plan(ctype, total_site, multiplicity, tag) → copy_plan`¶

`mk_gpt_field(ctype, geo) → lattice`¶

`gauge_fix_coulomb`¶

`check_gauge_fix_coulomb`¶

`non_linear_cg`¶

`line_search_quadratic`¶

`mk_grid(geo=None) → g.grid`¶

`get_fgrid(total_site, fermion_params) → grid`¶

`save_gauge_field(gf, path)`¶

`load_gauge_field(path) → GaugeField`¶