qrunch.quantum.algorithms.pauli.vqes.stopping_criteria

Defines Criteria for deciding when to stop an optimization.

Classes

`ModelEstimation`	Stop if the current value is within the threshold of the estimated minimum.
`Patience`	Stop if the cost doesn't improve within a certain number of iterations by the given threshold.
`Quantile`	Stop if the lower quantile of the recent cost values shows no significant improvement.
`Slope`	Stop if the slope of the cost function is below the threshold.
`SmoothedCost`	Checks for improvements in the smoothed cost.
`StoppingCriterion`	The abstract base class for a stopping criterion.
`StoppingCriterionSubCreator`	Creator for setting a stopping criterion on a parent creator.

class ModelEstimation

Bases: StoppingCriterion

Stop if the current value is within the threshold of the estimated minimum.

The minimum is estimated with fits to the expectation values by two different models:

Power-law model: f(x) = a(1 + x)^b + c
Exponential model: f(x) = a exp(-bx) + c

The model that best fits the data is dynamically selected.

__init__(minimum_points: int = 10, threshold: float = 0.001, maximum_uncertainty: float = 0.0005) → None

Initialize the StoppingCriterion.

Parameters:

minimum_points (int) – The minimum amount of point required before considering stopping. Defaults to 10. Must be at least 4, as the models have 3 parameters.
threshold (float) – The minimum distance to the estimated minimum before stopping. Defaults to 1e-3.
maximum_uncertainty (float) – The allowed uncertainty on the estimated minimum. Defaults to 0.5e-3.

Return type:

None

should_stop() → bool

Inquire if stopping criterion is reached. Return True if stopping.

Return type:: bool

update(expectation_value: ExpectationValue) → None

Update with a new expectation_value.

Parameters:: expectation_value (ExpectationValue) – The expectation value of the current iteration
Return type:: None

write_cost_history(expectation_values: list[ExpectationValue]) → None

Set the cost history to the given list of expectation values.

Parameters:: expectation_values (list[ExpectationValue])
Return type:: None

class Patience

Bases: StoppingCriterion

Stop if the cost doesn’t improve within a certain number of iterations by the given threshold.

__init__(patience: int = 5, threshold: float = 0.0001) → None

Initialize Patience criterion.

Parameters:

patience (int) – Number of iterations to wait for improvement.
threshold (float) – Improvement threshold for stopping.

Return type:

None

should_stop() → bool

Inquire if stopping criterion is reached. Return True if stopping.

Return type:: bool

update(expectation_value: ExpectationValue) → None

Update with a new expectation_value.

Parameters:: expectation_value (ExpectationValue) – The expectation value of the current iteration
Return type:: None

write_cost_history(expectation_values: list[ExpectationValue]) → None

Set the cost history to the given list of expectation values.

Parameters:: expectation_values (list[ExpectationValue])
Return type:: None

class Quantile

Bases: StoppingCriterion

Stop if the lower quantile of the recent cost values shows no significant improvement.

__init__(window: int = 10, percentile: float = 20.0, threshold: float = 0.0001) → None

Initialize QuantileStopping criterion.

Parameters:

window (int) – Number of iterations for quantile calculation.
percentile (float) – Percentile to track for stopping.
threshold (float) – Improvement threshold for stopping.

Return type:

None

should_stop() → bool

Inquire if stopping criterion is reached. Return True if stopping.

Return type:: bool

update(expectation_value: ExpectationValue) → None

Update with a new expectation_value.

Parameters:: expectation_value (ExpectationValue) – The expectation value of the current iteration
Return type:: None

write_cost_history(expectation_values: list[ExpectationValue]) → None

Set the cost history to the given list of expectation values.

Parameters:: expectation_values (list[ExpectationValue])
Return type:: None

class Slope

Bases: StoppingCriterion

Stop if the slope of the cost function is below the threshold.

Uses repeated median regression for robust linear fitting.

__init__(window: int = 10, threshold: float = 0.0001) → None

Initialize SlopeStopping criterion.

Parameters:

window (int) – Number of iterations for the slope calculation.
threshold (float) – The threshold for the slope. Defaults to 1e-4.

Return type:

None

should_stop() → bool

Inquire if stopping criterion is reached. Return True if stopping.

Return type:: bool

update(expectation_value: ExpectationValue) → None

Update with a new expectation_value.

Parameters:: expectation_value (ExpectationValue) – The expectation value of the current iteration
Return type:: None

write_cost_history(expectation_values: list[ExpectationValue]) → None

Set the cost history to the given list of expectation values.

