---
title: truncating (latest version)
description: API reference for qiskit_addon_obp.utils.truncating in the latest version of qiskit-addon-obp
source: https://eu-de.quantum.cloud.ibm.com/docs/en/api/qiskit-addon-obp/utils-truncating
---

# 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)`

[GitHub](https://github.com/Qiskit/qiskit-addon-obp/tree/main/qiskit_addon_obp/utils/truncating.py#L25-L58)

Bases: [`object`](https://docs.python.org/3/library/functions.html#object)

A class for storing the constants that determine the truncation error budget.

Refer to the [how-to guide](/docs/addons/qiskit-addon-obp/guides/truncate-operator-terms) for a detailed discussion on truncating operator terms during backpropagation and bounding the incurred error.

**Parameters**

- **per\_slice\_budget** ([*list*](https://docs.python.org/3/library/stdtypes.html#list)*\[*[*float*](https://docs.python.org/3/library/functions.html#float)*]*)
- **max\_error\_total** ([*float*](https://docs.python.org/3/library/functions.html#float))
- **p\_norm** ([*int*](https://docs.python.org/3/library/functions.html#int))
- **tol** ([*float*](https://docs.python.org/3/library/functions.html#float))

#### is\_active

`is_active()`

[GitHub](https://github.com/Qiskit/qiskit-addon-obp/tree/main/qiskit_addon_obp/utils/truncating.py#L56-L58)

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

**Return type**

[bool](https://docs.python.org/3/library/functions.html#bool)

#### 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`](https://numpy.org/doc/stable/reference/constants.html#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](/docs/addons/qiskit-addon-obp/guides/bound-error-using-p-norm) 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)`

[GitHub](https://github.com/Qiskit/qiskit-addon-obp/tree/main/qiskit_addon_obp/utils/truncating.py#L61-L141)

Calculate the budget available to each slice for observable term truncation.

This method makes the construction of a [`TruncationErrorBudget`](#qiskit_addon_obp.utils.truncating.TruncationErrorBudget "qiskit_addon_obp.utils.truncating.TruncationErrorBudget") easier for an end-user. This error budget can be provided to the [`backpropagate()`](/docs/api/qiskit-addon-obp/qiskit-addon-obp#backpropagate "qiskit_addon_obp.backpropagate") method to enable the truncation of low-weight Pauli terms. Refer to the [how-to guide](/docs/addons/qiskit-addon-obp/guides/truncate-operator-terms) 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`](#qiskit_addon_obp.utils.truncating.TruncationErrorBudget.per_slice_budget "qiskit_addon_obp.utils.truncating.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`](#qiskit_addon_obp.utils.truncating.TruncationErrorBudget.per_slice_budget "qiskit_addon_obp.utils.truncating.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`](#qiskit_addon_obp.utils.truncating.TruncationErrorBudget.per_slice_budget "qiskit_addon_obp.utils.truncating.TruncationErrorBudget.per_slice_budget").

**Parameters**

- **max\_error\_per\_slice** ([*float*](https://docs.python.org/3/library/functions.html#float)  *|*[*Sequence*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence)*\[*[*float*](https://docs.python.org/3/library/functions.html#float)*] | None*) – Specifies the maximum error per backpropagated slice. See above for more details.
- **max\_error\_total** ([*float*](https://docs.python.org/3/library/functions.html#float) *| None*) – Specifies the total maximum error for the entire backpropagation. See above for more details.
- **num\_slices** ([*int*](https://docs.python.org/3/library/functions.html#int) *| None*) – The number of slices over which to distribute the budget. See above for more details.
- **p\_norm** ([*int*](https://docs.python.org/3/library/functions.html#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](/docs/addons/qiskit-addon-obp/guides/bound-error-using-p-norm) for a detailed conversation on bounding truncation error using higher Lp-norms.

**Returns**

The resulting [`TruncationErrorBudget`](#qiskit_addon_obp.utils.truncating.TruncationErrorBudget "qiskit_addon_obp.utils.truncating.TruncationErrorBudget").

**Raises**

[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – if `max_error_per_slice` and `max_error_total` are both `None`.

**Return type**

[*TruncationErrorBudget*](#qiskit_addon_obp.utils.truncating.TruncationErrorBudget "qiskit_addon_obp.utils.truncating.TruncationErrorBudget")

### truncate\_binary\_search

`truncate_binary_search(observable, budget, *, p_norm=1, tol=1e-08)`

[GitHub](https://github.com/Qiskit/qiskit-addon-obp/tree/main/qiskit_addon_obp/utils/truncating.py#L144-L204)

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*](/docs/api/qiskit/qiskit.quantum_info.SparsePauliOp)) – the `SparsePauliOp` to truncate terms from.
- **budget** ([*float*](https://docs.python.org/3/library/functions.html#float)) – the maximum permissible truncation error.
- **p\_norm** ([*int*](https://docs.python.org/3/library/functions.html#int)) – an integer specifying what p-norm to use.
- **tol** ([*float*](https://docs.python.org/3/library/functions.html#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.

> **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](https://docs.python.org/3/library/stdtypes.html#tuple)\[[*SparsePauliOp*](/docs/api/qiskit/qiskit.quantum_info.SparsePauliOp), [float](https://docs.python.org/3/library/functions.html#float)]