pygsti.tools.chi2fns
¶
Chisquared and related functions
Module Contents¶
Functions¶

Computes the total (aggregate) chi^2 for a set of circuits. 

Computes the percircuit chi^2 contributions for a set of cirucits. 

Compute the gradient of the chi^2 function computed by :function:`chi2`. 

Compute the Hessian matrix of the 

Compute and approximate Hessian matrix of the 

Compute the chialpha objective function. 

Compute the percircuit chialpha objective function. 

Computes chi^2 for a 2outcome measurement. 

Computes chi^2 for a 2outcome measurement using frequencyweighting. 

Computes the chi^2 term corresponding to a single outcome. 

Computes the frequencyweighed chi^2 term corresponding to a single outcome. 
 pygsti.tools.chi2fns.chi2(model, dataset, circuits=None, min_prob_clip_for_weighting=0.0001, prob_clip_interval=( 10000, 10000), op_label_aliases=None, mdc_store=None, comm=None, mem_limit=None)¶
Computes the total (aggregate) chi^2 for a set of circuits.
The chi^2 test statistic obtained by summing up the contributions of a given set of circuits or all the circuits available in a dataset. For the gradient or Hessian, see the :function:`chi2_jacobian` and :function:`chi2_hessian` functions.
 Parameters
model (Model) – The model used to specify the probabilities and SPAM labels
dataset (DataSet) – The data used to specify frequencies and counts
circuits (list of Circuits or tuples, optional) – List of circuits whose terms will be included in chi^2 sum. Default value (None) means “all strings in dataset”.
min_prob_clip_for_weighting (float, optional) – defines the clipping interval for the statistical weight.
prob_clip_interval (tuple, optional) – A (min, max) tuple that specifies the minium (possibly negative) and maximum values allowed for probabilities generated by the model. If the model gives probabilities outside this range they are clipped to min or max. These values can be quite generous, as the optimizers are quite tolerant of badly behaved probabilities.
op_label_aliases (dictionary, optional) – Dictionary whose keys are operation label “aliases” and whose values are tuples corresponding to what that operation label should be expanded into before querying the dataset. Defaults to the empty dictionary (no aliases defined) e.g. op_label_aliases[‘Gx^3’] = (‘Gx’,’Gx’,’Gx’)
mdc_store (ModelDatasetCircuitsStore, optional) – An object that bundles cached quantities along with a given model, dataset, and circuit list. If given, model and dataset and circuits should be set to None.
comm (mpi4py.MPI.Comm, optional) – When not None, an MPI communicator for distributing the computation across multiple processors.
mem_limit (int, optional) – A rough memory limit in bytes which restricts the amount of intermediate values that are computed and stored.
 Returns
chi2 (float) – chi^2 value, equal to the sum of chi^2 terms from all specified circuits
 pygsti.tools.chi2fns.chi2_per_circuit(model, dataset, circuits=None, min_prob_clip_for_weighting=0.0001, prob_clip_interval=( 10000, 10000), op_label_aliases=None, mdc_store=None, comm=None, mem_limit=None)¶
Computes the percircuit chi^2 contributions for a set of cirucits.
This function returns the same value as
chi2()
except the contributions from different circuits are not summed but returned as an array (the contributions of all the outcomes of a given cirucit are summed together). Parameters
model (Model) – The model used to specify the probabilities and SPAM labels
dataset (DataSet) – The data used to specify frequencies and counts
circuits (list of Circuits or tuples, optional) – List of circuits whose terms will be included in chi^2 sum. Default value (None) means “all strings in dataset”.
min_prob_clip_for_weighting (float, optional) – defines the clipping interval for the statistical weight.
prob_clip_interval (tuple, optional) – A (min, max) tuple that specifies the minium (possibly negative) and maximum values allowed for probabilities generated by the model. If the model gives probabilities outside this range they are clipped to min or max. These values can be quite generous, as the optimizers are quite tolerant of badly behaved probabilities.
op_label_aliases (dictionary, optional) – Dictionary whose keys are operation label “aliases” and whose values are tuples corresponding to what that operation label should be expanded into before querying the dataset. Defaults to the empty dictionary (no aliases defined) e.g. op_label_aliases[‘Gx^3’] = (‘Gx’,’Gx’,’Gx’)
mdc_store (ModelDatasetCircuitsStore, optional) – An object that bundles cached quantities along with a given model, dataset, and circuit list. If given, model and dataset and circuits should be set to None.
comm (mpi4py.MPI.Comm, optional) – When not None, an MPI communicator for distributing the computation across multiple processors.
mem_limit (int, optional) – A rough memory limit in bytes which restricts the amount of intermediate values that are computed and stored.
 Returns
