qcmet.benchmarks.GST

class qcmet.benchmarks.GST(gst_experiment_design, save_path=None, *, target_model=None, target_model_factory=None, model_pack=None, parameterization='CPTP', use_standard_gst=False, gst_gaugeopt_suite=None, gst_objfn_builders=None, gst_optimizer=None, gst_badfit_options=None, gst_verbosity=0)

Run Gate Set Tomography (GST) with pyGSTi in a minimal QCMet-friendly way.

Parameters:

• gst_experiment_design (GSTDesign) – A pyGSTi experiment design that defines GST circuits, qubit labels, and a processor spec.

• save_path (str | Path | FileManager | None, optional) – Location to store design, dataset, and results. If None, a temporary directory is used and cleaned up on destruction.

• target_model (Model | None, optional) – Explicit pyGSTi model to use as the initial/target model. Must be compatible with the design.

• target_model_factory (Callable[[QPS], Model] | None, optional) – Callback that builds a model from the design processor_spec.

• model_pack (object | None, optional) – A pygsti.modelpacks module (e.g., smq1Q_XY) providing target_model(parameterization).

• parameterization (str, optional) – Parameterization passed to model_pack.target_model(…) (e.g., ‘TP’, ‘CPTP’, ‘full’). Used only when model_pack is supplied.

• use_standard_gst (bool, optional) – If True, run StandardGST (standard-practice long-sequence GST + default gauge optimization). If False, run the core GateSetTomography protocol.

• gst_gaugeopt_suite (object | None, optional) – Core-path only. A GSTGaugeOptSuite or dict of directives describing gauge optimization passes. If None, core path does no gauge opt.

• gst_objfn_builders (object | None, optional) – Core-path only. A GSTObjFnBuilders specifying long-sequence objective functions (e.g., χ² or log-likelihood).

• gst_optimizer (object | str | None, optional) – Core-path only. A pyGSTi optimizer instance or ‘auto’ for numerical fitting.

• gst_badfit_options (object | None, optional) – Core-path only. A GSTBadFitOptions defining remediation steps for poor fits.

• gst_verbosity (int, optional) – Core-path only. pyGSTi runner verbosity.

Notes

This module provides a thin QCMet-friendly wrapper that: - Writes a pyGSTi experiment design and dataset skeleton to disk. - Runs GST via either StandardGST (standard practice) or the core GateSetTomography protocol (optionally customizable). - Computes concise gate and SPAM quality metrics for downstream reporting.

• It exposes two analysis modes:

  • Standard practice GST (StandardGST): a canonical orchestration of

    long-sequence GST that includes iterative objective functions and a built-in gauge-optimization suite. This is the quickest path to a gauge-optimized estimate using widely adopted defaults.

  • Core GST (GateSetTomography): the low-level protocol performing the

    actual parameter estimation. This path is intentionally lean and can be configured via optional kwargs (gauge-opt suite, objective builders, optimizer, and “bad fit” options). If you leave them None, the core path runs with minimal assumptions and skips gauge optimization.

• After analysis, it computes concise quality metrics:

  • Per-gate process fidelity (ideal vs. fitted model).

  • Optional per-gate (half) diamond norm (requires cvxpy).

  • SPAM metrics:

    • Fidelity of the prepared |0⟩ state (as Hilbert–Schmidt vectors).

    • Aggregate measurement fidelity from POVM entanglement infidelity.

Design

This wrapper aims to be as basic as possible while still providing the hooks for more advanced usage: - All heavy lifting (experiment design, objective functions, fitting, gauge optimization) is handled by pyGSTi. - The wrapper only standardizes I/O (dataset writing) and provides a set of result metrics .

Advanced usage — please use pyGSTi directly

For research-level customization (new objective functions, bespoke constraints, novel gauge groups/metrics, leakage-aware modeling, etc.), it is advisable to interact with pyGSTi directly:

• Protocols: pygsti.protocols.gst (e.g., GateSetTomography, StandardGST,

• GSTObjFnBuilders, GSTGaugeOptSuite).

• Algorithms: pygsti.algorithms.core and pygsti.algorithms.gaugeopt.

• Models: pygsti.models.* (explicit/crosstalk/cloud-noise).

