Truncation utilities
qiskit_addon_obp.utils.truncating
Functions for truncating Pauli operators within given error budgets.
TruncationErrorBudget
class TruncationErrorBudget(per_slice_budget=<factory>, max_error_total=0.0, p_norm=1, tol=1e-08)
Bases: object
A class for storing the constants that determine the truncation error budget.
Refer to the how-to guide for a detailed discussion on truncating operator terms during backpropagation and bounding the incurred error.
Parameters
is_active
is_active()
Return whether the truncation is active, i.e. whether the budget is non-zero.
Return type
max_error_total
Type: float
Default value: 0.0
The maximum total truncation error to allow for each observable during the entire backpropagation. This value may be numpy.inf, for example when the maximum error was left unspecified during setup_budget().
p_norm
Type: int
Default value: 1
Indicates which Lp-norm is used for calculating truncation errors.
Refer to the how-to guide for a detailed conversation on bounding truncation error using higher Lp-norms.
per_slice_budget
Type: list[float]
The maximum amount of truncation error to allow per backpropagated slice. This list will be looped over during the backpropagation of the circuit slices.
tol
Type: float
Default value: 1e-08
Absolute tolerance used during truncation. Once an optimal truncation threshold, up to this tolerance, has been found, the search for an optimal threshold will stop.
setup_budget
setup_budget(*, max_error_per_slice=None, max_error_total=None, num_slices=None, p_norm=1)
Calculate the budget available to each slice for observable term truncation.
This method makes the construction of a TruncationErrorBudget easier for an end-user. This error budget can be provided to the backpropagate() method to enable the truncation of low-weight Pauli terms. Refer to the how-to guide for a detailed discussion on truncating terms from the output operator and bounding the incurred error.
The construction logic is as follows:
- if
max_error_per_sliceis provided its value is converted to a list and used immediately forTruncationErrorBudget.per_slice_budget - if the above is not the case,
max_error_totalhas to be set - if
num_slicesis not set,:attr:.TruncationErrorBudget.per_slice_budget gets set to[max_error_total]resulting in the entire budget being consumed greedily - however, if
num_slicesis provided, thenTruncationErrorBudget.per_slice_budgetassumes an even distribution of the maximum total error across the specified number of slices:[max_error_total / num_slices]
Finally, if max_error_total is set, this puts a hard limit on the total maximum error to be accumulated throughout the entire backpropagation. Thus, setting max_error_per_slice and max_error_total can be of value.
Budget not spent during a previous iteration will carry over into subsequent iterations, meaning that the maximum budget for any slice during backpropagation may in fact exceed TruncationErrorBudget.per_slice_budget.
Parameters
- max_error_per_slice (float |Sequence[float] | None) – Specifies the maximum error per backpropagated slice. See above for more details.
- max_error_total (float | None) – Specifies the total maximum error for the entire backpropagation. See above for more details.
- num_slices (int | None) – The number of slices over which to distribute the budget. See above for more details.
- p_norm (int) – The Lp norm of the error. This affects the gradual distribution of
max_error_totalin the case ofnum_slicesalso being set (see above). Refer to the how-to guide for a detailed conversation on bounding truncation error using higher Lp-norms.
Returns
The resulting TruncationErrorBudget.
Raises
ValueError – if max_error_per_slice and max_error_total are both None.
Return type
truncate_binary_search
truncate_binary_search(observable, budget, *, p_norm=1, tol=1e-08)
Perform binary search to find an optimal observable truncation threshold.
Removes the Pauli terms from a SparsePauliOp whose sum of their absolute coefficients values does not exceed the provided error budget.
Parameters
- observable (SparsePauliOp) – the
SparsePauliOpto truncate terms from. - budget (float) – the maximum permissable truncation error.
- p_norm (int) – an integer specifying what p-norm to use.
- tol (float) – when the binary search thresholds differ by an amount smaller than
tol, the threshold search will stop.
Returns
The truncated observable and a bound on the incurred truncation error.
The incurred truncation error bound, , is calculated as the p-norm of the truncated terms’ coefficient magnitudes, , such that .
Return type