Choose a Stopping Criterion

Goal

Configure when the adaptive/optimization loop should stop (i.e., declare convergence).

Overview

A stopping rule can be attached to the calculator via the fluent step .choose_stopping_criterion() and then picking one criterion. Each criterion has a small set of parameters.

import qrunch as qc

calculator = (
    qc.calculator_creator()
    .vqe()
    .iterative()
    .standard()
    .choose_stopping_criterion()
      # .<pick-a-stopping-criterion>(...)
    .create()
)

Available Criteria

Patience (Recommended Default)

Stops if no improvement larger than threshold occurs within the last patience number of iterations.

calculator = (
    qc.calculator_creator()
    .vqe()
    .iterative()
    .standard()
    .choose_stopping_criterion()
    .patience(patience=5, threshold=1e-4)
    .create()
)

This can be used when looking for a practical, stable rule that works well across many conditions. This is the recommended criteria for most standard applications (internal evaluations show reliable results for both FAST-VQE and BEAST-VQE runs).

Smoothed Cost

Stops when the current minimum is better than the moving average (within a sliding window) by at least threshold.

calculator = (
    qc.calculator_creator()
    .vqe()
    .iterative()
    .standard()
    .choose_stopping_criterion()
    .smoothed_cost(window=5, threshold=1e-4)
    .create()
)

This option can be used when the objective is moderately noisy; it provides a simple, robust rule that ignores small oscillations.

Slope

Fits a robust linear trend (repeated-median regression) to the most recent window points and stops when the slope magnitude is below threshold.

calculator = (
    qc.calculator_creator()
    .vqe()
    .iterative()
    .standard()
    .choose_stopping_criterion()
    .slope(window=10, threshold=1e-4)
    .create()
)

This criterion can be used when the tail of the energy convergence is roughly linear. It provides a trend-aware stopping rule that is resistant to outliers.

Quantile

Looks at the improvement of a low quantile (e.g., 20th percentile) over a window and stops if it’s less than threshold.

calculator = (
    qc.calculator_creator()
    .vqe()
    .iterative()
    .standard()
    .choose_stopping_criterion()
    .quantile(window=10, percentile=20.0, threshold=1e-4)
    .create()
)

This criterion favors a distribution-aware approach that is robust to outliers.

Model Estimation

Fits simple tail models to recent values (power-law or exponential with an offset) and estimates the asymptotic minimum. Stops when the current cost is within threshold of the estimated minimum, provided the fit uncertainty is acceptable.

calculator = (
    qc.calculator_creator()
    .vqe()
    .iterative()
    .standard()
    .choose_stopping_criterion()
    .model_estimation(minimum_points=10, threshold=1e-3, maximum_uncertainty=0.5e-3)
    .create()
)

This criterion can be used when the tail of the energy convergence is smooth and well-behaved. It aims to stop near a target accuracy (e.g., chemical accuracy ~1e-3 Ha). More powerful but more assumptive—guardrails are applied against poor fits.

Practical Guidance

Default recommendation: .patience(patience=5, threshold=1e-4). Offers a strong balance of reliability and simplicity across noisy and clean runs.
Chemical accuracy target: if you want to stop near ~``1e-3`` Ha, consider .model_estimation(threshold=1e-3) (works best with smooth tails), or use .patience with a suitable per-step threshold.
Noisy measurements / hardware runs: prefer .patience or .smoothed_cost.
Plateaus and drops: .patience tends to behave better than purely slope-based rules.
Highly variable tails: .quantile can be helpful.