Truncation utilities (qiskit_addon_obp.utils.truncating)

Functions for truncating Pauli operators within given error budgets.

class TruncationErrorBudget(per_slice_budget=<factory>, max_error_total=0.0, p_norm=1)[source]

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()[source]

Return whether the truncation is active, i.e. whether the budget is non-zero.

Return type:

bool

max_error_total: float = 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: int = 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: 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(*, max_error_per_slice=None, max_error_total=None, num_slices=None, p_norm=1)[source]

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 for TruncationErrorBudget.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, then TruncationErrorBudget.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 of num_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:

TruncationErrorBudget

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, \(E\), is calculated as the p-norm of the truncated terms’ coefficient magnitudes, \(c\), such that \(E = \|c\|_p\).

Return type:

tuple[SparsePauliOp, float]