> ## Documentation Index
> Fetch the complete documentation index at: https://docs.classiq.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Error Correction
The fault-tolerant engine lowers a logical circuit onto a surface-code lattice and
estimates its logical error rate under a physical noise model. A typical workflow runs in
four stages: initialize a logical noise model from physical noise, route a transpiled
Clifford+T circuit onto the lattice, visualize the routed program, and estimate its total
error across code distances.
## Initialize Logical Noise
## LogicalNoise
Logical noise parameters retrieved from the backend, with utility methods to
analyze and visualize the noise.
**Methods:**
| Name | Description |
| ------------------------------------------------------------ | ----------------------------------------------------------------------------- |
| [get\_clifford\_logical\_error](#get_clifford_logical_error) | Evaluate the fitted 1-qubit Clifford logical error rate at a code distance. |
| [get\_cnot\_logical\_error](#get_cnot_logical_error) | Evaluate the fitted CNOT logical error rate at a code distance. |
| [get\_s\_logical\_error](#get_s_logical_error) | Evaluate the fitted S gate logical error rate at a code distance. |
| [plot\_clifford](#plot_clifford) | Plot the 1-qubit Clifford logical error rates as a function of code distance. |
| [plot\_cnot](#plot_cnot) | Plot the CNOT logical error rates as a function of code distance. |
| [plot\_s](#plot_s) | Plot the S gate logical error rate as a function of code distance. |
**Attributes:**
| Name | Type | Description |
| -------- | ------------------------ | -------------------------------------------------------------------------------- |
| `params` | `LogicalNoiseParameters` | The stored logical error-rate fits, as returned by the logical noise simulation. |
### get\_clifford\_logical\_error
get\_clifford\_logical\_error(
self: ,
code\_distance: int,
error\_type: Literal\['X', 'Z']
) -> float
Evaluate the fitted 1-qubit Clifford logical error rate at a code distance.
The stored fit is `p_L(d) = 10 ** (a * cd + b)`, where `(a, b)` are the
coefficients returned by the simulation for the requested error type.
**Parameters:**
| Name | Type | Description | Default |
| --------------- | ------------------- | -------------------------------------------------------------------------- | ---------- |
| `self` | \`\` | | *required* |
| `code_distance` | `int` | Code distance `cd` at which to evaluate the fit. | *required* |
| `error_type` | `Literal['X', 'Z']` | Which Clifford error curve to evaluate; `"X"` or `"Z"` (case-insensitive). | *required* |
**Returns:**
* **Type:** `float`
* The logical error rate `p_L(d)`.
### get\_cnot\_logical\_error
get\_cnot\_logical\_error(
self: ,
code\_distance: int,
error\_type: Literal\['IX', 'XI', 'XX', 'IZ', 'ZI', 'ZZ']
) -> float
Evaluate the fitted CNOT logical error rate at a code distance.
The stored fit is `p_L(d) = 10 ** (a * cd + b)`, where `(a, b)` are the
coefficients returned by the simulation for the requested Pauli term.
**Parameters:**
| Name | Type | Description | Default |
| --------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `self` | \`\` | | *required* |
| `code_distance` | `int` | Code distance `cd` at which to evaluate the fit. | *required* |
| `error_type` | `Literal['IX', 'XI', 'XX', 'IZ', 'ZI', 'ZZ']` | Which CNOT Pauli-error curve to evaluate; one of `"IX"`, `"XI"`, `"XX"`, `"IZ"`, `"ZI"`, `"ZZ"` (case-insensitive). The first character is the Pauli error on the control qubit and the second is the Pauli error on the target qubit, where `I` denotes no error. For example, `"IX"` is an X error on the target qubit, and `"ZI"` is a Z error on the control qubit. | *required* |
**Returns:**
* **Type:** `float`
* The logical error rate `p_L(d)`.
### get\_s\_logical\_error
get\_s\_logical\_error(
self: ,
code\_distance: int
) -> float
Evaluate the fitted S gate logical error rate at a code distance.
The stored fit is `p_L(d) = 10 ** (a * cd + b)`, where `(a, b)` are
the coefficients returned by the S gate simulation.
**Parameters:**
| Name | Type | Description | Default |
| --------------- | ----- | ------------------------------------------------ | ---------- |
| `self` | \`\` | | *required* |
| `code_distance` | `int` | Code distance `cd` at which to evaluate the fit. | *required* |
**Returns:**
* **Type:** `float`
* The logical error rate `p_L(d)`.
### plot\_clifford
plot\_clifford(
self: ,
start: int = 5,
end: int = 31,
show: bool = True
) -> None
Plot the 1-qubit Clifford logical error rates as a function of code distance.
**Parameters:**
| Name | Type | Description | Default |
| ------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
| `self` | \`\` | | *required* |
| `start` | `int` | Lower bound of the code-distance axis. | 5 |
| `end` | `int` | Upper bound of the code-distance axis. | 31 |
| `show` | `bool` | Whether to call `plt.show()` after building the figure. Set to `False` to keep the figure open for further customization or when rendering in a non-interactive context. | True |
### plot\_cnot
plot\_cnot(
self: ,
start: int = 5,
end: int = 31,
show: bool = True
) -> None
Plot the CNOT logical error rates as a function of code distance.
**Parameters:**
| Name | Type | Description | Default |
| ------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
| `self` | \`\` | | *required* |
| `start` | `int` | Lower bound of the code-distance axis. | 5 |
| `end` | `int` | Upper bound of the code-distance axis. | 31 |
| `show` | `bool` | Whether to call `plt.show()` after building the figure. Set to `False` to keep the figure open for further customization or when rendering in a non-interactive context. | True |
### plot\_s
plot\_s(
self: ,
start: int = 5,
end: int = 31,
show: bool = True
) -> None
Plot the S gate logical error rate as a function of code distance.
**Parameters:**
| Name | Type | Description | Default |
| ------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
| `self` | \`\` | | *required* |
| `start` | `int` | Lower bound of the code-distance axis. | 5 |
| `end` | `int` | Upper bound of the code-distance axis. | 31 |
| `show` | `bool` | Whether to call `plt.show()` after building the figure. Set to `False` to keep the figure open for further customization or when rendering in a non-interactive context. | True |
## PhysicalNoiseModel
A description of physical noise on a quantum device.
Each list field composes the rules it contains: for example, a
`clifford_1q` field with both a `DepolarizeRule` and a `PauliRule(X)`
applies both channels after every 1-qubit Clifford operation.
**Attributes:**
| Name | Type | Description |
| ------------- | ------------------------------------ | ----------- |
| `idle` | `list[PhysicalNoiseRule]` | |
| `long_idle` | `list[PhysicalNoiseRule]` | |
| `clifford_1q` | `list[PhysicalNoiseRule]` | |
| `clifford_2q` | `list[PhysicalNoiseRule]` | |
| `measure` | `dict[str, Probability]` | |
| `gates` | `dict[str, list[PhysicalNoiseRule]]` | |
## DepolarizeRule
Applies a uniformly random Pauli error with total probability `p`.
`p` is the probability that *some* error occurs; with probability `1-p`
the identity is applied (no error).
For a 1-qubit operation, each of the 3 Pauli errors (X, Y, Z) has
probability `p/3` of being applied.
For a 2-qubit operation, each of the 15 non-identity two-qubit Pauli errors
has probability `p/15` of being applied.
**Attributes:**
| Name | Type | Description |
| ------ | ----------------------- | ----------- |
| `kind` | `Literal['depolarize']` | |
| `p` | `Probability` | |
## PauliRule
Applies a specific Pauli error selected by `pauli` with probability `p`.
With probability `1-p` the identity is applied (no error).
**Attributes:**
| Name | Type | Description |
| ------- | ------------------------ | ----------- |
| `kind` | `Literal['pauli']` | |
| `pauli` | `Literal['X', 'Y', 'Z']` | |
| `p` | `Probability` | |
## LogicalNoiseParameters
Representation for logical error rates of different gates.
**Attributes:**
| Name | Type | Description |
| ---------- | ------------------- | ----------- |
| `clifford` | `CliffordErrors` | |
| `cnot` | `CnotErrors` | |
| `s` | `LogLinear \| None` | |
| `t` | `dict[int, float]` | |
## Route a Program
## TopologicalProgram
A circuit lowered to a 3-D surface-code lattice routing.
**Attributes:**
| Name | Type | Description |
| --------- | ------------------ | ----------- |
| `layout` | `Layout` | |
| `circuit` | `list[RoutedGate]` | |
| `pipes` | `list[Pipe]` | |
| `stats` | `RoutingStats` | |
## Visualize
## Estimate Total Error
## Functions
### initialize\_logical\_noise
initialize\_logical\_noise(
name: str,
noise\_model: PhysicalNoiseModel
) -> None
Simulate logical error rates for a physical noise model and store them under `name`.
Runs the logical noise simulation on the backend and persists the resulting
`LogicalNoiseParameters` so they can later be retrieved with
`get_logical_noise` or used by subsequent stages of the engine.
This is a long-running operation (interrupting this SDK function will not interrupt
the initialization in the backend).
**Parameters:**
| Name | Type | Description | Default |
| ------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------- | ---------- |
| `name` | `str` | Identifier to store the resulting logical noise under. Must not already exist for the current user. | *required* |
| `noise_model` | [PhysicalNoiseModel](#physicalnoisemodel) | Physical noise description to simulate. | *required* |
### get\_logical\_noise
get\_logical\_noise(
name: str
) -> LogicalNoise
Retrieve previously initialized logical noise parameters.
**Parameters:**
| Name | Type | Description | Default |
| ------ | ----- | -------------------------------------------------------- | ---------- |
| `name` | `str` | Identifier used when calling `initialize_logical_noise`. | *required* |
**Returns:**
* **Type:** [LogicalNoise](#logicalnoise)
* The stored parameters wrapped in a `LogicalNoise` for plotting and
* analyzing.
### remove\_logical\_noise
remove\_logical\_noise(
name: str
) -> None
Delete logical noise parameters stored under `name`.
**Parameters:**
| Name | Type | Description | Default |
| ------ | ----- | -------------------------------------------------------- | ---------- |
| `name` | `str` | Identifier used when calling `initialize_logical_noise`. | *required* |
### route\_circuit
route\_circuit(
qasm: str
) -> TopologicalProgram
Route a transpiled Clifford+T QASM circuit onto a 3-D surface-code lattice.
**Parameters:**
| Name | Type | Description | Default |
| ------ | ----- | ------------------------------------------------------------------- | ---------- |
| `qasm` | `str` | Transpiled OpenQASM 2 or 3 source (single-qubit Clifford+T and CX). | *required* |
**Returns:**
* **Type:** [TopologicalProgram](#topologicalprogram)
* A `TopologicalProgram` describing the routed lattice: per-gate cube
* placements, pipes, and aggregate stats.
### view\_program
view\_program(
program: TopologicalProgram,
output\_path: str | Path | None = None,
show: bool = False,
start\_cycle: int = 0,
end\_cycle: int | None = None
) -> str
Render a routed `TopologicalProgram` as an interactive HTML visualization.
The returned HTML is a self-contained page that can be opened directly in a
web browser.
**Parameters:**
| Name | Type | Description | Default |
| ------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
| `program` | [TopologicalProgram](#topologicalprogram) | The routed program to visualise. | *required* |
| `output_path` | `str \| Path \| None` | If given, also write the HTML to this file. | None |
| `show` | `bool` | If `True`, display the visualization. In a Jupyter notebook the HTML is embedded inline; otherwise it is opened in a web browser, which requires `output_path` to be set. | False |
| `start_cycle` | `int` | First cycle (z-layer) to include; cubes below it are hidden. Defaults to 0. | 0 |
| `end_cycle` | `int \| None` | Cycle (z-layer) to stop before; cubes at or above it are hidden. Defaults to the program's total cycle count (show all), but is capped to {cap} cycles from `start_cycle` when left unspecified. | None |
**Returns:**
* **Type:** `str`
* The HTML document as a string.
### estimate\_total\_errors
estimate\_total\_errors(
program: TopologicalProgram,
logical\_noise: LogicalNoiseParameters | LogicalNoise | str,
code\_distances: Iterable\[int]
) -> dict\[int, float]
Estimate the routed program's total error (`1 - fidelity`) at multiple
code distances.
**Parameters:**
| Name | Type | Description | Default |
| ---------------- | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `program` | [TopologicalProgram](#topologicalprogram) | The routed program to evaluate. | *required* |
| `logical_noise` | [LogicalNoiseParameters](#logicalnoiseparameters) \| [LogicalNoise](#logicalnoise) \| str | Logical-noise fits to evaluate the per-gate fidelities against. Accepts a `LogicalNoiseParameters` directly, a `LogicalNoise` wrapper (its `params` are used), or a `str` name looked up via `get_logical_noise`. | *required* |
| `code_distances` | `Iterable[int]` | Surface-code distances at which to estimate the total error. | *required* |
**Returns:**
* **Type:** `dict[int, float]`
* A mapping from each requested code distance to the estimated total error.