API documentation

This is the autogenerated reference for the pygsti package, built from docstrings and intended primarily for advanced usage and development. It is organized by subpackage; within each subpackage the modules are listed and link through to their classes and functions.

Subpackages

pygsti.algorithms

Core GST and characterization algorithms: model fitting, gauge optimization, fiducial/germ selection, and RB analysis.

pygsti.algorithms.compilers	Clifford circuit, CNOT circuit, and stabilizer state/measurement generation compilation routines
pygsti.algorithms.contract(model, to_what[, ...])	Contract a Model to a specified space.
pygsti.algorithms.core	Core GST algorithms
pygsti.algorithms.fiducialpairreduction	Functions for reducing the number of required fiducial pairs for analysis.
pygsti.algorithms.fiducialselection	Functions for selecting a complete set of fiducials for a GST analysis.
pygsti.algorithms.gaugeopt	GST gauge optimization algorithms
pygsti.algorithms.germselection	Functions for selecting a complete set of germs for a GST analysis.
pygsti.algorithms.grammatrix	Utility functions related to Gram matrix construction.
pygsti.algorithms.grasp	Functions to facilitate using GRASP.
pygsti.algorithms.mirroring	circuit mirroring functions.
pygsti.algorithms.randomcircuit	Random circuit sampling functions.
pygsti.algorithms.rbfit	Functions for analyzing RB data
pygsti.algorithms.robust_phase_estimation	Robust Phase Estimation platform agnostic portion
pygsti.algorithms.scoring	Common functions used in scoring germ and fiducial sets.

pygsti.baseobjs

Foundational utility objects: labels, matrix bases, state spaces, polynomials, and resource allocation.

pygsti.baseobjs.advancedoptions	Utilities for defining advanced low-level parameterizations for various pyGSTi operations
pygsti.baseobjs.basis	Defines the Basis object and supporting functions
pygsti.baseobjs.basisconstructors	Functions for creating the standard sets of matrices in the standard, Pauli, Gell-Mann, and qutrit bases
pygsti.baseobjs.errorgenbasis	Defines the ElementaryErrorgenBasis class and supporting functionality.
pygsti.baseobjs.errorgenlabel	Defines the ElementaryErrorgenLabel class and supporting functionality.
pygsti.baseobjs.errorgenspace	Defines the ErrorgenSpace class and supporting functionality.
pygsti.baseobjs.exceptions	Defines GST exception classes
pygsti.baseobjs.label	Defines the Label class
pygsti.baseobjs.mongoserializable	Defines the MongoSerializable class
pygsti.baseobjs.nicelyserializable	Defines the NicelySerializable class
pygsti.baseobjs.opcalc	Implementations of common polynomial operations
pygsti.baseobjs.outcomelabeldict	Defines the OutcomeLabelDict class
pygsti.baseobjs.polynomial	Defines the Polynomial class
pygsti.baseobjs.profiler	Defines the Profiler class and supporting functionality
pygsti.baseobjs.protectedarray	Defines the ProtectedArray class
pygsti.baseobjs.qubitgraph	Defines the QubitGraph class and supporting functions
pygsti.baseobjs.resourceallocation	Resource allocation manager
pygsti.baseobjs.smartcache	Defines SmartCache and supporting functions
pygsti.baseobjs.statespace	Defines OrderedDict-derived classes used to store specific pyGSTi objects
pygsti.baseobjs.unitarygatefunction	Defines the UnitaryGateFunction class and supporting functionality.
pygsti.baseobjs.verbosityprinter	Defines the VerbosityPrinter class, used for logging output.

pygsti.circuits

Quantum circuits and circuit lists, plus their construction and parsing.

pygsti.circuits.circuit	Defines the Circuit class
pygsti.circuits.circuitconstruction	Utility functions for creating and acting on lists of circuits.
pygsti.circuits.circuitlist	Defines the CircuitList class, for holding meta-data alongside a list or tuple of Circuits.
pygsti.circuits.circuitparser	Implementations of a text parser for reading GST input files.
pygsti.circuits.circuitstructure	Defines the CircuitStructure class and supporting functionality.
pygsti.circuits.cloudcircuitconstruction	Defines classes which represent gates, as well as supporting functions
pygsti.circuits.gstcircuits	Circuit list creation functions using repeated-germs limited by a max-length.
pygsti.circuits.rpecircuits	Functions for creating circuit lists
pygsti.circuits.subcircuit_selection	Utility functions for subcircuit selection

