qlat.hmc_stats — HMC Diagnostic and Analysis Utilities

Source: qlat/qlat/hmc_stats.py

Note: Update this document when updating the source file.

Outline

1. Overview

2. Functions

   • Force Magnitude Inspection

   • Gauge-Field Info with Wilson Flow

3. Examples

---

Overview

hmc_stats provides diagnostic utilities for monitoring and analysing Hybrid Monte Carlo (HMC) trajectories. The functions wrap C/C++ routines exposed through qlat.c and are typically called during or after HMC evolution to:

• Inspect the magnitude distribution of the molecular-dynamics force across lattice sites.

• Save accumulated force-magnitude data to files for post-processing.

• Generate gauge-field information tables augmented with Wilson-flow energy density measurements.

All functions depend on the HMC machinery from qlat.hmc (imported via from qlat.hmc import *).

---

Functions

Force Magnitude Inspection

get_gm_force_magnitudes(gm_force, n_elems)

get_gm_force_magnitudes(gm_force: GaugeMomentum, n_elems: int) -> list

Compute and return the magnitude distribution of the gauge-momentum force field. The force magnitude is binned into n_elems categories.

Parameter	Type	Description
gm_force	GaugeMomentum	The molecular-dynamics force field
n_elems	int	Number of magnitude bins

Returns a list of magnitude values.

display_gm_force_magnitudes(gm_force, n_elems)

display_gm_force_magnitudes(gm_force: GaugeMomentum, n_elems: int) -> None

Compute the force magnitude distribution and display it to the log output. Internally calls the C function and prints the result.

Parameter	Type	Description
gm_force	GaugeMomentum	The molecular-dynamics force field
n_elems	int	Number of magnitude bins

save_gm_force_magnitudes_list(fn)

save_gm_force_magnitudes_list(fn: str) -> None

Save the accumulated list of gauge-momentum force magnitudes to a file. Creates parent directories if needed.

Parameter	Type	Description
fn	str	Output file path

---

Gauge-Field Info with Wilson Flow

display_gauge_field_info_table_with_wilson_flow(fn_gf_info, fn_wilson_flow_energy, gf, flow_time, flow_steps, steps, c1=0.0)

display_gauge_field_info_table_with_wilson_flow(
    fn_gf_info: str,
    fn_wilson_flow_energy: str,
    gf: GaugeField,
    flow_time: float,
    flow_steps: int,
    steps: int,
    c1: float = 0.0,
) -> None

Generate a gauge-field information table with Wilson-flow energy density measurements. Applies Wilson flow to gf and records both plaquette-based observables and the flowed energy density at each step.

Parameter	Type	Default	Description
fn_gf_info	str	—	Output path for gauge-field info table
fn_wilson_flow_energy	str	—	Output path for Wilson-flow energy data
gf	GaugeField	—	Gauge field to analyse
flow_time	float	—	Total Wilson flow time
flow_steps	int	—	Number of flow steps
steps	int	—	Number of measurement intervals
c1	float	0.0	Symanzik improvement coefficient

---

Examples

Inspecting Force Magnitudes During HMC

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)
rs = q.RngState("force-test")

gf = q.GaugeField(geo)
gf.set_unit()

ga = q.GaugeAction(6.0)
gm = q.GaugeMomentum(geo)
q.set_rand_gauge_momentum(gm, 1.0, rs.split("gm"))

q.set_gm_force(gm, gf, ga)
q.display_gm_force_magnitudes(gm, 5)

q.end_with_mpi()

Wilson-Flow Analysis After HMC Trajectories

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)
rs = q.RngState("hmc-wflow")

gf = q.GaugeField(geo)
gf.set_unit()

ga = q.GaugeAction(5.5)

for traj in range(3):
    q.run_hmc_pure_gauge(
        gf, ga, traj, rs.split(f"traj-{traj}"), is_always_accept=True
    )
    plaq = q.gf_avg_plaq(gf)
    print(f"traj={traj}  plaq={plaq:.12E}")

    q.display_gauge_field_info_table_with_wilson_flow(
        f"results/gf_info/traj={traj}.lat",
        f"results/wilson_flow_energy/traj={traj}.lat",
        gf,
        0.1,
        5,
        2,
    )

q.end_with_mpi()

Saving Force Magnitude Data

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)
rs = q.RngState("save-force")

gf = q.GaugeField(geo)
gf.set_unit()

ga = q.GaugeAction(6.0)
gm = q.GaugeMomentum(geo)

for traj in range(3):
    q.run_hmc_pure_gauge(
        gf, ga, traj, rs.split(f"traj-{traj}"), is_always_accept=True
    )
    q.set_gm_force(gm, gf, ga)
    q.display_gm_force_magnitudes(gm, 5)

q.save_gm_force_magnitudes_list("results/gm_force_info/all.dat")

q.end_with_mpi()