:py:mod:`pygsti.tools.rbtools`
==============================

.. py:module:: pygsti.tools.rbtools

.. autoapi-nested-parse::

   Tools for analyzing RB data






Module Contents
---------------


Functions
~~~~~~~~~

.. autoapisummary::

   pygsti.tools.rbtools.p_to_r
   pygsti.tools.rbtools.r_to_p
   pygsti.tools.rbtools.adjusted_success_probability
   pygsti.tools.rbtools.marginalized_success_counts
   pygsti.tools.rbtools.hamming_distance
   pygsti.tools.rbtools.marginalized_hamming_distance_counts
   pygsti.tools.rbtools.rescaling_factor



.. py:function:: p_to_r(p, d, rtype='EI')

   Converts an RB decay constant (`p`) to the RB error rate (`r`).

   Here `p` is (normally) obtained from fitting data to `A + Bp^m`. There are two
   'types' of RB error rate corresponding to different rescalings of `1 - p`.
   These are the entanglement infidelity (EI) type r and the average gate
   infidelity (AGI) type `r`. The EI-type `r` is given by:

   `r =  (d^2 - 1)(1 - p)/d^2`,

   where `d` is the dimension of the system (i.e., 2^n for n qubits).
   The AGI-type `r` is given by

   `r =  (d - 1)(1 - p)/d`.

   For RB on gates whereby every gate is followed by an n-qubit
   uniform depolarizing channel (the most idealized RB scenario)
   then the EI-type (AGI-type) r corresponds to the EI (AGI) of
   the depolarizing channel to the identity channel.

   The default (EI) is the convention used in direct RB, and is perhaps
   the most well-motivated as then r corresponds to the error probablity
   of the gates (in the idealized pauli-errors scenario). AGI is
   the convention used throughout Clifford RB theory.

   Parameters
   ----------
   p : float
       Fit parameter p from P_m = A + B*p**m.

   d : int
       Number of dimensions of the Hilbert space

   rtype : {'EI','AGI'}, optional
       The RB error rate rescaling convention.

   Returns
   -------
   r : float
       The RB error rate


.. py:function:: r_to_p(r, d, rtype='EI')

   Inverse of the p_to_r function.

   Parameters
   ----------
   r : float
       The RB error rate

   d : int
       Number of dimensions of the Hilbert space

   rtype : {'EI','AGI'}, optional
       The RB error rate rescaling convention.

   Returns
   -------
   p : float
       The RB decay constant


.. py:function:: adjusted_success_probability(hamming_distance_pdf)

   The success probabilitys adjusted by hamming weights.

   TODO: docstring - more explanation

   Parameters
   ----------
   hamming_distance_pdf : <TODO typ>
       <TODO description>

   Returns
   -------
   numpy.ndarray


.. py:function:: marginalized_success_counts(dsrow, circ, target, qubits)

   Marginalize the success counts over qubits.

   Parameters
   ----------
   dsrow : _DataSetRow
       The circuit outcome data to marginalize.

   circ : Circuit
       The circuit.

   target : str
       The ideal outcome, e.g. `"0010"`.

   qubits : tuple
       The qubit labels that are retained after the marginalization.

   Returns
   -------
   int
       The number of success counts.


.. py:function:: hamming_distance(bs1, bs2)

   TODO: docstring

   Parameters
   ----------
   bs1 : <TODO typ>
       <TODO description>

   bs2 : <TODO typ>
       <TODO description>

   Returns
   -------
   <TODO typ>


.. py:function:: marginalized_hamming_distance_counts(dsrow, circ, target, qubits)

   TODO: docstring

   Parameters
   ----------
   dsrow : _DataSetRow
       The circuit outcome data to marginalize.

   circ : Circuit
       The circuit.

   target : str
       The ideal outcome, e.g. `"0010"`.

   qubits : tuple
       The qubit labels that are retained after the marginalization.

   Returns
   -------
   list


.. py:function:: rescaling_factor(lengths, quantity, offset=2)

   Finds a rescaling value `alpha` that maps the Clifford RB decay constant `p` to `p_(rescaled) = p^(1/alpha)`.

   This can be used for finding, e.g., a "CRB r per CNOT" or a "CRB r per compiled Clifford depth".

   Parameters
   ----------
   lengths : list
       A list of the RB lengths, which each value in 'quantity' will be rescaled by.

   quantity : list
       A list, of the same length as `lengths`, that contains lists of values of the quantity
       that the rescaling factor is extracted from.

   offset : int, optional
       A constant offset to add to lengths.

   Returns
   -------
   float