{
"cells": [
{
"cell_type": "markdown",
"id": "cell-00",
"metadata": {},
"source": [
"# How to tune the configuration options\n",
"\n",
"The bounds computation is exact in principle but approximate in practice: evolving a Pauli error\n",
"term through a circuit produces an operator with exponentially many terms, and finding the spectral\n",
"norm of the resulting commutator is itself expensive. The options below control that cost. They fall\n",
"into three groups:\n",
"\n",
"- **Accuracy** options change the numerical value of the bounds, trading tightness for cost.\n",
"- **Scope** determines *which* bounds are computed.\n",
"- **Execution** options change *how* the computation runs (not what it computes).\n",
"\n",
"| Option | Default | Controls | Effect on the result |\n",
"| --- | --- | --- | --- |\n",
"| **Accuracy** | | | |\n",
"| `evolution_max_terms` | `1_000_000` | How many operator terms survive the evolution | Lower: cheaper, looser bounds |\n",
"| `atol_simplify` | `1e-8` | Which commutator terms are discarded as negligible | Higher: cheaper, looser bounds |\n",
"| `eigval_max_qubits` | `14` | How wide a commutator can be for its spectral norm to be computed | Lower: cheaper, looser bounds |\n",
"| `atol_eigenvalue` | `1e-10` | When the iterative eigensolver counts as converged | Higher: cheaper, less accurate bounds |\n",
"| **Scope** | | | |\n",
"| `max_num_boxes` | `None` | How many boxes have bounds computed | Boxes beyond the limit keep the trivial bound of 2.0 |\n",
"| **Execution** | | | |\n",
"| `timeout` | `None` | A wall-clock budget for the whole computation | Any remaining work keeps the trivial bound of 2.0 |\n",
"| `num_processes` | `1` | How many worker processes compute bounds in parallel | None on its own |\n",
"\n",
"A bound is only useful if it is *valid*: it must never understate an error term's effect on the\n",
"observable. Loosening any of these options other than `atol_eigenvalue` can only make the bounds\n",
"larger (more conservative), never smaller. Thus, the cost of a loose setting is a larger sampling\n",
"overhead, not a wrong expectation value - [`atol_eigenvalue`](#atol_eigenvalue) is the exception."
]
},
{
"cell_type": "markdown",
"id": "cell-01",
"metadata": {},
"source": [
"## Circuit definition\n",
"\n",
"The following experiments use the same Trotterized Ising circuit and observable as the [quickstart guide](quickstart.ipynb). At\n",
"this size, every option has a visible effect while each computation still takes less than a second."
]
},
{
"cell_type": "code",
"execution_count": 1,
"id": "cell-02",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"noisy layers: 2\n",
"Pauli error terms: 198\n"
]
}
],
"source": [
"import numpy as np\n",
"from qiskit import QuantumCircuit\n",
"from qiskit.quantum_info import Pauli\n",
"from qiskit_addon_slc.utils import generate_noise_model_paulis\n",
"from samplomatic.transpiler import generate_boxing_pass_manager\n",
"from samplomatic.utils import find_unique_box_instructions\n",
"\n",
"\n",
"def trotter_ising_circuit(num_qubits, num_steps, rx_angle, rzz_angle):\n",
" \"\"\"Trotterized transverse-field Ising evolution on a 1D chain.\"\"\"\n",
" circuit = QuantumCircuit(num_qubits)\n",
" for _ in range(num_steps):\n",
" circuit.rx(rx_angle, range(num_qubits))\n",
" circuit.barrier()\n",
" for start in (0, 1): # even then odd bonds\n",
" for i in range(start, num_qubits - 1, 2):\n",
" circuit.rzz(rzz_angle, i, i + 1)\n",
" circuit.barrier()\n",
" return circuit\n",
"\n",
"\n",
"num_qubits = 10\n",
"circuit = trotter_ising_circuit(num_qubits, num_steps=4, rx_angle=np.pi / 16, rzz_angle=-np.pi / 3)\n",
"observable = Pauli(\"I\" * num_qubits).compose(\"Z\", [num_qubits // 2])\n",
"\n",
"boxing_pass = generate_boxing_pass_manager(\n",
" inject_noise_targets=\"all\",\n",
" inject_noise_strategy=\"individual_modification\",\n",
" inject_noise_site=\"after\",\n",
" twirling_strategy=\"active\",\n",
" remove_barriers=\"never\",\n",
")\n",
"boxed_circuit = boxing_pass.run(circuit)\n",
"noise_model_paulis = generate_noise_model_paulis(find_unique_box_instructions(boxed_circuit))\n",
"\n",
"print(f\"noisy layers: {len(noise_model_paulis)}\")\n",
"print(f\"Pauli error terms: {sum(len(p) for p in noise_model_paulis.values())}\")"
]
},