pygsti.data

Datasets of experimental counts and the supporting analysis objects.

pygsti.data.datacomparator	Defines the DataComparator class used to compare multiple DataSets.
pygsti.data.dataset	Defines the DataSet class and supporting classes and functions
pygsti.data.datasetconstruction	Functions for creating data
pygsti.data.freedataset	Defines the FreeformDataSet class and supporting classes and functions
pygsti.data.hypothesistest	Defines HypothesisTest object and supporting functions
pygsti.data.multidataset	Defines the MultiDataSet class and supporting classes and functions
pygsti.data.rpedata	Functions for creating RPE data sets

pygsti.drivers

High-level driver routines that tie protocols and analysis together.

pygsti.drivers.bootstrap

Functions for generating bootstrapped error bars

pygsti.errorgenpropagation

Tools for propagating error generators through the layers of a circuit.

pygsti.errorgenpropagation.errorpropagator
pygsti.errorgenpropagation.localstimerrorgen

pygsti.extras

Beyond-GST sub-packages: drift, idle tomography, IBMQ and Cirq interfaces, interpolation, and more.

pygsti.extras.devices	Exteneral Device Specifications Sub-package
pygsti.extras.drift	Drift Detection and Characterization Sub-package
pygsti.extras.ibmq	IBMQ Experiment Sub-package
pygsti.extras.idletomography	Idle Tomography Sub-package
pygsti.extras.interpygate	Interpygate Sub-package
pygsti.extras.lfh	Low Frequency Hamiltonian Sub-package
pygsti.extras.paritybenchmarking	Parity Benchmarking Sub-package
pygsti.extras.rpe	Robubst Phase Estimation Sub-package

pygsti.forwardsims

Forward simulators that compute the outcome probabilities a model predicts for a circuit.

pygsti.forwardsims.distforwardsim	Defines the DistributableForwardSimulator calculator class
pygsti.forwardsims.forwardsim	Defines the ForwardSimulator calculator class
pygsti.forwardsims.mapforwardsim	Defines the MapForwardSimulator calculator class
pygsti.forwardsims.mapforwardsim_calc_generic	Defines generic Python-version of map forward simulator calculations
pygsti.forwardsims.matrixforwardsim	Defines the MatrixForwardSimulator calculator class
pygsti.forwardsims.successfailfwdsim	Defines the OplessForwardSimulator calculator class
pygsti.forwardsims.termforwardsim	Defines the TermForwardSimulator calculator class
pygsti.forwardsims.termforwardsim_calc_generic	Defines generic Python-version of map forward simulator calculations
pygsti.forwardsims.torchfwdsim	Defines a ForwardSimulator class called "TorchForwardSimulator" that can leverage the automatic differentation features of PyTorch.
pygsti.forwardsims.weakforwardsim	Defines the WeakForwardSimulator calculator class

pygsti.io

Reading and writing pyGSTi objects, datasets, and results.

pygsti.io.metadir	Serialization routines to/from a meta.json based directory
pygsti.io.mongodb	Serialization routines to/from a MongoDB database
pygsti.io.readers	Functions for loading GST objects from text files.
pygsti.io.stdinput	Text-parsing classes and functions to read input files.
pygsti.io.writers	Functions for writing GST objects to text files.

pygsti.layouts

Circuit/COPA layouts that organize (and distribute) the computation behind forward simulation.

pygsti.layouts.cachedlayout	A object representing the indexing into a (flat) array of circuit outcome probabilities.
pygsti.layouts.copalayout	A object representing the indexing into a (flat) array of circuit outcome probabilities.
pygsti.layouts.distlayout	Defines the DistributableCOPALayout class.
pygsti.layouts.evaltree	Defines the EvalTree class.
pygsti.layouts.maplayout	Defines the MapCOPALayout class.
pygsti.layouts.matrixlayout	Defines the MatrixCOPALayout class.
pygsti.layouts.prefixtable	Defines the PrefixTable class.
pygsti.layouts.termlayout	Defines the TermCOPALayout class.

