FAQ - Haiqu Documentation

General

Where does the name “Haiqu” come from?

It reflects compression—reducing large quantum circuits into smaller ones, similar to how a haiku compresses meaning into a few lines.

What is Haiqu SDK and who is it for?

Haiqu SDK is quantum middleware — a software layer that sits between your code and quantum hardware. Instead of wrestling with low-level noise, transpilation quirks, and device-specific constraints, you write standard Qiskit circuits and let Haiqu handle the rest: circuit compression, error mitigation, transpilation, and experiment tracking are all built in.It is designed for:

Quantum researchers and engineers who want to push the limits of what runs on real QPUs today
Enterprise teams exploring quantum advantage in optimization, simulation, machine learning, and finance
Applied scientists who want reproducible, tracked quantum experiments without building their own infrastructure

The SDK connects to IBM Quantum, AWS Braket, and IonQ Cloud, so you can target whichever hardware your use case demands.

Do I need a quantum computing background to use Haiqu SDK?

Not a deep one. If you can write a Qiskit QuantumCircuit, you can use Haiqu SDK. The hardest parts of running on real quantum hardware — optimizing transpilation, compressing a circuit, and applying error mitigation — are handled automatically by the SDK.If you are starting from scratch, the Quick Start gets you from zero to a running circuit, including error mitigation, with fewer than ten lines of code.

Which quantum frameworks does Haiqu SDK support?

Haiqu SDK works with Qiskit QuantumCircuit objects. All core features — haiqu.run(), haiqu.state_compression(), haiqu.transpile(), and data loading — expect Qiskit circuits as input.

If you are working in PennyLane or Cirq, you will need to convert your circuits to Qiskit format before passing them to the SDK. Qiskit provides interoperability tools for common conversions.

Does Haiqu SDK give me access to quantum hardware, or do I need my own?

Haiqu SDK is middleware, not a hardware provider. It routes your jobs to hardware you already have credentials for. To run on real QPUs you need:

IBM Quantum: an IBM Quantum account and API token
AWS Braket: AWS IAM credentials with Braket permissions
IonQ Cloud: an IonQ Cloud API key

Simulators (aer_simulator, fake_fez, fake_torino, and other fake_* backends) work out of the box with no external credentials and are the best place to start.

Getting Started & Installation

What is the fastest way to get started?

The quickest path is the cloud JupyterLab environment — everything is pre-installed and pre-configured. No setup required. You just need your API key and you can run your first circuit within minutes.See the Quick Start guide.

Authentication & API Keys

How do I authenticate with Haiqu SDK?

Call haiqu.login() at the start of every session:

from haiqu.sdk import haiqu

# Cloud JupyterLab: API key is pre-configured, no argument needed
haiqu.login()

# Local install: pass your API key explicitly
haiqu.login(api_access_key="YOUR_HAIQU_API_KEY")

After login, initialize an experiment to keep your work organized:

haiqu.init("My Experiment")

I'm getting an authentication error even though I'm using the correct API key. What's wrong?

The most common causes, in order of frequency:

Trailing whitespace — copy-pasting an API key from an email or PDF often includes an invisible space or newline at the end. Try api_access_key=key.strip().
Wrong token — using the GitHub install token instead of the Haiqu API key (see the installation FAQ above).
Expired or revoked key — keys can be rotated. Check the Dashboard or contact support at feedback.haiqu.ai to request a new key.

Do I need separate credentials for IBM Quantum or AWS Braket?

Yes. There are two independent credential layers:

Layer	What it does	Where it comes from
Haiqu API key	Authenticates you to the Haiqu platform	Your Haiqu welcome email
IBM / AWS / IonQ credentials	Authorizes QPU job submission to the hardware provider	Your IBM Quantum, AWS, or IonQ account

Your Haiqu API key does not grant access to external QPUs. You need provider credentials to run on real hardware. Simulators work without them.

How do I avoid entering my IBM or AWS credentials on every run?

Use the credential-saving helpers once per environment:

# IBM Quantum
haiqu.save_ibm_credentials(
    ibm_quantum_token="YOUR_IBM_TOKEN",
    ibm_quantum_instance="YOUR_INSTANCE_CRN",
)

# AWS Braket
haiqu.save_aws_credentials(
    aws_access_key_id="YOUR_KEY_ID",
    aws_secret_access_key="YOUR_SECRET",
    aws_default_region="us-east-1",
)

After saving, you can omit the options dict from haiqu.run() entirely — the SDK reads the stored credentials automatically.

