> ## 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.

# State Compression

#### Haiqu.state\_compression(circuit=None, circuits=None, compression\_level='balanced', noise\_profile='default', fine\_tuning='low', max\_time=1200, approximation\_level=None)

Compress an arbitrary quantum circuit.

Haiqu's state compression is an approximate fixed-input-state compilation method to extend the effective depth of
circuits that can be executed on noisy hardware. It features several tunable parameters to adjust the trade-off
between compression level and circuit quality, allowing the user to tailor the compression to the circuit and
device noise characteristics.

Both the input and output circuits are assumed to be applied to the all-zero state (|00⋯0⟩). The action of the circuit
on other input states is not preserved by the compression.

* **Parameters:**
  * **circuit** (*QuantumCircuit* *|* *CircuitModel*) -- Deprecated. The quantum circuit to be compressed.
    Circuit must have no more than 1000 qubits.
  * **circuits** (*list* \*\[\**QuantumCircuit* *]*  *|* *list* \*\[\**CircuitModel* *]*) -- The quantum circuit(s) to be compressed.
  * **compression\_level** (*str*) --

    The qualitative compression level. Increased compression level will lead to
    larger part of the input circuit being compressed.
    Four options are available:

    * "low": best used for shallow input circuits or very low noise levels
    * "balanced" (default): gives the best performance for most circuits and noise profiles
    * "high": may sometimes yield better results for very deep circuits
    * "max": the largest possible part of the input circuit will be compressed,
      : yielding the most extreme depth reduction. Recommended to combine
      with custom approximation level to tune the quality.
  * **noise\_profile** (*str*) -- The device noise profile to assume during compression. The currently available options are:
    "ibm\_eagle\_r3", "ibm\_heron\_r1", "ibm\_heron\_r2" (default), "ibm\_heron\_r3",
    "iqm\_garnet" and "iqm\_emerald". Used to automatically set the approximation level.
  * **fine\_tuning** (*str*) --

    The extent to which classical resources should be used to further improve the compressed circuit.
    Three options are available:

    * "disabled": no fine-tuning is performed, yielding the lowest latency
    * "low" (default): best balance between speed and accuracy
    * "heavy": improved circuit accuracy, but time-intensive
  * **max\_time** (*int* *|* *float*) -- Soft time limit for the job (in seconds).
    The compression job will first always produce the initial result and then limit the fine-tuning
    stage by the remaining time left. If time limit exceeds during the fine-tuning - the best
    current result will be returned. Defaults to 1200
    (20 min). Max allowed job time is 20 min.
    The job can take more wall clock time than user specified max\_time due to latency,
    initialization overheads or if the initial result already takes more time.
  * **approximation\_level** (*int* *|* *None*) -- A small integer related to circuit complexity. Larger values improve the noiseless
    quality metric, but may degrade noisy performance. Defaults to `None`, which
    corresponds to auto-selection using the chosen `noise_profile`. Can be set from
    1 (very weak approximation) to 8 (very high approximation). Larger approximation
    level values lead to slower fine-tuning.
* **Returns:**
  The State Compression job(s) that will generate the
  : compressed circuit(s).
  Call `job.result()` to retrieve the compressed circuit as a `CircuitModel`. `job.quality` is the
  compression quality, computed in a noiseless setting; `job.info` exposes compression metadata
  (`compression_quality`, `success`, `compression_status`, `compression_time`,
  `compression_percent`, `approximation_level`).
  Use `job.progress()` for live status updates and `help(job.result)` for the full description of result
  and `info` contents.
* **Return type:**
  StateCompressionJobModel | list\[StateCompressionJobModel]

#### Examples

Generate a circuit:

```python theme={null}
>>> from qiskit.circuit.random import random_circuit
>>> qc = random_circuit(num_qubits=50, depth=5, max_operands=4, seed=2025, measure=False)
>>> circuit_aer = haiqu.transpile(qc, device=haiqu.get_device("aer_simulator"), basis_gates=["cx", "u3"])
>>> print(f"{circuit_aer.analytics.gates_2q} two-qubit gates in the original circuit")
278 two-qubit gates in the original circuit
```

Submit a State Compression job to shrink it:

```python theme={null}
>>> job = haiqu.state_compression(qc)
>>> circuit_comp = job.result()
>>> quality = job.quality
>>> print(f"Circuit is compressed with quality {quality:.6f}")
Circuit is compressed with quality 0.898719
```

Submit an Analytics job to confirm that the compressed circuit has far fewer two-qubit gates:

```python theme={null}
>>> circuit_comp_aer = haiqu.transpile(circuit_comp, device=haiqu.get_device("aer_simulator"),
...                                    basis_gates=["cx", "u3"])
>>> print(f"{circuit_comp_aer.analytics.gates_2q} two-qubit gates in the compressed circuit")
95 two-qubit gates in the compressed circuit
```

Batch submission of the State Compression jobs:

```python theme={null}
>>> circuits = [random_circuit(num_qubits=20, depth=10, max_operands=4, seed=s, measure=False) for s in range(3)]
>>> jobs = haiqu.state_compression(circuits=circuits)
>>> for job in jobs:
...     circuit_comp = job.result()
...     quality = job.quality
...     print(f"Circuit is compressed with quality {quality:.6f}")
```

#### Haiqu.state\_compression\_2d(circuit=None, circuits=None, device=None, device\_id=None, compression\_level='balanced', noise\_profile=None, fine\_tuning='disabled', max\_time=1200, approximation\_level=None)

