About cookies on this site Our websites require some cookies to function properly (required). In addition, other cookies may be used with your consent to analyze site usage, improve the user experience and for advertising. For more information, please review your options. By visiting our website, you agree to our processing of information as described in IBM’sprivacy statement. To provide a smooth navigation, your cookie preferences will be shared across the IBM web domains listed here.
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)
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.
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_slice
is provided its value is converted to a list and used immediately forTruncationErrorBudget.per_slice_budget
- if the above is not the case,
max_error_total
has to be set - if
num_slices
is not set,:attr:.TruncationErrorBudget.per_slice_budget gets set to[max_error_total]
resulting in the entire budget being consumed greedily - however, if
num_slices
is provided, thenTruncationErrorBudget.per_slice_budget
assumes 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.
Note
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_total
in the case ofnum_slices
also 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)
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
SparsePauliOp
to truncate terms from. - budget (float) – the maximum permissable truncation error.
- p_norm (int) – an integer specifying what p-norm to use.
Returns
The truncated observable and a bound on the incurred truncation error.
Note
The incurred truncation error bound, , is calculated as the p-norm
of the truncated terms’ coefficient magnitudes, , such that .
Return type
Was this page helpful?
Report a bug or request content on GitHub.