pygsti.tools.rbtheory
RBrelated functions of gates and models
Module Contents
Functions

Predicts the RB error rate from a model. 

Computes the second largest eigenvalue of the 'L matrix' (see the L_matrix function). 

Computes the gauge transformation required so that the RB number matches the average model infidelity. 

Transforms a Model into the "RB gauge" (see the RB_gauge function). 

Constructs a generalization of the 'Lmatrix' linear operator on superoperators. 

Returns the second largest eigenvalue of a generalization of the 'Rmatrix' [see the R_matrix function]. 

Constructs a generalization of the 'Rmatrix' of Proctor et al Phys. Rev. Lett. 119, 130502 (2017). 

Computes the 'leftmultiplied' error maps associated with a noisy gate set, along with the average error map. 

Computes the "gatedependence of errors maps" parameter defined by 
 pygsti.tools.rbtheory.predicted_rb_number(model, target_model, weights=None, d=None, rtype='EI')
Predicts the RB error rate from a model.
Uses the “Lmatrix” theory from Proctor et al Phys. Rev. Lett. 119, 130502 (2017). Note that this gives the same predictions as the theory in Wallman Quantum 2, 47 (2018).
This theory is valid for various types of RB, including standard Clifford RB – i.e., it will accurately predict the perClifford error rate reported by standard Clifford RB. It is also valid for “direct RB” under broad circumstances.
For this function to be valid the model should be trace preserving and completely positive in some representation, but the particular representation of the model used is irrelevant, as the predicted RB error rate is a gaugeinvariant quantity. The function is likely reliable when complete positivity is slightly violated, although the theory on which it is based assumes complete positivity.
Parameters
 modelModel
The model to calculate the RB number of. This model is the model randomly sampled over, so this is not necessarily the set of physical primitives. In Clifford RB this is a set of Clifford gates; in “direct RB” this normally would be the physical primitives.
 target_modelModel
The target model, corresponding to model. This function is not invariant under swapping model and target_model: this Model must be the target model, and should consistent of perfect gates.
 weightsdict, optional
If not None, a dictionary of floats, whereby the keys are the gates in model and the values are the unnormalized probabilities to apply each gate at each stage of the RB protocol. If not None, the values in weights must all be nonnegative, and they must not all be zero. Because, when divided by their sum, they must be a valid probability distribution. If None, the weighting defaults to an equal weighting on all gates, as this is used in many RB protocols (e.g., Clifford RB). But, this weighting is flexible in the “direct RB” protocol.
 dint, optional
The Hilbert space dimension. If None, then sqrt(model.dim) is used.
 rtypestr, optional
The type of RB error rate, either “EI” or “AGI”, corresponding to different dimensiondependent rescalings of the RB decay constant p obtained from fitting to Pm = A + Bp^m. “EI” corresponds to an RB error rate that is associated with entanglement infidelity, which is the probability of error for a gate with stochastic errors. This is the RB error rate defined in the “direct RB” protocol, and is given by:
r = (d^2  1)(1  p)/d^2,
The AGItype r is given by
r = (d  1)(1  p)/d,
which is the conventional r definition in Clifford RB. This r is associated with (gateaveraged) average gate infidelity.
Returns
 rfloat.
The predicted RB number.
 pygsti.tools.rbtheory.predicted_rb_decay_parameter(model, target_model, weights=None)
Computes the second largest eigenvalue of the ‘L matrix’ (see the L_matrix function).
For standard Clifford RB and direct RB, this corresponds to the RB decay parameter p in Pm = A + Bp^m for “reasonably low error” trace preserving and completely positive gates. See also the predicted_rb_number function.
Parameters
 modelModel
The model to calculate the RB decay parameter of. This model is the model randomly sampled over, so this is not necessarily the set of physical primitives. In Clifford RB this is a set of Clifford gates; in “direct RB” this normally would be the physical primitives.
 target_modelModel
The target model corresponding to model. This function is not invariant under swapping model and target_model: this Model must be the target model, and should consistent of perfect gates.
 weightsdict, optional
If not None, a dictionary of floats, whereby the keys are the gates in model and the values are the unnormalized probabilities to apply each gate at each stage of the RB protocol. If not None, the values in weights must all be nonnegative, and they must not all be zero. Because, when divided by their sum, they must be a valid probability distribution. If None, the weighting defaults to an equal weighting on all gates, as this is used in many RB protocols (e.g., Clifford RB). But, this weighting is flexible in the “direct RB” protocol.
Returns
 pfloat.
The second largest eigenvalue of L. This is the RB decay parameter for various types of RB.
 pygsti.tools.rbtheory.rb_gauge(model, target_model, weights=None, mx_basis=None, eigenvector_weighting=1.0)
Computes the gauge transformation required so that the RB number matches the average model infidelity.
This function computes the gauge transformation required so that, when the model is transformed via this gaugetransformation, the RB number – as predicted by the function predicted_rb_number – is the average model infidelity between the transformed model model and the target model target_model. This transformation is defined Proctor et al Phys. Rev. Lett. 119, 130502 (2017), and see also Wallman Quantum 2, 47 (2018).
Parameters
 modelModel
The RB model. This is not necessarily the set of physical primitives – it is the model randomly sampled over in the RB protocol (e.g., the Cliffords).
 target_modelModel
The target model corresponding to model. This function is not invariant under swapping model and target_model: this Model must be the target model, and should consistent of perfect gates.
 weightsdict, optional
If not None, a dictionary of floats, whereby the keys are the gates in model and the values are the unnormalized probabilities to apply each gate at each stage of the RB protocol. If not None, the values in weights must all be nonnegative, and they must not all be zero. Because, when divided by their sum, they must be a valid probability distribution. If None, the weighting defaults to an equal weighting on all gates, as this is used in many RB protocols (e.g., Clifford RB). But, this weighting is flexible in the “direct RB” protocol.
 mx_basis{“std”,”gm”,”pp”}, optional
The basis of the models. If None, the basis is obtained from the model.
 eigenvector_weightingfloat, optional
Must be nonzero. A weighting on the eigenvector with eigenvalue that is the RB decay parameter, in the sum of this eigenvector and the eigenvector with eigenvalue of 1 that defines the returned matrix l_operator. The value of this factor does not change whether this l_operator transforms into a gauge in which r = AGsI, but it may impact on other properties of the gates in that gauge. It is irrelevant if the gates are unital.
Returns
 l_operatorarray
The matrix defining the gaugetransformation.
 pygsti.tools.rbtheory.transform_to_rb_gauge(model, target_model, weights=None, mx_basis=None, eigenvector_weighting=1.0)
Transforms a Model into the “RB gauge” (see the RB_gauge function).
This notion was introduced in Proctor et al Phys. Rev. Lett. 119, 130502 (2017). This gauge is a function of both the model and its target. These may be input in any gauge, for the purposes of obtaining “r = average model infidelity” between the output
Model
and target_model.Parameters
 modelModel
The RB model. This is not necessarily the set of physical primitives – it is the model randomly sampled over in the RB protocol (e.g., the Cliffords).
 target_modelModel
The target model corresponding to model. This function is not invariant under swapping model and target_model: this Model must be the target model, and should consistent of perfect gates.
 weightsdict, optional
If not None, a dictionary of floats, whereby the keys are the gates in model and the values are the unnormalized probabilities to apply each gate at each stage of the RB protocol. If not None, the values in weights must all be nonnegative, and they must not all be zero. Because, when divided by their sum, they must be a valid probability distribution. If None, the weighting defaults to an equal weighting on all gates, as this is used in many RB protocols (e.g., Clifford RB). But, this weighting is flexible in the “direct RB” protocol.
 mx_basis{“std”,”gm”,”pp”}, optional
The basis of the models. If None, the basis is obtained from the model.
 eigenvector_weightingfloat, optional
Must be nonzero. A weighting on the eigenvector with eigenvalue that is the RB decay parameter, in the sum of this eigenvector and the eigenvector with eigenvalue of 1 that defines the returned matrix l_operator. The value of this factor does not change whether this l_operator transforms into a gauge in which r = AGsI, but it may impact on other properties of the gates in that gauge. It is irrelevant if the gates are unital.
Returns
 model_in_RB_gaugeModel
The model model transformed into the “RB gauge”.
 pygsti.tools.rbtheory.L_matrix(model, target_model, weights=None)
Constructs a generalization of the ‘Lmatrix’ linear operator on superoperators.
From Proctor et al Phys. Rev. Lett. 119, 130502 (2017), the ‘Lmatrix’ is represented as a matrix via the “stack” operation. This eigenvalues of this matrix describe the decay constant (or constants) in an RB decay curve for an RB protocol whereby random elements of the provided model are sampled according to the weights probability distribution over the model. So, this facilitates predictions of Clifford RB and direct RB decay curves.
Parameters
 modelModel
The RB model. This is not necessarily the set of physical primitives – it is the model randomly sampled over in the RB protocol (e.g., the Cliffords).
 target_modelModel
The target model corresponding to model. This function is not invariant under swapping model and target_model: this Model must be the target model, and should consistent of perfect gates.
 weightsdict, optional
If not None, a dictionary of floats, whereby the keys are the gates in model and the values are the unnormalized probabilities to apply each gate at each stage of the RB protocol. If not None, the values in weights must all be nonnegative, and they must not all be zero. Because, when divided by their sum, they must be a valid probability distribution. If None, the weighting defaults to an equal weighting on all gates, as this is used in many RB protocols (e.g., Clifford RB). But, this weighting is flexible in the “direct RB” protocol.
Returns
 Lfloat