chi2 (numpy.ndarray) – Array of length either len(circuits) or len(dataset.keys()). Values are the chi2 contributions of the corresponding circuit aggregated over outcomes.
 pygsti.tools.chi2fns.chi2_jacobian(model, dataset, circuits=None, min_prob_clip_for_weighting=0.0001, prob_clip_interval=( 10000, 10000), op_label_aliases=None, mdc_store=None, comm=None, mem_limit=None)¶
Compute the gradient of the chi^2 function computed by :function:`chi2`.
The returned value holds the derivatives of the chi^2 function with respect to model’s parameters.
 Parameters
model (Model) – The model used to specify the probabilities and SPAM labels
dataset (DataSet) – The data used to specify frequencies and counts
circuits (list of Circuits or tuples, optional) – List of circuits whose terms will be included in chi^2 sum. Default value (None) means “all strings in dataset”.
min_prob_clip_for_weighting (float, optional) – defines the clipping interval for the statistical weight.
prob_clip_interval (tuple, optional) – A (min, max) tuple that specifies the minium (possibly negative) and maximum values allowed for probabilities generated by the model. If the model gives probabilities outside this range they are clipped to min or max. These values can be quite generous, as the optimizers are quite tolerant of badly behaved probabilities.
op_label_aliases (dictionary, optional) – Dictionary whose keys are operation label “aliases” and whose values are tuples corresponding to what that operation label should be expanded into before querying the dataset. Defaults to the empty dictionary (no aliases defined) e.g. op_label_aliases[‘Gx^3’] = (‘Gx’,’Gx’,’Gx’)
mdc_store (ModelDatasetCircuitsStore, optional) – An object that bundles cached quantities along with a given model, dataset, and circuit list. If given, model and dataset and circuits should be set to None.
comm (mpi4py.MPI.Comm, optional) – When not None, an MPI communicator for distributing the computation across multiple processors.
mem_limit (int, optional) – A rough memory limit in bytes which restricts the amount of intermediate values that are computed and stored.
 Returns
numpy array – The gradient vector of length model.num_params, the number of model parameters.
 pygsti.tools.chi2fns.chi2_hessian(model, dataset, circuits=None, min_prob_clip_for_weighting=0.0001, prob_clip_interval=( 10000, 10000), op_label_aliases=None, mdc_store=None, comm=None, mem_limit=None)¶
Compute the Hessian matrix of the
chi2()
function. Parameters
model (Model) – The model used to specify the probabilities and SPAM labels
dataset (DataSet) – The data used to specify frequencies and counts
circuits (list of Circuits or tuples, optional) – List of circuits whose terms will be included in chi^2 sum. Default value (None) means “all strings in dataset”.
min_prob_clip_for_weighting (float, optional) – defines the clipping interval for the statistical weight.
prob_clip_interval (tuple, optional) – A (min, max) tuple that specifies the minium (possibly negative) and maximum values allowed for probabilities generated by the model. If the model gives probabilities outside this range they are clipped to min or max. These values can be quite generous, as the optimizers are quite tolerant of badly behaved probabilities.
op_label_aliases (dictionary, optional) – Dictionary whose keys are operation label “aliases” and whose values are tuples corresponding to what that operation label should be expanded into before querying the dataset. Defaults to the empty dictionary (no aliases defined) e.g. op_label_aliases[‘Gx^3’] = (‘Gx’,’Gx’,’Gx’)
mdc_store (ModelDatasetCircuitsStore, optional) – An object that bundles cached quantities along with a given model, dataset, and circuit list. If given, model and dataset and circuits should be set to None.
comm (mpi4py.MPI.Comm, optional) – When not None, an MPI communicator for distributing the computation across multiple processors.
mem_limit (int, optional) – A rough memory limit in bytes which restricts the amount of intermediate values that are computed and stored.
 Returns
numpy array – The Hessian matrix of shape (nModelParams, nModelParams), where nModelParams = model.num_params.
 pygsti.tools.chi2fns.chi2_approximate_hessian(model, dataset, circuits=None, min_prob_clip_for_weighting=0.0001, prob_clip_interval=( 10000, 10000), op_label_aliases=None, mdc_store=None, comm=None, mem_limit=None)¶
Compute and approximate Hessian matrix of the
chi2()
function.This approximation neglects terms proportional to the Hessian of the probabilities w.r.t. the model parameters (which can take a long time to compute). See logl_approximate_hessian for details on the analogous approximation for the loglikelihood Hessian.
 Parameters