• Data & design: pygsti.io, pygsti.protocols.ExperimentDesign.

Data flow

1) You pass a GateSetTomographyDesign that encodes the circuits, qubit labels, and processor spec. 2) QCMet executes those circuits using the run() method; and writes counts into pyGSTi the pyGSTi dataset.txt. 3) analyze() runs the selected protocol on the design+dataset (read from disk), selects the best estimate (preferring ‘stdgaugeopt’), then computes metrics.

Target/ideal model

GST is model-based. This class resolves the target/initial model via: (1) target_model (explicit), or (2) target_model_factory(processor_spec), or (3) model_pack.target_model(parameterization), or (4) pygsti.models.create_explicit_model(processor_spec) (fallback).

I/O & storage

• If save_path is a QCMet FileManager or filesystem path, everything is written

there; otherwise a temporary directory is used (and cleaned up on destruction). • Outcome labels are set to 2**^**n bitstrings (e.g., ‘00’, ‘01’) to match standard qubit POVMs. Adjust if your design uses a different outcome alphabet.

Performance & parallelization

pyGSTi supports MPI/multiprocessing for large designs. This wrapper does not configure parallelism — please use pyGSTi directly to tune performance. One may save to disk and use the run function, but leave the analysis to bare pyGSTi code.

Assumptions

• The default POVM label used in metrics is “Mdefault”.

• Circuits are exported as OpenQASM 2 via convert_to_openqasm(); map/compile

upstream if your backend expects other intermediate representations.

__init__(gst_experiment_design, save_path=None, *, target_model=None, target_model_factory=None, model_pack=None, parameterization='CPTP', use_standard_gst=False, gst_gaugeopt_suite=None, gst_objfn_builders=None, gst_optimizer=None, gst_badfit_options=None, gst_verbosity=0)

Initialize the GST analyzer and serialize the experiment design.

Parameters:

• gst_experiment_design (GSTDesign) – pyGSTi experiment design specifying circuits, qubit labels, and processor spec.

• save_path (str | Path | FileManager | None, optional) – Storage location for design/data/results. If None, a temp dir is used.

• target_model (Model | None, optional) – Explicit initial/target model.

• target_model_factory (Callable[[QPS], Model] | None, optional) – Factory to build a model from the design’s processor_spec.

• model_pack (object | None, optional) – Model pack providing a target_model(parameterization) function.

• parameterization (str, optional) – Parameterization for the model pack’s target model (‘TP’, ‘CPTP’, ‘full’).

• use_standard_gst (bool, optional) – Select StandardGST (True) or basic GateSetTomography (False).

• gst_gaugeopt_suite (object | None, optional) – basic GST gauge-opt suite or directives. If None, no gauge optimization is performed.

• gst_objfn_builders (object | None, optional) – basic GST objective builders for long-sequence GST.

• gst_optimizer (object | str | None, optional) – basic GST optimizer instance or ‘auto’.

• gst_badfit_options (object | None, optional) – basic GST remediation options for poor fits.

• gst_verbosity (int, optional) – basic GST runner verbosity.

Notes

• Immediately writes an empty pyGSTi protocol data tree to self.config[“experiment_design_path”] so analysis can read it.

• Resolves the initial/target model via precedence: target_model -> target_model_factory -> model_pack -> create_explicit_model(processor_spec).

Methods

__init__(gst_experiment_design[, save_path, ...])	Initialize the GST analyzer and serialize the experiment design.
analyze()	Analyze measurements to return benchmark results.
generate_circuits()	Generate benchmark circuits, user facing.
has_plotting()	Check if _plot function is implemented in benchmark.
load_circuit_measurements(circuit_measurements)	Load measurement counts into the experiment_data DataFrame.
measurements_to_probabilities()	Convert raw measurement counts to normalized probabilities.
plot([axes])	Plot benchmark result, user facing.
run([device, num_shots, max_circs_per_job])	Run benchmark.
save()	Save benchmark current state.
set_save_path(save_path)	Set benchmark save path if not set in class constructor.

Attributes

circuits	Gets all benchmark circuits.
experiment_data	Getter for experiment_data dataframe.
num_qubits	Number of qubits in this benchmark.