Compress an arbitrary quantum circuit on a targeted device.
2D state compression follows the topology of a device and produces an already
transpiled circuit.

#### NOTE

2D state compression is currently limited to heavy hex devices.

Haiqu's 2D state compression is an approximate fixed-input-state compilation method to extend
the effective depth of circuits that can be executed on noisy hardware.
It features several tunable parameters to adjust the trade-off between compression
level and circuit quality, allowing the user to tailor the compression to the circuit and device noise characteristics.

Both the input and output circuits are assumed to be applied to the all-zero state (`|00⋯0⟩`). The action of the circuit
on other input states is not preserved by the compression.

* **Parameters:**
  * **circuit** (*QuantumCircuit* *|* *CircuitModel*) -- Deprecated. The quantum circuit to be compressed.
    The circuit size must not exceed device's size.
  * **circuits** (*list* \*\[\**QuantumCircuit* *]*  *|* *list* \*\[\**CircuitModel* *]*) -- The quantum circuit(s) to be compressed.
  * **device** (*DeviceModel* *|* *None*) -- The target device for compression. If specified, `device_id` is ignored.
  * **device\_id** (*str* *|* *None*) -- The ID of the target device for compression. Defaults to `None`.
  * **compression\_level** (*str*) --

    The qualitative compression level. Increased compression level will lead to
    larger part of the input circuit being compressed.
    Four options are available:

    * "low": best used for shallow input circuits or very low noise levels
    * "balanced" (default): gives the best performance for most circuits and noise profiles
    * "high": may sometimes yield better results for very deep circuits
    * "max": the largest possible part of the input circuit will be compressed,
      : yielding the most extreme depth reduction. Recommended to combine
      with custom approximation level to tune the quality.
  * **noise\_profile** (*str* *|* *None*) -- The device noise profile to use during compression. See state\_compression options.
    By default (None) the noise profile is automatically chosen to match the device.
    Used to automatically set the approximation level.
  * **fine\_tuning** (*str*) --

    The extent to which classical resources should be used to further improve the compressed circuit.
    Three options are available:

    * "disabled" (default): no fine-tuning is performed, yielding the lowest latency
    * "low": best balance between speed and accuracy
    * "heavy": improved circuit accuracy, but time-intensive
  * **max\_time** (*int* *|* *float*) -- Soft time limit for the job (in seconds).
    The compression job will first always produce the initial result and then limit the fine-tuning
    stage by the remaining time left. If time limit exceeds during the fine-tuning - the best
    current result will be returned. Defaults to 1200
    (20 min). Max allowed job time is 20 min.
    The job can take more wall clock time than user specified max\_time due to latency,
    initialization overheads or if the initial result already takes more time.
  * **approximation\_level** (*int* *|* *None*) -- A small integer related to circuit complexity. Larger values improve the noiseless
    quality metric, but may degrade noisy performance. Defaults to `None`, which
    corresponds to auto-selection using the chosen `noise_profile`. Can be set from
    1 (very weak approximation) to 8 (very high approximation). Larger approximation
    level values lead to slower fine-tuning.
* **Returns:**
  The State Compression job(s) that will generate the
  : compressed circuit(s).
  Call `job.result()` to retrieve the compressed circuit as a `CircuitModel`, already transpiled to the
  target device topology. `job.quality` is the compression quality, computed in a noiseless setting;
  `job.info` exposes compression metadata (`compression_quality`, `success`, `compression_status`,
  `compression_time`, `compression_percent`, `approximation_level`).
  Use `job.progress()` for live status updates and `help(job.result)` for the full description of result
  and `info` contents.
* **Return type:**
  StateCompressionJobModel | list\[StateCompressionJobModel]

#### Examples

Generate a circuit:

```python theme={null}
>>> from qiskit.circuit.random import random_circuit
>>> quantum_device = "fake_fez"
>>> qc = random_circuit(num_qubits=50, depth=5, max_operands=4, seed=2025, measure=False)
>>> circuit_fez = haiqu.transpile(qc, device=haiqu.get_device(quantum_device))
>>> print(f"{circuit_fez.analytics.gates_2q} two-qubit gates in the circuit transpiled to a device")
1125 two-qubit gates in the circuit transpiled to a device
```

Submit a 2D State Compression job to shrink it:

```python theme={null}
>>> job = haiqu.state_compression_2d(qc, device_id=quantum_device)
>>> circuit_comp = job.result()
>>> quality = job.quality
>>> print(f"Circuit is compressed with quality {quality:.6f}")
Circuit is compressed with quality 0.950118
```

Check the analytics to compare amount of two-qubit gates on a device.
Note that it is already transpiled to a device chosen in the compression call.

```python theme={null}
>>> print(f"{circuit_comp.analytics.gates_2q} two-qubit gates in the compressed circuit")
66 two-qubit gates in the compressed circuit
```

Batch submission of the 2D State Compression jobs:

```python theme={null}
>>> circuits = [random_circuit(num_qubits=20, depth=10, max_operands=4, seed=s, measure=False) for s in range(3)]
>>> jobs = haiqu.state_compression_2d(circuits=circuits, device_id=quantum_device)
>>> for job in jobs:
...     circuit_comp = job.result()
...     quality = job.quality
...     print(f"Circuit is compressed with quality {quality:.6f}")
```