> ## Documentation Index
> Fetch the complete documentation index at: https://docs.haiqu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Compression

> Record-breaking circuit depth reduction at utility scale

Haiqu SDK `state_compression` function is an approximate compilation method extending the depth of the circuit, which can be run on noisy hardware. It automatically adjusts the compression parameters to achieve the best performance by taking into account the device's characteristics, including noise and topology.

## Linear topology compression

To compress a circuit using idealized linear topology you simply create a state compression job

```python theme={null}
job = haiqu.state_compression(circuit=circuit)
```

and obtain the compressed circuit as a result

```python theme={null}
circuit_compressed = job.result()
quality = job.quality
```

The computed `quality` metric is a fidelity-like metric, which Haiqu internally computes in the end of the compression to quantify circuit approximation quality on a noiseless device. Unlike quantum state fidelity it is scalable and does not vanish with increasing the systems size, meanwhile it is highly correlated with the observables precision. As a rule of thumb you can treat its values as follows:

| Quality | Description                                                                             |
| ------- | --------------------------------------------------------------------------------------- |
| 100%    | Perfect match between quantum states, generated by the original and compressed circuits |
| 90%     | Very good quality                                                                       |
| 75%     | Good quality                                                                            |
| 50%     | Mediocre quality                                                                        |
| 0%      | States do not match at all                                                              |

<Note>
  Haiqu’s compression utilizes the device’s noise profile to ensure the best results on actual hardware. Default noise settings correspond to IBM's Heron R2 device and can be changed by modifying `noise_profile` parameter (see below). State compression function can trade-off theoretical approximation on an ideal device for more compact circuits that perform better on real quantum hardware.
</Note>

In the following frame you can see the metrics comparison of the original and compressed 50-qubits randomly generated circuit with `qiskit.circuit.random.random_circuit`.

<Frame>
  <img alt="Image" lightAlt="Image" darkAlt="Image" src="https://mintcdn.com/haiqu/DjRJlqQlLMCYZfXw/images/compression_comparison_example.png?fit=max&auto=format&n=DjRJlqQlLMCYZfXw&q=85&s=c4f761fba419cbdad5bc8c635cee6263" className="dark:hidden" width="1361" height="532" data-path="images/compression_comparison_example.png" />

  <img alt="Image" lightAlt="Image" darkAlt="Image" src="https://mintcdn.com/haiqu/DjRJlqQlLMCYZfXw/images/compression_comparison_example-dark.png?fit=max&auto=format&n=DjRJlqQlLMCYZfXw&q=85&s=d53884b6cbd4223aef54b63ef06e9089" className="hidden dark:block" width="1360" height="530" data-path="images/compression_comparison_example-dark.png" />
</Frame>

## Device topology-aware compression

To use device topology-aware compression, use the `state_compression_2d`  method. For example:

```python theme={null}
job = haiqu.state_compression_2d(circuit=circuit, device_id="ibm_fez")
circuit_compressed = job.result()
```

This call requires specifying the device, and results in an already compressed and transpiled circuit. The method uses noise data from the device to tune the compression approximation rates automatically.

<Note>
  `state_compression_2d` is currently limited only to devices with heavy-hex connectivity.
</Note>

<Tip>
  The basic `state_compression` function is computationally very efficient and should be used by default for general circuits. `state_compression_2d` is computationally more demanding and achieves very good results when the input circuits have already been designed with a particular device topology in mind.
</Tip>

## Parameters

* `circuit` – the quantum circuit whose action on all-0 state is to be compressed.
* `compression_level` – defines the compression level. Increased compression level will lead to larger part of the input circuit being compressed. Three options are available:
  * `low` – this setting is best used for already shallow input circuits or very low noise levels;
  * `balanced` – the default setting gives the best performance for most circuits and noise profiles;
  * `high` – this setting may sometimes yield better results for very deep circuits.
* `noise_profile` – sets the noise profile to which the function adjusts the compression algorithm. Used to automatically set the approximation level. Currently available options are `"ibm_eagle_r3"`, `"ibm_heron_r1"`, `"ibm_heron_r2"` (used by default), `"ibm_heron_r3"`, `"iqm_garnet"` and `"iqm_emerald"`.
* `fine_tuning` – uses classical resources to further improve the compressed circuit. Three options are available:
  * `disabled` – no fine-tuning performed, the lowest latency;
  * `low` – default, best balance between speed and accuracy;
  * `heavy` – improved circuit accuracy, but time-intensive.
* `approximation_level` – an integer-valued parameter influencing circuit complexity. Larger values improve the noiseless quality metric, but may degrade noisy performance. Defaults to None, which corresponds to auto-selection using the provided noise profile. Can be set to any value from **1** (very weak approximation) to **8** (very high approximation). Larger approximation level values lead to slower fine-tuning.
* `device` or `device_id` (only for `state_compression_2d`) – target device for the compression.

See [Haiqu SDK Reference | State Compression](/reference/middleware/compression) for more details on`haiqu.state_compression` and `haiqu.state_compression_2d`.

## State Compression Specifications

| **Parameter**               | **Details**                                                                                                                                                       |
| :-------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Number of qubits**        | Up to 1000                                                                                                                                                        |
| **Runtime (at 100 qubits)** | From few seconds and <br /> up to 2 minutes with no fine-tuning; <br /> up to 15 minutes with heavy fine-tuning                                                   |
| **Runtime scaling**         | Linear scaling with circuit size, problem-dependent                                                                                                               |
| **Supported circuits**      | - Circuits decomposable into CNOT, RX, RY, RZ basis gates <br />- Circuits with mid-circuit measurements are supported, but compression applies only prior to MCM |
| **Supported connectivity**  | Any. <br />  Not transpiled input with Linear connectivity is preferred.                                                                                          |
| **Compression rate**        | Up to 100× for various application circuits                                                                                                                       |
| **Returned metrics**        | - Compression rate <br />- Quality of the compression (fidelity-like metric)                                                                                      |

## State Compression 2D Specifications

| **Parameter**               | **Details**                                                                                                                                                       |
| :-------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Number of qubits**        | Up to the available number of qubits on the quantum device                                                                                                        |
| **Runtime (at 100 qubits)** | From 1 to 5 minutes with no fine-tuning; <br />up to 30 minutes with heavy fine-tuning                                                                            |
| **Runtime scaling**         | Polynomial scaling with circuit size, problem- and device-dependent                                                                                               |
| **Supported circuits**      | - Circuits decomposable into CNOT, RX, RY, RZ basis gates <br />- Circuits with mid-circuit measurements are supported, but compression applies only prior to MCM |
| **Supported connectivity**  | Any. Circuit will be transpiled to the device connectivity but preferable to already follow it.                                                                   |
| **Compression rate**        | Up to 100× for various application circuits                                                                                                                       |
| **Returned metrics**        | - Compression rate <br />- Quality of the compression (fidelity-like metric)                                                                                      |

\*runtime can vary for different circuit classes of the same size