auto_contractor.runtime — Runtime for Compiled Expression Evaluation

Source: qlat/auto_contractor/runtime.py

Note: Update this document when updating the source file.

Outline

1. Overview

2. Exported Names

   • NumPy and Timers

   • AMA Utilities

   • Matrix Types

   • Matrix Operations

   • Gamma and Propagator Utilities

3. Usage

4. Examples

---

Overview

runtime re-exports the symbols needed at runtime by compiled auto-contractor expressions (CExpr). When a CExpr is evaluated, it uses functions and types from this module to load propagators, perform matrix arithmetic, and compute traces. Importing this module ensures all required runtime dependencies are available.

Exported Names

NumPy and Timers

Name	Source	Description
np	numpy	NumPy array library
timer	qlat.timer	Scope-based timer decorator
timer_flops	qlat.timer_flops	Timer with FLOPS counting

AMA Utilities

Name	Source	Description
ama_list	qlat_utils.ama	Accumulate multi-shift solver results
ama_apply1	qlat_utils.ama	Apply AMA correction to a single result
ama_counts	qlat_utils.ama	Count AMA samples
ama_extract	qlat_utils.ama	Extract corrected value from AMA list

Matrix Types

Name	Source	Description
WilsonMatrix	qlat_utils	\(4\times3\) spin-color matrix (propagator element)
SpinMatrix	qlat_utils	\(4\times4\) spin matrix (gamma matrices)
ColorMatrix	qlat_utils	\(3\times3\) color matrix (gauge links)

Matrix Operations

All mat_* functions are low-level C++ routines exposed via qlat_utils:

Trace operations:

Function	Description
mat_tr_sm(m)	Trace of SpinMatrix
mat_tr_cm(m)	Trace of ColorMatrix
mat_tr_wm(m)	Trace of WilsonMatrix
mat_tr_wm_wm(a, b)	Trace of product \(\mathrm{tr}(A \cdot B)\), both WilsonMatrix
mat_tr_wm_sm(a, b)	Trace of WilsonMatrix times SpinMatrix
mat_tr_sm_wm(a, b)	Trace of SpinMatrix times WilsonMatrix
mat_tr_sm_sm(a, b)	Trace of SpinMatrix times SpinMatrix
mat_tr_wm_cm(a, b)	Trace of WilsonMatrix times ColorMatrix
mat_tr_cm_wm(a, b)	Trace of ColorMatrix times WilsonMatrix
mat_tr_cm_cm(a, b)	Trace of ColorMatrix times ColorMatrix

Multiplication operations:

Function	Description
mat_mul_a_wm(a, m)	Scalar times WilsonMatrix
mat_mul_a_sm(a, m)	Scalar times SpinMatrix
mat_mul_a_cm(a, m)	Scalar times ColorMatrix
mat_mul_wm_wm(a, b)	WilsonMatrix times WilsonMatrix
mat_mul_wm_sm(a, b)	WilsonMatrix times SpinMatrix
mat_mul_sm_wm(a, b)	SpinMatrix times WilsonMatrix
mat_mul_sm_sm(a, b)	SpinMatrix times SpinMatrix
mat_mul_wm_cm(a, b)	WilsonMatrix times ColorMatrix
mat_mul_cm_wm(a, b)	ColorMatrix times WilsonMatrix
mat_mul_cm_cm(a, b)	ColorMatrix times ColorMatrix

Addition operations:

Function	Description
mat_add_wm_wm(a, b)	WilsonMatrix + WilsonMatrix
mat_add_sm_sm(a, b)	SpinMatrix + SpinMatrix
mat_add_cm_cm(a, b)	ColorMatrix + ColorMatrix

Special operations:

Function	Description
mat_epsilon_contraction_wm_wm_wm(a, b, c)	\(\epsilon_{ijk}\) contraction of three WilsonMatrix objects

Gamma and Propagator Utilities

Function	Description
load_prop(...)	Load a propagator from disk
get_gamma_matrix(tag)	Get gamma matrix by tag (0–3, 5)
wilson_matrix_g5_herm(m)	Compute \(\gamma_5 m^\dagger \gamma_5\)

Auto-contractor Functions

Name	Description
aff	auto_contractor.auto_fac_funcs module — callable functions for CExpr evaluation

Usage

The runtime module is typically imported by compiled expression code, not directly by users:

from qlat.auto_contractor.runtime import *

Examples

import qlat as q
q.begin_with_mpi([[1, 1, 1, 4]])

from qlat.auto_contractor.runtime import (
    WilsonMatrix, SpinMatrix, get_gamma_matrix,
    mat_tr_wm_wm, mat_mul_wm_sm,
)

# Create a WilsonMatrix and multiply by gamma_5
wm = WilsonMatrix()
g5 = get_gamma_matrix(5)
result = mat_mul_wm_sm(wm, g5)
trace = mat_tr_wm_wm(result, wm)

q.end_with_mpi()