pygsti.tools.likelihoodfns
¶
Functions related to computation of the loglikelihood.
Module Contents¶
Functions¶

The loglikelihood function. 

Computes the percircuit loglikelihood contribution for a set of circuits. 

The jacobian of the loglikelihood function. 

The hessian of the loglikelihood function. 

An approximate Hessian of the loglikelihood function. 

The maximum loglikelihood possible for a DataSet. 

The vector of maximum loglikelihood contributions for each circuit, aggregated over outcomes. 

See docstring for :function:`pygsti.tools.two_delta_logl` 

Twice the difference between the maximum and actual loglikelihood. 

Twice the percircuit difference between the maximum and actual loglikelihood. 

Term of the 2*[log(L)upperbound  log(L)] sum corresponding to a single circuit and spam label. 
Attributes¶
 pygsti.tools.likelihoodfns.TOL = 1e20¶
 pygsti.tools.likelihoodfns.logl(model, dataset, circuits=None, min_prob_clip=1e06, prob_clip_interval=( 1000000.0, 1000000.0), radius=0.0001, poisson_picture=True, op_label_aliases=None, wildcard=None, mdc_store=None, comm=None, mem_limit=None)¶
The loglikelihood function.
 Parameters
model (Model) – Model of parameterized gates
dataset (DataSet) – Probability data
circuits (list of (tuples or Circuits), optional) – Each element specifies a circuit to include in the loglikelihood sum. Default value of None implies all the circuits in dataset should be used.
min_prob_clip (float, optional) – The minimum probability treated normally in the evaluation of the loglikelihood. A penalty function replaces the true loglikelihood for probabilities that lie below this threshold so that the loglikelihood never becomes undefined (which improves optimizer performance).
prob_clip_interval (2tuple or None, optional) – (min,max) values used to clip the probabilities predicted by models during MLEGST’s search for an optimal model (if not None). if None, no clipping is performed.
radius (float, optional) – Specifies the severity of rounding used to “patch” the zerofrequency terms of the loglikelihood.
poisson_picture (boolean, optional) – Whether the loglikelihoodinthePoissonpicture terms should be included in the returned logl value.
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’)
wildcard (WildcardBudget) – A wildcard budget to apply to this loglikelihood computation. This increases the returned loglikelihood value by adjusting (by a maximal amount measured in TVD, given by the budget) the probabilities produced by model to optimially match the data (within the bugetary constraints) evaluating the loglikelihood.
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 – The log likelihood
 pygsti.tools.likelihoodfns.logl_per_circuit(model, dataset, circuits=None, min_prob_clip=1e06, prob_clip_interval=( 1000000.0, 1000000.0), radius=0.0001, poisson_picture=True, op_label_aliases=None, wildcard=None, mdc_store=None, comm=None, mem_limit=None)¶
Computes the percircuit loglikelihood contribution for a set of circuits.
 Parameters
model (Model) – Model of parameterized gates
dataset (DataSet) – Probability data
circuits (list of (tuples or Circuits), optional) – Each element specifies a circuit to include in the loglikelihood sum. Default value of None implies all the circuits in dataset should be used.
min_prob_clip (float, optional) – The minimum probability treated normally in the evaluation of the loglikelihood. A penalty function replaces the true loglikelihood for probabilities that lie below this threshold so that the loglikelihood never becomes undefined (which improves optimizer performance).
prob_clip_interval (2tuple or None, optional) – (min,max) values used to clip the probabilities predicted by models during MLEGST’s search for an optimal model (if not None). if None, no clipping is performed.
radius (float, optional) – Specifies the severity of rounding used to “patch” the zerofrequency terms of the loglikelihood.
poisson_picture (boolean, optional) – Whether the loglikelihoodinthePoissonpicture terms should be included in the returned logl value.
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’)
wildcard (WildcardBudget) – A wildcard budget to apply to this loglikelihood computation. This increases the returned loglikelihood value by adjusting (by a maximal amount measured in TVD, given by the budget) the probabilities produced by model to optimially match the data (within the bugetary constraints) evaluating the loglikelihood.
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 loglikelihood contributions of the corresponding circuit aggregated over outcomes.
 pygsti.tools.likelihoodfns.logl_jacobian(model, dataset, circuits=None, min_prob_clip=1e06, prob_clip_interval=( 1000000.0, 1000000.0), radius=0.0001, poisson_picture=True, op_label_aliases=None, mdc_store=None, comm=None, mem_limit=None, verbosity=0)¶
