:py:mod:`pygsti.tools.rbtheory` =============================== .. py:module:: pygsti.tools.rbtheory .. autoapi-nested-parse:: RB-related functions of gates and models Module Contents --------------- Functions ~~~~~~~~~ .. autoapisummary:: pygsti.tools.rbtheory.predicted_rb_number pygsti.tools.rbtheory.predicted_rb_decay_parameter pygsti.tools.rbtheory.rb_gauge pygsti.tools.rbtheory.transform_to_rb_gauge pygsti.tools.rbtheory.L_matrix pygsti.tools.rbtheory.R_matrix_predicted_rb_decay_parameter pygsti.tools.rbtheory.R_matrix pygsti.tools.rbtheory.errormaps pygsti.tools.rbtheory.gate_dependence_of_errormaps .. py:function:: predicted_rb_number(model, target_model, weights=None, d=None, rtype='EI') Predicts the RB error rate from a model. Uses the "L-matrix" 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 per-Clifford 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 gauge-invariant quantity. The function is likely reliable when complete positivity is slightly violated, although the theory on which it is based assumes complete positivity. Parameters ---------- model : Model 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_model : Model 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. weights : dict, 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 non-negative, 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. d : int, optional The Hilbert space dimension. If None, then sqrt(model.dim) is used. rtype : str, optional The type of RB error rate, either "EI" or "AGI", corresponding to different dimension-dependent 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 AGI-type r is given by r = (d - 1)(1 - p)/d, which is the conventional r definition in Clifford RB. This r is associated with (gate-averaged) average gate infidelity. Returns ------- r : float. The predicted RB number. .. py:function:: 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 ---------- model : Model 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_model : Model 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. weights : dict, 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 non-negative, 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 ------- p : float. The second largest eigenvalue of L. This is the RB decay parameter for various types of RB. .. py:function:: 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 gauge-transformation, 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 ---------- model : Model 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_model : Model 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. weights : dict, 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 non-negative, 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_weighting : float, optional Must be non-zero. 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_operator : array The matrix defining the gauge-transformation. .. py:function:: 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 :class:`Model` and `target_model`. Parameters ---------- model : Model 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_model : Model 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. weights : dict, 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 non-negative, 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_weighting : float, optional Must be non-zero. 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_gauge : Model The model `model` transformed into the "RB gauge". .. py:function:: L_matrix(model, target_model, weights=None) Constructs a generalization of the 'L-matrix' linear operator on superoperators. From Proctor et al Phys. Rev. Lett. 119, 130502 (2017), the 'L-matrix' 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 ---------- model : Model 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_model : Model 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. weights : dict, 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 non-negative, 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 ------- L : float 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. .. py:function:: R_matrix_predicted_rb_decay_parameter(model, group, group_to_model=None, weights=None) Returns the second largest eigenvalue of a generalization of the 'R-matrix' [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 trace-preserving gates and a variety of forms of RB, including Clifford and direct RB. This function creates a matrix which scales super-exponentially in the number of qubits. Parameters ---------- model : Model 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. group : MatrixGroup 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_model : dict, 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. weights : dict, 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 ------- p : float The predicted RB decay parameter. Valid for standard Clifford RB or direct RB with trace-preserving gates, and in a range of other circumstances. .. py:function:: R_matrix(model, group, group_to_model=None, weights=None) Constructs a generalization of the 'R-matrix' 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 super-exponentially large in the number of qubits, but can be constructed for 1-qubit models. Parameters ---------- model : Model 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. group : MatrixGroup The group that the `model` model contains gates from. For Clifford RB or direct RB, this would be the Clifford group. group_to_model : dict, 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`. weights : dict, 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 ------- R : float A weighted, a subset-sampling generalization of the 'R-matrix' from Proctor et al Phys. Rev. Lett. 119, 130502 (2017). .. py:function:: errormaps(model, target_model) Computes the 'left-multiplied' 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 ---------- model : Model The imperfect model. target_model : Model The target model. Returns ------- errormaps : Model The left multplied error gates, along with the average error map, with the key 'Gavg'. .. py:function:: gate_dependence_of_errormaps(model, target_model, norm='diamond', mx_basis=None) Computes the "gate-dependence 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 1-to-1 norm. This quantity is defined in Magesan et al PRA 85 042311 2012. Parameters ---------- model : Model The actual model target_model : Model The target model. norm : str, 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_avg : float The value of the parameter defined above.