Source code for utils.efficiency_runner

"""
Shared machinery for the Wolff-versus-Metropolis efficiency comparison.

The comparison asks the same question of every model here: at a given
temperature, how many statistically independent configurations per second of
wall-clock time does a local update deliver, and how many does the cluster
update deliver?  Nothing in that measurement is model-specific except the
simulation class and where the interesting temperature window lies, so the
worker, the figure, and the argument surface live here and each model script
supplies only its own physics.

Comparing raw autocorrelation times across the two algorithms would be
meaningless, because one Wolff step touches a cluster and one Metropolis sweep
touches the whole lattice.  The Wolff run therefore records one sample every
``round(L^2 / <C>)`` cluster flips, roughly one lattice sweep of work, so that
both algorithms receive the same measurement budget in sweep units; giving
both the same number of raw steps would leave Wolff with a few sweeps of work
in the paramagnet, where clusters hold a handful of spins.  ``tau_wolff`` is
stored in cluster flips as before, and the work-normalised time multiplies it
by the mean cluster fraction, putting both algorithms on a lattice-sweep
footing; the independent-samples-per-second figure sidesteps the question
entirely by measuring against the clock.
"""
from __future__ import annotations

import argparse
import logging
import os
import time
from typing import Any, NamedTuple, cast

import matplotlib.pyplot as plt
import numpy as np

from utils.equilibration import prepare_equilibrated_simulation
from utils.exceptions import ZeroVarianceAutocorrelationError
from utils.observables import calculate_thermodynamics
from utils.statistics import (
    DEFAULT_CONFIDENCE_LEVEL,
    UNCERTAINTY_METHOD_REPLICATE,
    calculate_autocorr,
    summarize_replicate_samples,
)
from utils.sweep_helpers import derive_point_seed
from utils.system import parallel_sweep, setup_logging

#: Quantities the worker reports per (temperature, seed) point.
_MEASURED_KEYS = (
    'tau_metro', 'tau_wolff', 'iss_metro', 'iss_wolff',
    'mean_cluster_frac', 'chi_metro', 'chi_wolff',
    'wolff_flips_per_sample', 'converged_metro', 'converged_wolff',
)

#: Cluster sizes are measured in a separate short pass so that the timing runs
#: stay free of the per-step bookkeeping the cluster record would add. The
#: same pass sets how many cluster flips make up one sweep-equivalent sample.
_CLUSTER_PASS_STEPS = 300


[docs] class EfficiencyPoint(NamedTuple): """ Typed worker payload for one (temperature, seed) efficiency measurement. Parameters ---------- temp_idx : int Index of this temperature in the sweep grid. seed_idx : int Replica index within the seed ensemble for this temperature. temperature : float Simulation temperature T. size : int Linear lattice dimension L. eq_probe_steps : int Chunk size for the two-start convergence check. eq_max_steps : int Hard cap on equilibration steps. meas_steps : int Timed measurement steps per algorithm. model_cls : type Simulation class to instantiate. It must be importable under its qualified name so that it survives the multiprocessing pickle. model_kwargs : dict[str, typing.Any] Extra constructor arguments beyond size, temperature, update, start, and seed. detect_stuck : bool Enable quasi-steady stuck detection for both equilibrations; set only below the ordering temperature of a model with metastable domain states (default False). """ temp_idx: int seed_idx: int temperature: float size: int eq_probe_steps: int eq_max_steps: int meas_steps: int model_cls: type model_kwargs: dict[str, Any] detect_stuck: bool = False
def _equilibrated_simulation( *, point: EfficiencyPoint, update: str, seed: int, ) -> tuple[Any, bool]: """ Build a two-start pair, equilibrate it, and return the start to measure. Parameters ---------- point : EfficiencyPoint Payload describing the measurement. update : str Update scheme for both simulations. seed : int Seed of the random start; the ordered start derives its own. Returns ------- tuple[typing.Any, bool] The simulation to measure (the random start after convergence, the ordered start otherwise) and whether the pair is certified for measurement (``TwoStartOutcome.certified``). """ sim, outcome = prepare_equilibrated_simulation( model_cls=point.model_cls, model_kwargs=point.model_kwargs, size=point.size, temp=point.temperature, seed=seed, chunk_size=point.eq_probe_steps, max_steps=point.eq_max_steps, update=update, detect_stuck=point.detect_stuck, ) return sim, bool(outcome.certified) def _record_samples( *, sim: Any, n_samples: int, steps_per_sample: int, ) -> tuple[np.ndarray, np.ndarray, float]: """ Record magnetisation and energy every ``steps_per_sample`` steps, timed. Parameters ---------- sim : typing.Any Equilibrated simulation to measure. n_samples : int Number of samples to record. steps_per_sample : int Steps between two samples; 1 reproduces ``sim.run``. Returns ------- tuple[np.ndarray, np.ndarray, float] Magnetisation series, energy series, and elapsed wall-clock seconds. """ started = time.perf_counter() if steps_per_sample == 1: mags, engs = sim.run(n_steps=n_samples) elapsed = time.perf_counter() - started return np.asarray(mags), np.asarray(engs), elapsed mags_arr = np.empty(n_samples) engs_arr = np.empty(n_samples) for k in range(n_samples): for _ in range(steps_per_sample): sim.step() mags_arr[k] = sim.get_magnetization() engs_arr[k] = sim.get_energy() elapsed = time.perf_counter() - started return mags_arr, engs_arr, elapsed def _timed_measurement( *, sim: Any, meas_steps: int, temperature: float, size: int, steps_per_sample: int = 1, ) -> tuple[float, float, float]: """ Run a timed measurement pass and reduce it to the efficiency quantities. Parameters ---------- sim : typing.Any Equilibrated simulation to measure. meas_steps : int Number of samples to record and time. steps_per_sample : int Update steps between two samples (default 1). The autocorrelation time is returned in update steps, i.e. multiplied by this factor. temperature : float Temperature, needed for the susceptibility. size : int Linear lattice dimension, needed for the susceptibility. Returns ------- tuple[float, float, float] Integrated autocorrelation time, independent samples per second, and magnetic susceptibility. The first two are NaN where the magnetisation series has no usable variance. """ mags_arr, engs_arr, elapsed = _record_samples( sim=sim, n_samples=meas_steps, steps_per_sample=steps_per_sample, ) try: _, tau_samples = calculate_autocorr(time_series=mags_arr) except ZeroVarianceAutocorrelationError: tau_samples = float('nan') # Independent samples per second count samples, so they use the # autocorrelation time in sample units; the returned time is in steps. tau_int = tau_samples * steps_per_sample _, _, chi, _ = calculate_thermodynamics( mags=mags_arr, engs=engs_arr, T=temperature, L=size, ) iss = ( (meas_steps / elapsed) / tau_samples if np.isfinite(tau_samples) and tau_samples > 0 else float('nan') ) return tau_int, iss, chi
[docs] def measure_efficiency_point(point: EfficiencyPoint) -> dict[str, float]: """ Measure local-update and cluster-update efficiency at one grid point. Both algorithms start from their own independently equilibrated state, so that neither inherits the other's correlations. Metropolis records one sample per sweep; Wolff records one sample every ``round(L^2 / <C>)`` cluster flips, so both receive the same budget in sweep units. Parameters ---------- point : EfficiencyPoint Payload describing the measurement. Returns ------- dict[str, float] Grid indices, temperature, the measured quantities, and the ``converged_metro`` and ``converged_wolff`` flags. An algorithm whose two starts did not converge within ``eq_max_steps`` is not measured, and its quantities are NaN. """ seed = derive_point_seed( temperature_index=point.temp_idx, seed_index=point.seed_idx, ) nan = float('nan') # A pair that never converged is not measured; its quantities stay NaN. sim_metro, converged_metro = _equilibrated_simulation( point=point, update='checkerboard', seed=seed, ) tau_metro, iss_metro, chi_metro = nan, nan, nan if converged_metro: tau_metro, iss_metro, chi_metro = _timed_measurement( sim=sim_metro, meas_steps=point.meas_steps, temperature=point.temperature, size=point.size, ) sim_wolff, converged_wolff = _equilibrated_simulation( point=point, update='wolff', seed=seed + 1, ) tau_wolff, iss_wolff, chi_wolff = nan, nan, nan mean_cluster_frac, flips_per_sample = nan, nan if converged_wolff: # The cluster pass on the equilibrated Wolff run sets the sample # spacing: one sample per lattice sweep of flipped spins on average. _, _, cluster_sizes = sim_wolff.run_with_cluster_sizes( n_steps=min(point.meas_steps, _CLUSTER_PASS_STEPS), ) mean_cluster_frac = float(np.mean(cluster_sizes)) / float(point.size**2) spacing = max(1, int(round(1.0 / mean_cluster_frac))) flips_per_sample = float(spacing) tau_wolff, iss_wolff, chi_wolff = _timed_measurement( sim=sim_wolff, meas_steps=point.meas_steps, temperature=point.temperature, size=point.size, steps_per_sample=spacing, ) return { 'temp_idx': float(point.temp_idx), 'seed_idx': float(point.seed_idx), 'T': float(point.temperature), 'tau_metro': tau_metro, 'tau_wolff': tau_wolff, 'iss_metro': iss_metro, 'iss_wolff': iss_wolff, 'mean_cluster_frac': mean_cluster_frac, 'chi_metro': chi_metro, 'chi_wolff': chi_wolff, 'wolff_flips_per_sample': flips_per_sample, 'converged_metro': float(converged_metro), 'converged_wolff': float(converged_wolff), }
def _summarize(*, samples: np.ndarray) -> dict[str, np.ndarray]: """Reduce a (temperature, seed) sample grid to a median and a 16-84 band.""" summary = summarize_replicate_samples(samples=samples) return { 'value': np.asarray(summary['value']), 'err': np.asarray(summary['err']), 'p16': np.asarray(summary['ci_low']), 'p84': np.asarray(summary['ci_high']), } def _band( *, ax: plt.Axes, temperatures: np.ndarray, summary: dict[str, np.ndarray], color: str, marker: str, label: str | None, log: bool, ) -> None: """Draw one median curve with its percentile band on the given axes.""" plot = ax.semilogy if log else ax.plot plot(temperatures, summary['value'], marker, color=color, ms=4, label=label) ax.fill_between( temperatures, summary['p16'], summary['p84'], color=color, alpha=0.15, )
[docs] def plot_efficiency( *, temperatures: np.ndarray, summaries: dict[str, dict[str, np.ndarray]], title: str, directory: str, transitions: dict[str, float] | None, ) -> None: """ Produce and save the four-panel efficiency comparison figure. Parameters ---------- temperatures : numpy.ndarray Sorted temperature grid. summaries : dict[str, dict[str, numpy.ndarray]] Median and band for each plotted quantity, keyed by ``tau_metro_norm``, ``tau_wolff_norm``, ``iss_metro``, ``iss_wolff``, ``mean_cluster_frac``, ``chi_metro``, and ``chi_wolff``. title : str Figure suptitle. directory : str Output directory for the saved PNG. transitions : dict[str, float] or None Vertical reference lines to draw in every panel, keyed by legend label, or None to omit them. Returns ------- None The figure is written to ``wolff_efficiency.png`` in ``directory``. """ metro, wolff = '#4878CF', '#D65F5F' fig, axes = plt.subplots(2, 2, figsize=(11, 8)) fig.suptitle(title, fontsize=13) def mark_transition(ax: plt.Axes) -> None: for offset, (label, temperature) in enumerate(sorted((transitions or {}).items())): ax.axvline( temperature, color='0.4', ls='--' if offset == 0 else ':', lw=1, label=label, ) ax = axes[0, 0] _band(ax=ax, temperatures=temperatures, summary=summaries['tau_metro_norm'], color=metro, marker='-o', label='Metropolis', log=True) _band(ax=ax, temperatures=temperatures, summary=summaries['tau_wolff_norm'], color=wolff, marker='-s', label='Wolff (normalised)', log=True) mark_transition(ax) ax.set_xlabel('Temperature $T$') ax.set_ylabel(r'$\tau^{\mathrm{norm}}_{\mathrm{int}}$ ($L^2$-sweep equiv.)') ax.set_title('Integrated autocorrelation time\n(work-normalised; median with 16–84% band)') ax.legend(fontsize=8) ax = axes[0, 1] _band(ax=ax, temperatures=temperatures, summary=summaries['iss_metro'], color=metro, marker='-o', label='Metropolis', log=True) _band(ax=ax, temperatures=temperatures, summary=summaries['iss_wolff'], color=wolff, marker='-s', label='Wolff', log=True) mark_transition(ax) ax.set_xlabel('Temperature $T$') ax.set_ylabel('Independent samples / s') ax.set_title('Sampling efficiency ISS\n(median with 16–84% band)') ax.legend(fontsize=8) ax = axes[1, 0] _band(ax=ax, temperatures=temperatures, summary=summaries['mean_cluster_frac'], color=wolff, marker='-^', label=None, log=False) mark_transition(ax) ax.set_xlabel('Temperature $T$') ax.set_ylabel(r'$\langle C \rangle \,/\, N^2$') ax.set_title( 'Mean cluster size fraction (Wolff)\n' r'= normalisation factor $\langle C\rangle/L^2$', ) ax.legend(fontsize=8) ax = axes[1, 1] _band(ax=ax, temperatures=temperatures, summary=summaries['chi_metro'], color=metro, marker='-o', label='Metropolis', log=False) _band(ax=ax, temperatures=temperatures, summary=summaries['chi_wolff'], color=wolff, marker='-s', label='Wolff', log=False) mark_transition(ax) ax.set_xlabel('Temperature $T$') ax.set_ylabel(r'$\chi$') ax.set_title('Susceptibility (agreement validates correctness)') ax.legend(fontsize=8) fig.tight_layout() os.makedirs(directory, exist_ok=True) fig.savefig(os.path.join(directory, 'wolff_efficiency.png'), dpi=150, bbox_inches='tight') plt.close(fig)
[docs] def add_wolff_efficiency_arguments( *, parser: argparse.ArgumentParser, size: int, t_min: float, t_max: float, output_dir: str, ) -> None: """ Add the argument surface shared by the per-model efficiency scripts. Parameters ---------- parser : argparse.ArgumentParser Parser to extend. size : int Default linear lattice size L. t_min : float Default lower end of the temperature window. t_max : float Default upper end of the temperature window. output_dir : str Default directory for the NPZ file and the figure. Returns ------- None The parser is modified in place. """ parser.add_argument('--size', type=int, default=size, help='Lattice size L') parser.add_argument( '--eq-probe-steps', type=int, default=500, help='Chunk size for convergence check during equilibration', ) parser.add_argument( '--eq-max-steps', type=int, default=200_000, help='Hard cap on equilibration steps', ) parser.add_argument( '--meas-steps', type=int, default=2000, help='Measurement steps per algorithm per temperature point', ) parser.add_argument('--t-min', type=float, default=t_min, help='Minimum temperature') parser.add_argument('--t-max', type=float, default=t_max, help='Maximum temperature') parser.add_argument('--t-points', type=int, default=20, help='Temperature grid points') parser.add_argument( '--n-seeds', type=int, default=10, help='Independent seed replicas per temperature point', ) parser.add_argument('--output-dir', type=str, default=output_dir, help='Output directory') parser.add_argument('--log-file', type=str, default=None, help='Optional log file path') parser.add_argument('--verbose', action='store_true', help='Enable verbose logging')
[docs] def run_wolff_efficiency( *, args: argparse.Namespace, model_cls: type, model_kwargs: dict[str, Any], model_label: str, transitions: dict[str, float] | None, stuck_below: float | None = None, ) -> None: """ Run the efficiency comparison and write its NPZ file and figure. Parameters ---------- args : argparse.Namespace Arguments parsed from a parser extended by ``add_wolff_efficiency_arguments``. model_cls : type Simulation class to compare the two update schemes on. model_kwargs : dict[str, typing.Any] Extra constructor arguments beyond size, temperature, update, start, and seed. model_label : str Model name for the figure title and the NPZ metadata. transitions : dict[str, float] or None Temperatures to mark in every panel, keyed by legend label, or None to omit the markers. The first by label is drawn dashed, the rest dotted. stuck_below : float or None Temperature below which stuck detection is enabled, i.e. the ordering temperature of a model with metastable domain states. None disables stuck detection everywhere. Returns ------- None Results are written to ``args.output_dir``. """ logger = setup_logging( level=logging.DEBUG if args.verbose else logging.INFO, log_file=args.log_file, ) size = int(args.size) n_seeds = int(args.n_seeds) temperatures: np.ndarray = np.linspace(args.t_min, args.t_max, args.t_points) logger.info( f'{model_label} Wolff efficiency: L={size}, ' f'T in [{args.t_min:.2f}, {args.t_max:.2f}], {args.t_points} points, ' f'{n_seeds} seed replicas, {args.meas_steps} meas steps.' ) points = [ EfficiencyPoint( temp_idx=temp_idx, seed_idx=seed_idx, temperature=float(temperature), size=size, eq_probe_steps=int(args.eq_probe_steps), eq_max_steps=int(args.eq_max_steps), meas_steps=int(args.meas_steps), model_cls=model_cls, model_kwargs=model_kwargs, detect_stuck=stuck_below is not None and temperature < stuck_below, ) for temp_idx, temperature in enumerate(temperatures) for seed_idx in range(n_seeds) ] raw = parallel_sweep(worker_func=measure_efficiency_point, params=points) samples = { key: np.full((len(temperatures), n_seeds), np.nan) for key in _MEASURED_KEYS } for record in raw: i, s = int(record['temp_idx']), int(record['seed_idx']) for key in _MEASURED_KEYS: samples[key][i, s] = float(record[key]) # One Wolff step touches a cluster while one Metropolis sweep touches the # whole lattice, so the Wolff autocorrelation time is scaled by the mean # cluster fraction to put both algorithms on a lattice-sweep footing. samples['tau_metro_norm'] = samples['tau_metro'] samples['tau_wolff_norm'] = samples['tau_wolff'] * samples['mean_cluster_frac'] summaries = {key: _summarize(samples=array) for key, array in samples.items()} marked = transitions or {} os.makedirs(args.output_dir, exist_ok=True) npz_path = os.path.join(args.output_dir, 'wolff_efficiency.npz') np.savez( npz_path, temperatures=temperatures, n_seeds=np.int64(n_seeds), uncertainty_method=UNCERTAINTY_METHOD_REPLICATE, confidence_level=DEFAULT_CONFIDENCE_LEVEL, nan_or_undefined_count=int(sum( int(np.isnan(samples[key]).sum()) for key in _MEASURED_KEYS )), model=model_label, transition_labels=np.array(sorted(marked)), transition_temperatures=np.array([marked[k] for k in sorted(marked)], dtype=float), meas_steps=np.int64(args.meas_steps), L=np.int64(size), size=np.int64(size), **cast(Any, {f'{key}_samples': samples[key] for key in _MEASURED_KEYS}), **cast(Any, {key: summaries[key]['value'] for key in _MEASURED_KEYS}), **cast(Any, {f'{key}_p16': summaries[key]['p16'] for key in _MEASURED_KEYS}), **cast(Any, {f'{key}_p84': summaries[key]['p84'] for key in _MEASURED_KEYS}), # Standardized uncertainty schema (AGENTS.md section 8), additive: the # value is the seed median and the interval the 16-84 % replicate band. # The quantities are per-run summaries, so no autocorrelation time or # effective sample size applies to them. **cast(Any, { f'{key}_{field}': array for key in _MEASURED_KEYS for field, array in ( ('value', summaries[key]['value']), ('err', summaries[key]['err']), ('ci_low', summaries[key]['p16']), ('ci_high', summaries[key]['p84']), ('tau_int', np.full(len(temperatures), np.nan)), ('n_eff', np.full(len(temperatures), np.nan)), ) }), bootstrap_resamples=0, ) logger.info(f'Data saved to {npz_path}') plot_efficiency( temperatures=temperatures, summaries=summaries, title=( f'Wolff vs. Metropolis Efficiency — {model_label} ' f'(L = {size}, seeds = {n_seeds})' ), directory=args.output_dir, transitions=transitions, )