Quantinuum Quick Start¶

This notebook walks you through running your first QESEM job on a Quantinuum system.

Setup¶

Install the Qedma client, import the relevant packages, and configure your Qedma client. See Installation for more information.

In [ ]:

!pip install -U "qedma-api[quantinuum]" qiskit

!pip install -U "qedma-api[quantinuum]" qiskit

In [2]:

import qedma_api
import qiskit
import getpass
import qnexus

import qedma_api import qiskit import getpass import qnexus

In [ ]:

def get_quantinuum_refresh_token():
    qnexus.logout()
    response = qnexus.client.get_nexus_client().post(
        "https://nexus.quantinuum.com/auth/login",
        json={
            "email": input("Quantinuum email: "),
            "password": getpass.getpass("Quantinuum password: "),
        },
    )
    response.raise_for_status()

    refresh_token = response.cookies.get("myqos_oat")
    if refresh_token is None:
        raise RuntimeError("Quantinuum did not return a refresh token.")
    return refresh_token

refresh_token = get_quantinuum_refresh_token()

def get_quantinuum_refresh_token(): qnexus.logout() response = qnexus.client.get_nexus_client().post( "https://nexus.quantinuum.com/auth/login", json={ "email": input("Quantinuum email: "), "password": getpass.getpass("Quantinuum password: "), }, ) response.raise_for_status() refresh_token = response.cookies.get("myqos_oat") if refresh_token is None: raise RuntimeError("Quantinuum did not return a refresh token.") return refresh_token refresh_token = get_quantinuum_refresh_token()

In [ ]:

qedma_client = qedma_api.Client(api_token="<Qedma API token>")
qedma_client.unregister_qpu_token()
qedma_client.register_qpu_token(token=refresh_token)

provider = qedma_api.QuantinuumProvider()
qedma_client.set_provider(provider)

qedma_client = qedma_api.Client(api_token="") qedma_client.unregister_qpu_token() qedma_client.register_qpu_token(token=refresh_token) provider = qedma_api.QuantinuumProvider() qedma_client.set_provider(provider)

Build a Circuit and Observables¶

Create a circuit using Qiskit or pytket.

In [ ]:

circuit = qiskit.QuantumCircuit(5)
circuit.h(0)
circuit.cx(0, 1)
circuit.cx(1, 2)
circuit.cx(2, 3)
circuit.cx(3, 4)

avg_magnetization = qiskit.quantum_info.SparsePauliOp.from_sparse_list(
    [("Z", [q], 1 / 5) for q in range(5)], num_qubits=5
)

circuit = qiskit.QuantumCircuit(5) circuit.h(0) circuit.cx(0, 1) circuit.cx(1, 2) circuit.cx(2, 3) circuit.cx(3, 4) avg_magnetization = qiskit.quantum_info.SparsePauliOp.from_sparse_list( [("Z", [q], 1 / 5) for q in range(5)], num_qubits=5 )

Create the Job¶

The QESEM flow begins with create_job(...). This step registers the workload, starts analytical estimation automatically, and returns a job identifier that can then be used to estimate the HQC cost of the empirical estimation and the remaining mitigation.

In [ ]:

job = qedma_client.create_job(
    circuit=circuit,
    observables=[avg_magnetization],
    observables_metadata=[
        qedma_api.ObservableMetadata(description="Average magnetization"),
    ],
    precision=0.05,
    backend="H2-1E",
    description="quantinuum qesem quick start",
    enable_notifications=True,
)

print(job.job_id)

job = qedma_client.create_job( circuit=circuit, observables=[avg_magnetization], observables_metadata=[ qedma_api.ObservableMetadata(description="Average magnetization"), ], precision=0.05, backend="H2-1E", description="quantinuum qesem quick start", enable_notifications=True, ) print(job.job_id)

Note

The precision specifies the acceptable absolute error on the expectation values of the observables. QESEM continues mitigation until each input observable reaches the requested precision within a 1σ confidence interval. The total HQC cost is the exact analytical-estimation cost for empirical estimation plus the HQC cost returned by empirical estimation.

Note

When the QESEM job completes, an email notification is sent to the job creator. In some cases, the email might end up in the spam or quarantine folder. If that happens, mark the sender as trusted to prevent this in the future. To disable email notifications, set enable_notifications=False when creating the QESEM job.

Wait for Analytical Resource Estimation¶

The analytical stage provides the exact HQC cost required for the empirical estimation pass.

In [ ]:

analytical_estimation = qedma_client.wait_for_analytical_resource_estimation(
    job_id=job.job_id,
)

print(analytical_estimation)

analytical_estimation = qedma_client.wait_for_analytical_resource_estimation( job_id=job.job_id, ) print(analytical_estimation)

Start Empirical Resource Estimation¶

After the analytical result is available, start the empirical estimation stage explicitly. It determines the exact HQC required for the remaining mitigation at the specified precision. Use wait_for_resource_estimation(...) to wait until it completes and retrieve the empirical HQC cost and the mitigation results produced during empirical estimation.

In [ ]:

qedma_client.start_resource_estimation(job_id=job.job_id)

qedma_client.start_resource_estimation(job_id=job.job_id)

In [ ]:

empirical_hqc, empirical_estimation_results = qedma_client.wait_for_resource_estimation(
    job_id=job.job_id,
)

print(empirical_hqc)
print(empirical_estimation_results)

empirical_hqc, empirical_estimation_results = qedma_client.wait_for_resource_estimation( job_id=job.job_id, ) print(empirical_hqc) print(empirical_estimation_results)

Start the Full QESEM Run¶

Once the remaining mitigation HQC looks acceptable, start the full job with an explicit max_hqc budget. Here, we use empirical_hqc because it is the HQC cost needed to achieve the requested precision.

In [ ]:

max_hqc = empirical_hqc

qedma_client.start_job(
    job_id=job.job_id,
    max_hqc=empirical_hqc
)

max_hqc = empirical_hqc qedma_client.start_job( job_id=job.job_id, max_hqc=empirical_hqc )

Wait for Completion¶

The final wait step returns the job payload, including the mitigated and unmitigated results for each observable and the total HQC consumed.

In [ ]:

job = qedma_client.wait_for_job_complete(job_id=job.job_id)

job = qedma_client.wait_for_job_complete(job_id=job.job_id)

Read the Results¶

Retrieve the completed job with its results. For each observable, the QESEM result format includes both a mitigated and an unmitigated value.

In [ ]:

job = qedma_client.get_job(job_id=job.job_id, include_results=True)

for observable, result in job.results:
    print("Observable:", observable)
    print("Mitigated:", result.mitigated)
    print("Unmitigated:", result.unmitigated)
    print()

print("Total HQC consumed:", job.hqc)

job = qedma_client.get_job(job_id=job.job_id, include_results=True) for observable, result in job.results: print("Observable:", observable) print("Mitigated:", result.mitigated) print("Unmitigated:", result.unmitigated) print() print("Total HQC consumed:", job.hqc)

Summary¶

The Quantinuum QESEM workflow lets you:

1. create a job
2. determine the exact HQC cost of empirical estimation
3. determine the exact time required for the remaining mitigation and inspect intermediate results
4. launch the final run with an explicit budget
5. retrieve mitigated and unmitigated outputs together with total HQC usage

For more detail on the returned fields, continue to Execution Metrics and Reference.