Parameters:: expectation_values (list[ExpectationValue])
Return type:: None

class SmoothedCost

Bases: StoppingCriterion

Checks for improvements in the smoothed cost.

__init__(window: int = 5, threshold: float = 0.0001) → None

Initialize the SmoothedCost criterion.

Parameters:

window (int) – The sliding window to consider. Defaults to 5.
threshold (float) – Improvement threshold for stopping. Defaults to 1e-4.

Return type:

None

should_stop() → bool

Inquire if stopping criterion is reached. Return True if stopping.

Return type:: bool

update(expectation_value: ExpectationValue) → None

Update with a new expectation_value.

Parameters:: expectation_value (ExpectationValue) – The expectation value of the current iteration
Return type:: None

write_cost_history(expectation_values: list[ExpectationValue]) → None

Set the cost history to the given list of expectation values.

Parameters:: expectation_values (list[ExpectationValue])
Return type:: None

class StoppingCriterion

Bases: ABC

The abstract base class for a stopping criterion.

abstractmethod should_stop() → bool

Inquire if stopping criterion is reached. Return True if stopping.

Return type:: bool

update(expectation_value: ExpectationValue) → None

Update with a new expectation_value.

Parameters:: expectation_value (ExpectationValue) – The expectation value of the current iteration
Return type:: None

write_cost_history(expectation_values: list[ExpectationValue]) → None

Set the cost history to the given list of expectation values.

Parameters:: expectation_values (list[ExpectationValue])
Return type:: None

class StoppingCriterionSubCreator

Bases: Generic[T]

Creator for setting a stopping criterion on a parent creator.

__init__(parent: T, field_name: str) → None

Initialize the stopping criterion creator.

Parameters:

parent (T) – The parent creator to which the stopping criterion will be assigned.
field_name (str) – The name of the field in the parent creator.

Return type:

None

model_estimation(minimum_points: int = 10, threshold: float = 0.001, maximum_uncertainty: float = 0.0005) → T

Set the stopping criterion to the model estimation criterion.

The model estimation criterion stops the optimization if the current expectation value is within the threshold of the estimated minimum.

The minimum is estimated with fits to the expectation values by two different models: - Power-law model: f(x) = a(1 + x)^b + c - Exponential model: f(x) = a exp(-bx) + c

The model that best fits the data is dynamically selected.

Parameters:

minimum_points (int) – The minimum number of points required for estimation.
threshold (float) – The accepted distance from the estimated minimum. Defaults to 1e-3. Note that this threshold works a bit differently than for the other stopping criteria, as it is not related to a pre-iteration improvement, but rather an accepted error from the estimated real minimum.
maximum_uncertainty (float) – The maximum std in the estimated minimum (from the fit) allowed. Defaults to 0.5e-3.

Return type:

T

patience(patience: int = 5, threshold: float = 0.0001) → T

Set the stopping criterion to use the patience criterion.

The patience criterion stops the optimization if there is no improvement over a certain number of iterations (patience) by more than a given threshold.

Parameters:

patience (int) – The number of iterations to wait for improvement. Defaults to 5.
threshold (float) – Improvement threshold for stopping. Defaults to 1e-4.

Return type:

T

quantile(window: int = 10, percentile: float = 20.0, threshold: float = 0.0001) → T

Set the stopping criterion to use the quantile criterion.

The quantile criterion stops the optimization if the lower quantile of the recent cost values does not improve more than the specified threshold.

Parameters:

window (int) – The sliding window to consider. Defaults to 10.
percentile (float) – The percentile threshold for stopping. Defaults to 20.0.
threshold (float) – Improvement threshold for stopping. Defaults to 1e-4.

Return type:

T

slope(window: int = 10, threshold: float = 0.0001) → T

Set the stopping criterion to use the slope criterion.

The slope criterion stops the optimization if the slope of the cost function over a sliding window is below a certain threshold.

Parameters:

window (int) – The sliding window to consider. Defaults to 10.
threshold (float) – Slope threshold for stopping. Defaults to 1e-4.

Return type:

T

smoothed_cost(window: int = 5, threshold: float = 0.0001) → T

Set the stopping criterion to use the smoothed cost criterion.

Checks for improvements in the smoothed cost, calculated as a moving average over a sliding window. As soon as the moving average does not improve over the minimum in the window by more than the threshold, the optimization is stopped.

Parameters:

window (int) – The sliding window to consider. Defaults to 5.
threshold (float) – Improvement threshold for stopping. Defaults to 1e-4.

Return type:

T