Source code for utils.equilibration

"""Equilibration algorithms for Monte Carlo simulations.

Provides adaptive and two-start convergence equilibration routines, together
with the underlying relaxation-time estimation and quasi-steady-state detection
helpers that support them.  These algorithms were previously split between
``utils.system`` (equilibrate functions) and ``utils.analysis``
(relaxation diagnostic helpers), which required a lazy cross-import to avoid
circular dependencies.  Unifying them here eliminates that workaround.
"""
from __future__ import annotations

import logging
from typing import Any, NamedTuple, Protocol

import numpy as np

from utils.exceptions import ZeroVarianceAutocorrelationError

# ---------------------------------------------------------------------------
# Structural type
# ---------------------------------------------------------------------------


class _Sim(Protocol):
    """Structural type for any MonteCarloSimulation; avoids a models/ → utils/ import."""

    size: int

    def equilibrate(self, *, n_steps: int) -> None: ...

    def run(self, *, n_steps: int) -> tuple[np.ndarray, np.ndarray]: ...


#: Offset between the seed of a random start and that of its ordered partner.
#: The per-sweep RNG streams depend only on (seed, step), so two starts built
#: with one seed draw identical random numbers and their traces become
#: correlated, which weakens the cross-band test that assumes independent
#: runs. The offset sits inside the 1000-seed block that ``derive_point_seed``
#: reserves for one replica, clear of the small ``seed + 1`` and ``seed + 2``
#: sub-streams callers derive.
ORDERED_START_SEED_OFFSET = 500

_MAX_SEED = 2**32 - 1


