Skip to main content

​
Haiqu.state_compression(circuit=None, circuits=None, compression_level=‘balanced’, noise_profile=‘default’, fine_tuning=‘low’, 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. Three 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
    • 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
    • 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: 
>>> 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: 
>>> 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: 
>>> 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: 
>>> 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’, 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. Three 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
    • 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
    • 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: 
>>> 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: 
>>> 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. 
>>> 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: 
>>> 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}")