
{
"cell_type": "markdown",
"id": "cell-03",
"metadata": {},
"source": [
"A small helper summarizes each set of bounds in one line, so the effect of an option shows up as a\n",
"few numbers rather than a wall of arrays.\n",
"\n",
"Every bound lies between 0 and the trivial bound of 2.0. The summary reports the mean bound and its\n",
"standard deviation, followed by how the terms fall into these groups: \n",
" - Terms bounded by exactly 0 because they commute with the evolved observable\n",
" - Terms with a bound computed between 0 and 2.0\n",
" - Terms left at the trivial 2.0\n",
"\n",
"Note that **a lower mean is tighter, and tighter means a smaller sampling overhead later.**\n",
"\n",
"A sweep over one option marks the option's default with `*`:"
]
},
{
"cell_type": "code",
"execution_count": 2,
"id": "cell-04",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
" defaults mean 0.3639 ± 0.684 │ at 0: 59% computed: 36% at 2.0: 5% │ 0.29s\n"
]
}
],
"source": [
"import inspect\n",
"import time\n",
"\n",
"from qiskit_addon_slc.bounds import compute_forward_bounds\n",
"\n",
"\n",
"def summarize(rates, label, elapsed):\n",
" \"\"\"Prints a one-line summary of a set of bounds.\"\"\"\n",
" # The bounds are floating-point results, so a term counts as bounded by 0, or as left at the\n",
" # trivial 2.0, when it is within rounding error of that value.\n",
" exact = np.isclose(rates, 0.0, rtol=0.0, atol=1e-12)\n",
" trivial = np.isclose(rates, 2.0, rtol=0.0, atol=1e-12)\n",
" computed = ~exact & ~trivial\n",
" print(\n",
" f\"{label:28} mean {rates.mean():.4f} ± {rates.std():.3f} │ \"\n",
" f\"at 0: {exact.mean():4.0%} computed: {computed.mean():4.0%} \"\n",
" f\"at 2.0: {trivial.mean():4.0%} │ \"\n",
" f\"{elapsed:4.2f}s\"\n",
" )\n",
"\n",
"\n",
"def forward(label, **kwargs):\n",
" \"\"\"Computes the forward bounds, summarizes them and returns all their rates.\"\"\"\n",
" start = time.perf_counter()\n",
" bounds = compute_forward_bounds(boxed_circuit, noise_model_paulis, observable, **kwargs)\n",
" elapsed = time.perf_counter() - start\n",
" rates = np.concatenate([bound.rates for bound in bounds.values()])\n",
" summarize(rates, label, elapsed)\n",
" return rates\n",
"\n",
"\n",
"def sweep(option, values):\n",
" \"\"\"Computes the forward bounds for each value of one option, marking the default with `*`.\"\"\"\n",
" default = inspect.signature(compute_forward_bounds).parameters[option].default\n",
" for value in values:\n",
" marker = \"*\" if value == default else \" \"\n",
" forward(f\"{marker} {option}={value:g}\", **{option: value})\n",
"\n",
"\n",
"baseline = forward(\" defaults\")"
]
},
{
"cell_type": "markdown",
"id": "cell-05",
"metadata": {},
"source": [
"## Accuracy\n",
"\n",
"### `evolution_max_terms`\n",
"\n",
"Evolving a Pauli error term through non-Clifford gates turns it into a sum of Paulis, and that sum\n",
"grows with circuit depth. `evolution_max_terms` caps how many of those terms are kept. The 1-norm of\n",
"whatever is discarded is added to the bound, so nothing is silently lost.\n",
"\n",
"The sweep runs from tighter than the default down to an extreme cut. Lowering the cap makes the\n",
"computation cheaper and the bounds looser."
]
},
{
"cell_type": "code",
"execution_count": 3,
"id": "cell-06",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
" evolution_max_terms=1e+07 mean 0.3639 ± 0.684 │ at 0: 59% computed: 36% at 2.0: 5% │ 0.38s\n",
"* evolution_max_terms=1e+06 mean 0.3639 ± 0.684 │ at 0: 59% computed: 36% at 2.0: 5% │ 0.31s\n",
" evolution_max_terms=1000 mean 0.3639 ± 0.684 │ at 0: 59% computed: 36% at 2.0: 5% │ 0.30s\n",
" evolution_max_terms=100 mean 0.3639 ± 0.684 │ at 0: 59% computed: 36% at 2.0: 5% │ 0.29s\n",
" evolution_max_terms=10 mean 0.3927 ± 0.711 │ at 0: 59% computed: 31% at 2.0: 9% │ 0.28s\n",
" evolution_max_terms=2 mean 0.5245 ± 0.792 │ at 0: 59% computed: 23% at 2.0: 18% │ 0.21s\n"
]
}
],
"source": [
"sweep(\"evolution_max_terms\", (10_000_000, 1_000_000, 1000, 100, 10, 2))"
]
},
{
"cell_type": "markdown",
"id": "cell-07",
"metadata": {},
"source": [
"Raising the cap past its default changes nothing here. For a circuit of this size, the default\n",
"already keeps every term, so the bounds are as tight as this option can make them. That is the\n",
"typical situation. Tightening an accuracy option only pays off once its default is actually limiting,\n",
"and the way to find out is the experiment above. Rerun it with a tighter value and see whether the\n",
"bounds move.\n",
"\n",
"\n",
"\n",
"**Warning:** The underlying propagation routine treats `evolution_max_terms` as a *capacity to\n",
"pre-allocate*, not as an upper limit to check against. Passing something nominally unlimited, such\n",
"as `numpy.iinfo(numpy.uint).max`, asks the allocator for terabytes of memory and aborts the process.\n",
"Keep it to a realistic number. The default of one million is already generous.\n",
"\n",
"
\n",
"\n",
"### `atol_simplify`\n",
"\n",
"After the commutator is formed, terms with a coefficient below `atol_simplify` are dropped. As with\n",
"the evolution cap, the 1-norm lost this way is added to the bound."
]
},
{
"cell_type": "code",
"execution_count": 4,
"id": "cell-08",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
" atol_simplify=0 mean 0.3639 ± 0.684 │ at 0: 59% computed: 36% at 2.0: 5% │ 0.32s\n",
"* atol_simplify=1e-08 mean 0.3639 ± 0.684 │ at 0: 59% computed: 36% at 2.0: 5% │ 0.31s\n",
" atol_simplify=0.0001 mean 0.3639 ± 0.684 │ at 0: 59% computed: 36% at 2.0: 5% │ 0.33s\n",
" atol_simplify=0.01 mean 0.3656 ± 0.685 │ at 0: 59% computed: 35% at 2.0: 6% │ 0.31s\n",
" atol_simplify=0.1 mean 0.3837 ± 0.697 │ at 0: 59% computed: 31% at 2.0: 10% │ 0.31s\n"
]
}
],
"source": [
"sweep(\"atol_simplify\", (0.0, 1e-8, 1e-4, 1e-2, 1e-1))"
]
},
{
"cell_type": "markdown",
"id": "cell-09",
"metadata": {},
"source": [
"### `eigval_max_qubits`\n",
"\n",
"The tightest available bound is the spectral norm of the commutator, which needs an eigenvalue\n",
"computation. That becomes expensive as the commutator widens, so `eigval_max_qubits` sets the width\n",
"beyond which the attempt is abandoned in favour of the triangle inequality. That bound,\n",
"$2 \\sum_i |c_i|$ over the commutator's coefficients $c_i$, is valid but looser.\n",
"\n",
"Setting it to zero forces the fallback everywhere, which shows the benefit of the eigensolver\n",
"in one number."
]
},
{
"cell_type": "code",
"execution_count": 5,
"id": "cell-10",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
" eigval_max_qubits=20 mean 0.3639 ± 0.684 │ at 0: 59% computed: 36% at 2.0: 5% │ 0.31s\n",
"* eigval_max_qubits=14 mean 0.3639 ± 0.684 │ at 0: 59% computed: 36% at 2.0: 5% │ 0.30s\n",
" eigval_max_qubits=8 mean 0.3639 ± 0.684 │ at 0: 59% computed: 36% at 2.0: 5% │ 0.32s\n",
" eigval_max_qubits=4 mean 0.3742 ± 0.694 │ at 0: 59% computed: 35% at 2.0: 6% │ 0.30s\n",
" eigval_max_qubits=2 mean 0.4983 ± 0.809 │ at 0: 59% computed: 23% at 2.0: 18% │ 0.27s\n",
" eigval_max_qubits=0 mean 0.5081 ± 0.810 │ at 0: 59% computed: 21% at 2.0: 19% │ 0.27s\n"
]
}
],
"source": [
"sweep(\"eigval_max_qubits\", (20, 14, 8, 4, 2, 0))"
]
},
{
"cell_type": "markdown",
"id": "cell-11",
"metadata": {},
"source": [
"Even with the eigensolver switched off, the mean stays far below the trivial 2.0. The share\n",
"of terms bounded by 0 does not change: a term that commutes exactly with the evolved observable\n",
"has a zero commutator, which is recognized before any eigenvalue computation is considered. Of the\n",
"others, the triangle-inequality bound reaches 2.0 for some and is capped there, but for many it is\n",
"still smaller, so they keep a computed bound below 2.0.\n",
"\n",
"### `atol_eigenvalue`\n",
"\n",
"When the spectral norm *is* computed, `atol_eigenvalue` is the convergence tolerance of the\n",
"iterative eigensolver. Most commutators never reach that solver, though:\n",
"\n",
"- A commutator acting on at most four qubits is diagonalized exactly, directly.\n",
"- A wider one is first reduced to the smallest number of qubits that its Pauli terms need,\n",
" and if that reduced form acts on at most eight qubits, it is diagonalized exactly.\n",
"\n",
"Only a commutator that still needs more than eight qubits after that reduction goes to the iterative\n",
"solver, which is the only place this tolerance applies. Circuits of the size used in this guide never get\n",
"that far, so a sweep over this option would show identical bounds for every value. It matters for\n",
"wide light cones on large devices.\n",
"\n",
"Unlike the other accuracy options, loosening `atol_eigenvalue` is *not* safe in one direction. An\n",
"iterative eigensolver approaches the extremal eigenvalue from inside the spectrum, so an estimate\n",
"that has not fully converged understates the spectral norm, and the bound. The default is\n",
"deliberately tight for that reason. If the solver fails to converge, the triangle-inequality\n",
"fallback takes over, which is valid again."
]
},
{
"cell_type": "markdown",
"id": "cell-13",
"metadata": {},
"source": [
"## Scope\n",
"\n",
"### `max_num_boxes`\n",
"\n",
"Sometimes the useful limit is not accuracy but depth. `max_num_boxes` stops spawning bound\n",
"computations past a given number of boxes, and every layer beyond it is assigned the trivial bound\n",
"of 2.0 instead.\n",
"\n",
"The limit counts the noisy `BoxOp` instructions (those carrying an `InjectNoise` annotation) rather\n",
"than, for example, a depth in gates. That keeps it tied to the user-visible structure of the circuit and\n",
"avoids coupling to the auto-generated annotation references, which can change between\n",
"transpilation runs.\n",
"\n",
"This is the natural choice for a circuit whose two halves are handled by forward and backward bounds\n",
"respectively: compute each only as deep as it will be used."
]
},
{
"cell_type": "code",
"execution_count": 6,
"id": "cell-14",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"the circuit has 9 noisy boxes drawn from 2 distinct noise models\n",
"\n",
"* max_num_boxes=None mean 0.3639 ± 0.684 │ at 0: 59% computed: 36% at 2.0: 5% │ 0.33s\n",
" max_num_boxes=6 mean 0.7486 ± 0.935 │ at 0: 53% computed: 18% at 2.0: 30% │ 0.18s\n",
" max_num_boxes=4 mean 1.1506 ± 0.980 │ at 0: 40% computed: 5% at 2.0: 55% │ 0.11s\n",
" max_num_boxes=2 mean 1.5707 ± 0.821 │ at 0: 21% computed: 0% at 2.0: 79% │ 0.05s\n",
" max_num_boxes=1 mean 1.8157 ± 0.579 │ at 0: 9% computed: 0% at 2.0: 91% │ 0.03s\n"
]
}
],
"source": [
"from qiskit.circuit import BoxOp\n",
"from samplomatic import InjectNoise\n",
"\n",
"# The limit counts the noisy boxes encountered while iterating the circuit, not the unique ones:\n",
"# a repeated layer is one noise model but several boxes. Boxes without an `InjectNoise`\n",
"# annotation carry no error terms and do not count.\n",
"num_boxes = sum(\n",
" 1\n",
" for inst in boxed_circuit.data\n",
" if isinstance(inst.operation, BoxOp)\n",
" and any(isinstance(annotation, InjectNoise) for annotation in inst.operation.annotations)\n",
")\n",
"print(\n",
" f\"the circuit has {num_boxes} noisy boxes drawn from \"\n",
" f\"{len(noise_model_paulis)} distinct noise models\\n\"\n",
")\n",
"\n",
"for limit in (None, 6, 4, 2, 1):\n",
" marker = \"*\" if limit is None else \" \"\n",
" forward(f\"{marker} max_num_boxes={limit}\", max_num_boxes=limit)"
]
},
{
"cell_type": "markdown",
"id": "cell-15",
"metadata": {},
"source": [
"## Execution\n",
"\n",
"### `timeout`\n",
"\n",
"`timeout` is a wall-clock budget in seconds. When it expires, the bounds that have been computed are kept\n",
"and everything outstanding keeps the trivial bound of 2.0, so the result is always usable, just\n",
"looser the earlier you cut it off.\n",
"\n",
"It is not a hard deadline: already-running tasks are allowed to finish, so the call can overrun the\n",
"budget by the duration of one task.\n",
"\n",
"### `num_processes`\n",
"\n",
"Bounds for different error terms are independent, so `num_processes` distributes them over worker\n",
"processes. On its own, this affects only how long the computation takes, never its result.\n",
"\n",
"\n",
"\n",
"**Note:** A `timeout` combined with `num_processes` makes the result depend on timing: which tasks\n",
"finish before the budget expires is not deterministic. The bounds stay valid, but they are no longer\n",
"reproducible from run to run.\n",
"\n",
"
"
]
},
{
"cell_type": "markdown",
"id": "cell-16",
"metadata": {},
"source": [
"## Where to start\n",
"\n",
"The defaults are chosen to give tight bounds on circuits of a size where that is affordable. When a\n",
"computation is too slow, try applying the options in roughly this order:\n",
"\n",
"1. `num_processes`: A free speed-up, with no accuracy cost.\n",
"2. `max_num_boxes`: If you know in advance how deep into the circuit you care about.\n",
"3. `eigval_max_qubits`: Skips the most expensive step for the widest commutators, which are usually\n",
" a small minority of the terms.\n",
"4. `evolution_max_terms` and `atol_simplify`: These impact accuracy throughout, so tune\n",
" them last, checking with a sweep like the ones above to determine how far the bounds move.\n",
"5. `timeout`: A hard stop rather than a tuning aid, for when a computation must finish by a deadline,\n",
" whatever the quality.\n",
"\n",
"The looser the bounds, the larger the sampling overhead that `compute_local_scales` will report for\n",
"a given bias tolerance. That overhead is the quantity worth watching while tuning: it tells you what\n",
"the approximations actually cost."
]
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3 (ipykernel)",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.13.15"
}
},
"nbformat": 4,
"nbformat_minor": 5
}