The jacobian of the loglikelihood function.
 Parameters
model (Model) – Model of parameterized gates (including SPAM)
dataset (DataSet) – Probability data
circuits (list of (tuples or Circuits), optional) – Each element specifies a circuit to include in the loglikelihood sum. Default value of None implies all the circuits in dataset should be used.
min_prob_clip (float, optional) – The minimum probability treated normally in the evaluation of the loglikelihood. A penalty function replaces the true loglikelihood for probabilities that lie below this threshold so that the loglikelihood never becomes undefined (which improves optimizer performance).
prob_clip_interval (2tuple or None, optional) – (min,max) values used to clip the probabilities predicted by models during MLEGST’s search for an optimal model (if not None). if None, no clipping is performed.
radius (float, optional) – Specifies the severity of rounding used to “patch” the zerofrequency terms of the loglikelihood.
poisson_picture (boolean, optional) – Whether the Poissonpicutre loglikelihood should be differentiated.
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.
verbosity (int, optional) – How much detail to print to stdout.
 Returns
numpy array – array of shape (M,), where M is the length of the vectorized model.
 pygsti.tools.likelihoodfns.logl_hessian(model, dataset, circuits=None, min_prob_clip=1e06, prob_clip_interval=( 1000000.0, 1000000.0), radius=0.0001, poisson_picture=True, op_label_aliases=None, mdc_store=None, comm=None, mem_limit=None, verbosity=0)¶
The hessian of the loglikelihood function.
 Parameters
model (Model) – Model of parameterized gates (including SPAM)
dataset (DataSet) – Probability data
circuits (list of (tuples or Circuits), optional) – Each element specifies a circuit to include in the loglikelihood sum. Default value of None implies all the circuits in dataset should be used.
min_prob_clip (float, optional) – The minimum probability treated normally in the evaluation of the loglikelihood. A penalty function replaces the true loglikelihood for probabilities that lie below this threshold so that the loglikelihood never becomes undefined (which improves optimizer performance).
prob_clip_interval (2tuple or None, optional) – (min,max) values used to clip the probabilities predicted by models during MLEGST’s search for an optimal model (if not None). if None, no clipping is performed.
radius (float, optional) – Specifies the severity of rounding used to “patch” the zerofrequency terms of the loglikelihood.
poisson_picture (boolean, optional) – Whether the Poissonpicutre loglikelihood should be differentiated.
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.
verbosity (int, optional) – How much detail to print to stdout.
 Returns
numpy array – array of shape (M,M), where M is the length of the vectorized model.
 pygsti.tools.likelihoodfns.logl_approximate_hessian(model, dataset, circuits=None, min_prob_clip=1e06, prob_clip_interval=( 1000000.0, 1000000.0), radius=0.0001, poisson_picture=True, op_label_aliases=None, mdc_store=None, comm=None, mem_limit=None, verbosity=0)¶
An approximate Hessian of the loglikelihood function.
An approximation to the true Hessian is computed using just the Jacobian (and not the Hessian) of the probabilities w.r.t. the model parameters. Let J = d(probs)/d(params) and denote the Hessian of the loglikelihood w.r.t. the probabilities as d2(logl)/dprobs2 (a diagonal matrix indexed by the term, i.e. probability, of the loglikelihood). Then this function computes:
H = J * d2(logl)/dprobs2 * J.T
Which simply neglects the d2(probs)/d(params)2 terms of the true Hessian. Since this curvature is expected to be small at the MLE point, this approximation can be useful for computing approximate error bars.
 Parameters
model (Model) – Model of parameterized gates (including SPAM)
dataset (DataSet) – Probability data
circuits (list of (tuples or Circuits), optional) – Each element specifies a circuit to include in the loglikelihood sum. Default value of None implies all the circuits in dataset should be used.
min_prob_clip (float, optional) – The minimum probability treated normally in the evaluation of the loglikelihood. A penalty function replaces the true loglikelihood for probabilities that lie below this threshold so that the loglikelihood never becomes undefined (which improves optimizer performance).
prob_clip_interval (2tuple or None, optional) – (min,max) values used to clip the probabilities predicted by models during MLEGST’s search for an optimal model (if not None). if None, no clipping is performed.
radius (float, optional) – Specifies the severity of rounding used to “patch” the zerofrequency terms of the loglikelihood.
poisson_picture (boolean, optional) – Whether the Poissonpicutre loglikelihood should be differentiated.
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.
verbosity (int, optional) – How much detail to print to stdout.
 Returns