model (Model) – The model used to specify the probabilities and SPAM labels
dataset (DataSet) – The data used to specify frequencies and counts
circuits (list of Circuits or tuples, optional) – List of circuits whose terms will be included in chi^2 sum. Default value (None) means “all strings in dataset”.
min_prob_clip_for_weighting (float, optional) – defines the clipping interval for the statistical weight.
prob_clip_interval (tuple, optional) – A (min, max) tuple that specifies the minium (possibly negative) and maximum values allowed for probabilities generated by the model. If the model gives probabilities outside this range they are clipped to min or max. These values can be quite generous, as the optimizers are quite tolerant of badly behaved probabilities.
op_label_aliases (dictionary, optional) – Dictionary whose keys are operation label “aliases” and whose values are tuples corresponding to what that operation label should be expanded into before querying the dataset. Defaults to the empty dictionary (no aliases defined) e.g. op_label_aliases[‘Gx^3’] = (‘Gx’,’Gx’,’Gx’)
mdc_store (ModelDatasetCircuitsStore, optional) – An object that bundles cached quantities along with a given model, dataset, and circuit list. If given, model and dataset and circuits should be set to None.
comm (mpi4py.MPI.Comm, optional) – When not None, an MPI communicator for distributing the computation across multiple processors.
mem_limit (int, optional) – A rough memory limit in bytes which restricts the amount of intermediate values that are computed and stored.
 Returns
numpy array – The Hessian matrix of shape (nModelParams, nModelParams), where nModelParams = model.num_params.
 pygsti.tools.chi2fns.chialpha(alpha, model, dataset, circuits=None, pfratio_stitchpt=0.01, pfratio_derivpt=0.01, prob_clip_interval=( 10000, 10000), radius=None, op_label_aliases=None, mdc_store=None, comm=None, mem_limit=None)¶
Compute the chialpha objective function.
 Parameters
alpha (float) – The alpha parameter, which lies in the interval (0,1].
model (Model) – The model used to specify the probabilities and SPAM labels
dataset (DataSet) – The data used to specify frequencies and counts
circuits (list of Circuits or tuples, optional) – List of circuits whose terms will be included in chialpha sum. Default value (None) means “all strings in dataset”.
pfratio_stitchpt (float, optional) – The xvalue (x = probility/frequency ratio) below which the chialpha function is replaced with it secondorder Taylor expansion.
pfratio_derivpt (float, optional) – The xvalue at which the Taylor expansion derivatives are evaluated at.
prob_clip_interval (tuple, optional) – A (min, max) tuple that specifies the minium (possibly negative) and maximum values allowed for probabilities generated by model. If the model gives probabilities outside this range they are clipped to min or max. These values can be quite generous, as the optimizers are quite tolerant of badly behaved probabilities.
radius (float, optional) – If radius is not None then a “harsh” method of regularizing the zerofrequency terms (where the local function = N*p) is used. If radius is None, then fmin is used to handle the zerofrequency terms.
op_label_aliases (dictionary, optional) – Dictionary whose keys are operation label “aliases” and whose values are tuples corresponding to what that operation label should be expanded into before querying the dataset. Defaults to the empty dictionary (no aliases defined) e.g. op_label_aliases[‘Gx^3’] = (‘Gx’,’Gx’,’Gx’)
mdc_store (ModelDatasetCircuitsStore, optional) – An object that bundles cached quantities along with a given model, dataset, and circuit list. If given, model and dataset and circuits should be set to None.
comm (mpi4py.MPI.Comm, optional) – When not None, an MPI communicator for distributing the computation across multiple processors.
mem_limit (int, optional) – A rough memory limit in bytes which restricts the amount of intermediate values that are computed and stored.
 Returns
float
 pygsti.tools.chi2fns.chialpha_per_circuit(alpha, model, dataset, circuits=None, pfratio_stitchpt=0.01, pfratio_derivpt=0.01, prob_clip_interval=( 10000, 10000), radius=None, op_label_aliases=None, mdc_store=None, comm=None, mem_limit=None)¶
Compute the percircuit chialpha objective function.
 Parameters
