:py:mod:`pygsti.extras.paritybenchmarking` ========================================== .. py:module:: pygsti.extras.paritybenchmarking .. autoapi-nested-parse:: Parity Benchmarking Sub-package Submodules ---------- .. toctree:: :titlesonly: :maxdepth: 1 disturbancecalc/index.rst Package Contents ---------------- Functions ~~~~~~~~~ .. autoapisummary:: pygsti.extras.paritybenchmarking.compute_disturbances pygsti.extras.paritybenchmarking.compute_disturbances_with_confidence pygsti.extras.paritybenchmarking.compute_disturbances_from_bootstrap_rawdata pygsti.extras.paritybenchmarking.compute_disturbances_bootstrap_rawdata pygsti.extras.paritybenchmarking.resample_data pygsti.extras.paritybenchmarking.compute_residual_tvds pygsti.extras.paritybenchmarking.compute_ovd_over_tvd_ratio pygsti.extras.paritybenchmarking.compute_ovd_corrected_disturbances pygsti.extras.paritybenchmarking.compute_ovd_corrected_disturbances_bootstrap_rawdata Attributes ~~~~~~~~~~ .. autoapisummary:: pygsti.extras.paritybenchmarking.build_basis .. py:function:: compute_disturbances(n_bits, data_ref, data_test, num_bootstrap_samples=20, max_weight=4, solver='SCS', verbosity=1, add_one_to_data=True) Compute the weight-X disturbances between two data sets (including error bars). This function is computes the weight-X disturbance, defined as the difference between the weight-(X-1) and weight-X residual TVDs, (evaluated at the ML probability distributions implied by the data) for all weights up to `max_weight`. It also uses the data to compute 1-sigma error bar for each value using the boostrap method. Parameters ---------- n_bits : int The number of bits (qubits). data_ref, data_test : numpy array Arrays of outcome counts from the reference and test experiments, respectively. Each array has one element per 2^n_bits bit string. num_bootstrap_samples : int The number of boostrap (re-)samples to use. If 0, then error bars are not computed. max_weight : int, optional The maximum weight disturbance to compute. Typically this is the same as `n_bits`. solver : str, optional The name of the solver to used (see `cvxpy.installed_solvers()`) verbosity : int, optional Sets the level of detail for messages printed to the console (higher = more detail). add_one_to_data : bool, optional Sets whether the bootstrap should be calculated after adding a single fake count to every possible outcome. Returns ------- list A list of the disturbances by weight. The lists i-th element is a `(disturbance, errorbar_length)` tuple for the weight (i+1) disturbance. That is, the weight (i+1) disturbance = `disturbance +/- errorbar_length`. .. py:function:: compute_disturbances_with_confidence(n_bits, data_ref, data_test, confidence_percent=68.0, max_weight=4, maxiters=20, search_tol=0.1, reltol=1e-05, abstol=1e-05, solver='SCS', initial_treg_factor=0.001, verbosity=1) Compute the weight-X distrubances between two data sets (including error bars). This function is computes the weight-X disturbance, defined as the difference between the weight-(X-1) and weight-X residual TVDs, (evaluated at the ML probability distributions implied by the data) for all weights up to `max_weight`. It also uses the data to compute `confidence_percent`% confidence intervals for each residualTVD and adds these in quadrature to arrive at error bars on each weight-X disturbance. Parameters ---------- n_bits : int The number of bits (qubits). data_ref, data_test : numpy array Arrays of outcome counts from the reference and test experiments, respectively. Each array has one element per 2^n_bits bit string. confidence_percent : float or None, optional The confidence level desired for the computed error bars. Note that this number can range between 0 and 100, not 0 and 1. If None, then no error bars are computed. max_weight : int, optional The maximum weight disturbance to compute. Typically this is the same as `n_bits`. maxiters : int, optional The maximum number of alternating-minimization iterations to allow within the profile-loglikelihood computation before giving up and deeming the final result "ok". search_tol : float, optional The tolerance on the log-likelihood used when trying to locate the (residualTVD, logL) pair with logL at the edge of the confidence interval. reltol : float, optional The relative tolerance used to within profile likelihood. abstol : float, optional The absolute tolerance used to within profile likelihood. solver : str, optional The name of the solver to used (see `cvxpy.installed_solvers()`) initial_treg_factor : float, optional The magnitude of an internal penalty factor on the off-diagonals of the T matrix (see :class:`ResidualTVD`). verbosity : int, optional Sets the level of detail for messages printed to the console (higher = more detail). Returns ------- list A list of the disturbances by weight. The lists i-th element is a `(disturbance, errorbar_length)` tuple for the weight (i+1) disturbance. That is, the weight (i+1) disturbance = `disturbance +/- errorbar_length`. .. py:function:: compute_disturbances_from_bootstrap_rawdata(ml_disturbances, bootstrap_disturbances, num_bootstrap_samples='all') Compute 1-sigma error bars for a set of disturbances (given by `ml_disturbances`) using boostrap data. Parameters ---------- ml_disturbances : numpy.ndarray The disturbances by weight (length `max_weight`) for the maximum-likelhood (ML) distribution of some set of data. bootstrap_disturbances : numpy.ndarray A (max_weight, num_bootstrap_samples) sized array where each column is the set of by-weight disturbances for a distribution corresponding to a re-sampled bootstrap data set. num_bootstrap_samples : int or tuple or 'all' How many bootstrap samples to use when computing the boostrap error bars. This number can be less than the total number of bootstrap samples to test how using fewer boostrap samples would have performed. `'all'` means to use all available bootstrap samples. If a tuple, then each entry should be an integer and a series of error bars is returned (instead of a single one) corresponding to using each number of samples. Returns ------- list A list of the disturbances by weight. The lists i-th element is a `(disturbance, errorbar_length)` tuple for the weight (i+1) disturbance. That is, the weight (i+1) disturbance = `disturbance +/- errorbar_length`. If `num_bootstrap_samples` is a tuple, then elements are instead `(disturbance, errorbar_length1, errorbar_length2, ...)` where error bar lengths correspond to entries in `num_bootstrap_samples`. .. py:function:: compute_disturbances_bootstrap_rawdata(n_bits, data_ref, data_test, num_bootstrap_samples=20, max_weight=4, solver='SCS', verbosity=1, seed=0, return_resampled_data=False, add_one_to_data=True) Compute the weight-X distrubances between two data sets (including error bars). This function is computes the weight-X disturbance, defined as the difference between the weight-(X-1) and weight-X residual TVDs, (evaluated at the ML probability distributions implied by the data) for all weights up to `max_weight`. It also uses the data to compute 1-sigma error bar for each value using the boostrap method. Parameters ---------- n_bits : int The number of bits (qubits). data_ref, data_test : numpy array Arrays of outcome counts from the reference and test experiments, respectively. Each array has one element per 2^n_bits bit string. num_bootstrap_samples : int The number of boostrap (re-)samples to use. max_weight : int, optional The maximum weight disturbance to compute. Typically this is the same as `n_bits`. solver : str, optional The name of the solver to used (see `cvxpy.installed_solvers()`) verbosity : int, optional Sets the level of detail for messages printed to the console (higher = more detail). add_one_to_data : bool, optional Sets whether the bootstrap should be calculated after adding a single fake count to every possible outcome. Returns ------- disturbance_by_weight_ML : numpy.ndarray The ML disturbances by weight (length `max_weight`) bootstrap_disturbances_by_weight : numpy.ndarray A (max_weight, num_bootstrap_samples) sized array of each disturbance computed for each of the `num_bootstrap_samples` re-sampled data sets. .. py:function:: resample_data(data, n_data_points=None, seed=None) Sample from the ML probability distrubution of `data`. .. py:function:: compute_residual_tvds(n_bits, data_ref, data_test, confidence_percent=68.0, max_weight=4, maxiters=20, search_tol=0.1, reltol=1e-05, abstol=1e-05, solver='SCS', initial_treg_factor=0.001, verbosity=1) Compute the weight-X residual TVDs between two data sets (including error bars). Parameters ---------- n_bits : int The number of bits (qubits). data_ref, data_test : numpy array Arrays of outcome counts from the reference and test experiments, respectively. Each array has one element per 2^n_bits bit string. confidence_percent : float or None, optional The confidence level desired for the computed error bars. Note that this number can range between 0 and 100, not 0 and 1. If None, then no error bars are computed. max_weight : int, optional The maximum weight residual TVD to compute. Typically this is the same as `n_bits`. maxiters : int, optional The maximum number of alternating-minimization iterations to allow within the profile-loglikelihood computation before giving up and deeming the final result "ok". search_tol : float, optional The tolerance on the log-likelihood used when trying to locate the (residualTVD, logL) pair with logL at the edge of the confidence interval. reltol : float, optional The relative tolerance used to within profile likelihood. abstol : float, optional The absolute tolerance used to within profile likelihood. solver : str, optional The name of the solver to used (see `cvxpy.installed_solvers()`) initial_treg_factor : float, optional The magnitude of an internal penalty factor on the off-diagonals of the T matrix (see :class:`ResidualTVD`). verbosity : int, optional Sets the level of detail for messages printed to the console (higher = more detail). Returns ------- list A list of the residual TVDs by weight. The lists i-th element is a `(residual_tvd, errorbar_length)` tuple for the weight (i+1) residual TVD. That is, the weight (i+1) residual TVD = `residual_tvd +/- errorbar_length`. .. py:data:: build_basis .. py:function:: compute_ovd_over_tvd_ratio(n_bits, data_ref, data_test, p_ideal, return_all=False) TODO: docstring .. py:function:: compute_ovd_corrected_disturbances(n_bits, data_ref, data_test, p_ideal, num_bootstrap_samples=20, max_weight=4, solver='SCS', verbosity=1, add_one_to_data=True) Compute the weight-X disturbances between two data sets (including error bars). This function is computes the weight-X disturbance, defined as the difference between the weight-(X-1) and weight-X residual TVDs, (evaluated at the ML probability distributions implied by the data) for all weights up to `max_weight`. It also uses the data to compute 1-sigma error bar for each value using the boostrap method. Parameters ---------- n_bits : int The number of bits (qubits). data_ref, data_test : numpy array Arrays of outcome counts from the reference and test experiments, respectively. Each array has one element per 2^n_bits bit string. num_bootstrap_samples : int The number of boostrap (re-)samples to use. If 0, then error bars are not computed. max_weight : int, optional The maximum weight disturbance to compute. Typically this is the same as `n_bits`. solver : str, optional The name of the solver to used (see `cvxpy.installed_solvers()`) verbosity : int, optional Sets the level of detail for messages printed to the console (higher = more detail). add_one_to_data : bool, optional Sets whether the bootstrap should be calculated after adding a single fake count to every possible outcome. Returns ------- list A list of the disturbances by weight. The lists i-th element is a `(disturbance, errorbar_length)` tuple for the weight (i+1) disturbance. That is, the weight (i+1) disturbance = `disturbance +/- errorbar_length`. the `max_weight`-th element gives the OVD/TVD ratio used to correct the TVD-based disturbance values, along with its error bar. .. py:function:: compute_ovd_corrected_disturbances_bootstrap_rawdata(n_bits, data_ref, data_test, p_ideal, num_bootstrap_samples=20, max_weight=4, solver='SCS', verbosity=1, seed=0, return_resampled_data=False, add_one_to_data=True) Compute the weight-X distrubances between two data sets (including error bars). This function is computes the weight-X disturbance, defined as the difference between the weight-(X-1) and weight-X residual TVDs, (evaluated at the ML probability distributions implied by the data) for all weights up to `max_weight`. It also uses the data to compute 1-sigma error bar for each value using the boostrap method. Parameters ---------- n_bits : int The number of bits (qubits). data_ref, data_test : numpy array Arrays of outcome counts from the reference and test experiments, respectively. Each array has one element per 2^n_bits bit string. p_ideal : numpy array The ideal probability distribution (of both reference and test experiments). num_bootstrap_samples : int The number of boostrap (re-)samples to use. max_weight : int, optional The maximum weight disturbance to compute. Typically this is the same as `n_bits`. solver : str, optional The name of the solver to used (see `cvxpy.installed_solvers()`) verbosity : int, optional Sets the level of detail for messages printed to the console (higher = more detail). add_one_to_data : bool, optional Sets whether the bootstrap should be calculated after adding a single fake count to every possible outcome. Returns ------- disturbance_by_weight_ML : numpy.ndarray The ML OVD-corrected disturbances by weight, with the OVD/TVD ratio tagged on at the end (so the length is `max_weight + 1`) bootstrap_disturbances_by_weight : numpy.ndarray A (max_weight + 1, num_bootstrap_samples) sized array of each disturbance and the OVD/TVD ratio (included as the final row in this matrix) for each of the `num_bootstrap_samples` re-sampled data sets.