[docs] def ordered_start_seed(*, seed: int | None) -> int | None: """ Return the seed for the ordered-start partner of a seeded random start. Parameters ---------- seed : int or None Seed of the random-start simulation. ``None`` (unseeded) is passed through unchanged. Returns ------- int or None ``seed + ORDERED_START_SEED_OFFSET``, or ``None`` for an unseeded run. Raises ------ ValueError If the partner seed would leave the 32-bit generator range. """ if seed is None: return None partner = int(seed) + ORDERED_START_SEED_OFFSET if partner > _MAX_SEED: raise ValueError( f'seed {seed} leaves no room for its ordered-start partner ' f'(seed + {ORDERED_START_SEED_OFFSET} exceeds {_MAX_SEED}).' ) return partner
[docs] class TwoStartOutcome(NamedTuple): """Result of a two-start equilibration. Parameters ---------- total_steps : int MC steps run by each of the two simulations. converged : bool Whether the mutual cross-band criterion was met, i.e. both starts reached the same stationary state. stuck : bool Whether the run stopped on a quasi-steady stuck state: the ordered start had settled while the random start stayed stranded on a metastable plateau. Only the ordered start is then a valid measurement source. """ total_steps: int converged: bool stuck: bool @property def certified(self) -> bool: """Whether a measurement on this pair is valid. True after convergence or after a stuck exit. A stuck exit can only occur where the caller enabled ``detect_stuck``, which callers do only where a stuck state is accepted. A run that reached ``max_steps`` is not certified: neither start is known to have relaxed, and callers store NaN for the point instead of measuring it. """ return self.converged or self.stuck
[docs] def select_measurement_simulation[SimT]( *, outcome: TwoStartOutcome, sim_random: SimT, sim_ordered: SimT ) -> SimT: """ Choose which start of an equilibrated pair to measure. The random start is used only when the two starts converged to the same state. After a stuck exit the random start sits on a metastable plateau, so the ordered start is returned. After hitting the step cap the ordered start is returned as well, but neither start is certified (``outcome.certified`` is False) and callers must not measure it. Parameters ---------- outcome : TwoStartOutcome Result of ``convergence_equilibrate_two_start``. sim_random : simulation Random-start simulation. sim_ordered : simulation Ordered-start simulation. Returns ------- simulation ``sim_random`` if the pair converged, otherwise ``sim_ordered``. """ return sim_random if outcome.converged else sim_ordered
# --------------------------------------------------------------------------- # Private signal-processing helpers # --------------------------------------------------------------------------- def _valid_prefix(x: np.ndarray) -> np.ndarray: """Return the non-NaN prefix from a padded trajectory.""" valid = np.isfinite(x) if not np.any(valid): return np.empty(0, dtype=float) end = int(np.where(valid)[0][-1]) + 1 return x[:end] def _moving_average(x: np.ndarray, window: int) -> np.ndarray: window = max(3, min(window, len(x))) return np.convolve(x, np.ones(window) / window, mode='valid') # --------------------------------------------------------------------------- # Relaxation-time estimation # --------------------------------------------------------------------------- _QS_SIGMA_REF_L: int = 32 """Reference lattice side-length for ``_detect_quasi_steady_stuck`` threshold scaling. The ``qs_sigma_threshold`` parameter is calibrated at this L and scaled proportionally as ``threshold * _QS_SIGMA_REF_L / lattice_size`` for other sizes. """ # Shared defaults for the two-start criteria. The convergence loop forwards # user overrides via **kwargs to both the relaxation estimator and the stuck # detector; keeping the fallback values here (instead of repeating literals) # guarantees the two criteria cannot silently drift apart. _TWO_START_DEFAULT_K: float = 1.0 _TWO_START_DEFAULT_SMOOTH_WINDOW: int = 60 _TWO_START_DEFAULT_SIGMA_FLOOR: float = 0.02 def _prepare_smoothed_traces( *, trace_random: np.ndarray, trace_ordered: np.ndarray, smooth_window: int, skip_validation: bool, ) -> tuple[np.ndarray, np.ndarray, int] | None: """Shared preprocessing for the two-start criteria. Takes the absolute values (optionally after finite-prefix validation), truncates both traces to a common length ``n``, and applies the moving-average smoother. Returns ``(r_smoothed, o_smoothed, n)``, or ``None`` when the traces are too short to analyze (fewer than 8 common raw samples). """ if skip_validation: r = np.abs(trace_random) o = np.abs(trace_ordered) else: r = np.abs(_valid_prefix(np.asarray(trace_random, dtype=float))) o = np.abs(_valid_prefix(np.asarray(trace_ordered, dtype=float))) n = min(len(r), len(o)) if n < 8: return None r_sm = _moving_average(r[:n], smooth_window) o_sm = _moving_average(o[:n], smooth_window) m = min(len(r_sm), len(o_sm)) return r_sm[:m], o_sm[:m], n
[docs] def estimate_relaxation_time_two_start( *, trace_random: np.ndarray, trace_ordered: np.ndarray, k: float = _TWO_START_DEFAULT_K, smooth_window: int = _TWO_START_DEFAULT_SMOOTH_WINDOW, dwell_window: int = 60, min_fraction_inside: float = 0.85, sigma_floor: float = _TWO_START_DEFAULT_SIGMA_FLOOR, skip_validation: bool = False, ) -> int: """Estimate thermalization time from convergence of random- and ordered-start traces. Compares a trajectory started from a random spin configuration against one started from a fully ordered configuration. Returns the first step at which both smoothed traces pass a mutual cross-band test sustained over a dwell window. The criterion is asymmetric in the correct physical sense: the smoothed random-start trace must lie within ``k`` standard deviations of the ordered-start tail mean, and the ordered-start trace must simultaneously lie within ``k`` standard deviations of the random-start tail mean. Tail statistics are computed from the second half of each smoothed trace independently. A ``sigma_floor`` prevents band collapse when one trace is nearly variance-free (e.g. in the deep ordered phase near T=0). Parameters ---------- trace_random : np.ndarray 1-D magnetization trace from a random initial state. trace_ordered : np.ndarray 1-D magnetization trace from an ordered initial state. k : float Half-width of each convergence band in units of the respective tail standard deviation. Larger values are more permissive. smooth_window : int Window length (steps) for the moving-average smoother. dwell_window : int Window length (steps) for the sustained-convergence test. min_fraction_inside : float Fraction of steps within ``dwell_window`` that must satisfy the mutual cross-band condition to declare convergence. sigma_floor : float Minimum allowed standard deviation for each tail, preventing band collapse when a trajectory is nearly flat. skip_validation : bool If True, skip np.asarray and finite-prefix checks. Returns ------- int Estimated relaxation time as a 0-indexed position in the original input traces (i.e. a sweep count minus one). The first index at which both smoothed traces have been mutually inside each other's band for ``dwell_window`` steps is mapped back to the corresponding raw-trace position as ``hits[0] + smooth_window - 1``. Returns ``n`` (full trace length) if no convergence is detected, or ``0`` for very short traces. """ prepared = _prepare_smoothed_traces( trace_random=trace_random, trace_ordered=trace_ordered, smooth_window=smooth_window, skip_validation=skip_validation, ) if prepared is None: return 0 r_sm, o_sm, n = prepared m = len(r_sm) # Compute tail statistics independently for each trace half = m // 2 tail_r = r_sm[half:] tail_o = o_sm[half:] mu_r = tail_r.mean() mu_o = tail_o.mean() sig_r = max(float(tail_r.std()), sigma_floor) sig_o = max(float(tail_o.std()), sigma_floor) # Mutual cross-band test: each trace must be inside the other trace's band in_o_band = np.abs(r_sm - mu_o) <= k * sig_o # random inside ordered's band in_r_band = np.abs(o_sm - mu_r) <= k * sig_r # ordered inside random's band both_inside = (in_o_band & in_r_band).astype(float) dwell_window = max(3, min(dwell_window, len(both_inside))) sustained_fraction = ( np.convolve(both_inside, np.ones(dwell_window), mode='valid') / dwell_window ) hits = np.where(sustained_fraction >= min_fraction_inside)[0] return int(hits[0]) + smooth_window - 1 if hits.size else n
def _detect_quasi_steady_stuck( *, trace_random: np.ndarray, trace_ordered: np.ndarray, k: float = _TWO_START_DEFAULT_K, smooth_window: int = _TWO_START_DEFAULT_SMOOTH_WINDOW, qs_sigma_threshold: float = 0.05, sigma_floor: float = _TWO_START_DEFAULT_SIGMA_FLOOR, lattice_size: int | None = None, skip_validation: bool = False, ) -> bool: """Detect low-temperature stuck states in two-start equilibration. A stuck state is declared when the ordered-start trace has settled (small tail variance, as expected for any equilibrated state) but the two smoothed traces still fail the mutual cross-band condition, indicating the random-start trace is stranded in a metastable plateau. The guard uses only the ordered-trace tail variance, not the random-trace variance. The random trace in a multi-domain stuck state has domain-wall fluctuations of similar amplitude to the thermal fluctuations of a thermalized disordered system, making it an unreliable discriminator. The ordered trace is always the reliable anchor: in the deep ordered phase its variance is essentially zero; in the disordered phase it carries thermal fluctuations of magnitude ``sigma ~ 1 / lattice_size``. When ``lattice_size`` is provided, the effective threshold scales as ``qs_sigma_threshold * _QS_SIGMA_REF_L / lattice_size``. This keeps a constant safety margin between the threshold and the thermal ordered-trace variance at any system size. At ``lattice_size = _QS_SIGMA_REF_L`` the effective threshold equals ``qs_sigma_threshold`` exactly. """ prepared = _prepare_smoothed_traces( trace_random=trace_random, trace_ordered=trace_ordered, smooth_window=smooth_window, skip_validation=skip_validation, ) if prepared is None: return False r_sm, o_sm, _ = prepared m = len(r_sm) if m < 8: return False half = m // 2 tail_r = r_sm[half:] tail_o = o_sm[half:] raw_sig_r = float(tail_r.std()) raw_sig_o = float(tail_o.std()) effective_threshold = ( qs_sigma_threshold * _QS_SIGMA_REF_L / lattice_size if lattice_size is not None else qs_sigma_threshold ) # Guard on the ordered trace only: it is the reliable anchor. # The random trace in a stuck multi-domain state has domain-wall fluctuations # of similar amplitude to thermal noise in the disordered phase, making # raw_sig_r an unreliable discriminator between stuck and thermalized. if raw_sig_o >= effective_threshold: return False mu_r = float(tail_r.mean()) mu_o = float(tail_o.mean()) sig_r = max(raw_sig_r, sigma_floor) sig_o = max(raw_sig_o, sigma_floor) random_inside_ordered_band = abs(mu_r - mu_o) <= k * sig_o ordered_inside_random_band = abs(mu_o - mu_r) <= k * sig_r mutually_inside = random_inside_ordered_band and ordered_inside_random_band return not mutually_inside # --------------------------------------------------------------------------- # Adaptive equilibration # ---------------------------------------------------------------------------
[docs] def adaptive_equilibrate( sim: _Sim, *, min_steps: int, probe_steps: int = 500, factor: float = 50.0, max_steps: int = 200_000, ) -> int: """ Equilibrate a simulation adaptively, extending the burn-in until the probe window covers ``factor`` integrated autocorrelation times. After the mandatory ``min_steps`` burn-in, the function repeatedly runs a ``probe_steps`` measurement via ``sim.run()`` and computes ``tau_int`` from the resulting magnetization series. If ``probe_steps >= factor * tau_int``, the probe spans enough correlation times for the initial state to be forgotten and equilibration is declared complete. Otherwise the probe has advanced the system state and the loop continues. In the ordered phase the magnetization series has zero variance; this is treated as full equilibration and the function returns immediately. Parameters ---------- sim : _Sim Any simulation object implementing ``equilibrate`` and ``run``. min_steps : int Mandatory burn-in passed to ``sim.equilibrate`` before probing. probe_steps : int MC steps per probe run (default 500). factor : float Required ratio ``probe_steps / tau_int`` (default 50.0). max_steps : int Hard cap on total steps to prevent unbounded runtime near criticality (default 200 000). Returns ------- int Total number of MC steps run (burn-in + probes). Raises ------ ValueError If the adaptive-equilibration parameters are invalid. """ from utils.statistics import calculate_autocorr # lazy import; avoids pickle issues if min_steps < 0: raise ValueError(f'min_steps must be non-negative, got {min_steps}') if probe_steps < 3: raise ValueError(f'probe_steps must be >= 3, got {probe_steps}') if factor <= 0.0: raise ValueError(f'factor must be positive, got {factor}') if max_steps < min_steps: raise ValueError( f'max_steps must be >= min_steps, got max_steps={max_steps} and min_steps={min_steps}' ) logger = logging.getLogger('vibespin') sim.equilibrate(n_steps=min_steps) total = min_steps while total < max_steps: mags, _ = sim.run(n_steps=probe_steps) total += probe_steps try: _, tau_int = calculate_autocorr(time_series=mags) except ZeroVarianceAutocorrelationError: # Zero variance: fully ordered phase, equilibration is trivially satisfied. return total if probe_steps >= factor * tau_int: return total logger.warning( f'adaptive_equilibrate: reached max_steps={max_steps} without satisfying ' f'criterion probe_steps({probe_steps}) >= factor({factor}) * tau_int; ' 'proceeding anyway.' ) return total
# --------------------------------------------------------------------------- # Two-start convergence equilibration # ---------------------------------------------------------------------------
[docs] def convergence_equilibrate( *, sim_random: _Sim, sim_ordered: _Sim, chunk_size: int = 500, max_steps: int = 200_000, qs_sigma_threshold: float = 0.05, qs_min_steps: int = 1500, **kwargs: Any, ) -> int: """ Equilibrate two simulations (random- and ordered-start) until they converge. Uses ``estimate_relaxation_time_two_start`` to detect convergence via the mutual cross-band criterion: each smoothed trajectory must enter and sustain a band defined by the other trajectory's tail statistics. A sigma floor prevents false positives when one trace is nearly flat. This is more robust than one-start adaptive methods for complex energy landscapes. Parameters ---------- sim_random : _Sim Simulation instance started from a random state. sim_ordered : _Sim Simulation instance started from an ordered state. chunk_size : int Number of steps to run between convergence checks. max_steps : int Hard cap on total steps. qs_sigma_threshold : float Tail-std threshold used to detect a quasi-steady, non-converged stuck state and exit early. qs_min_steps : int Minimum accumulated steps before stuck detection is allowed to fire. Ensures tail statistics are computed from enough data to be reliable, preventing false positives when traces have not yet had time to settle. **kwargs : Any Passed to ``estimate_relaxation_time_two_start`` (k, smooth_window, dwell_window, min_fraction_inside, sigma_floor, etc.). Returns ------- int Total number of MC steps run per simulation. """ total, _ = convergence_equilibrate_with_status( sim_random=sim_random, sim_ordered=sim_ordered, chunk_size=chunk_size, max_steps=max_steps, qs_sigma_threshold=qs_sigma_threshold, qs_min_steps=qs_min_steps, **kwargs, ) return total
[docs] def convergence_equilibrate_two_start( *, sim_random: _Sim, sim_ordered: _Sim, chunk_size: int = 500, max_steps: int = 200_000, qs_sigma_threshold: float = 0.05, qs_min_steps: int = 1500, detect_stuck: bool = False, **kwargs: Any, ) -> TwoStartOutcome: """ Equilibrate a random-start and an ordered-start simulation side by side. The two runs advance in chunks until their smoothed magnetization traces pass the mutual cross-band criterion of ``estimate_relaxation_time_two_start``, until the quasi-steady stuck detector fires, or until ``max_steps`` is reached. Unlike ``convergence_equilibrate_with_status`` the result keeps a stuck exit apart from genuine convergence, so callers can measure on the start that is actually valid (see ``select_measurement_simulation``). Parameters ---------- sim_random : _Sim Simulation instance started from a random state. sim_ordered : _Sim Simulation instance started from an ordered state. It should carry a different seed from ``sim_random`` (see ``ordered_start_seed``). chunk_size : int Number of steps to run between convergence checks. max_steps : int Hard cap on total steps. qs_sigma_threshold : float Tail-std threshold used to detect a quasi-steady stuck state. qs_min_steps : int Minimum accumulated steps before stuck detection may fire. detect_stuck : bool Whether a quasi-steady stuck state ends the run early (default False). The detector cannot tell a stranded random start from one that is still relaxing slowly, which is common near a transition and for the XY model below T_BKT, so it is opt-in: enable it only in the ordered phase of a model with metastable domain states, where measuring the ordered start after a stuck exit is valid. **kwargs : Any Passed to ``estimate_relaxation_time_two_start`` (k, smooth_window, dwell_window, min_fraction_inside, sigma_floor, etc.). Returns ------- TwoStartOutcome Steps run, convergence flag, and stuck flag. At most one flag is set. """ mags_r = np.full(max_steps, np.nan, dtype=float) mags_o = np.full(max_steps, np.nan, dtype=float) total = 0 # Every convergence check re-analyzes the full accumulated trace, so # checking after every chunk costs O(total^2 / chunk_size) over a long # run. Once the trace is much longer than a chunk, space the checks # geometrically (25% growth); the summed analysis cost then stays linear # in max_steps. Convergence between two checks is caught at the next # check, so equilibration can only end slightly later, never earlier. next_check_total = 100 while total < max_steps: # Run next chunk mr, _ = sim_random.run(n_steps=chunk_size) mo, _ = sim_ordered.run(n_steps=chunk_size) # Clip chunk if it would exceed max_steps actual_len = min(len(mr), max_steps - total) if actual_len <= 0: break mags_r[total : total + actual_len] = mr[:actual_len] mags_o[total : total + actual_len] = mo[:actual_len] total += actual_len # Only check if we have enough data for a meaningful estimate # smooth_window defaults to 60, dwell_window to 60. if total >= next_check_total: next_check_total = total + max(chunk_size, total // 4) # Pass slices (views) to avoid copying trace_r = mags_r[:total] trace_o = mags_o[:total] tau = estimate_relaxation_time_two_start( trace_random=trace_r, trace_ordered=trace_o, skip_validation=True, **kwargs, ) # If estimate_relaxation_time_two_start returns a value < total, # it means convergence was detected at some point in the past. if tau < total: return TwoStartOutcome(total_steps=total, converged=True, stuck=False) if detect_stuck and total >= qs_min_steps and _detect_quasi_steady_stuck( trace_random=trace_r, trace_ordered=trace_o, k=float(kwargs.get('k', _TWO_START_DEFAULT_K)), smooth_window=int(kwargs.get('smooth_window', _TWO_START_DEFAULT_SMOOTH_WINDOW)), qs_sigma_threshold=qs_sigma_threshold, sigma_floor=float(kwargs.get('sigma_floor', _TWO_START_DEFAULT_SIGMA_FLOOR)), lattice_size=getattr(sim_random, 'size', None), skip_validation=True, ): return TwoStartOutcome(total_steps=total, converged=False, stuck=True) return TwoStartOutcome(total_steps=total, converged=False, stuck=False)
[docs] def convergence_equilibrate_with_status( *, sim_random: _Sim, sim_ordered: _Sim, chunk_size: int = 500, max_steps: int = 200_000, qs_sigma_threshold: float = 0.05, qs_min_steps: int = 1500, qs_allow_stuck: bool = False, **kwargs: Any, ) -> tuple[int, bool]: """ Equilibrate two simulations and report whether convergence was reached. Uses ``estimate_relaxation_time_two_start`` to detect convergence via the mutual cross-band criterion: each smoothed trajectory must enter and sustain a band defined by the other trajectory's tail statistics. A sigma floor prevents false positives when one trace is nearly flat. This variant returns both the total number of MC steps executed and a boolean convergence flag. The boolean cannot tell an accepted stuck state from genuine convergence; after an accepted stuck state only the ordered start is a valid measurement source. Callers that measure should use ``convergence_equilibrate_two_start`` with ``select_measurement_simulation`` instead. Parameters ---------- sim_random : _Sim Simulation instance started from a random state. sim_ordered : _Sim Simulation instance started from an ordered state. chunk_size : int Number of steps to run between convergence checks. max_steps : int Hard cap on total steps. qs_sigma_threshold : float Tail-std threshold used to detect a quasi-steady, non-converged stuck state and exit early. qs_min_steps : int Minimum accumulated steps before stuck detection is allowed to fire. Ensures tail statistics are computed from enough data to be reliable, preventing false positives when traces have not yet had time to settle. qs_allow_stuck : bool If True, detecting a quasi-steady stuck state (where the ordered trace is stable but the random trace is stranded) is treated as a successful equilibration. Useful for Ising sweeps where random-start domain-wall trapping is physically expected. **kwargs : Any Passed to ``estimate_relaxation_time_two_start`` (k, smooth_window, dwell_window, min_fraction_inside, sigma_floor, etc.). Returns ------- tuple[int, bool] Tuple ``(total_steps, converged)``. """ # The legacy wrapper keeps its historical behaviour of stopping on a # stuck state unless the caller passes detect_stuck explicitly. kwargs.setdefault('detect_stuck', True) outcome = convergence_equilibrate_two_start( sim_random=sim_random, sim_ordered=sim_ordered, chunk_size=chunk_size, max_steps=max_steps, qs_sigma_threshold=qs_sigma_threshold, qs_min_steps=qs_min_steps, **kwargs, ) _log_two_start_outcome(outcome=outcome, max_steps=max_steps, qs_allow_stuck=qs_allow_stuck) if outcome.stuck: return outcome.total_steps, qs_allow_stuck return outcome.total_steps, outcome.converged
def _log_two_start_outcome( *, outcome: TwoStartOutcome, max_steps: int, qs_allow_stuck: bool ) -> None: """Log a stuck or capped two-start equilibration in the established wording.""" logger = logging.getLogger('vibespin') if outcome.stuck: if qs_allow_stuck: logger.info( 'convergence_equilibrate: detected stable quasi-steady stuck state; ' 'stopping early and accepting ordered start.' ) else: logger.warning( 'convergence_equilibrate: detected quasi-steady stuck state ' f'before max_steps={max_steps}; stopping early without convergence.' ) elif not outcome.converged: logger.warning( f'convergence_equilibrate: reached max_steps={max_steps} without convergence; ' 'proceeding anyway.' )
[docs] def prepare_equilibrated_simulation( *, model_cls: type, model_kwargs: dict[str, Any], size: int, temp: float, seed: int | None, chunk_size: int, max_steps: int, update: str = 'checkerboard', **kwargs: Any, ) -> tuple[Any, TwoStartOutcome]: """ Build a two-start pair, equilibrate it, and return the start to measure. The random start receives ``seed`` and the ordered start ``ordered_start_seed(seed=seed)``, so the two runs draw independent random numbers. After equilibration the random start is returned when the pair converged, and the ordered start otherwise (see ``select_measurement_simulation``). When the run hit ``max_steps``, ``outcome.certified`` is False and the caller should record NaN for the point rather than measure the returned simulation. Parameters ---------- model_cls : type Simulation class to instantiate. model_kwargs : dict[str, Any] Constructor arguments beyond size, temperature, update, start, and seed. size : int Linear lattice size L. temp : float Simulation temperature T. seed : int or None Seed of the random start; ``None`` leaves both starts unseeded. chunk_size : int Steps between convergence checks. max_steps : int Hard cap on equilibration steps. update : str Update scheme for both starts (default ``'checkerboard'``). **kwargs : Any Passed to ``convergence_equilibrate_two_start``, for example ``detect_stuck=True`` in the ordered phase of a model with metastable domain states. Returns ------- tuple[Any, TwoStartOutcome] The simulation to measure and the equilibration outcome. """ common = dict(size=size, temp=temp, update=update, **model_kwargs) sim_random = model_cls(init_state='random', seed=seed, **common) sim_ordered = model_cls(init_state='ordered', seed=ordered_start_seed(seed=seed), **common) outcome = convergence_equilibrate_two_start( sim_random=sim_random, sim_ordered=sim_ordered, chunk_size=chunk_size, max_steps=max_steps, **kwargs, ) logger = logging.getLogger('vibespin') if outcome.stuck: logger.info(f'T={temp:.4f}, L={size}: random start stranded; measuring the ordered start.') elif not outcome.converged: logger.warning( f'T={temp:.4f}, L={size}: no convergence in {max_steps} steps; ' 'the point is not certified and is stored as NaN.' ) sim = select_measurement_simulation( outcome=outcome, sim_random=sim_random, sim_ordered=sim_ordered, ) return sim, outcome