Skip to content

Search advisor#

Ground-state-search guidance: choose the coldest useful β before tuning (one autotune, no raise-and-retry loops), and diagnose after a draw which knob — mixing, draw budget, or β — limits the minimum found. Host-side numpy; no XLA compiles. Ising front ends: hamon.ising_estimate_beta and ising_sample(..., beta="auto"); continuation: hamon.NRPTPlan.extend and NRPTPlan.sample_until.

hamon.estimate_beta_max(costs: np.ndarray, energy_scale: float, *, gap_tol: float = 0.001, method: str = 'unspecified') -> BetaEstimate #

Smallest β whose predicted equilibrium excess is ≤ gap_tol·|energy_scale|.

Arguments:

  • costs: elementary excitation costs of the landscape — 2|J_i| per nonzero bond on a field-free forest (exact), or 2|local field| spectra from greedy-descent minima elsewhere (see :func:hamon.models.ising.ising_excitation_costs). Non-positive entries are ignored (zero-cost modes are degeneracies, not defects).
  • energy_scale: magnitude of the ground-state energy (or best estimate); sets the meaning of the relative tolerance.
  • gap_tol: target relative thermal floor. The default 1e-3 reproduced the empirically-good β on every benchmark family; lower is safe but pays (slightly, Λ saturates) in chains.

Monotone bisection; returns the full rationale as a :class:BetaEstimate.

hamon.BetaEstimate #

Result of :func:estimate_beta_max, with its rationale.

summary() -> str #

Classify what limits a minimum-energy search and say which knob to turn.

Arguments:

  • energy_trace: cold-chain energies of the draws the caller received (post-warmup, post-thinning), in draw order.
  • stats: per-draw-window NRPT stats dict(s) (each containing rejection_rates, n_rounds, total_round_trips — or a round_trip_diagnostics sub-dict with them); pooled exactly across windows. Optional; report is the fallback evidence source.
  • report: the :class:hamon.AutotuneReport of the plan (tuning-time mixing evidence).
  • predicted_floor_rel / estimator_beta: optional landscape context (from :func:estimate_beta_max at the current β): the predicted relative thermal floor and the estimator's recommended β. When the floor exceeds floor_alarm, "records still arriving" is overridden to BETA_LIMITED — going colder beats going longer by orders of magnitude when the current β's equilibrium sits far above tolerance.
  • warn_beta_limited: escalate a confident BETA_LIMITED verdict to logger.warning. Off by default — sampling at the requested β is working-as-designed unless the caller declared a search intent (extend / sample_until set this).

Decision order:

  1. A saturated ladder (barrier_is_identified False) is MIXING_LIMITED outright — structural, nothing downstream is trustworthy.
  2. Recent records (x = ln(T/(r_last+1)) < draw_evidence) mean draws are still paying → DRAW_LIMITED — unless the landscape context says the thermal floor at this β is ≫ tolerance (BETA override above). Record recency is checked before any effective-sample gate: a drifting trace has ~zero ESS precisely because it is improving.
  3. A silent tail only establishes a plateau if enough conveyor deliveries occurred in it: at cold β records arrive per round trip, not per draw, so fewer than min_tail_deliveries expected deliveries since the last record → INCONCLUSIVE (ESS is the fallback gate when no round-trip data exists).
  4. An established plateau with a dead conveyor AND little mass at the minimum (< 25%) means stuck-in-a-basin → MIXING_LIMITED. A dead-slow conveyor with heavy floor mass is cold-β freeze-out — expected during ground-state search — and stays a note on the BETA/converged verdict.

hamon.SearchAdvice #

Verdict of :func:diagnose_search plus the evidence behind it.

summary() -> str #

hamon.SearchVerdict #

BETA_LIMITED class-attribute #
DRAW_LIMITED class-attribute #
INCONCLUSIVE class-attribute #
MIXING_LIMITED class-attribute #
__module__ class-attribute #

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

__format__(format_spec) method descriptor #

Return a formatted version of the string as described by format_spec.

__str__() method descriptor #

Return str(self).

hamon.advisor.excess_energy(costs: np.ndarray, beta: float) -> float #

Equilibrium mean excess ⟨E⟩_β − E_GS of an independent-defect spectrum.

hamon.advisor.gs_occupancy(costs: np.ndarray, beta: float) -> float #

P(one equilibrium draw sits exactly at the ground state) — exact for independent defects (forests), an upper-bound proxy elsewhere.

hamon.advisor.communication_barrier(costs: np.ndarray, beta_max: float, n_grid: int = 400) -> float #

Predicted NRPT barrier Λ(0→β_max) = ∫ σ_E(β)/√π dβ (trapezoid).

Small-Δβ rejection density of Predescu/Syed under a Gaussian energy marginal; measured within 1-6% of hamon's own Λ̂ on chain instances.