For IonQ, pass ionq_api_key directly in the options dict on each run — there is no persistent save helper for IonQ credentials at this time.

Running Circuits

Why should I use haiqu.run() instead of submitting directly to IBM or AWS?

When you submit a circuit directly through an IBM or AWS SDK, you get back raw noisy results with no automatic optimizations applied. haiqu.run() wraps execution with:

Automatic transpilation to the target device’s gate set and qubit connectivity
Optional error mitigation (use_mitigation=True) to reduce the effect of hardware noise
Experiment tracking — every circuit and job is saved to your experiment history
A unified interface across IBM, AWS, and IonQ — the same call works regardless of hardware provider

For development and rapid iteration, any of the free simulators work without credentials and give you the same interface.

What is the difference between device_id and device?

Both work in haiqu.run() — they are two ways to specify the same thing:

# Short form: pass a string directly
job = haiqu.run(circuit, shots=1000, device_id="ibm_boston")

# Long form: initialize a device object first
device = haiqu.get_device("ibm_boston")
job = haiqu.run(circuit, shots=1000, device=device)

Use device_id for quick one-liners. Use device when you want to inspect backend properties or reuse the same device object across multiple runs.

What simulators can I use without hardware credentials?

The following backends work out of the box — no IBM, AWS, or IonQ account required:

Backend	What it simulates
`aer_simulator`	Ideal noiseless simulation
`fake_fez`	IBM Fez noise model
`fake_torino`	IBM Torino noise model
other `fake_*` backends	Various IBM device noise models

Use simulators for all development and debugging. Switch to a real QPU only when you need hardware-level validation.

job = haiqu.run(circuit, shots=1000, device_id="aer_simulator")

Does Haiqu SDK handle transpilation automatically when I call haiqu.run()?

Yes. You do not need to transpile your circuit before calling haiqu.run(). The SDK automatically transpiles to the target device’s native gate set and qubit connectivity.Call haiqu.transpile() explicitly only when you want to inspect the transpiled circuit or compare transpilation strategies:

transpiled = haiqu.transpile(circuit, device, optimization_level=3)
haiqu.compare_metrics(transpiled, another_transpiled)

See the Transpilation guide for details.

My job is stuck in a pending/queued state. What should I do?

Queue behavior depends on where the job is running:

Real QPUs (IBM, AWS, IonQ): queue times are controlled by the hardware provider and can range from minutes to hours depending on demand. This is outside Haiqu’s control. Use job.progress() or job.retrieve_status() to monitor without blocking your session.
Simulators: jobs should complete in seconds. If a simulator job is stuck, check your credit balance in the Dashboard and contact support at feedback.haiqu.ai if the issue persists.

job.retrieve_status()  # non-blocking status check
job.progress()         # visual progress indicator

How do I retrieve results from a job I ran in a previous session?

All jobs are persisted on the Haiqu platform. Find the job ID in your Dashboard or by listing jobs programmatically, then retrieve it:

# List all jobs in the current experiment
haiqu.list_jobs()

# Retrieve a specific job by ID
job = haiqu.get_job("JOB_ID")
results = job.result()

You can also filter by circuit: haiqu.list_jobs(circuit=circuit_id).

Circuit Compression

What does state_compression actually do to my circuit?

state_compression produces a shallower approximate circuit that acts on the all-zero input state in a way that closely mimics your original circuit. It is not lossless — the approximation quality is reported by job.quality after the job completes.The key insight is that on noisy hardware, a shallower approximate circuit often produces better results than the exact deep circuit. Fewer gates means less accumulated noise, which more than compensates for the approximation error. Haiqu’s compression is designed with this trade-off in mind: it actively uses the device’s noise profile to optimize for real-hardware performance, not just ideal-device fidelity.

job = haiqu.state_compression(circuit=circuit)
compressed_circuit = job.result()

print(job.quality)  # approximation quality on an ideal device

When should I use compression, and when should I skip it?

Use compression when:

Your circuit is deep (many two-qubit gates) and hardware noise is limiting your results
You are targeting a real QPU and want to maximize the signal-to-noise ratio
You want to run circuits that would otherwise be too deep to produce meaningful results

Skip compression when:

Your circuit is already shallow — the approximation overhead is not worth the gain
Your circuit uses mid-circuit measurements with classical feedforward logic (compression applies only to the portion before the first MCM)
You are prototyping on a noiseless simulator — compression serves no purpose there

If unsure, try compression_level="low" first on shallow circuits. Check job.quality to decide whether the trade-off is acceptable before committing to heavier compression.