numpy array – array of shape (M,M), where M is the length of the vectorized model.
 pygsti.tools.likelihoodfns.logl_max(model, dataset, circuits=None, poisson_picture=True, op_label_aliases=None, mdc_store=None)¶
The maximum loglikelihood possible for a DataSet.
That is, the loglikelihood obtained by a maximal model that can fit perfectly the probability of each circuit.
 Parameters
model (Model) – the model, used only for circuit compilation
dataset (DataSet) – the data set to use.
circuits (list of (tuples or Circuits), optional) – Each element specifies a circuit to include in the maxloglikelihood sum. Default value of None implies all the circuits in dataset should be used.
poisson_picture (boolean, optional) – Whether the Poissonpicture maximum loglikelihood should be returned.
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.
 Returns
float
 pygsti.tools.likelihoodfns.logl_max_per_circuit(model, dataset, circuits=None, poisson_picture=True, op_label_aliases=None, mdc_store=None)¶
The vector of maximum loglikelihood contributions for each circuit, aggregated over outcomes.
 Parameters
model (Model) – the model, used only for circuit compilation
dataset (DataSet) – the data set to use.
circuits (list of (tuples or Circuits), optional) – Each element specifies a circuit to include in the maxloglikelihood sum. Default value of None implies all the circuits in dataset should be used.
poisson_picture (boolean, optional) – Whether the Poissonpicture maximum loglikelihood should be returned.
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.
 Returns
numpy.ndarray – Array of length either len(circuits) or len(dataset.keys()). Values are the maximum loglikelihood contributions of the corresponding circuit aggregated over outcomes.
 pygsti.tools.likelihoodfns.two_delta_logl_nsigma(model, dataset, circuits=None, min_prob_clip=1e06, prob_clip_interval=( 1000000.0, 1000000.0), radius=0.0001, poisson_picture=True, op_label_aliases=None, dof_calc_method='modeltest', wildcard=None)¶
See docstring for :function:`pygsti.tools.two_delta_logl`
 Parameters
model (Model) – Model of parameterized gates
dataset (DataSet) – Probability data
circuits (list of (tuples or Circuits), optional) – Each element specifies a circuit to include in the loglikelihood sum. Default value of None implies all the circuits in dataset should be used.
min_prob_clip (float, optional) – The minimum probability treated normally in the evaluation of the loglikelihood. A penalty function replaces the true loglikelihood for probabilities that lie below this threshold so that the loglikelihood never becomes undefined (which improves optimizer performance).
prob_clip_interval (2tuple or None, optional) – (min,max) values used to clip the probabilities predicted by models during MLEGST’s search for an optimal model (if not None). if None, no clipping is performed.
radius (float, optional) – Specifies the severity of rounding used to “patch” the zerofrequency terms of the loglikelihood.
poisson_picture (boolean, optional) – Whether the loglikelihoodinthePoissonpicture terms should be included in the returned logl value.
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’)
dof_calc_method ({"all", "modeltest"}) – How model’s number of degrees of freedom (parameters) are obtained when computing the number of standard deviations and pvalue relative to a chi2_k distribution, where k is additional degrees of freedom possessed by the maximal model. “all” uses model.num_params whereas “modeltest” uses model.num_modeltest_params (the number of nongauge parameters by default).
wildcard (WildcardBudget) – A wildcard budget to apply to this loglikelihood computation. This increases the returned loglikelihood value by adjusting (by a maximal amount measured in TVD, given by the budget) the probabilities produced by model to optimially match the data (within the bugetary constraints) evaluating the loglikelihood.
 Returns
float
 pygsti.tools.likelihoodfns.two_delta_logl(model, dataset, circuits=None, min_prob_clip=1e06, prob_clip_interval=( 1000000.0, 1000000.0), radius=0.0001, poisson_picture=True, op_label_aliases=None, dof_calc_method=None, wildcard=None, mdc_store=None, comm=None)¶
