dqmc: Instructions file for Codex

AGENTS.md

Operating manual for LLM agents working with this DQMC codebase.

Mission & Boundaries

What this repo does: Determinantal Quantum Monte Carlo (DQMC) simulation for the Hubbard model. High-performance C code with Python utilities for simulation setup and data analysis.

Agent modes:

• Mode A: Code Development - Editing C/Python code, running tests, refactoring. Check .claude/skills/dqmc-dev/ first.
• Mode B: Simulation & Analysis - Generating sim files, running DQMC, analyzing results. Check .claude/skills/ for the relevant runbook before starting.

CRITICAL: Skills First This repository contains optimized runbooks in .claude/skills/.

• NEVER manually script parallel runs or parameter sweeps without first consulting dqmc-run and dqmc-parameter-scans.
• Use the built-in dqmc-util queue and worker system as documented in the skills.
• Default rule: if you are running 2+ HDF5 files, use dqmc-util enqueue + dqmc-util worker (even on a local workstation). Avoid ad-hoc for loops unless explicitly requested.

Generally avoid:

• Deleting or overwriting existing HDF5 data files
• Changing default parameter values in gen_1band_hub.py
• Running simulations with n_sweep_meas > 10000
• Creating new virtual environments

---

Quickstart Commands

# Environment setup
conda activate dqmc
make deps          # first time only: downloads HDF5

# Build
make               # -> build/dqmc
make clean         # remove build/

# Test
cd test && make && ./test_greens   # unit tests

# Smoke run (minimal simulation)
dqmc-util gen Nx=4 Ny=4 U=4 L=20 n_sweep_warm=50 n_sweep_meas=100
build/dqmc sim_0.h5
dqmc-util summary sim_0.h5

---

Repository Map

├── src/                    # C source code
│   ├── main_1.c           # Entry point
│   ├── wrapper.c          # Dispatches to real/complex
│   ├── mem.c/h            # Memory allocation (64-byte aligned)
│   ├── prof.c/h           # Profiling infrastructure
│   └── rc/                # Real/Complex dual-compiled code
│       ├── dqmc.c         # Main sweep loop
│       ├── greens.c/h     # Green's function calculation
│       ├── updates.c/h    # Delayed update scheme
│       ├── meas.c/h       # Measurements (equal/unequal time)
│       ├── data.c/h       # HDF5 I/O
│       ├── sim_types.h    # X-macro parameter/measurement definitions
│       ├── linalg.h       # BLAS/LAPACK wrappers
│       └── numeric.h      # RC() macro for real/complex dispatch
│
├── dqmc_util/              # Python package (pip install -e .)
│   ├── cli.py             # CLI entry point (dqmc-util)
│   ├── gen_1band_hub.py   # Simulation file generation
│   ├── analyze_hub.py     # Analysis routines with @observable pattern
│   ├── core.py            # Jackknife resampling, data loading
│   ├── queue.py           # Sharded queue for clusters
│   └── worker.py          # Worker process management
│
├── test/                   # Tests
│   ├── test_greens.c      # Green's function tests
│   └── bench_linalg.c     # BLAS benchmarks
│
├── examples/               # Complete workflow examples
│   ├── mz2_vs_T/          # Magnetic moment vs temperature
│   └── n_vs_mu/           # Density vs chemical potential
│
├── build/dqmc             # Compiled binary (after make)
└── .claude/skills/         # Agent Skills (agentskills format)
    ├── dqmc-generate/      # Create simulation files
    ├── dqmc-run/           # Run simulations (checkpointing, queue)
    ├── dqmc-analyze/       # Analyze results
    ├── dqmc-parameter-scans/ # Parameter sweeps
    ├── dqmc-dev/           # Code development workflow
    └── dqmc-advanced/      # Unequal-time, MaxEnt