How do I choose the right compression_level?

Start with the default ("balanced") and adjust based on your circuit depth and job.quality score:

Level	Best for
`"low"`	Already-shallow circuits; very clean hardware; maximum fidelity preservation
`"balanced"`	Default; best performance across most circuits and noise levels
`"high"`	Very deep circuits where `"balanced"` does not reduce depth enough

The fine_tuning parameter also affects quality vs. speed:

Fine-tuning	When to use
`"disabled"`	Fastest; good for rapid iteration
`"low"`	Default; best balance of speed and accuracy
`"heavy"`	Best accuracy; use for final production runs

Which noise_profile should I set?

Set noise_profile to match the QPU device you plan to execute on. If they do not match, the compression is tuned for the wrong noise characteristics and you leave performance on the table.

Profile	Device family
`"ibm_eagle_r3"`	IBM Eagle (e.g. ibm_brisbane)
`"ibm_heron_r1"`	IBM Heron R1
`"ibm_heron_r2"`	IBM Heron R2 — default
`"ibm_heron_r3"`	IBM Heron R3
`"iqm_garnet"`	IQM Garnet (via AWS Braket)
`"iqm_emerald"`	IQM Emerald (via AWS Braket)

job = haiqu.state_compression(
    circuit=circuit,
    noise_profile="ibm_heron_r2",   # matches ibm_torino, ibm_fez, etc.
)

Does compression work with mid-circuit measurements?

Yes, but with a limitation: compression is applied only to the portion of the circuit before the first mid-circuit measurement. The remainder of the circuit is left unchanged. If the first MCM is early in the circuit, compression will have little effect.

How long does compression take, and can I run it in the background?

state_compression is asynchronous — it submits a job and returns immediately. You can do other work while it runs and call job.result() when you need the output.At 100 qubits, approximate runtimes are:

Fine-tuning	Typical runtime
`"disabled"`	30 seconds
`"low"` (default)	Up to 5 minutes
`"heavy"`	Up to 15 minutes

The runtime depends on the circuits itself and their scale. Use "disabled" or "low" during development and "heavy" for final runs.

Error Mitigation

What does use_mitigation=True do under the hood?

Haiqu SDK automatically selects the appropriate mitigation strategy based on your workload type — you do not need to choose a technique manually.Simply toggle the flag and Haiqu handles the rest:

job = haiqu.run(
    circuits=circuit,
    device=device,
    shots=1000,
    use_mitigation=True,
)

Is error mitigation always beneficial? Should I always set use_mitigation=True?

Not always. The overhead is only worth it in certain conditions:Enable mitigation when:

Running on real QPUs where hardware noise is significant
Your circuits are moderately deep (more 2Q gates = more noise = more mitigation benefit)

Skip mitigation when:

Using simulators (aer_simulator, fake_*) — there is no real noise to mitigate
Rapid prototyping and debugging — the overhead increases latency without benefit
Your circuit is very shallow and the hardware noise floor is already low

For production QPU runs, combine both features: compress the circuit first to reduce depth, then run with use_mitigation=True. These two features are designed to work together.

Should I combine compression and error mitigation?

Yes — they are complementary and designed to work together. The recommended workflow for production QPU runs is:

Compress the circuit with haiqu.state_compression(), using the noise_profile that matches your target device
Run the compressed circuit with haiqu.run(..., use_mitigation=True)

Compression reduces circuit depth (less accumulated noise), and error mitigation then further cleans up the remaining hardware noise. Used together, they give significantly better results than either technique alone.

Transpilation

Do I need to transpile my circuit before calling haiqu.run()?

No. haiqu.run() transpiles automatically to the target device’s native gate set and qubit connectivity.Call haiqu.transpile() explicitly only when you want to:

Inspect the transpiled circuit before execution
Compare the effect of different transpilation parameters (optimization level, layout)

What transpiler does Haiqu use?

Haiqu uses the open-source Rivet Transpiler, developed by Haiqu. Rivet is built on top of Qiskit’s transpilation framework and exposes additional parameters for fine-grained control over layout, routing, and gate decomposition.Full parameter documentation is available in the Rivet docs.

How do I compare different transpilation strategies?

Transpile the same circuit with different parameters, then use haiqu.compare_metrics() to view depth, gate count, and other metrics side by side:

device = haiqu.get_device("fake_torino")

t_opt0 = haiqu.transpile(circuit, device, optimization_level=0)
t_opt3 = haiqu.transpile(circuit, device, optimization_level=3)

haiqu.compare_metrics(t_opt0, t_opt3)

Should I transpile before or after compression?

If you are using state_compression— pass the un-transpiled circuit (or one with minimal transpilation). The compression algorithm prefers linear-connectivity input and handles device adaptation internally as part of the compression process.After compression, call haiqu.run() as usual. It will apply the final transpilation to your target device automatically.

# 1. Compress the raw circuit
job = haiqu.state_compression(circuit=circuit, noise_profile="ibm_heron_r3")
compressed = job.result()

# 2. Run — haiqu.run() transpiles the compressed circuit for you
result = haiqu.run(compressed, device_id="ibm_boston", shots=1000)

If you are using state_compression_2d — also pass the un-transpiled circuit. However, the function will output a transpiled circuit.

Experiment Tracking

Do I have to call haiqu.init() before running circuits?

No — if you skip it, your circuits and jobs are placed in a default experiment automatically. Nothing breaks.That said, calling haiqu.init() with a descriptive name at the start of your session is strongly recommended. Experiments accumulate quickly, and without meaningful names it becomes difficult to find specific jobs in the Dashboard or via haiqu.list_jobs() later.

haiqu.init("VQE benchmark — ibm_torino — April 2025")

What is the difference between haiqu.log() and haiqu.run()?

	`haiqu.log()`	`haiqu.run()`
Executes the circuit	No	Yes
Saves to experiment history	Yes	Yes (automatically)
Returns	A tracked circuit object	A job object

Use haiqu.log() when you want to register a circuit for tracking, analysis, or future reference without running it yet. In most workflows you can skip haiqu.log() entirely — haiqu.run() saves the circuit automatically.

# Log without executing
tracked = haiqu.log(qc, name="Bell state", description="2-qubit entangled state")

# Run (also logs automatically)
job = haiqu.run(qc, shots=1000, device_id="aer_simulator")

I ran a long experiment and closed my notebook. How do I get my results back?

All jobs and circuits are persisted on the Haiqu platform — closing your notebook does not lose anything.

# Find your job in the current experiment
haiqu.list_jobs()

# Or retrieve from a specific experiment
haiqu.list_jobs(experiment_id="EXPERIMENT_ID")

# Load the job and get results
job = haiqu.get_job("JOB_ID")
results = job.result()

You can also browse all experiments and jobs in the Dashboard and copy job IDs from there.

How do I share experiment results with my team?

Use Experiment Reports in the Dashboard. Reports support LaTeX-style Markdown for scientific notation and equations. You can attach plots and metric tables as artifacts by drag and drop.To log a Matplotlib plot programmatically so it appears in the report:

import matplotlib.pyplot as plt

fig, ax = plt.subplots()
ax.bar(results.keys(), results.values())

haiqu.log(fig, name="Result distribution")

Supported table artifacts include circuit core metrics, advanced metrics, and comparison tables generated by haiqu.compare_metrics().

Hardware Integrations

How do I connect Haiqu SDK to my IBM Quantum account?

Save your credentials once using the helper, then submit jobs by device name:

haiqu.save_ibm_credentials(
    ibm_quantum_token="YOUR_IBM_TOKEN",
    ibm_quantum_instance="YOUR_INSTANCE_CRN",
)

# After saving, credentials are applied automatically
job = haiqu.run(circuit, shots=1000, device_id="ibm_boston")

Your IBM token and instance CRN are available at quantum.cloud.ibm.com. See the IBM Quantum integration page for a full walkthrough.

How do I use AWS Braket hardware through Haiqu SDK?

Configure AWS credentials using one of three methods:

# Option 1: Haiqu helper (recommended)
haiqu.save_aws_credentials(
    aws_access_key_id="YOUR_KEY_ID",
    aws_secret_access_key="YOUR_SECRET",
    aws_default_region="us-east-1",
)

# Option 2: AWS CLI (credentials stored in ~/.aws/)
# aws configure

# Option 3: Pass inline per run
options = {
    "aws_access_key_id": "YOUR_KEY_ID",
    "aws_secret_access_key": "YOUR_SECRET",
    "aws_default_region": "us-east-1",
}

AWS Braket gives access to multiple hardware providers including IQM, IonQ, and Rigetti. Use the appropriate device_id, for example "aws_ionq_aria_1". See the AWS Braket integration page for details.

We recommend issuing temporary AWS credentials with limited Braket-only permissions rather than long-lived root credentials.

Can I use IonQ hardware?

Yes, via the IonQ Cloud integration. Pass your IonQ API key in the options dict:

