pygsti.tools.chi2fns
Chi-squared and related functions
Module Contents
Functions
|
Computes the total (aggregate) chi^2 for a set of circuits. |
|
Computes the per-circuit chi^2 contributions for a set of cirucits. |
|
Compute the gradient of the chi^2 function computed by |
|
Compute the Hessian matrix of the |
|
Compute and approximate Hessian matrix of the |
|
Compute the chi-alpha objective function. |
|
Compute the per-circuit chi-alpha objective function. |
|
Computes chi^2 for a 2-outcome measurement. |
|
Computes chi^2 for a 2-outcome measurement using frequency-weighting. |
|
Computes the chi^2 term corresponding to a single outcome. |
|
Computes the frequency-weighed 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
chi2_jacobian()andchi2_hessian()functions.Parameters
- modelModel
The model used to specify the probabilities and SPAM labels
- datasetDataSet
The data used to specify frequencies and counts
- circuitslist 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_weightingfloat, optional
defines the clipping interval for the statistical weight.
- prob_clip_intervaltuple, 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_aliasesdictionary, 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_storeModelDatasetCircuitsStore, 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.
- commmpi4py.MPI.Comm, optional
When not None, an MPI communicator for distributing the computation across multiple processors.
- mem_limitint, optional
A rough memory limit in bytes which restricts the amount of intermediate values that are computed and stored.
Returns
- chi2float
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 per-circuit 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
- modelModel
The model used to specify the probabilities and SPAM labels
- datasetDataSet
The data used to specify frequencies and counts
- circuitslist 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_weightingfloat, optional
defines the clipping interval for the statistical weight.
- prob_clip_intervaltuple, 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_aliasesdictionary, 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_storeModelDatasetCircuitsStore, 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.
- commmpi4py.MPI.Comm, optional
When not None, an MPI communicator for distributing the computation across multiple processors.
- mem_limitint, optional
A rough memory limit in bytes which restricts the amount of intermediate values that are computed and stored.
Returns
- chi2numpy.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
chi2().The returned value holds the derivatives of the chi^2 function with respect to model’s parameters.
Parameters
- modelModel
The model used to specify the probabilities and SPAM labels
- datasetDataSet
The data used to specify frequencies and counts
- circuitslist 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_weightingfloat, optional
defines the clipping interval for the statistical weight.
- prob_clip_intervaltuple, 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_aliasesdictionary, 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_storeModelDatasetCircuitsStore, 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.
- commmpi4py.MPI.Comm, optional
When not None, an MPI communicator for distributing the computation across multiple processors.
- mem_limitint, 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
- modelModel
The model used to specify the probabilities and SPAM labels
- datasetDataSet
The data used to specify frequencies and counts
- circuitslist 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_weightingfloat, optional
defines the clipping interval for the statistical weight.
- prob_clip_intervaltuple, 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_aliasesdictionary, 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_storeModelDatasetCircuitsStore, 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.
- commmpi4py.MPI.Comm, optional
When not None, an MPI communicator for distributing the computation across multiple processors.
- mem_limitint, optional
A rough memory limit in bytes which restricts the amount of intermediate values that are computed and stored.
Returns
- numpy array or None
On the root processor, the Hessian matrix of shape (nModelParams, nModelParams), where nModelParams = model.num_params. None on non-root processors.
- 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 log-likelihood Hessian.
Parameters
- modelModel
The model used to specify the probabilities and SPAM labels
- datasetDataSet
The data used to specify frequencies and counts
- circuitslist 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_weightingfloat, optional
defines the clipping interval for the statistical weight.
- prob_clip_intervaltuple, 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_aliasesdictionary, 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_storeModelDatasetCircuitsStore, 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.
- commmpi4py.MPI.Comm, optional
When not None, an MPI communicator for distributing the computation across multiple processors.
- mem_limitint, optional
A rough memory limit in bytes which restricts the amount of intermediate values that are computed and stored.
Returns
- numpy array or None
On the root processor, the approximate Hessian matrix of shape (nModelParams, nModelParams), where nModelParams = model.num_params. None on non-root processors.
- 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 chi-alpha objective function.
Parameters
- alphafloat
The alpha parameter, which lies in the interval (0,1].
- modelModel
The model used to specify the probabilities and SPAM labels
- datasetDataSet
The data used to specify frequencies and counts
- circuitslist of Circuits or tuples, optional
List of circuits whose terms will be included in chi-alpha sum. Default value (None) means “all strings in dataset”.
- pfratio_stitchptfloat, optional
The x-value (x = probility/frequency ratio) below which the chi-alpha function is replaced with it second-order Taylor expansion.
- pfratio_derivptfloat, optional
The x-value at which the Taylor expansion derivatives are evaluated at.
- prob_clip_intervaltuple, 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.
- radiusfloat, optional
If radius is not None then a “harsh” method of regularizing the zero-frequency terms (where the local function = N*p) is used. If radius is None, then fmin is used to handle the zero-frequency terms.
- op_label_aliasesdictionary, 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_storeModelDatasetCircuitsStore, 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.
- commmpi4py.MPI.Comm, optional
When not None, an MPI communicator for distributing the computation across multiple processors.
- mem_limitint, 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 per-circuit chi-alpha objective function.
Parameters
- alphafloat
The alpha parameter, which lies in the interval (0,1].
- modelModel
The model used to specify the probabilities and SPAM labels
- datasetDataSet
The data used to specify frequencies and counts
- circuitslist of Circuits or tuples, optional
List of circuits whose terms will be included in chi-alpha sum. Default value (None) means “all strings in dataset”.
- pfratio_stitchptfloat, optional
The x-value (x = probility/frequency ratio) below which the chi-alpha function is replaced with it second-order Taylor expansion.
- pfratio_derivptfloat, optional
The x-value at which the Taylor expansion derivatives are evaluated at.
- prob_clip_intervaltuple, 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.
- radiusfloat, optional
If radius is not None then a “harsh” method of regularizing the zero-frequency terms (where the local function = N*p) is used. If radius is None, then fmin is used to handle the zero-frequency terms.
- op_label_aliasesdictionary, 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_storeModelDatasetCircuitsStore, 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.
- commmpi4py.MPI.Comm, optional
When not None, an MPI communicator for distributing the computation across multiple processors.
- mem_limitint, 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 chi-alpha 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 2-outcome measurement.
The chi-squared function for a 2-outcome measurement using a clipped probability for the statistical weighting.
Parameters
- nfloat or numpy array
Number of samples.
- pfloat or numpy array
Probability of 1st outcome (typically computed).
- ffloat or numpy array
Frequency of 1st outcome (typically observed).
- min_prob_clip_for_weightingfloat, optional
Defines clipping interval (see return value).
Returns
- float or numpy array
n(p-f)^2 / (cp(1-cp)), where cp is the value of p clipped to the interval (min_prob_clip_for_weighting, 1-min_prob_clip_for_weighting)
- pygsti.tools.chi2fns.chi2fn_2outcome_wfreqs(n, p, f)
Computes chi^2 for a 2-outcome measurement using frequency-weighting.
The chi-squared function for a 2-outcome measurement using the observed frequency in the statistical weight.
Parameters
- nfloat or numpy array
Number of samples.
- pfloat or numpy array
Probability of 1st outcome (typically computed).
- ffloat or numpy array
Frequency of 1st outcome (typically observed).
Returns
- float or numpy array
n(p-f)^2 / (f*(1-f*)), 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 chi-squared term for a single outcome of a multi-outcome measurement using a clipped probability for the statistical weighting.
Parameters
- nfloat or numpy array
Number of samples.
- pfloat or numpy array
Probability of 1st outcome (typically computed).
- ffloat or numpy array
Frequency of 1st outcome (typically observed).
- min_prob_clip_for_weightingfloat, optional
Defines clipping interval (see return value).
Returns
- float or numpy array
n(p-f)^2 / cp , where cp is the value of p clipped to the interval (min_prob_clip_for_weighting, 1-min_prob_clip_for_weighting)
- pygsti.tools.chi2fns.chi2fn_wfreqs(n, p, f, min_freq_clip_for_weighting=0.0001)
Computes the frequency-weighed chi^2 term corresponding to a single outcome.
The chi-squared term for a single outcome of a multi-outcome measurement using the observed frequency in the statistical weight.
Parameters
- nfloat or numpy array
Number of samples.
- pfloat or numpy array
Probability of 1st outcome (typically computed).
- ffloat or numpy array
Frequency of 1st outcome (typically observed).
- min_freq_clip_for_weightingfloat, 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