Twice the difference between the maximum and actual loglikelihood.
Optionally also can return the Nsigma (# std deviations from mean) and pvalue relative to expected chi^2 distribution (when dof_calc_method is not None).
This function’s arguments are supersets of :function:`logl`, and :function:`logl_max`. This is a convenience function, equivalent to 2*(logl_max(…)  logl(…)), whose value is what is often called the loglikelihoodratio between the “maximal model” (that which trivially fits the data exactly) and the model given by model.
 Parameters
model (Model) – Model of parameterized gates
dataset (DataSet) – Probability data
circuits (list of (tuples or Circuits), optional) – Each element specifies a circuit to include in the loglikelihood sum. Default value of None implies all the circuits in dataset should be used.
min_prob_clip (float, optional) – The minimum probability treated normally in the evaluation of the loglikelihood. A penalty function replaces the true loglikelihood for probabilities that lie below this threshold so that the loglikelihood never becomes undefined (which improves optimizer performance).
prob_clip_interval (2tuple or None, optional) – (min,max) values used to clip the probabilities predicted by models during MLEGST’s search for an optimal model (if not None). if None, no clipping is performed.
radius (float, optional) – Specifies the severity of rounding used to “patch” the zerofrequency terms of the loglikelihood.
poisson_picture (boolean, optional) – Whether the loglikelihoodinthePoissonpicture terms should be included in the computed loglikelihood values.
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’)
dof_calc_method ({None, "all", "modeltest"}) – How model’s number of degrees of freedom (parameters) are obtained when computing the number of standard deviations and pvalue relative to a chi2_k distribution, where k is additional degrees of freedom possessed by the maximal model. If None, then Nsigma and pvalue are not returned (see below).
wildcard (WildcardBudget) – A wildcard budget to apply to this loglikelihood computation. This increases the returned loglikelihood value by adjusting (by a maximal amount measured in TVD, given by the budget) the probabilities produced by model to optimially match the data (within the bugetary constraints) evaluating the loglikelihood.
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.
 Returns
twoDeltaLogL (float) – 2*(loglikelihood(maximal_model,data)  loglikelihood(model,data))
Nsigma, pvalue (float) – Only returned when dof_calc_method is not None.
 pygsti.tools.likelihoodfns.two_delta_logl_per_circuit(model, dataset, circuits=None, min_prob_clip=1e06, prob_clip_interval=( 1000000.0, 1000000.0), radius=0.0001, poisson_picture=True, op_label_aliases=None, dof_calc_method=None, wildcard=None, mdc_store=None, comm=None)¶
Twice the percircuit difference between the maximum and actual loglikelihood.
Contributions are aggregated over each circuit’s outcomes, but no further.
Optionally (when dof_calc_method is not None) returns parallel vectors containing the Nsigma (# std deviations from mean) and the pvalue relative to expected chi^2 distribution for each sequence.
 Parameters
model (Model) – Model of parameterized gates
dataset (DataSet) – Probability data
circuits (list of (tuples or Circuits), optional) – Each element specifies a circuit to include in the loglikelihood sum. Default value of None implies all the circuits in dataset should be used.
min_prob_clip (float, optional) – The minimum probability treated normally in the evaluation of the loglikelihood. A penalty function replaces the true loglikelihood for probabilities that lie below this threshold so that the loglikelihood never becomes undefined (which improves optimizer performance).
prob_clip_interval (2tuple or None, optional) – (min,max) values used to clip the probabilities predicted by models during MLEGST’s search for an optimal model (if not None). if None, no clipping is performed.
radius (float, optional) – Specifies the severity of rounding used to “patch” the zerofrequency terms of the loglikelihood.
poisson_picture (boolean, optional) – Whether the loglikelihoodinthePoissonpicture terms should be included in the returned logl value.
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’)
dof_calc_method ({"all", "modeltest"}) – How model’s number of degrees of freedom (parameters) are obtained when computing the number of standard deviations and pvalue relative to a chi2_k distribution, where k is additional degrees of freedom possessed by the maximal model.
wildcard (WildcardBudget) – A wildcard budget to apply to this loglikelihood computation. This increases the returned loglikelihood value by adjusting (by a maximal amount measured in TVD, given by the budget) the probabilities produced by model to optimially match the data (within the bugetary constraints) evaluating the loglikelihood.
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.
 Returns
twoDeltaLogL_terms (numpy.ndarray)
Nsigma, pvalue (numpy.ndarray) – Only returned when dof_calc_method is not None.
 pygsti.tools.likelihoodfns.two_delta_logl_term(n, p, f, min_prob_clip=1e06, poisson_picture=True)¶
Term of the 2*[log(L)upperbound  log(L)] sum corresponding to a single circuit and spam label.
 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 (float, optional) – Minimum probability clip point to avoid evaluating log(number <= zero)
poisson_picture (boolean, optional) – Whether the loglikelihoodinthePoissonpicture terms should be included in the returned logl value.
 Returns
float or numpy array