Defines classes which represent gates, as well as supporting functions

Module Contents


create_cloudnoise_circuits(processor_spec, ...[, ...])

Constructs a set of circuits that amplify all the parameters of a clould-noise model.

create_kcoverage_template(n, k[, verbosity])

Construct a template for how to create a "k-coverage" set of length-n sequences.



pygsti.circuits.cloudcircuitconstruction.RANK_TOL = '1e-09'
pygsti.circuits.cloudcircuitconstruction.create_cloudnoise_circuits(processor_spec, max_lengths, single_q_fiducials, max_idle_weight=1, maxhops=0, extra_weight_1_hops=0, extra_gate_weight=0, parameterization='H+S', verbosity=0, cache=None, idle_only=False, idt_pauli_dicts=None, algorithm='greedy', idle_op_str=((),), comm=None)

Constructs a set of circuits that amplify all the parameters of a clould-noise model.

Create a set of fiducial1+germ^power+fiducial2 sequences which amplify all of the parameters of a CloudNoiseModel created by passing the arguments of this function to function:create_cloudnoise_model_from_hops_and_weights.

Note that this function essentialy performs fiducial selection, germ selection, and fiducial-pair reduction simultaneously. It is used to generate a short (ideally minimal) list of sequences needed for multi- qubit GST.



Defines the prcoessor interface (API) for which circuits are created. This API includes the number of qubits and their labels, gate names, qubit geometry or gate availability, etc.


A list of integers specifying the different maximum lengths for germ powers. Typically these values start a 1 and increase by powers of 2, e.g. [1,2,4,8,16].


A list of gate-name-tuples, e.g. [(), (‘Gx’,), (‘Gy’,), (‘Gx’,’Gx’)], which form a set of 1-qubit fiducials for the given model (compatible with both the gates it posseses and their parameterizations - for instance, only [(), (‘Gx’,), (‘Gy’,)] is needed for just Hamiltonian and Stochastic errors. If a list of two such lists is given, they specify preparation and measurement fiducials, respectively, e.g. [ [(), (‘Gx’,), (‘Gx’,’Gz’)], [(), (‘Gx’,), (‘Gz’,’Gx’)] ].

max_idle_weightint, optional

The maximum-weight for errors on the global idle gate.


The locality constraint: for a gate, errors (of weight up to the maximum weight for the gate) are allowed to occur on the gate’s target qubits and those reachable by hopping at most maxhops times from a target qubit along nearest-neighbor links (defined by the geometry).

extra_weight_1_hopsint, optional

Additional hops (adds to maxhops) for weight-1 errors. A value > 0 can be useful for allowing just weight-1 errors (of which there are relatively few) to be dispersed farther from a gate’s target qubits. For example, a crosstalk-detecting model might use this.

extra_gate_weightint, optional

Addtional weight, beyond the number of target qubits (taken as a “base weight” - i.e. weight 2 for a 2Q gate), allowed for gate errors. If this equals 1, for instance, then 1-qubit gates can have up to weight-2 errors and 2-qubit gates can have up to weight-3 errors.

parameterization{“CPTP”, “H+S+A”, “H+S”, “S”, “H+D+A”, “D+A”, “D”}

The parameterization used to define which parameters need to be amplified.

verbosityint, optional

The level of detail printed to stdout. 0 means silent.

cachedict, optional

A cache dictionary which holds template information so that repeated calls to create_cloudnoise_circuits can draw on the same pool of templates.

idle_onlybool, optional

If True, only sequences for the idle germ are returned. This is useful for idle tomography in particular.

idt_pauli_dictstuple, optional

A (prepDict,measDict) tuple of dicts that maps a 1-qubit Pauli basis string (e.g. ‘X’ or ‘-Y’) to a sequence of gate names. If given, the idle-germ fiducial pairs chosen by this function are restricted to those where either 1) each qubit is prepared and measured in the same basis or 2) each qubits is prepared and measured in different bases (note: ‘-X’ and ‘X” are considered the same basis). This restriction makes the resulting sequences more like the “standard” ones of idle tomography, and thereby easier to interpret.


The algorithm is used internall by _find_amped_polynomials_for_syntheticidle(). You should leave this as the default unless you know what you’re doing.

idle_op_strCircuit or tuple, optional

The circuit or label that is used to indicate a completely idle layer (all qubits idle).

commmpi4py.MPI.Comm, optional

When not None, an MPI communicator for distributing the computation across multiple processors.



An object holding a structured (using germ and fiducial sub-sequences) list of circuits.

pygsti.circuits.cloudcircuitconstruction.create_kcoverage_template(n, k, verbosity=0)

Construct a template for how to create a “k-coverage” set of length-n sequences.

Consider a set of length-n words from a k-letter alphabet. These words (sequences of letters) have the “k-coverage” property if, for any choice of k different letter positions (indexed from 0 to n-1), every permutation of the k distinct letters (symbols) appears in those positions for at least one element (word) in the set. Such a set of sequences is returned by this function, namely a list length-n lists containing the integers 0 to k-1.

This notion has application to idle-gate fiducial pair tiling, when we have found a set of fiducial pairs for k qubits and want to find a set of sequences on n > k qubits such that any subset of k qubits experiences the entire set of (k-qubit) fiducial pairs. Simply take the k-coverage template and replace the letters (0 to k-1) with the per-qubit 1Q pieces of each k-qubit fiducial pair.



The sequences length (see description above).


The coverage number (see description above).

verbosityint, optional

Amount of detail to print to stdout.



A list of length-n lists containing the integers 0 to k-1. The length of the outer lists depends on the particular values of n and k and is not guaranteed to be minimal.