pygsti.modelmembers

The states, POVMs, operations, and instruments held inside models.

pygsti.modelmembers.errorgencontainer	Defines the ErrorGeneratorContainer helper class.
pygsti.modelmembers.instruments	Sub-package holding model instrument objects.
pygsti.modelmembers.modelmember	Defines the ModelChild and ModelMember classes, which represent Model members
pygsti.modelmembers.modelmembergraph	Modelmember dependency graph related utility functions
pygsti.modelmembers.operations	Sub-package holding model operation objects.
pygsti.modelmembers.povms	Sub-package holding model POVM and POVM effect objects.
pygsti.modelmembers.states	Sub-package holding model state preparation objects.
pygsti.modelmembers.term	Defines classes which represent terms in gate expansions
pygsti.modelmembers.torchable	Defines the interface that ModelMembers must satisfy to be compatible with the PyTorch-backed forward simulator in pyGSTi/forwardsims/torchfwdsim.py.

pygsti.models

Model objects representing a QIP, plus model construction, parameterization, and noise.

pygsti.models.cloudnoisemodel	Defines the CloudNoiseModel class and supporting functions
pygsti.models.explicitcalc	Defines the ExplicitOpModelCalc class and supporting functionality.
pygsti.models.explicitmodel	Defines the ExplicitOpModel class and supporting functionality.
pygsti.models.fogistore	Defines the FirstOrderGaugeInvariantStore class and supporting functionality.
pygsti.models.gaugegroup	GaugeGroup and derived objects, used primarily in gauge optimization
pygsti.models.implicitmodel	Defines the ImplicitOpModel class and supporting functionality.
pygsti.models.layerrules	Defines the LayerLizard class and supporting functionality.
pygsti.models.localnoisemodel	Defines the LocalNoiseModel class and supporting functions
pygsti.models.memberdict	Defines OrderedDict-derived classes used to store specific pyGSTi objects
pygsti.models.model	Defines the Model class and supporting functionality.
pygsti.models.modelconstruction	Functions for the construction of new models.
pygsti.models.modelnoise	Objects for specifying the noise to be added to models when they are created.
pygsti.models.modelparaminterposer	Defines the ModelParamsInterposer class and supporting functionality.
pygsti.models.oplessmodel	Defines the OplessModel class
pygsti.models.qutrit	Routines for building qutrit gates and models
pygsti.models.rpemodel	Functions for creating RPE Models
pygsti.models.stencillabel	Stencil label classes and supporting functions.

pygsti.objectivefns

Objective functions (e.g. chi-squared, log-likelihood) and wildcard-error budgets.

pygsti.objectivefns.objectivefns	Defines objective-function objects
pygsti.objectivefns.wildcardbudget	Functions related to computation of the log-likelihood.

pygsti.optimize

Optimization routines used during model fitting.

pygsti.optimize.arraysinterface	Implements the ArraysInterface object and supporting functionality.
pygsti.optimize.customcg	A custom conjugate gradient descent algorithm
pygsti.optimize.customlm	Custom implementation of the Levenberg-Marquardt Algorithm
pygsti.optimize.customsolve	A custom MPI-enabled linear solver.
pygsti.optimize.optimize	Optimization (minimization) functions
pygsti.optimize.simplerlm	Custom implementation of the Levenberg-Marquardt Algorithm (but simpler than customlm.py)
pygsti.optimize.wildcardopt	Wildcard budget fitting routines

pygsti.processors

Processor specifications and compilation rules.

pygsti.processors.compilationrules	Defines CompilationLibrary class and supporting functions
pygsti.processors.processorspec	Defines the QubitProcessorSpec class and supporting functionality.
pygsti.processors.random_compilation	Randomized circuit compilation via random compiling and central Pauli propagation.

pygsti.protocols

Protocol objects (GST, RB, RPE, drift, …) with their inputs, data, and results.

