# `pygsti.tools.chi2fns`

Chi-squared and related functions

## Module Contents

### Functions

 `chi2`(model, dataset[, circuits, ...]) Computes the total (aggregate) chi^2 for a set of circuits. `chi2_per_circuit`(model, dataset[, circuits, ...]) Computes the per-circuit chi^2 contributions for a set of cirucits. `chi2_jacobian`(model, dataset[, circuits, ...]) Compute the gradient of the chi^2 function computed by `chi2()`. `chi2_hessian`(model, dataset[, circuits, ...]) Compute the Hessian matrix of the `chi2()` function. `chi2_approximate_hessian`(model, dataset[, circuits, ...]) Compute and approximate Hessian matrix of the `chi2()` function. `chialpha`(alpha, model, dataset[, circuits, ...]) Compute the chi-alpha objective function. `chialpha_per_circuit`(alpha, model, dataset[, ...]) Compute the per-circuit chi-alpha objective function. `chi2fn_2outcome`(n, p, f[, min_prob_clip_for_weighting]) Computes chi^2 for a 2-outcome measurement. `chi2fn_2outcome_wfreqs`(n, p, f) Computes chi^2 for a 2-outcome measurement using frequency-weighting. `chi2fn`(n, p, f[, min_prob_clip_for_weighting]) Computes the chi^2 term corresponding to a single outcome. `chi2fn_wfreqs`(n, p, f[, min_freq_clip_for_weighting]) 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()` and `chi2_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.

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.

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