"""
Shared command-line surface and orchestration for the temperature sweeps.
The Ising, XY, and Clock sweeps differ only in the model they instantiate, the
lattice and temperature window they default to, the transition overlay they
draw, and whether they prefer an ordered start below a known critical
temperature. Everything between those choices, the argument surface, the
seed-retry collection loop, the uncertainty bundles, the NPZ schema, and the
figure, is identical and lives here, so that a change to the uncertainty
schema reaches all three models at once instead of drifting between them.
"""
from __future__ import annotations
import argparse
import logging
import os
from typing import Any, cast
import numpy as np
from utils.plotting import plot_temperature_sweep
from utils.statistics import (
DEFAULT_CONFIDENCE_LEVEL,
UNCERTAINTY_METHOD_BLOCKING,
UNCERTAINTY_METHOD_BOOTSTRAP,
summarize_asymmetric_replicate_uncertainty,
summarize_entropy_observable,
)
from utils.sweep_helpers import (
ThermoPoint,
build_quality_flags,
build_uncertainty_bundle,
derive_point_seed,
simulate_thermo_point,
validate_sweep_uncertainty_args,
)
from utils.system import parallel_sweep, setup_logging
#: Observables carried through the full hierarchical uncertainty schema. The
#: worker emits ``<key>_value``, ``<key>_err``, ``<key>_tau_int``, and
#: ``<key>_n_eff`` for each of them.
_BUNDLED_OBSERVABLES = ('avg_m', 'avg_e', 'susc', 'spec_h')
[docs]
def add_temperature_sweep_arguments(
*,
parser: argparse.ArgumentParser,
size: int,
t_min: float,
t_max: float,
t_points: int,
eq_max_steps: int,
meas_steps: int,
output_dir: str,
transition_help: str,
) -> None:
"""
Add the argument surface shared by all three temperature sweeps.
Parameters
----------
parser : argparse.ArgumentParser
Parser to extend. Model-specific arguments such as the clock state
count are added by the caller, before or after this call.
size : int
Default linear lattice size L for this model.
t_min : float
Default lower end of the temperature window.
t_max : float
Default upper end of the temperature window.
t_points : int
Default number of temperature points.
eq_max_steps : int
Default hard cap on equilibration steps. The vector models need a far
higher cap than Ising because their relaxation is slower.
meas_steps : int
Default number of measurement sweeps per point.
output_dir : str
Default directory for the NPZ file and the figure.
transition_help : str
Model-specific help text for ``--transition-preset``, which names the
overlay that ``auto`` draws.
Returns
-------
None
The parser is modified in place.
"""
parser.add_argument('--size', type=int, default=size, help='Linear 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=eq_max_steps,
help='Hard cap on total equilibration steps',
)
parser.add_argument(
'--eq-qs-sigma-threshold', type=float, default=0.05,
help='Tail-std threshold for quasi-steady stuck detection (0 disables)',
)
parser.add_argument(
'--eq-qs-min-steps', type=int, default=1500,
help='Minimum accumulated equilibration steps before stuck detection can fire',
)
parser.add_argument('--meas-steps', type=int, default=meas_steps, help='Measurement steps')
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=t_points, help='Number of temperature points',
)
parser.add_argument(
'--n-seeds',
type=int,
default=5,
help='Target number of fully converged seed replicas to retain',
)
parser.add_argument(
'--max-seed-attempts',
type=int,
default=None,
help='Per-temperature cap on seed attempts, including replacements; defaults to 10*n-seeds',
)
parser.add_argument(
'--derived-uncertainty-method',
type=str,
default=UNCERTAINTY_METHOD_BLOCKING,
choices=[UNCERTAINTY_METHOD_BLOCKING, UNCERTAINTY_METHOD_BOOTSTRAP],
help='Uncertainty method for susceptibility and specific heat',
)
parser.add_argument(
'--derived-bootstrap-resamples',
type=int,
default=0,
help='Bootstrap resamples used when derived-uncertainty-method=bootstrap',
)
parser.add_argument(
'--confidence-level',
type=float,
default=DEFAULT_CONFIDENCE_LEVEL,
help='Two-sided confidence level for uncertainty intervals (0 < c < 1)',
)
parser.add_argument(
'--entropy-uncertainty-method',
type=str,
default=UNCERTAINTY_METHOD_BOOTSTRAP,
choices=[UNCERTAINTY_METHOD_BLOCKING, UNCERTAINTY_METHOD_BOOTSTRAP],
help='Uncertainty method for entropy curves',
)
parser.add_argument(
'--entropy-bootstrap-resamples',
type=int,
default=400,
help='Bootstrap resamples used when entropy-uncertainty-method=bootstrap',
)
parser.add_argument(
'--strict-uncertainty',
action='store_true',
help='Fail if undefined autocorrelation points exceed the allowed fraction',
)
parser.add_argument(
'--max-undefined-fraction',
type=float,
default=0.25,
help='Maximum allowed fraction of undefined tau_int points in strict mode',
)
parser.add_argument(
'--min-effective-samples',
type=float,
default=20.0,
help='Threshold used to flag low effective sample size points',
)
parser.add_argument(
'--max-tau-relative-width',
type=float,
default=1.0,
help='Relative width threshold to flag unstable tau intervals',
)
parser.add_argument(
'--transition-preset',
type=str,
default='auto',
choices=['auto', 'none', 'theory'],
help=transition_help,
)
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')
def _collect_seed_ensemble(
*,
args: argparse.Namespace,
temperatures: np.ndarray,
model_cls: type,
model_kwargs: dict[str, Any],
ordered_start_below: float | None,
target_n_seeds: int,
max_seed_attempts: int,
) -> list[list[dict[str, float]]]:
"""
Run the sweep until every temperature holds the target number of replicas.
Each pass submits the points that are still short of the target, keeps the
results that reached equilibrium, and repeats. A temperature that keeps
failing to converge is abandoned once it has used its attempt budget, so a
single pathological point cannot stall the whole sweep.
Parameters
----------
args : argparse.Namespace
Parsed sweep arguments.
temperatures : numpy.ndarray
Temperature grid of the sweep.
model_cls : type
Simulation class to instantiate for every point.
model_kwargs : dict[str, typing.Any]
Extra constructor arguments beyond size, temperature, start, and seed.
ordered_start_below : float or None
Temperature under which a quasi-steady stuck state counts as converged
and the ordered start may replace the random one. None disables both.
target_n_seeds : int
Number of converged replicas wanted per temperature.
max_seed_attempts : int
Per-temperature cap on attempts including replacements.
Returns
-------
list[list[dict[str, float]]]
Converged worker results, indexed by temperature then by replica.
"""
t_points = len(temperatures)
results_grid: list[list[dict[str, float]]] = [[] for _ in range(t_points)]
attempts_per_temp = np.zeros(t_points, dtype=int)
while any(len(results_grid[t]) < target_n_seeds for t in range(t_points)):
points_to_calculate = []
for t in range(t_points):
needed = target_n_seeds - len(results_grid[t])
if needed <= 0 or attempts_per_temp[t] >= max_seed_attempts:
continue
for _ in range(needed):
seed_idx = int(attempts_per_temp[t])
t_val = float(temperatures[t])
low_t = ordered_start_below is not None and t_val < ordered_start_below
points_to_calculate.append(ThermoPoint(
temperature=t_val,
size=int(args.size),
meas_steps=int(args.meas_steps),
eq_probe_steps=int(args.eq_probe_steps),
eq_max_steps=int(args.eq_max_steps),
eq_qs_sigma_threshold=float(args.eq_qs_sigma_threshold),
eq_qs_min_steps=int(args.eq_qs_min_steps),
qs_allow_stuck=low_t,
prefer_ordered_start=low_t,
temperature_index=t,
seed_index=seed_idx,
seed=derive_point_seed(temperature_index=t, seed_index=seed_idx),
model_cls=model_cls,
model_kwargs=model_kwargs,
confidence=float(args.confidence_level),
derived_method=str(args.derived_uncertainty_method),
bootstrap_resamples=int(args.derived_bootstrap_resamples),
))
attempts_per_temp[t] += 1
if not points_to_calculate:
break
for res in parallel_sweep(
worker_func=simulate_thermo_point,
params=points_to_calculate,
):
if res.get('equilibrated_flag', 0.0) > 0:
results_grid[int(res['temperature_index'])].append(res)
return results_grid
[docs]
def run_temperature_sweep(
*,
args: argparse.Namespace,
model_cls: type,
model_kwargs: dict[str, Any],
model_label: str,
plot_title: str,
metadata_note: str,
transition_temperatures: dict[str, float] | None,
variant_note: str = '',
ordered_start_below: float | None = None,
) -> None:
"""
Execute a temperature sweep and write its NPZ file and figure.
Parameters
----------
args : argparse.Namespace
Arguments parsed from a parser extended by
``add_temperature_sweep_arguments``.
model_cls : type
Simulation class to instantiate for every point. 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, start, and seed.
model_label : str
Model name used in log messages, for example ``'Ising'``.
plot_title : str
Title of the thermodynamics figure.
metadata_note : str
Run provenance line printed under the figure.
transition_temperatures : dict[str, float] or None
Vertical overlays to draw, already resolved against
``--transition-preset`` by the caller, since which overlay is
meaningful depends on the model.
variant_note : str, optional
Extra model configuration to mention in the opening log line, for
example the clock variant and anisotropy.
ordered_start_below : float, optional
Temperature under which a quasi-steady stuck state counts as converged
and the ordered start may replace the random one. Set it to the
critical temperature for models with true long-range order below it;
leave it None where the low-temperature phase has none.
Returns
-------
None
Results are written to ``args.output_dir``.
Raises
------
RuntimeError
If no temperature produced a converged replica, or if strict
uncertainty mode is on and too many points have undefined
autocorrelation.
"""
validate_sweep_uncertainty_args(
confidence_level=float(args.confidence_level),
max_undefined_fraction=float(args.max_undefined_fraction),
min_effective_samples=float(args.min_effective_samples),
max_tau_relative_width=float(args.max_tau_relative_width),
derived_uncertainty_method=str(args.derived_uncertainty_method),
derived_bootstrap_resamples=int(args.derived_bootstrap_resamples),
n_seeds=int(args.n_seeds),
)
log_level = logging.DEBUG if args.verbose else logging.INFO
logger = setup_logging(level=log_level, log_file=args.log_file)
temperatures: np.ndarray = np.linspace(args.t_min, args.t_max, args.t_points)
t_points = len(temperatures)
target_n_seeds = int(args.n_seeds)
max_seed_attempts = int(
10 * target_n_seeds if args.max_seed_attempts is None else args.max_seed_attempts
)
logger.info(
f'Starting {model_label} temperature sweep (L={args.size}, '
f'{variant_note}target_n_seeds={target_n_seeds}, '
f'max_seed_attempts={max_seed_attempts})...'
)
results_grid = _collect_seed_ensemble(
args=args,
temperatures=temperatures,
model_cls=model_cls,
model_kwargs=model_kwargs,
ordered_start_below=ordered_start_below,
target_n_seeds=target_n_seeds,
max_seed_attempts=max_seed_attempts,
)
missing = sum(max(0, target_n_seeds - len(results_grid[t])) for t in range(t_points))
if missing:
logger.warning(
f'Could not reach target_n_seeds={target_n_seeds} for all temperatures. '
f'Missing points: {missing}'
)
# Temperatures that produced no converged replica at all are dropped rather
# than carried as an all-NaN row, so downstream fits see only real points.
valid_t_mask = np.array([len(results_grid[t]) > 0 for t in range(t_points)])
valid_temperatures = temperatures[valid_t_mask]
n_valid_t = int(valid_t_mask.sum())
if n_valid_t == 0:
raise RuntimeError('Failed to collect any converged results.')
# Replica counts can differ between temperatures once attempts are
# exhausted, so the grid is padded with NaN to a common width.
max_seeds_retained = max(len(r) for r in results_grid)
def extract_grid(key: str) -> np.ndarray:
arr = np.full((n_valid_t, max_seeds_retained), np.nan)
valid_idx = 0
for t in range(t_points):
if not valid_t_mask[t]:
continue
for s, res in enumerate(results_grid[t]):
arr[valid_idx, s] = res.get(key, np.nan)
valid_idx += 1
return arr
bundles = {
name: build_uncertainty_bundle(
values_by_seed=extract_grid(f'{name}_value'),
errors_by_seed=extract_grid(f'{name}_err'),
tau_by_seed=extract_grid(f'{name}_tau_int'),
n_eff_by_seed=extract_grid(f'{name}_n_eff'),
confidence=float(args.confidence_level),
ci_low_by_seed=extract_grid(f'{name}_ci_low'),
ci_high_by_seed=extract_grid(f'{name}_ci_high'),
)
for name in _BUNDLED_OBSERVABLES
}
mag_bundle = bundles['avg_m']
spec_h_bundle = bundles['spec_h']
entropy_res = summarize_entropy_observable(
temperatures=valid_temperatures,
specific_heat_samples=spec_h_bundle['samples'],
specific_heat_err=spec_h_bundle['err'],
method=str(args.entropy_uncertainty_method),
confidence=float(args.confidence_level),
bootstrap_resamples=int(args.entropy_bootstrap_resamples),
)
# Interval for tau_int itself, from its spread across seed replicas. The
# flag used to compare the confidence interval of <|m|> with tau_int,
# two quantities in different units; a single seed has no tau interval.
tau_grid = extract_grid('avg_m_tau_int')
tau_summaries = [
summarize_asymmetric_replicate_uncertainty(
samples=row, confidence=float(args.confidence_level),
)
for row in tau_grid
]
tau_int_ci_low = np.array([summ['ci_low'] for summ in tau_summaries])
tau_int_ci_high = np.array([summ['ci_high'] for summ in tau_summaries])
quality = build_quality_flags(
tau_int=mag_bundle['tau_int'],
ci_low=tau_int_ci_low,
ci_high=tau_int_ci_high,
n_eff=mag_bundle['n_eff'],
min_effective_samples=float(args.min_effective_samples),
max_tau_relative_width=float(args.max_tau_relative_width),
)
if args.strict_uncertainty:
undef_frac = float(np.mean(quality['undefined_autocorr_flag']))
if undef_frac > args.max_undefined_fraction:
raise RuntimeError(
f'Strict uncertainty failed: {undef_frac:.1%} of points have '
'undefined autocorrelation.'
)
os.makedirs(args.output_dir, exist_ok=True)
outpath = os.path.join(args.output_dir, 'temperature_sweep_data.npz')
np.savez(
outpath,
temperatures=valid_temperatures,
# Legacy scalar arrays, kept for notebooks that predate the schema.
avg_m=mag_bundle['value'],
avg_e=bundles['avg_e']['value'],
susc=bundles['susc']['value'],
spec_h=spec_h_bundle['value'],
entropy=entropy_res['value'],
tau_int=mag_bundle['tau_int'],
tau_int_ci_low=tau_int_ci_low,
tau_int_ci_high=tau_int_ci_high,
# Full uncertainty schema.
**cast(Any, {
f'{name}_{k}': v
for name, bundle in bundles.items()
for k, v in bundle.items()
}),
**cast(Any, {f'entropy_{k}': v for k, v in entropy_res.items()}),
**cast(Any, quality),
entropy_uncertainty_method=str(args.entropy_uncertainty_method),
uncertainty_method=str(args.derived_uncertainty_method),
confidence_level=float(args.confidence_level),
n_seeds=max_seeds_retained,
size=int(args.size),
meas_steps=int(args.meas_steps),
bootstrap_resamples=int(args.derived_bootstrap_resamples),
requested_n_seeds=target_n_seeds,
max_seed_attempts=max_seed_attempts,
retained_n_seeds=max_seeds_retained,
nan_or_undefined_count=int(np.sum(quality['undefined_autocorr_flag'])),
)
logger.info(f'Saved sweep data to {outpath}')
plot_temperature_sweep(
temperatures=valid_temperatures,
avg_m=cast(Any, mag_bundle['value']),
avg_m_err=mag_bundle['err'],
avg_e=cast(Any, bundles['avg_e']['value']),
avg_e_err=bundles['avg_e']['err'],
susc=cast(Any, bundles['susc']['value']),
susc_err=bundles['susc']['err'],
spec_h=cast(Any, spec_h_bundle['value']),
spec_h_err=spec_h_bundle['err'],
entropy=entropy_res['value'],
entropy_err=entropy_res['err'],
entropy_ci_low=entropy_res['ci_low'],
entropy_ci_high=entropy_res['ci_high'],
tau_int=mag_bundle['tau_int'],
tau_unstable_flag=quality['tau_interval_unstable_flag'],
low_effective_sample_flag=quality['low_effective_sample_flag'],
title=plot_title,
filename='temperature_sweep.png',
directory=args.output_dir,
run_metadata_note=metadata_note,
transition_temperatures=transition_temperatures,
)