options = {
    "ionq_api_key": "YOUR_IONQ_API_KEY",
}

# Check available devices first
haiqu.list_devices()

job = haiqu.run(
    circuit,
    shots=1000,
    device_id="ionq_qpu.forte-enterprise-1",
    options=options,
)

Get your IonQ API key at cloud.ionq.com/settings/keys.

Unlike IBM and AWS, there is no persistent save_ionq_credentials() helper — you need to include ionq_api_key in options for each run.

I have access to a QPU backend not listed in the docs. Can I still use it?

Reach out via feedback.haiqu.ai. Haiqu’s device abstraction is designed to support additional backends, and the team evaluates new integration requests based on demand. Include the provider name and backend identifier in your request.

Credits & Pricing

What counts toward my early access credits?

Credits are measured in SDK execution time (1 second = 1 credit). The early access plan includes 1 hour of execution time.

Credits are topped up to 1 hour once a month for each user.

How do I check my remaining credit balance?

Your credit usage progress bar is visible on the main Dashboard.

What happens when I run out of credits?

Job submissions will return an error and you will not be charged once your credit balance is exhausted. To continue using Haiqu SDK, contact the Haiqu team via feedback.haiqu.ai.

Troubleshooting

I'm getting an ImportError when importing haiqu. What should I do?

Work through this checklist in order:

Is the right conda environment active?

conda activate haiqu-env
python -c "import haiqu"

Is the Python version 3.10?
```
python --version  # must be 3.10.x
```
Is the Haiqu SDK version updated?
```
pip show haiqu-sdk
```
Did the installation complete successfully? Re-run the install command and confirm the final line reads Successfully installed haiqu-sdk-x.y.z.
```
pip install 'git+https://GITHUB_TOKEN@github.com/haiqu-ai/haiqu-sdk.git#egg=haiqu-sdk'
```
Is there a conflicting Qiskit version? Run pip show qiskit and compare against the version installed by Haiqu SDK. Mixed-version environments are a frequent source of import errors.

If none of the above resolves the issue, share the full error traceback at feedback.haiqu.ai.

The documentation seems to be out of sync with the SDK. What do I do?

Please check the Haiqu SDK version; if it’s mismatched, upgrade and restart the kernel. If matched, contact us.

My circuit results look wrong or significantly worse than expected on a real QPU.

Go through this checklist:

Enable error mitigation: is use_mitigation=True set in haiqu.run()?
Check circuit depth: very deep circuits degrade even with mitigation. Try haiqu.state_compression() first and verify the job.quality score.
Match the noise profile: if using compression, confirm noise_profile matches your target device (see the compression FAQ above).
Run a simulator baseline: execute the same circuit on aer_simulator and compare. If the ideal simulator result also looks wrong, the issue is in the circuit logic, not hardware noise.
Check shot count: too few shots lead to high statistical variance. For distributions, try at least 1000 shots; for observables, 2000+ with mitigation.

haiqu.run() returns immediately but job.result() hangs. What is happening?

haiqu.run() is non-blocking — it submits the job and returns a job handle right away. job.result() is blocking — it waits until the job is complete before returning.On real QPUs, jobs can sit in provider queues for minutes to hours. To track the progress of your job:

# Check status without blocking
print(job.retrieve_status())

# Visual progress indicator (is a blocking display)
job.progress()

# Only call result() once the job is done
if job.retrieve_status() == "DONE":
    results = job.result()

Where do I report a bug or request a feature?

Submit bug reports and feature requests at feedback.haiqu.ai.For bugs, include:

Haiqu SDK version (pip show haiqu-sdk)
Python version (python --version)
All relevant IDs (experiment, circuit, job, etc.)
A minimal code snippet that reproduces the issue
The full error message and traceback

I'm not finding an answer here. Where else can I look?

SDK Reference — full API documentation for every function and parameter
API Reference — REST API documentation
Cookbook — end-to-end code examples for real use cases (LR-QAOA, quantum dynamics, and more)
Benchmarks — performance data and specifications across hardware platforms
Support — direct contact with the Haiqu team

Documentation Index

​General

​Getting Started & Installation

​Authentication & API Keys

​Running Circuits

​Circuit Compression

​Error Mitigation

​Transpilation

​Experiment Tracking

​Hardware Integrations

​Credits & Pricing

​Troubleshooting

General

Getting Started & Installation

Authentication & API Keys

Running Circuits

Circuit Compression

Error Mitigation

Transpilation

Experiment Tracking

Hardware Integrations

Credits & Pricing

Troubleshooting