alpha (float) – The alpha parameter, which lies in the interval (0,1].
model (Model) – The model used to specify the probabilities and SPAM labels
dataset (DataSet) – The data used to specify frequencies and counts
circuits (list of Circuits or tuples, optional) – List of circuits whose terms will be included in chialpha sum. Default value (None) means “all strings in dataset”.
pfratio_stitchpt (float, optional) – The xvalue (x = probility/frequency ratio) below which the chialpha function is replaced with it secondorder Taylor expansion.
pfratio_derivpt (float, optional) – The xvalue at which the Taylor expansion derivatives are evaluated at.
prob_clip_interval (tuple, optional) – A (min, max) tuple that specifies the minium (possibly negative) and maximum values allowed for probabilities generated by model. If the model gives probabilities outside this range they are clipped to min or max. These values can be quite generous, as the optimizers are quite tolerant of badly behaved probabilities.
radius (float, optional) – If radius is not None then a “harsh” method of regularizing the zerofrequency terms (where the local function = N*p) is used. If radius is None, then fmin is used to handle the zerofrequency terms.
op_label_aliases (dictionary, optional) – Dictionary whose keys are operation label “aliases” and whose values are tuples corresponding to what that operation label should be expanded into before querying the dataset. Defaults to the empty dictionary (no aliases defined) e.g. op_label_aliases[‘Gx^3’] = (‘Gx’,’Gx’,’Gx’)
mdc_store (ModelDatasetCircuitsStore, optional) – An object that bundles cached quantities along with a given model, dataset, and circuit list. If given, model and dataset and circuits should be set to None.
comm (mpi4py.MPI.Comm, optional) – When not None, an MPI communicator for distributing the computation across multiple processors.
mem_limit (int, optional) – A rough memory limit in bytes which restricts the amount of intermediate values that are computed and stored.
 Returns
numpy.ndarray – Array of length either len(circuits) or len(dataset.keys()). Values are the chialpha contributions of the corresponding circuit aggregated over outcomes.
 pygsti.tools.chi2fns.chi2fn_2outcome(n, p, f, min_prob_clip_for_weighting=0.0001)¶
Computes chi^2 for a 2outcome measurement.
The chisquared function for a 2outcome measurement using a clipped probability for the statistical weighting.
 Parameters
n (float or numpy array) – Number of samples.
p (float or numpy array) – Probability of 1st outcome (typically computed).
f (float or numpy array) – Frequency of 1st outcome (typically observed).
min_prob_clip_for_weighting (float, optional) – Defines clipping interval (see return value).
 Returns
float or numpy array – n(pf)^2 / (cp(1cp)), where cp is the value of p clipped to the interval (min_prob_clip_for_weighting, 1min_prob_clip_for_weighting)
 pygsti.tools.chi2fns.chi2fn_2outcome_wfreqs(n, p, f)¶
Computes chi^2 for a 2outcome measurement using frequencyweighting.
The chisquared function for a 2outcome measurement using the observed frequency in the statistical weight.
 Parameters
n (float or numpy array) – Number of samples.
p (float or numpy array) – Probability of 1st outcome (typically computed).
f (float or numpy array) – Frequency of 1st outcome (typically observed).
 Returns
float or numpy array – n(pf)^2 / (f*(1f*)), where f* = (f*n+1)/n+2 is the frequency value used in the statistical weighting (prevents divide by zero errors)
 pygsti.tools.chi2fns.chi2fn(n, p, f, min_prob_clip_for_weighting=0.0001)¶
Computes the chi^2 term corresponding to a single outcome.
The chisquared term for a single outcome of a multioutcome measurement using a clipped probability for the statistical weighting.
 Parameters
n (float or numpy array) – Number of samples.
p (float or numpy array) – Probability of 1st outcome (typically computed).
f (float or numpy array) – Frequency of 1st outcome (typically observed).
min_prob_clip_for_weighting (float, optional) – Defines clipping interval (see return value).
 Returns
float or numpy array – n(pf)^2 / cp , where cp is the value of p clipped to the interval (min_prob_clip_for_weighting, 1min_prob_clip_for_weighting)
 pygsti.tools.chi2fns.chi2fn_wfreqs(n, p, f, min_freq_clip_for_weighting=0.0001)¶
Computes the frequencyweighed chi^2 term corresponding to a single outcome.
The chisquared term for a single outcome of a multioutcome measurement using the observed frequency in the statistical weight.
 Parameters
n (float or numpy array) – Number of samples.
p (float or numpy array) – Probability of 1st outcome (typically computed).
f (float or numpy array) – Frequency of 1st outcome (typically observed).
min_freq_clip_for_weighting (float, optional) – The minimum frequency weighting used in the weighting, i.e. the largest weighting factor is 1 / fmin_freq_clip_for_weighting.
 Returns
float or numpy array