iqm.error_reduction_tools.readout_characterization.readout_error_characterization.ReadoutErrorCharacterization#

class iqm.error_reduction_tools.readout_characterization.readout_error_characterization.ReadoutErrorCharacterization(client)#

Bases: object

High-level interface for readout error characterization.

Wraps the lower-level functions in iqm.error_reduction_tools.readout_characterization.data_collection and iqm.error_reduction_tools.readout_characterization.data_processing behind a clean, lifecycle-oriented API.

Typical online usage:

config = RECConfiguration(shots=20_000, qubits=["QB1", "QB2", "QB5"])
rec = ReadoutErrorCharacterization(client)
rec.submit_job(config)
rec.retrieve_results()
probs = rec.get_readout_error_probabilities()

Chained usage:

probs = (
    ReadoutErrorCharacterization(client)
    .submit_job(config)
    .retrieve_results()
    .get_readout_error_probabilities()
)

Offline usage (reload saved results):

rec = ReadoutErrorCharacterization.load("charact_garnet_20260311.json")
probs = rec.get_readout_error_probabilities()

Methods

`__repr__`()	Printable representation.
`from_dict`(data)	Construct a `ReadoutErrorCharacterization` from a dictionary.
`get_readout_error_probabilities`()	Return per-qubit readout error probabilities.
`load`(path)	Reconstruct a `ReadoutErrorCharacterization` from a JSON file.
`plot_error_probabilities`(**kwargs)	Plot per-qubit readout error probabilities.
`retrieve_results`([job, job_info])	Retrieve measurement results from the calibration job.
`save`(path)	Serialize the characterization state to a JSON file.
`submit_job`([config])	Submit calibration circuits to the quantum computer.
`to_dict`()	Serialize the characterization state to a JSON-compatible dictionary.

Parameters:: client (Pulla | None)

submit_job(config=None)#

Submit calibration circuits to the quantum computer.

Stores the returned PullaJob and job metadata internally.

Parameters:: config (RECConfiguration | None) – Characterization configuration. Defaults to RECConfiguration with all default values when None.
Returns:: The current instance for method chaining.
Raises:: RuntimeError – If no client was provided at construction time.
Return type:: Self

retrieve_results(job=None, job_info=None)#

Retrieve measurement results from the calibration job.

Wraps retrieve_calibration_results() and stores the raw counts internally.

job and job_info are always treated as a matched pair from the same calibration run. Either supply both to use an externally obtained job, or omit both to use the job stored internally by submit_job(). Passing only one of the two is an error.

Parameters:

job (PullaJob | None) – Job to fetch results from.
job_info (CalibrationJobInfo | None) – CalibrationJobInfo that accompanies job (preparation strings, qubit list, etc.).

Returns:

The current instance for method chaining.

Raises:

ValueError – If exactly one of job / job_info is provided.
RuntimeError – If neither explicit arguments nor internal state are available.

Return type:

Self

get_readout_error_probabilities()#

Return per-qubit readout error probabilities.

Computes the probabilities on the first call (lazy evaluation) and caches the result internally. Subsequent calls return the cached value without recomputation.

Returns:: Per-qubit readout error probabilities. See ErrorProbabilities for the structure.
Raises:: RuntimeError – If retrieve_results() has not been called.
Return type:: ErrorProbabilities

to_dict()#

Serialize the characterization state to a JSON-compatible dictionary.

The serialized form contains everything required to reconstruct a post-retrieval object offline via from_dict():

Key	Contents
`counts_by_prep`	Raw calibration counts
`measured_qubits`	Qubit labels
`config`	`RECConfiguration` used
`charact_data`	Cached assignment matrices (optional, present only if already computed)
`charact_data_std`	Matching standard deviations (optional, present only if already computed)
`timestamp`	ISO-8601 creation timestamp, in UTC

Returns:: JSON-serializable dictionary.
Raises:: RuntimeError – If retrieve_results() has not been called.
Return type:: dict[str, Any]

classmethod from_dict(data)#

Construct a ReadoutErrorCharacterization from a dictionary.

The reconstructed object holds raw results and cached error probabilities (when available). It has no client or job handle, but all analysis and visualization methods work normally.

Parameters:: data (dict[str, Any]) – Dictionary produced by to_dict() or loaded via load().
Returns:: New ReadoutErrorCharacterization instance ready for offline analysis.
Return type:: Self

save(path)#

Serialize the characterization state to a JSON file.

Parameters:: path (str) – Destination file path (file will be overwritten if it exists).
Raises:: RuntimeError – If retrieve_results() has not been called yet.
Return type:: None

classmethod load(path)#

Reconstruct a ReadoutErrorCharacterization from a JSON file.

Parameters:: path (str) – Path to a file created by save().
Returns:: New ReadoutErrorCharacterization instance ready for offline analysis.
Return type:: Self

plot_error_probabilities(**kwargs)#

Plot per-qubit readout error probabilities.

Thin convenience wrapper around plot_error_probabilities(). All keyword arguments are forwarded verbatim (e.g. title, show_plot).

The visualization module is imported lazily to avoid pulling in matplotlib at package import time.

Raises:: RuntimeError – If retrieve_results() has not been called yet.
Return type:: None

iqm.error_reduction_tools.readout_characterization.readout_error_characterization.ReadoutErrorCharacterization

Contents

iqm.error_reduction_tools.readout_characterization.readout_error_characterization.ReadoutErrorCharacterization#