A weighted version of the L operator from Proctor et al Phys. Rev. Lett. 119, 130502 (2017), represented as a matrix using the ‘stacking’ convention.
 pygsti.tools.rbtheory.R_matrix_predicted_rb_decay_parameter(model, group, group_to_model=None, weights=None)
Returns the second largest eigenvalue of a generalization of the ‘Rmatrix’ [see the R_matrix function].
Introduced in Proctor et al Phys. Rev. Lett. 119, 130502 (2017). This number is a prediction of the RB decay parameter for tracepreserving gates and a variety of forms of RB, including Clifford and direct RB. This function creates a matrix which scales superexponentially in the number of qubits.
Parameters
 modelModel
The model to predict the RB decay paramter for. If group_to_model is None, the labels of the gates in model should be the same as the labels of the group elements in group. For Clifford RB this would be the clifford model, for direct RB it would be the primitive gates.
 groupMatrixGroup
The group that the model model contains gates from (model does not need to be the full group, and could be a subset of group). For Clifford RB and direct RB, this would be the Clifford group.
 group_to_modeldict, optional
If not None, a dictionary that maps labels of group elements to labels of model. If model and group elements have the same labels, this dictionary is not required. Otherwise it is necessary.
 weightsdict, optional
If not None, a dictionary of floats, whereby the keys are the gates in model and the values are the unnormalized probabilities to apply each gate at each stage of the RB protocol. If not None, the values in weights must all be positive or zero, and they must not all be zero (because, when divided by their sum, they must be a valid probability distribution). If None, the weighting defaults to an equal weighting on all gates, as used in most RB protocols.
Returns
 pfloat
The predicted RB decay parameter. Valid for standard Clifford RB or direct RB with tracepreserving gates, and in a range of other circumstances.
 pygsti.tools.rbtheory.R_matrix(model, group, group_to_model=None, weights=None)
Constructs a generalization of the ‘Rmatrix’ of Proctor et al Phys. Rev. Lett. 119, 130502 (2017).
This matrix described the exact behaviour of the average success probablities of RB sequences. This matrix is superexponentially large in the number of qubits, but can be constructed for 1qubit models.
Parameters
 modelModel
The noisy model (e.g., the Cliffords) to calculate the R matrix of. The correpsonding target model (not required in this function) must be equal to or a subset of (a faithful rep of) the group group. If group_to_model `is None, the labels of the gates in model should be the same as the labels of the corresponding group elements in `group. For Clifford RB model should be the clifford model; for direct RB this should be the native model.
 groupMatrixGroup
The group that the model model contains gates from. For Clifford RB or direct RB, this would be the Clifford group.
 group_to_modeldict, optional
If not None, a dictionary that maps labels of group elements to labels of model. This is required if the labels of the gates in model are different from the labels of the corresponding group elements in group.
 weightsdict, optional
If not None, a dictionary of floats, whereby the keys are the gates in model and the values are the unnormalized probabilities to apply each gate at for each layer of the RB protocol. If None, the weighting defaults to an equal weighting on all gates, as used in most RB protocols (e.g., Clifford RB).
Returns
 Rfloat
A weighted, a subsetsampling generalization of the ‘Rmatrix’ from Proctor et al Phys. Rev. Lett. 119, 130502 (2017).
 pygsti.tools.rbtheory.errormaps(model, target_model)
Computes the ‘leftmultiplied’ error maps associated with a noisy gate set, along with the average error map.
This is the model [E_1,…] such that
G_i = E_iT_i,
where T_i is the gate which G_i is a noisy implementation of. There is an additional gate in the set, that has the key ‘Gavg’. This is the average of the error maps.
Parameters
 modelModel
The imperfect model.
 target_modelModel
The target model.
Returns
 errormapsModel
The left multplied error gates, along with the average error map, with the key ‘Gavg’.
 pygsti.tools.rbtheory.gate_dependence_of_errormaps(model, target_model, norm='diamond', mx_basis=None)
Computes the “gatedependence of errors maps” parameter defined by
delta_avg = avg_i E_i  avg_i(E_i) ,
where E_i are the error maps, and the norm is either the diamond norm or the 1to1 norm. This quantity is defined in Magesan et al PRA 85 042311 2012.
Parameters
 modelModel
The actual model
 target_modelModel
The target model.
 normstr, optional
The norm used in the calculation. Can be either ‘diamond’ for the diamond norm, or ‘1to1’ for the Hermitian 1 to 1 norm.
 mx_basis{“std”,”gm”,”pp”}, optional
The basis of the models. If None, the basis is obtained from the model.
Returns
 delta_avgfloat
The value of the parameter defined above.