Run Simulations

Inputs

• HDF5 simulation file(s) from the dqmc-generate and dqmc-parameter-scans skills
• Binary at build/dqmc, worker utility from dqmc-util worker

Outputs

• Updated HDF5 files with measurements in /meas_eqlt/ (and /meas_uneqlt/ if enabled)

Decision Rules (single vs queue)

• Exactly 1 file: run it directly with build/dqmc sim_0.h5.
• 2+ files: use the queue/worker system (dqmc-util enqueue + dqmc-util worker) even on a local workstation.
  • This avoids ad-hoc shell loops, makes restarts/checkpointing consistent, and scales to parallel execution safely.

Procedure

Single file:

build/dqmc sim_0.h5

With checkpointing (long runs):

build/dqmc -s 300 -t 3600 sim_0.h5  # checkpoint every 300 seconds, max runtime 3600 seconds

Multiple files (queue system):

# 1. Add files to queue/ (globs are expanded by Python, so quote them)
dqmc-util enqueue queue 'data/run/bin_*.h5'

# 2. Start workers
dqmc-util worker queue ./build/dqmc -n 8 -s 300 -t 3600  # 8 parallel workers

Multiple files (local temperature scan example):

# enqueue all bins across temperatures
dqmc-util enqueue queue 'runs/pi_pi_U8_6x6/T*/bin_*.h5'

# run N workers in parallel (pick N for your machine)
dqmc-util worker queue ./build/dqmc -n 8 -s 300 -t 3600

Validation (single file)

dqmc-util summary sim_0.h5

For multiple files:

dqmc-util print-n data/run/   # directory paths should end with '/'

Failure Modes

Symptom	Cause	Recovery
"opening... failed"	File doesn't exist	Check path
NaN in output	Numerical instability	Reduce dt and/or n_matmul. Check parameters
Killed by scheduler	Exceeded time limit	Use -t flag, checkpoint enabled
Large errorbars	Sign problem	Add more sweeps and/or bins

Do Not

• Kill running simulations without checkpointing (-s flag)
• Run multiple workers on the same file
• Use manual shell loops for 2+ files (prefer dqmc-util enqueue + dqmc-util worker)