pygsti.protocols.confidenceregionfactory	Classes for constructing confidence regions
pygsti.protocols.estimate	Defines the Estimate class.
pygsti.protocols.freeformsim	ModelTest Protocol objects
pygsti.protocols.gst	GST Protocol objects
pygsti.protocols.mirror_edesign	Functions for creating mirror experiment designs for mirror circuit fidelity estimation (MCFE)
pygsti.protocols.modeltest	ModelTest Protocol objects
pygsti.protocols.protocol	Protocol object
pygsti.protocols.rb	RB Protocol objects
pygsti.protocols.rpe	RPE Protocol objects
pygsti.protocols.scarab	scarab is a software tool for creating scalable, robust benchmarks from any quantum circuit.
pygsti.protocols.stability	Stability analysis protocol objects
pygsti.protocols.treenode	The TreeNode class
pygsti.protocols.vb	Volumetric Benchmarking Protocol objects
pygsti.protocols.vbdataframe	Techniques for manipulating benchmarking data stored in a Pandas DataFrame.

pygsti.serialization

JSON serialization helpers.

pygsti.serialization.jsoncodec

Defines JSON-format encoding and decoding functions

pygsti.tools

General-purpose numerical and quantum-information utilities.

pygsti.tools.basistools	Utility functions for working with Basis objects
pygsti.tools.chi2fns	Chi-squared and related functions
pygsti.tools.compilationtools	Functions for manipulating gates in circuits
pygsti.tools.dataframetools	Tools for working with Pandas dataframes
pygsti.tools.edesigntools	Tools for working with ExperimentDesigns
pygsti.tools.errgenproptools	Tools for the propagation of error generators through circuits.
pygsti.tools.exceptions	Defines GST exception classes
pygsti.tools.fogitools	Utility functions for computing and working with first-order-gauge-invariant (FOGI) quantities.
pygsti.tools.gatetools	Functions for creating gates
pygsti.tools.group	Encapsulates a group in terms of matrices and relations
pygsti.tools.hypothesis	Tools for general statistical hypothesis testing
pygsti.tools.internalgates	The standard unitaries and gate names, used internal compilers and short-hand model init
pygsti.tools.jamiolkowski	Utility functions related to the Choi representation of gates.
pygsti.tools.legacytools	Functions related deprecating other functions
pygsti.tools.likelihoodfns	Functions related to computation of the log-likelihood.
pygsti.tools.lindbladtools	Utility functions relevant to Lindblad forms and projections
pygsti.tools.listtools	Utility functions for working with lists
pygsti.tools.locking
pygsti.tools.matrixmod2	General matrix utilities.
pygsti.tools.matrixtools	Matrix related utility functions
pygsti.tools.mcfetools	Tools for analyzing MCFE data
pygsti.tools.metaprogramming
pygsti.tools.mpitools	Functions for working with MPI processor distributions
pygsti.tools.mptools	Functions for working with Python multiprocessing (more than just map)
pygsti.tools.nameddict	The NamedDict class
pygsti.tools.optools	Utility functions operating on operation matrices
pygsti.tools.opttools	This module defines tools for optimization and profiling
pygsti.tools.pdftools	Tools for manipulating classical probability distributions.
pygsti.tools.rbtheory	RB-related functions of gates and models
pygsti.tools.rbtools	Tools for analyzing RB data
pygsti.tools.sdptools	Functions for constructing semidefinite programming models
pygsti.tools.sharedmemtools	Utility functions for working with shared memory
pygsti.tools.slicetools	Utility functions for working with Python slice objects
pygsti.tools.symplectic	Symplectic representation utility functions
pygsti.tools.typeddict	The TypedDict class

Large internal subpackages

A few subpackages are large internal or data-heavy trees that are not expanded in this reference: pygsti.report (HTML-report generation machinery), pygsti.modelpacks (standard model packs — data rather than API), and pygsti.evotypes (internal evolution-type representations). The most commonly used entry points from these areas are listed below.

Frequently used entry points

A handful of widely used classes and functions from the subpackages above are documented individually here for convenience.

pygsti.report.Report(templates, results, ...)	The internal model of a report.
pygsti.modelpacks.GSTModelPack()	ABC for modelpacks with GST information

pygsti.report.construct_standard_report(results)

Create a "standard" GST report, containing details about each estimate in results individually.