iqm.error_reduction_tools.rem.rem_api.REMWorkflow

iqm.error_reduction_tools.rem.rem_api.REMWorkflow#

class iqm.error_reduction_tools.rem.rem_api.REMWorkflow(client, *, config=None, characterization=None)#

Bases: object

End-to-end readout error mitigation workflow.

Combines readout error characterization, circuit twirling, and postprocessing behind a clean, lifecycle-oriented API.

Two-step (async) usage — submit jobs, do other things, then retrieve:

workflow = REMWorkflow(client, config=config)
workflow.submit(circuits, observables=["ZZII", "IIZZ"])
# ... user can do other things while QPU jobs run ...
results = workflow.get_results()

One-liner (blocking) usage — for notebooks and demos:

results = REMWorkflow(client).run(circuits)

Reusing previous characterization:

workflow = REMWorkflow(client, characterization="charact.json")
results = workflow.run(circuits)
Parameters:

Methods

get_characterization()

Return the ReadoutErrorCharacterization (saveable for reuse).

get_expectation_values()

Return observable expectation values per circuit, or None.

get_mitigated_counts()

Return mitigated quasi-probability distributions per input circuit.

get_raw_counts()

Return unmitigated (but untwirled) counts per input circuit.

get_results()

Wait for jobs, retrieve results, and apply readout error mitigation.

load_characterization(source)

Load pre-existing readout error characterization.

run(circuits[, observables])

Submit jobs and retrieve results in one blocking call.

submit(circuits[, observables])

Submit characterization and twirled circuit jobs to the QPU.
load_characterization(source)#

Load pre-existing readout error characterization.

Parameters:

source (ReadoutErrorCharacterization | dict | str) – A ReadoutErrorCharacterization object, a dict (as returned by rec.to_dict()), or a JSON file path.

Returns:

self for method chaining.

Raises:

TypeError – If the source type is not supported.

Return type:

REMWorkflow

submit(circuits, observables=None)#

Submit characterization and twirled circuit jobs to the QPU.

If no characterization was loaded, a REC job is submitted automatically. All input circuits are twirled and submitted as a separate job.

Parameters:

  • circuits (list) – Quantum circuits to mitigate. Accepts any type supported by twirl(): Qiskit QuantumCircuit, Circuit, TwirledCircuit, or any object with a to_qiskit() method (e.g. qrisp.QuantumCircuit).

  • observables (list[list[str] | str | list[int]] | None) – Observable specifications for expectation value computation. Supports qubit names ([["QB3", "QB5"]]), Pauli strings (["ZZII"]), or bit indices ([[0, 1]]). Pass None to mitigate the full distribution only.

Returns:

self for method chaining.

Return type:

REMWorkflow

get_results()#

Wait for jobs, retrieve results, and apply readout error mitigation.

Blocks until both the characterization and circuit jobs complete, then performs REM postprocessing and packages all outputs.

Returns:

REMResults with mitigated counts, expectation values, raw counts, characterization data, and metadata.

Raises:

RuntimeError – If submit() has not been called.

Return type:

REMResults

run(circuits, observables=None)#

Submit jobs and retrieve results in one blocking call.

Convenience wrapper equivalent to:

self.submit(circuits, observables=observables)
return self.get_results()
Parameters:

  • circuits (list) – Quantum circuits to mitigate. Accepts any type supported by twirl().

  • observables (list[list[str] | str | list[int]] | None) – Observable specifications (same format as submit()).

Returns:

REMResults with all outputs.

Return type:

REMResults

get_characterization()#

Return the ReadoutErrorCharacterization (saveable for reuse).

Raises:

RuntimeError – If characterization is not yet available.

Return type:

ReadoutErrorCharacterization

get_raw_counts()#

Return unmitigated (but untwirled) counts per input circuit.

Raises:

RuntimeError – If results are not yet available.

Return type:

list[dict[str, float]]

get_mitigated_counts()#

Return mitigated quasi-probability distributions per input circuit.

Raises:

RuntimeError – If results are not yet available.

Return type:

list[dict[str, float]]

get_expectation_values()#

Return observable expectation values per circuit, or None.

Returns None if no observables were specified.

Raises:

RuntimeError – If results are not yet available.

Return type:

list[list[float]] | None

Contents