pygsti.circuits.cloudcircuitconstruction

Defines classes which represent gates, as well as supporting functions

Module Contents

Functions

_onqubit(s, i_qubit)

Takes s, a tuple of gate names and creates a Circuit

_find_amped_polynomials_for_syntheticidle(qubit_filter, idle_str, model, single_q_fiducials=None, prep_lbl=None, effect_lbls=None, init_j=None, init_j_rank=None, wrt_params=None, algorithm='greedy', require_all_amped=True, idt_pauli_dicts=None, comm=None, verbosity=0)

Find fiducial pairs which amplify the parameters of a synthetic idle gate.

_test_amped_polynomials_for_syntheticidle(fidpairs, idle_str, model, prep_lbl=None, effect_lbls=None, wrt_params=None, verbosity=0)

Compute the number of model parameters amplified by a given (synthetic) idle sequence.

_find_amped_polynomials_for_clifford_syntheticidle(qubit_filter, core_filter, true_idle_pairs, idle_str, max_weight, model, single_q_fiducials=None, prep_lbl=None, effect_lbls=None, init_j=None, init_j_rank=None, wrt_params=None, verbosity=0)

A specialized version of :function:`_find_amped_polynomials_for_syntheticidle`.

_get_fidpairs_needed_to_access_amped_polynomials(qubit_filter, core_filter, germ_power_str, amped_poly_j, idle_gatename_fidpair_lists, model, single_q_fiducials=None, prep_lbl=None, effect_lbls=None, wrt_params=None, verbosity=0)

Finds a set of fiducial pairs that probe germ_power_str so that the underlying germ is effective.

_tile_idle_fidpairs(qubit_labels, idle_gatename_fidpair_lists, max_idle_weight)

Tile a set of fiducial pairs that amplify idle errors.

_tile_cloud_fidpairs(template_gatename_fidpair_lists, template_germpower, max_len, template_germ, clouds, qubit_labels)

Tile fiducial pairs that amplify "cloud" errors.

_compute_reps_for_synthetic_idle(model, germ_str, nqubits, core_qubits)

Return the number of times germ_str must be repeated to form a synthetic idle gate.

_get_candidates_for_core(model, core_qubits, candidate_counts, seed_start)

Returns a list of candidate germs which act on a given set of "core" qubits.

_create_xycnot_cloudnoise_circuits(num_qubits, max_lengths, geometry, cnot_edges, 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', comm=None)

Compute circuits which amplify the parameters of a particular CloudNoiseModel.

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.

_get_kcoverage_template_k2(n)

Special case where k == 2 -> use hypercube construction

create_kcoverage_template(n, k, verbosity=0)

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

_check_kcoverage_template(rows, n, k, verbosity=0)

Check that k-coverage conditions are met.

_filter_nqubit_circuittuple(sequence_tuples, sectors_to_keep, new_sectors=None, idle='Gi')

Filters a list of n-qubit circuit tuples.

_gatename_fidpair_list_to_fidpairs(gatename_fidpair_list)

Converts a fiducial pair list between formats.

_fidpairs_to_gatename_fidpair_list(fidpairs, num_qubits)

The inverse of :function:`_gatename_fidpair_list_to_fidpairs`.

Attributes

RANK_TOL

pygsti.circuits.cloudcircuitconstruction.RANK_TOL = 1e-09
pygsti.circuits.cloudcircuitconstruction._onqubit(s, i_qubit)

Takes s, a tuple of gate names and creates a Circuit where those names act on the i_qubit-th qubit

pygsti.circuits.cloudcircuitconstruction._find_amped_polynomials_for_syntheticidle(qubit_filter, idle_str, model, single_q_fiducials=None, prep_lbl=None, effect_lbls=None, init_j=None, init_j_rank=None, wrt_params=None, algorithm='greedy', require_all_amped=True, idt_pauli_dicts=None, comm=None, verbosity=0)

Find fiducial pairs which amplify the parameters of a synthetic idle gate.

This routine is primarily used internally within higher-level n-qubit sequence selection routines.

Parameters
  • qubit_filter (list) – A list specifying which qubits fiducial pairs should be placed upon. Typically this is a subset of all the qubits, as the synthetic idle is composed of nontrivial gates acting on a localized set of qubits and noise/errors are localized around these.

  • idle_str (Circuit) – The circuit specifying the idle operation to consider. This may just be a single idle gate, or it could be multiple non-idle gates which together act as an idle.

  • model (Model) – The model used to compute the polynomial expressions of probabilities to first-order. Thus, this model should always have (simulation) type “termorder”.

  • single_q_fiducials (list, optional) – A list of gate-name tuples (e.g. (‘Gx’,)) which specify a set of single- qubit fiducials to use when trying to amplify gate parameters. Note that no qubit “state-space” label is required here (i.e. not ((‘Gx’,1),)); the tuples just contain single-qubit gate names. If None, then [(), (‘Gx’,), (‘Gy’,)] is used by default. If a list of two such lists is given, they specify preparation and measurement fiducials, respectively, e.g. [ [(), (‘Gx’,), (‘Gx’,’Gz’)], [(), (‘Gx’,), (‘Gz’,’Gx’)] ].

  • prep_lbl (Label, optional) – The state preparation label to use. If None, then the first (and usually the only) state prep label of model is used, so it’s usually fine to leave this as None.

  • effect_lbls (list, optional) – The list of POVM effect labels to use, as a list of Label objects. These are simplified POVM effect labels, so something like “Mdefault_0”, and if None the default is all the effect labels of the first POVM of model, which is usually what you want.

  • init_j (numpy.ndarray, optional) – An initial Jacobian giving the derivatives of some other polynomials with respect to the same wrt_params that this function is called with. This acts as a starting point, and essentially informs the fiducial-pair selection algorithm that some parameters (or linear combos of them) are already amplified (e.g. by some other germ that’s already been selected) and for which fiducial pairs are not needed.

  • init_j_rank (int, optional) – The rank of init_j. The function could compute this from init_j but in practice one usually has the rank of init_j lying around and so this saves a call to np.linalg.matrix_rank.

  • wrt_params (slice, optional) – The parameters to consider for amplification. (This function seeks fiducial pairs that amplify these parameters.) If None, then pairs which amplify all of model’s parameters are searched for.

  • algorithm ({"greedy","sequential"}) – Which algorithm is used internally to find fiducial pairs. “greedy” will give smaller sets of fiducial pairs (better) but takes longer. Usually it’s worth the wait and you should use the default (“greedy”).

  • require_all_amped (bool, optional) – If True and AssertionError is raised when fewer than all of the requested parameters (in wrt_params) are amplifed by the final set of fiducial pairs.

  • idt_pauli_dicts (tuple, 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.

  • comm (mpi4py.MPI.Comm, optional) – When not None, an MPI communicator for distributing the computation across multiple processors.

  • verbosity (int, optional) – The level of detail printed to stdout. 0 means silent.

Returns

  • J (numpy.ndarray) – The final jacobian with rows equal to the number of chosen amplified polynomials (note there is one row per fiducial pair including the outcome - so there will be two different rows for two different outcomes) and one column for each parameter specified by wrt_params.

  • Jrank (int) – The rank of the jacobian J, equal to the number of amplified parameters (at most the number requested).

  • fidpair_lists (list) – The selected fiducial pairs, each in “gatename-fidpair-list” format. Elements of fidpair_lists are themselves lists, all of length=#qubits. Each element of these lists is a (prep1Qnames, meas1Qnames) 2-tuple specifying the 1-qubit gates (by name only) on the corresponding qubit. For example, the single fiducial pair prep=Gx:1Gy:2, meas=Gx:0Gy:0 in a 3-qubit system would have fidpair_lists equal to: [ [ [(),(‘Gx’,’Gy’)], [(‘Gx’,), () ], [(‘Gy’,), () ] ] ] ` < Q0 prep,meas >, < Q1 prep,meas >, < Q2 prep,meas >`

pygsti.circuits.cloudcircuitconstruction._test_amped_polynomials_for_syntheticidle(fidpairs, idle_str, model, prep_lbl=None, effect_lbls=None, wrt_params=None, verbosity=0)

Compute the number of model parameters amplified by a given (synthetic) idle sequence.

Parameters
  • fidpairs (list) – A list of (prep,meas) 2-tuples, where prep and meas are Circuit objects, specifying the fiducial pairs to test.

  • idle_str (Circuit) – The circuit specifying the idle operation to consider. This may just be a single idle gate, or it could be multiple non-idle gates which together act as an idle.

  • model (Model) – The model used to compute the polynomial expressions of probabilities to first-order. Thus, this model should always have (simulation) type “termorder”.

  • prep_lbl (Label, optional) – The state preparation label to use. If None, then the first (and usually the only) state prep label of model is used, so it’s usually fine to leave this as None.

  • effect_lbls (list, optional) – The list of POVM effect labels to use, as a list of Label objects. These are simplified POVM effect labels, so something like “Mdefault_0”, and if None the default is all the effect labels of the first POVM of model, which is usually what you want.

  • wrt_params (slice, optional) – The parameters to consider for amplification. If None, then pairs which amplify all of model’s parameters are searched for.

  • verbosity (int, optional) – The level of detail printed to stdout. 0 means silent.

Returns

  • nAmplified (int) – The number of parameters amplified.

  • nTotal (int) – The total number of parameters considered for amplification.

pygsti.circuits.cloudcircuitconstruction._find_amped_polynomials_for_clifford_syntheticidle(qubit_filter, core_filter, true_idle_pairs, idle_str, max_weight, model, single_q_fiducials=None, prep_lbl=None, effect_lbls=None, init_j=None, init_j_rank=None, wrt_params=None, verbosity=0)

A specialized version of :function:`_find_amped_polynomials_for_syntheticidle`.

Similar to :function:`_find_amped_polynomials_for_syntheticidle` but specialized to “qubit cloud” processing case used in higher-level functions and assumes that idle_str is composed of Clifford gates only which act on a “core” of qubits (given by core_filter).

In particular, we assume that we already know the fiducial pairs needed to amplify all the errors of a “true” (non-synthetic) idle on various number of qubits (i.e. max-weights of idle error). Furthermore, we assume that the errors found by these true-idle fiducial pairs are of the same kind as those afflicting the synthetic idle, so that by restricting our search to just certain true-idle pairs we’re able to amplify all the parameters of the synthetic idle.

Because of these assumptions and pre-computed information, this function often takes considerably less time to run than :function:`_find_amped_polynomials_for_syntheticidle`.

Parameters
  • qubit_filter (list) – A list specifying which qubits fiducial pairs should be placed upon. Typically this is a subset of all the qubits, as the synthetic idle is composed of nontrivial gates acting on a localized set of qubits and noise/errors are localized around these. Within the “cloud” picture, qubit_filter specifies all the qubits in the cloud, not just the “core”.

  • core_filter (list) – A list specifying the “core” qubits - those which the non-idle gates within idle_str ideally act upon. This is often a proper subset of qubit_filter since errors are allowed on qubits which neighbor the core qubits in addition to the core qubits themselves.

  • true_idle_pairs (dict) – A dictionary whose keys are integer max-weight values and whose values are lists of fiducial pairs, each in “gatename-fidpair-list” format, whcih give the fiducial pairs needed to amplify all the parameters of a non-synthetic idle gate on max-weight qubits.

  • idle_str (Circuit) – The circuit specifying the idle operation to consider. This may just be a single idle gate, or it could be multiple non-idle gates which together act as an idle.

  • max_weight (int) – The maximum weight such that the pairs given by true_idle_pairs[max_weight] will amplify all the possible errors on idle_str. This must account for the fact that the nontrivial comprising idle_str may increase the weight of errors. For instance if idle_str contains CNOT gates on qubits 0 and 1 (the “core”) and the noise model allows insertion of up to weight-2 errors at any location, then a single weight-2 error (recall termorder:1 means there can be only 1 error per circuit) on qubits 1 and 2 followed by a CNOT on 0 and 1 could yield an weight-3 error on qubits 0,1, and 2.

  • model (Model) – The model used to compute the polynomial expressions of probabilities to first-order. Thus, this model should always have (simulation) type “termorder”.

  • single_q_fiducials (list, optional) – A list of gate-name tuples (e.g. (‘Gx’,)) which specify a set of single- qubit fiducials to use when trying to amplify gate parameters. Note that no qubit “state-space” label is required here (i.e. not ((‘Gx’,1),)); the tuples just contain single-qubit gate names. If None, then [(), (‘Gx’,), (‘Gy’,)] is used by default. If a list of two such lists is given, they specify preparation and measurement fiducials, respectively, e.g. [ [(), (‘Gx’,), (‘Gx’,’Gz’)], [(), (‘Gx’,), (‘Gz’,’Gx’)] ].

  • prep_lbl (Label, optional) – The state preparation label to use. If None, then the first (and usually the only) state prep label of model is used, so it’s usually fine to leave this as None.

  • effect_lbls (list, optional) – The list of POVM effect labels to use, as a list of Label objects. These are simplified POVM effect labels, so something like “Mdefault_0”, and if None the default is all the effect labels of the first POVM of model, which is usually what you want.

  • init_j (numpy.ndarray, optional) – An initial Jacobian giving the derivatives of some other polynomials with respect to the same wrt_params that this function is called with. This acts as a starting point, and essentially informs the fiducial-pair selection algorithm that some parameters (or linear combos of them) are already amplified (e.g. by some other germ that’s already been selected) and for which fiducial pairs are not needed.

  • init_j_rank (int, optional) – The rank of init_j. The function could compute this from init_j but in practice one usually has the rank of init_j lying around and so this saves a call to np.linalg.matrix_rank.

  • wrt_params (slice, optional) – The parameters to consider for amplification. (This function seeks fiducial pairs that amplify these parameters.) If None, then pairs which amplify all of model’s parameters are searched for.

  • verbosity (int, optional) – The level of detail printed to stdout. 0 means silent.

Returns

  • J (numpy.ndarray) – The final jacobian with rows equal to the number of chosen amplified polynomials (note there is one row per fiducial pair including the outcome - so there will be two different rows for two different outcomes) and one column for each parameter specified by wrt_params.

  • Jrank (int) – The rank of the jacobian J, equal to the number of amplified parameters (at most the number requested).

  • fidpair_lists (list) – The selected fiducial pairs, each in “gatename-fidpair-list” format. See :function:`_find_amped_polynomials_for_syntheticidle` for details.

pygsti.circuits.cloudcircuitconstruction._get_fidpairs_needed_to_access_amped_polynomials(qubit_filter, core_filter, germ_power_str, amped_poly_j, idle_gatename_fidpair_lists, model, single_q_fiducials=None, prep_lbl=None, effect_lbls=None, wrt_params=None, verbosity=0)

Finds a set of fiducial pairs that probe germ_power_str so that the underlying germ is effective.

More specifically, fiducial pairs must be found that probe or access the given germ-power such that probabilities from the prep_fiducial + germ_power + meas_fiducial circuits are sensitive to changes in the known-amplifiable directions in parameter space for the germ.

This function works within the “cloud” picture of a core of qubits where there is nontrivial ideal action and a larger set of qubits upon which errors may exist.

This function is used to find, after we know which directions in parameter -space are amplifiable by a germ (via analyzing its synthetic idle counterpart), which fiducial pairs are needed to amplify these directions when a non-synthetic-idle power of the germ is used.

Parameters
  • qubit_filter (list) – A list specifying which qubits fiducial pairs should be placed upon. Typically this is a subset of all the qubits, and a “cloud” around the qubits being ideally acted upon.

  • core_filter (list) – A list specifying the “core” qubits - those which the gates in germ_power_str ideally act upon. This is often a proper subset of qubit_filter since errors are allowed on qubits which neighbor the core qubits in addition to the core qubits themselves.

  • germ_power_str (Circuit) – The (non-synthetic-idle) germ power string under consideration.

  • amped_poly_j (numpy.ndarray) – A jacobian matrix whose rowspace gives the space of amplifiable parameters. The shape of this matrix is (Namplified, Np), where Namplified is the number of independent amplified parameters and Np is the total number of parameters under consideration (the length of wrt_params). This function seeks to find fiducial pairs which amplify this same space of parameters.

  • idle_gatename_fidpair_lists (list) – A list of the fiducial pairs which amplify the entire space given by amped_poly_j for the germ when it is repeated enough to be a synthetic idle. The strategy for finding fiducial pairs in the present case it to just monkey with the core-qubit parts of the measurement idle fiducials (non-core qubits are ideally the idle, and one can either modify the prep or the measure to “catch” what the non-idle germ_power_str does to the amplified portion of the state space).

  • model (Model) – The model used to compute the polynomial expressions of probabilities to first-order. Thus, this model should always have (simulation) type “termorder:1”.

  • single_q_fiducials (list, optional) – A list of gate-name tuples (e.g. (‘Gx’,)) which specify a set of single- qubit fiducials to use when trying to amplify gate parameters. Note that no qubit “state-space” label is required here (i.e. not ((‘Gx’,1),)); the tuples just contain single-qubit gate names. If None, then [(), (‘Gx’,), (‘Gy’,)] is used by default. If a list of two such lists is given, they specify preparation and measurement fiducials, respectively, e.g. [ [(), (‘Gx’,), (‘Gx’,’Gz’)], [(), (‘Gx’,), (‘Gz’,’Gx’)] ].

  • prep_lbl (Label, optional) – The state preparation label to use. If None, then the first (and usually the only) state prep label of model is used, so it’s usually fine to leave this as None.

  • effect_lbls (list, optional) – The list of POVM effect labels to use, as a list of Label objects. These are simplified POVM effect labels, so something like “Mdefault_0”, and if None the default is all the effect labels of the first POVM of model, which is usually what you want.

  • wrt_params (slice, optional) – The parameters being considered for amplification. (This should be the same as that used to produce idle_gatename_fidpair_lists).

  • verbosity (int, optional) – The level of detail printed to stdout. 0 means silent.

Returns

fidpair_lists (list) – The selected fiducial pairs, each in “gatename-fidpair-list” format. See :function:`_find_amped_polynomials_for_syntheticidle` for details.

pygsti.circuits.cloudcircuitconstruction._tile_idle_fidpairs(qubit_labels, idle_gatename_fidpair_lists, max_idle_weight)

Tile a set of fiducial pairs that amplify idle errors.

Tile a set of fiducial pairs that are sufficient for amplifying all the true-idle errors on max_idle_weight qubits (so with weight up to max_idle_weight onto nQubits qubits.

This function essentaily converts fiducial pairs that amplify all up-to-weight-k errors on k qubits to fiducial pairs that amplify all up-to-weight-k errors on nQubits qubits (where k = max_idle_weight).

Parameters
  • qubit_labels (int) – The labels of the final qubits. These are the line labels of the returned circuits.

  • idle_gatename_fidpair_lists (list) – A list of the fiducial pairs which amplify the errors on max_idle_weight qubits (so with weight up to max_idle_weight). Each element of this list is a fiducial pair in “gatename-fidpair-list” format. These are the fiducial pairs to “tile”.

  • max_idle_weight (int) – The number of qubits and maximum amplified error weight for the fiducial pairs given by idle_gatename_fidpair_lists.

Returns

fidpairs (list) – A list of (prep,meas) 2-tuples, where prep and meas are Circuit objects, giving the tiled fiducial pairs.

pygsti.circuits.cloudcircuitconstruction._tile_cloud_fidpairs(template_gatename_fidpair_lists, template_germpower, max_len, template_germ, clouds, qubit_labels)

Tile fiducial pairs that amplify “cloud” errors.

Take a “cloud template”, giving the fiducial pairs for a germ power acting on qubits labeled 0 to cloudsize-1, and map those fiducial pairs into fiducial pairs for all the qubits by placing in parallel the pairs for as many non-overlapping clouds as possible. This function performs a function analogous to :function:`_tile_idle_fidpairs` except here we tile fiducial pairs for non-idle operations.

Parameters
  • template_gatename_fidpair_lists (list) – A list of the fiducial pairs for the given template - that is, the pairs with which amplify all the desired errors for template_germpower (acting on qubits labeled by the integers 0 to the cloud size minus one).

  • template_germpower (Circuit) – The germ power string under consideration. This gives the action on the “core” qubits of the clouds, and is needed to construct the final fiducial + germPower + fiducial sequences returned by this function.

  • max_len (int) – The maximum length used to construct template_germpower. This is only needed to tag elements of the returned sequences list.

  • template_germ (Circuit) – The germ string under consideration. This is only needed to tag elements of the returned sequences list and place elements in the returned germs list.

  • clouds (list) – A list of (cloud_dict, template_to_cloud_map) tuples specifying the set of equivalent clouds corresponding to the template.

  • qubit_labels (list) – A list of the final qubit labels, which are the line labels of the returned circuits.

Returns

  • sequences (list) – A list of (Circuit, max_len, germ, prepFid, measFid) tuples specifying the final “tiled” fiducial pairs sandwiching germPowerStr for as many clouds in parallel as possible. Actual qubit labels (not the always- integer labels used in templates) are used in these strings. There are no duplicates in this list.

  • germs (list) – A list of Circuit objects giving all the germs (with appropriate qubit labels).

pygsti.circuits.cloudcircuitconstruction._compute_reps_for_synthetic_idle(model, germ_str, nqubits, core_qubits)

Return the number of times germ_str must be repeated to form a synthetic idle gate.

Parameters
  • model (Model) – A model containing matrix representations of all the gates in germ_str.

  • germ_str (Circuit) – The germ circuit to repeat.

  • nqubits (int) – The total number of qubits that model acts on. This is used primarily for sanity checks.

  • core_qubits (list) – A list of the qubit labels upon which germ_str ideally acts nontrivially. This could be inferred from germ_str but serves as a sanity check and more concrete specification of what state space the gate action takes place within.

Returns

int

pygsti.circuits.cloudcircuitconstruction._get_candidates_for_core(model, core_qubits, candidate_counts, seed_start)

Returns a list of candidate germs which act on a given set of “core” qubits.

This function figures out what gates within model are available to act (only) on core_qubits and then randomly selects a set of them based on candidate_counts. In each candidate germ, at least one gate will act on all of the core qubits (if the core is 2 qubits then this function won’t return a germ consisting of just 1-qubit gates).

This list serves as the inital candidate list when a new cloud template is created within create_cloudnoise_circuits.

Parameters
  • model (Model) – The model specifying the gates allowed to be in the germs.

  • core_qubits (list) – A list of the qubit labels. All returned candidate germs (ideally) act nontrivially only on these qubits.

  • candidate_counts (dict) – A dictionary specifying how many germs of each length to include in the returned set. Thus both keys and values are integers (key specifies germ length, value specifies number). The special value “all upto” means that all possible candidate germs up to the corresponding key’s value should be included. A typical value for this argument might be {4: ‘all upto’, 5: 10, 6: 10 }.

  • seed_start (int) – A initial random number generator seed value to use. Incrementally greater seeds are used for the different keys of candidate_counts.

Returns

list (candidate_germs) – A list of Circuit objects.

pygsti.circuits.cloudcircuitconstruction._create_xycnot_cloudnoise_circuits(num_qubits, max_lengths, geometry, cnot_edges, 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', comm=None)

Compute circuits which amplify the parameters of a particular CloudNoiseModel.

Returns circuits that amplify the parameters of a CloudNoiseModel containing X(pi/2), Y(pi/2) and CNOT gates using the specified arguments.

Parameters
  • num_qubits (int) – The total number of qubits.

  • max_lengths (list) – 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].

  • geometry ({"line","ring","grid","torus"} or QubitGraph) – The type of connectivity among the qubits, specifying a graph used to define neighbor relationships. Alternatively, a QubitGraph object may be passed directly.

  • cnot_edges (list) – A list of 2-tuples giving the pairs of qubits where CNOT gates exist (i.e. are available).

  • max_idle_weight (int, optional) – The maximum-weight for errors on the global idle gate.

  • maxhops (int) – 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_hops (int, 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_weight (int, 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.

  • paramroot ({"CPTP", "H+S+A", "H+S", "S", "H+D+A", "D+A", "D"}) – The “root” (no trailing ” terms”, etc.) parameterization used for the cloud noise model (which specifies what needs to be amplified).

  • verbosity (int, optional) – An integer >= 0 dictating how much output to send to stdout.

  • cache (dict, optional) – A cache dictionary which holds template information so that repeated calls to _create_xycnot_cloudnoise_circuits can draw on the same pool of templates.

  • idle_only (bool, optional) – If True, only sequences for the idle germ are returned. This is useful for idle tomography in particular.

  • idt_pauli_dicts (tuple, 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.

  • algorithm ({"greedy","sequential"}) – The algorithm is used internall by :function:`_find_amped_polynomials_for_syntheticidle`. You should leave this as the default unless you know what you’re doing.

  • comm (mpi4py.MPI.Comm, optional) – When not None, an MPI communicator for distributing the computation across multiple processors.

Returns

list – A list of :class:`Circuit`s

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.

Parameters
  • processor_spec (ProcessorSpec) – 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.

  • max_lengths (list) – 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].

  • single_q_fiducials (list) – 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_weight (int, optional) – The maximum-weight for errors on the global idle gate.

  • maxhops (int) – 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_hops (int, 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_weight (int, 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.

  • verbosity (int, optional) – The level of detail printed to stdout. 0 means silent.

  • cache (dict, 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_only (bool, optional) – If True, only sequences for the idle germ are returned. This is useful for idle tomography in particular.

  • idt_pauli_dicts (tuple, 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.

  • algorithm ({"greedy","sequential"}) – The algorithm is used internall by :function:`_find_amped_polynomials_for_syntheticidle`. You should leave this as the default unless you know what you’re doing.

  • idle_op_str (Circuit or tuple, optional) – The circuit or label that is used to indicate a completely idle layer (all qubits idle).

  • comm (mpi4py.MPI.Comm, optional) – When not None, an MPI communicator for distributing the computation across multiple processors.

Returns

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

pygsti.circuits.cloudcircuitconstruction._get_kcoverage_template_k2(n)

Special case where k == 2 -> use hypercube construction

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.

Parameters
  • n (int) – The sequences length (see description above).

  • k (int) – The coverage number (see description above).

  • verbosity (int, optional) – Amount of detail to print to stdout.

Returns

list – 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.

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

Check that k-coverage conditions are met.

Verify that rows satisfies the k-coverage conditions for length-n sequences. Raises an AssertionError if the check fails.

Parameters
  • rows (list) – A list of k-coverage words. The same as whas is returned by :function:`create_kcoverage_template`.

  • n (int) – The sequences length.

  • k (int) – The coverage number.

  • verbosity (int, optional) – Amount of detail to print to stdout.

Returns

None

pygsti.circuits.cloudcircuitconstruction._filter_nqubit_circuittuple(sequence_tuples, sectors_to_keep, new_sectors=None, idle='Gi')

Filters a list of n-qubit circuit tuples.

Creates a new set of qubit sequences-tuples that is the restriction of sequence_tuples to the sectors identified by sectors_to_keep.

More specifically, this function removes any operation labels which act specifically on sectors not in sectors_to_keep (e.g. an idle gate acting on all sectors because it’s .sslbls is None will not be removed – see :function:`filter_circuit` for details). Non-empty sequences for which all labels are removed in the germ are not included in the output (as these correspond to an irrelevant germ).

A typical case is when the state-space is that of n qubits, and the state space labels the intergers 0 to n-1. One may want to “rebase” the indices to 0 in the returned data set using new_sectors (E.g. sectors_to_keep == [4,5,6] and new_sectors == [0,1,2]).

Parameters
  • sequence_tuples (list) – A list of (circuit, L, germ, prepfid, measfid) tuples giving the sequences to process.

  • sectors_to_keep (list or tuple) – The state-space labels (strings or integers) of the “sectors” to keep in the returned tuple list.

  • new_sectors (list or tuple, optional) – New sectors names to map the elements of sectors_to_keep onto in the output DataSet’s circuits. None means the labels are not renamed. This can be useful if, for instance, you want to run a 2-qubit protocol that expects the qubits to be labeled “0” and “1” on qubits “4” and “5” of a larger set. Simply set sectors_to_keep == [4,5] and new_sectors == [0,1].

  • idle (string or Label, optional) – The operation label to be used when there are no kept components of a “layer” (element) of a circuit.

Returns

filtered_sequence_tuples (list) – A list of tuples with the same structure as sequence tuples.

pygsti.circuits.cloudcircuitconstruction._gatename_fidpair_list_to_fidpairs(gatename_fidpair_list)

Converts a fiducial pair list between formats.

Converts a “gatename fiducial pair list” to a standard list of 2-tuples of Circuit objects. This format is used internally for storing fiducial circuits containing only single-qubit gates.

A “gatename fiducial pair list” is a list with one element per fiducial pair. Each element is itself a list of (prep_names, meas_names) tuples, one per qubit. prep_names and meas_names are tuples of simple strings giving the names of the (1-qubit) gates acting on the respective qubit. The qubit labels for the output circuits are taken to be the integers starting at 0.

For example, the input: [ [ ((‘Gx’,’Gx’),(‘Gy’,)),((‘Gz’,’Gz’),()) ] ] would result in: [ ( Circuit(Gx:0Gx:0Gz:1Gz:1), Circuit(Gy:0) ) ]

Parameters

gatename_fidpair_list (list) – Each element corresponds to one (prep, meas) pair of circuits, and is a list of (prep_names, meas_names) tuples, on per qubit.

Returns

list – A list of (prep_fiducial, meas_fiducial) pairs, where prep_fiducial and meas_fiducial are Circuit objects.

pygsti.circuits.cloudcircuitconstruction._fidpairs_to_gatename_fidpair_list(fidpairs, num_qubits)

The inverse of :function:`_gatename_fidpair_list_to_fidpairs`.

Converts a list of (prep,meas) pairs of fiducial circuits (containing only single-qubit gates!) to the “gatename fiducial pair list” format, consisting of per-qubit lists of gate names (see docstring for :function:`_gatename_fidpair_list_to_fidpairs` for mor details).

Parameters
  • fidpairs (list) – A list of (prep_fiducial, meas_fiducial) pairs, where prep_fiducial and meas_fiducial are Circuit objects.

  • num_qubits (int) – The number of qubits. Qubit labels within fidpairs are assumed to be the integers from 0 to num_qubits-1.

Returns

gatename_fidpair_list (list) – Each element corresponds to an elmeent of fidpairs, and is a list of (prep_names, meas_names) tuples, on per qubit. prep_names and meas_names are tuples of single-qubit gate names (strings).