pygsti.objectivefns.objectivefns
¶
Defines objectivefunction objects
Module Contents¶
Classes¶
A factory class for building objective functions. 

So far, this is just a base class for organizational purposes 

An objective function that acts on probabilities and counts directly. 

Contains all the information that we'd like to persist when performing 

Additionally holds quantities at a specific modelparameterspace point. 

An objective function whose probabilities and counts are given by a Model and DataSet, respectively. 

The function N(pf)^2 / p 

The function N[x + 1/(alpha * x^alpha)  (1 + 1/alpha)] where x := p/f. 

The function N(pf)^2 / f 

The function N*f*log(f/p)  N*(fp). 

The function N*f*log(f/p). 

The function N*f*log(f) (note this doesn't depend on the probability!). 

The function 0.5 * pf. 

A timeindependent modelbased ( 

Modelbased chisquared function: N(pf)^2 / p 

Modelbased chialpha function: N[x + 1/(alpha * x^alpha)  (1 + 1/alpha)] where x := p/f. 

Modelbased frequencyweighted chisquared function: N(pf)^2 / f 

Modelbased poissonpicture delta loglikelihood function: N*f*log(f/p)  N*(fp). 

Modelbased delta loglikelihood function: N*f*log(f/p). 

Modelbased maximummodel loglikelihood function: N*f*log(f) 

Modelbased TVD function: 0.5 * pf. 

A timedependent modelbased objective function 

Chisquared function that can handle timedependent circuits and data. 

Poissonpicture delta loglikelihood function that can handle timedependent circuits and data. 

A wildcardbudget bolton to an existing objective function. 

Holds various values of an objective function at a particular point. 
Functions¶

A convenience function for creating an objective function. 





Helper function  CPTP penalty: (sum of tracenorms of gates), 

Helper function  CPTP penalty: (sum of tracenorms of gates), 

Helper function  errorgen penalty: sum_i errorgen_coeff_i 

Helper function  jacobian of CPTP penalty (sum of tracenorms of gates) 

Helper function  jacobian of CPTP penalty (sum of tracenorms of gates) 

 pygsti.objectivefns.objectivefns._objfn(objfn_cls, model, dataset, circuits=None, regularization=None, penalties=None, op_label_aliases=None, comm=None, mem_limit=None, method_names=None, array_types=None, mdc_store=None, verbosity=0, **addl_args)¶
A convenience function for creating an objective function.
Takes a number of common parameters and automates the creation of intermediate objects like a
ResourceAllocation
andCircuitList
. Parameters
objfn_cls (class) – The
MDCObjectiveFunction
derived class to create.model (Model) – The model.
dataset (DataSet) – The data.
circuits (list, optional) – The circuits.
regularization (dict, optional) – A dictionary of regularization values.
penalties (dict, optional) – A dictionary of penalty values.
op_label_aliases (dict, optional) – An alias dictionary.
comm (mpi4py.MPI.Comm, optional) – For splitting load among processors.
mem_limit (int, optional) – Rough memory limit in bytes.
method_names (tuple) – A tuple of the method names of the returned objective function that will be called (used to estimate memory and setup resource division)
array_types (tuple) – A tuple of array types that will be allocated, in addition to those contained in the returned objective functon itself and within the methods given by method_names.
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.
verbosity (int or VerbosityPrinter, optional) – Amount of information printed to stdout.
 Returns
ObjectiveFunction
 class pygsti.objectivefns.objectivefns.ObjectiveFunctionBuilder(cls_to_build, name=None, description=None, regularization=None, penalties=None, **kwargs)¶
Bases:
pygsti.baseobjs.nicelyserializable.NicelySerializable
A factory class for building objective functions.
This is useful because often times the user will want to specify some but not all of the information needed to create an actual objective function object. Namely, regularization and penalty values are known ahead of time, while the model, dataset, and circuits are supplied later, internally, when running a protocol.
 Parameters
cls_to_build (class) – The
MDCObjectiveFunction
derived objective function class to build.name (str, optional) – A name for the built objective function (can be anything).
description (str, optional) – A description for the built objective function (can be anything)
regularization (dict, optional) – Regularization values (allowed keys depend on cls_to_build).
penalties (dict, optional) – Penalty values (allowed keys depend on cls_to_build).
 classmethod cast(cls, obj)¶
Cast obj to an ObjectiveFunctionBuilder instance.
If obj is already an ObjectiveFunctionBuilder instance, it is simply returned. Otherwise a new ObjectiveFunctionBuilder instance is created from obj if possible.
 Parameters
obj (None or str or dict or list or tuple or ObjectiveFunctionBuilder) – Object to cast.
 Returns
ObjectiveFunctionBuilder
 classmethod create_from(cls, objective='logl', freq_weighted_chi2=False)¶
Creates common :class:`ObjectiveFunctionBuilder`s from a few arguments.
 Parameters
objective ({'logl', 'chi2'}, optional) – The objective function type: loglikelihood or chisquared.
freq_weighted_chi2 (bool, optional) – Whether to use 1/frequency values as the weights in the “chi2” case.
 Returns
ObjectiveFunctionBuilder
 _to_nice_serialization(self)¶
 classmethod _from_nice_serialization(cls, state)¶
 compute_array_types(self, method_names, forwardsim)¶
 build(self, model, dataset, circuits, resource_alloc=None, verbosity=0)¶
Build an objective function. This is the workhorse method of an
ObjectiveFunctionBuilder
.Arguments are the additional information needed to construct a
MDCObjectiveFunction
object, beyond what is stored in this builder object. Parameters
model (Model) – The model.
dataset (DataSet.) – The data set.
circuits (list) – The circuits.
resource_alloc (ResourceAllocation, optional) – Available resources and how they should be allocated for objective function computations.
verbosity (int, optional) – Level of detail to print to stdout.
 Returns
MDCObjectiveFunction
 build_from_store(self, mdc_store, verbosity=0)¶
Build an objective function. This is a workhorse method of an
ObjectiveFunctionBuilder
.Takes a single “store” argument (apart from verbosity) that encapsulates all the remaining ingredients needed to build a
MDCObjectiveFunction
object (beyond what is stored in this builder object). Parameters
mdc_store (ModelDatasetCircuitsStore) – The store object, which doubles as a cache for reused information.
verbosity (int, optional) – Level of detail to print to stdout.
 Returns
MDCObjectiveFunction
 class pygsti.objectivefns.objectivefns.ObjectiveFunction¶
Bases:
object
So far, this is just a base class for organizational purposes
 chi2k_distributed_qty(self, objective_function_value)¶
Convert a value of this objective function to one that is expected to be chi2_k distributed.
For instance, if the objective function is DeltaLogL then this function would multiply objective_function_value by 2, whereas in the case of a chisquared objective function this function just return objective_function_value.
 Parameters
objective_function_value (float) – A value of this objective function, i.e. one returned from self.fn(…).
 Returns
float
 class pygsti.objectivefns.objectivefns.RawObjectiveFunction(regularization=None, resource_alloc=None, name=None, description=None, verbosity=0)¶
Bases:
ObjectiveFunction
An objective function that acts on probabilities and counts directly.
Every
RawObjectiveFunction
is assumed to perform a “local” function elementwise on the vectors of probabilities, counts (usually for a single outcome), and totalcounts (usually for all the outcomes in a group), and sum the results to arrive at the final objective function’s value.That is, the function must be of the form: objective_function = sum_i local_function(probability_i, counts_i, total_counts_i).
Each element of this sum (local_function(probability_i, counts_i, total_counts_i)) is called a term of the objective function. A vector contains the squareroots of the terms is referred to as the leastsquares vector (since leastsquares optimizers use this vector as their objective function) and is abbreviated “lsvec”.
 Parameters
regularization (dict, optional) – Regularization values.
resource_alloc (ResourceAllocation, optional) – Available resources and how they should be allocated for computations.
name (str, optional) – A name for this objective function (can be anything).
description (str, optional) – A description for this objective function (can be anything)
verbosity (int, optional) – Level of detail to print to stdout.
 set_regularization(self)¶
Set regularization values.
 _intermediates(self, probs, counts, total_counts, freqs)¶
Intermediate values used by multiple functions (similar to a temporary cache)
 fn(self, probs, counts, total_counts, freqs)¶
Evaluate the objective function.
 Parameters
probs (numpy.ndarray) – Array of probability values.
counts (numpy.ndarray) – Array of count values.
total_counts (numpy.ndarray) – Array of total count values.
freqs (numpy.ndarray) – Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
 Returns
float
 jacobian(self, probs, counts, total_counts, freqs)¶
Evaluate the derivative of the objective function with respect to the probabilities.
 Parameters
probs (numpy.ndarray) – Array of probability values.
counts (numpy.ndarray) – Array of count values.
total_counts (numpy.ndarray) – Array of total count values.
freqs (numpy.ndarray) – Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
 Returns
numpy.ndarray – A 1D array of length equal to that of each argument, corresponding to the derivative with respect to each element of probs.
 hessian(self, probs, counts, total_counts, freqs)¶
Evaluate the Hessian of the objective function with respect to the probabilities.
 Parameters
probs (numpy.ndarray) – Array of probability values.
counts (numpy.ndarray) – Array of count values.
total_counts (numpy.ndarray) – Array of total count values.
freqs (numpy.ndarray) – Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
 Returns
numpy.ndarray – A 1D array of length equal to that of each argument, corresponding to the 2nd derivative with respect to each element of probs. Note that this is not a 2D matrix because all offdiagonal elements of the Hessian are zero (because only the ith term depends on the ith probability).
 terms(self, probs, counts, total_counts, freqs, intermediates=None)¶
Compute the terms of the objective function.
The “terms” are the per(probability, count, totalcount) values that get summed together to result in the objective function value. These are the “local” or “perelement” values of the objective function.
 Parameters
probs (numpy.ndarray) – Array of probability values.
counts (numpy.ndarray) – Array of count values.
total_counts (numpy.ndarray) – Array of total count values.
freqs (numpy.ndarray) – Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
intermediates (tuple, optional) – Used internally to speed up computations.
 Returns
numpy.ndarray – A 1D array of length equal to that of each array argument.
 lsvec(self, probs, counts, total_counts, freqs, intermediates=None)¶
Compute the leastsquares vector of the objective function.
This is the squareroot of the termsvector returned from :method:`terms`. This vector is the objective function value used by a leastsquares optimizer when optimizing this objective function. Note that the existence of this quantity requires that the terms be nonnegative. If this is not the case, an error is raised.
 Parameters
probs (numpy.ndarray) – Array of probability values.
counts (numpy.ndarray) – Array of count values.
total_counts (numpy.ndarray) – Array of total count values.
freqs (numpy.ndarray) – Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
intermediates (tuple, optional) – Used internally to speed up computations.
 Returns
numpy.ndarray – A 1D array of length equal to that of each array argument.
 dterms(self, probs, counts, total_counts, freqs, intermediates=None)¶
Compute the derivatives of the terms of this objective function.
Note that because each term only depends on the corresponding probability, this is just an elementwise derivative (or, the diagonal of a jacobian matrix), i.e. the resulting values are the derivatives of the local_function at each (probability, count, totalcount) value.
 Parameters
probs (numpy.ndarray) – Array of probability values.
counts (numpy.ndarray) – Array of count values.
total_counts (numpy.ndarray) – Array of total count values.
freqs (numpy.ndarray) – Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
intermediates (tuple, optional) – Used internally to speed up computations.
 Returns
numpy.ndarray – A 1D array of length equal to that of each array argument.
 dlsvec(self, probs, counts, total_counts, freqs, intermediates=None)¶
Compute the derivatives of the leastsquares vector of this objective function.
Note that because each lsvec element only depends on the corresponding probability, this is just an elementwise derivative (or, the diagonal of a jacobian matrix), i.e. the resulting values are the derivatives of the local_function at each (probability, count, totalcount) value.
 Parameters
probs (numpy.ndarray) – Array of probability values.
counts (numpy.ndarray) – Array of count values.
total_counts (numpy.ndarray) – Array of total count values.
freqs (numpy.ndarray) – Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
intermediates (tuple, optional) – Used internally to speed up computations.
 Returns
numpy.ndarray – A 1D array of length equal to that of each array argument.
 dlsvec_and_lsvec(self, probs, counts, total_counts, freqs, intermediates=None)¶
Compute the derivatives of the leastsquares vector together with the vector itself.
This is sometimes more computationally efficient than calling :method:`dlsvec` and :method:`lsvec` separately, as the former call may require computing the latter.
 Parameters
probs (numpy.ndarray) – Array of probability values.
counts (numpy.ndarray) – Array of count values.
total_counts (numpy.ndarray) – Array of total count values.
freqs (numpy.ndarray) – Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
intermediates (tuple, optional) – Used internally to speed up computations.
 Returns
dlsvec (numpy.ndarray) – A 1D array of length equal to that of each array argument.
lsvec (numpy.ndarray) – A 1D array of length equal to that of each array argument.
 hterms(self, probs, counts, total_counts, freqs, intermediates=None)¶
Compute the 2nd derivatives of the terms of this objective function.
Note that because each term only depends on the corresponding probability, this is just an elementwise 2nd derivative, i.e. the resulting values are the 2ndderivatives of the local_function at each (probability, count, totalcount) value.
 Parameters
probs (numpy.ndarray) – Array of probability values.
counts (numpy.ndarray) – Array of count values.
total_counts (numpy.ndarray) – Array of total count values.
freqs (numpy.ndarray) – Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
intermediates (tuple, optional) – Used internally to speed up computations.
 Returns
numpy.ndarray – A 1D array of length equal to that of each array argument.
 hlsvec(self, probs, counts, total_counts, freqs, intermediates=None)¶
Compute the 2nd derivatives of the leastsquares vector of this objective function.
Note that because each lsvec element only depends on the corresponding probability, this is just an elementwise 2nd derivative, i.e. the resulting values are the 2ndderivatives of sqrt(local_function) at each (probability, count, totalcount) value.
 Parameters
probs (numpy.ndarray) – Array of probability values.
counts (numpy.ndarray) – Array of count values.
total_counts (numpy.ndarray) – Array of total count values.
freqs (numpy.ndarray) – Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
intermediates (tuple, optional) – Used internally to speed up computations.
 Returns
numpy.ndarray – A 1D array of length equal to that of each array argument.
 abstract zero_freq_terms(self, total_counts, probs)¶
Evaluate objective function terms with zero frequency (where count and frequency are zero).
Such terms are treated specially because, for some objective functions, having zero frequency is a special case and must be handled differently.
 Parameters
total_counts (numpy.ndarray) – The total counts.
probs (numpy.ndarray) – The probabilities.
 Returns
numpy.ndarray – A 1D array of the same length as total_counts and probs.
 abstract zero_freq_dterms(self, total_counts, probs)¶
Evaluate the derivative of zerofrequency objective function terms.
Zero frequency terms are treated specially because, for some objective functions, these are a special case and must be handled differently. Derivatives are evaluated elementwise, i.e. the ith element of the returned array is the derivative of the ith term with respect to the ith probability (derivatives with respect to all other probabilities are zero because of the function structure).
 Parameters
total_counts (numpy.ndarray) – The total counts.
probs (numpy.ndarray) – The probabilities.
 Returns
numpy.ndarray – A 1D array of the same length as total_counts and probs.
 abstract zero_freq_hterms(self, total_counts, probs)¶
Evaluate the 2nd derivative of zerofrequency objective function terms.
Zero frequency terms are treated specially because, for some objective functions, these are a special case and must be handled differently. Derivatives are evaluated elementwise, i.e. the ith element of the returned array is the 2nd derivative of the ith term with respect to the ith probability (derivatives with respect to all other probabilities are zero because of the function structure).
 Parameters
total_counts (numpy.ndarray) – The total counts.
probs (numpy.ndarray) – The probabilities.
 Returns
numpy.ndarray – A 1D array of the same length as total_counts and probs.
 class pygsti.objectivefns.objectivefns.ModelDatasetCircuitsStore(model, dataset, circuits=None, resource_alloc=None, array_types=(), precomp_layout=None, verbosity=0)¶
Bases:
object
Contains all the information that we’d like to persist when performing (multiple) evaluations of the same circuits using the same model and data set. For instance, the evaluation of mubltiple (different) objective functions.
This class holds only quantities that do not depend on the contained model’s parameters. See
EvaluatedObjectiveFunction
for a class (TODO??) that holds the values of an objective function at a certain parameterspace point. property opBasis(self)¶
 num_data_params(self)¶
The number of degrees of freedom in the data used by this objective function.
 Returns
int
 add_omitted_freqs(self, printer=None, force=False)¶
Detect omitted frequences (assumed to be 0) so we can compute objective fn correctly
 add_count_vectors(self, force=False)¶
Ensure this store contains count and totalcount vectors.
 class pygsti.objectivefns.objectivefns.EvaluatedModelDatasetCircuitsStore(mdc_store, verbosity)¶
Bases:
ModelDatasetCircuitsStore
Additionally holds quantities at a specific modelparameterspace point.
 class pygsti.objectivefns.objectivefns.MDCObjectiveFunction(raw_objfn, mdc_store, verbosity=0)¶
Bases:
ObjectiveFunction
,EvaluatedModelDatasetCircuitsStore
An objective function whose probabilities and counts are given by a Model and DataSet, respectively.
Instances of this class glue a model, dataset, and circuit list to a “raw” objective function, resulting in an objective function that is a function of modelparameters and contains counts based on a data set.
The model is treated as a function that computes probabilities (as a function of the model’s parameters) for each circuit outcome, and the data set as a function that similarly computes counts (and totalcounts).
 Parameters
raw_objfn (RawObjectiveFunction) – The raw objective function  specifies how probability and count values are turned into objective function values.
mdl (Model) – The model  specifies how parameter values are turned into probabilities for each circuit outcome.
dataset (DataSet) – The data set  specifies how counts and total_counts are obtained for each circuit outcome.
circuits (list or CircuitList) – The circuit list  specifies what probabilities and counts this objective function compares. If None, then the keys of dataset are used.
enable_hessian (bool, optional) – Whether hessian calculations are allowed. If True then more resources are needed. If False, calls to hessianrequiring function will result in an error.
 name¶
The name of this objective function.
 Type
str
 description¶
A description of this objective function.
 Type
str
 classmethod create_from(cls, raw_objfn, model, dataset, circuits, resource_alloc=None, verbosity=0, array_types=())¶
 classmethod _array_types_for_method(cls, method_name, fsim)¶
 property name(self)¶
Name of this objective function.
 property description(self)¶
A description of this objective function.
 chi2k_distributed_qty(self, objective_function_value)¶
Convert a value of this objective function to one that is expected to be chi2_k distributed.
For instance, if the objective function is DeltaLogL then this function would multiply objective_function_value by 2, whereas in the case of a chisquared objective function this function just return objective_function_value.
 Parameters
objective_function_value (float) – A value of this objective function, i.e. one returned from self.fn(…).
 Returns
float
 abstract lsvec(self, paramvec=None, oob_check=False)¶
Compute the leastsquares vector of the objective function.
This is the squareroot of the termsvector returned from :method:`terms`. This vector is the objective function value used by a leastsquares optimizer when optimizing this objective function. Note that the existence of this quantity requires that the terms be nonnegative. If this is not the case, an error is raised.
 Parameters
paramvec (numpy.ndarray, optional) – The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).
oob_check (bool, optional) – Whether the objective function should raise an error if it is being evaluated in an “out of bounds” region.
 Returns
numpy.ndarray – An array of shape (nElements,) where nElements is the number of circuit outcomes.
 abstract dlsvec(self, paramvec=None)¶
The derivative (jacobian) of the leastsquares vector.
Derivatives are taken with respect to model parameters.
 Parameters
paramvec (numpy.ndarray, optional) – The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).
 Returns
numpy.ndarray – An array of shape (nElements,nParams) where nElements is the number of circuit outcomes and nParams is the number of model parameters.
 terms(self, paramvec=None)¶
Compute the terms of the objective function.
The “terms” are the percircuitoutcome values that get summed together to result in the objective function value.
 Parameters
paramvec (numpy.ndarray, optional) – The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).
 Returns
numpy.ndarray – An array of shape (nElements,) where nElements is the number of circuit outcomes.
 dterms(self, paramvec=None)¶
Compute the jacobian of the terms of the objective function.
The “terms” are the percircuitoutcome values that get summed together to result in the objective function value. Differentiation is with respect to model parameters.
 Parameters
paramvec (numpy.ndarray, optional) – The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).
 Returns
numpy.ndarray – An array of shape (nElements,nParams) where nElements is the number of circuit outcomes and nParams is the number of model parameters.
 percircuit(self, paramvec=None)¶
Compute the percircuit contributions to this objective function.
These values collect (sum) together the contributions of the outcomes of a single circuit.
 Parameters
paramvec (numpy.ndarray, optional) – The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).
 Returns
numpy.ndarray – An array of shape (nCircuits,) where nCircuits is the number of circuits (specified when this objective function was constructed).
 dpercircuit(self, paramvec=None)¶
Compute the jacobian of the percircuit contributions of this objective function.
 Parameters
paramvec (numpy.ndarray, optional) – The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).
 Returns
numpy.ndarray – An array of shape (nCircuits, nParams) where nCircuits is the number of circuits and nParams is the number of model parameters (the circuits and model were specified when this objective function was constructed).
 fn_local(self, paramvec=None)¶
Evaluate the local value of this objective function.
When the objective function’s layout is distributed, each processor only holds a portion of the objective function terms, and this function returns only the sum of these local terms. See :method:`fn` for the global objective function value.
 Parameters
paramvec (numpy.ndarray, optional) – The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).
 Returns
float
 fn(self, paramvec=None)¶
Evaluate the value of this objective function.
 Parameters
paramvec (numpy.ndarray, optional) – The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).
 Returns
float
 jacobian(self, paramvec=None)¶
Compute the Jacobian of this objective function.
Derivatives are takes with respect to model parameters.
 Parameters
paramvec (numpy.ndarray, optional) – The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).
 Returns
numpy.ndarray – An array of shape (nParams,) where nParams is the number of model parameters.
 abstract hessian(self, paramvec=None)¶
Compute the Hessian of this objective function.
Derivatives are takes with respect to model parameters.
 Parameters
paramvec (numpy.ndarray, optional) – The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).
 Returns
numpy.ndarray – An array of shape (nParams, nParams) where nParams is the number of model parameters.
 abstract approximate_hessian(self, paramvec=None)¶
Compute an approximate Hessian of this objective function.
This is typically much less expensive than :method:`hessian` and does not require that enable_hessian=True was set upon initialization. It computes an approximation to the Hessian that only utilizes the information in the Jacobian. Derivatives are takes with respect to model parameters.
 Parameters
paramvec (numpy.ndarray, optional) – The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).
 Returns
numpy.ndarray – An array of shape (nParams, nParams) where nParams is the number of model parameters.
 _construct_hessian(self, counts, total_counts, prob_clip_interval)¶
Framework for constructing a hessian matrix row by row using a derived class’s _hessian_from_hprobs method. This function expects that this objective function has been setup for hessian computation, and it’s evaltree may be split in order to facilitate this.
 abstract _hessian_from_block(self, hprobs, dprobs12, probs, counts, total_counts, freqs, resource_alloc)¶
 _gather_hessian(self, local_hessian)¶
 class pygsti.objectivefns.objectivefns.RawChi2Function(regularization=None, resource_alloc=None, name='chi2', description='Sum of Chi^2', verbosity=0)¶
Bases:
RawObjectiveFunction
The function N(pf)^2 / p
Note that this equals Nf (1x)^2 / x where x := p/f.
 Parameters
regularization (dict, optional) – Regularization values.
resource_alloc (ResourceAllocation, optional) – Available resources and how they should be allocated for computations.
name (str, optional) – A name for this objective function (can be anything).
description (str, optional) – A description for this objective function (can be anything)
verbosity (int, optional) – Level of detail to print to stdout.
 chi2k_distributed_qty(self, objective_function_value)¶
Convert a value of this objective function to one that is expected to be chi2_k distributed.
 Parameters
objective_function_value (float) – A value of this objective function, i.e. one returned from self.fn(…).
 Returns
float
 set_regularization(self, min_prob_clip_for_weighting=0.0001)¶
Set regularization values.
 Parameters
min_prob_clip_for_weighting (float, optional) – Cutoff for probability prob in 1 / prob weighting factor (the maximum of prob and min_prob_clip_for_weighting is used in the denominator).
 Returns
None
 lsvec(self, probs, counts, total_counts, freqs, intermediates=None)¶
Compute the leastsquares vector of the objective function.
This is the squareroot of the termsvector returned from :method:`terms`. This vector is the objective function value used by a leastsquares optimizer when optimizing this objective function. Note that the existence of this quantity requires that the terms be nonnegative. If this is not the case, an error is raised.
 Parameters
probs (numpy.ndarray) – Array of probability values.
counts (numpy.ndarray) – Array of count values.
total_counts (numpy.ndarray) – Array of total count values.
freqs (numpy.ndarray) – Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
intermediates (tuple, optional) – Used internally to speed up computations.
 Returns
numpy.ndarray – A 1D array of length equal to that of each array argument.
 dlsvec(self, probs, counts, total_counts, freqs, intermediates=None)¶
Compute the derivatives of the leastsquares vector of this objective function.
Note that because each lsvec element only depends on the corresponding probability, this is just an elementwise derivative (or, the diagonal of a jacobian matrix), i.e. the resulting values are the derivatives of the local_function at each (probability, count, totalcount) value.
 Parameters
probs (numpy.ndarray) – Array of probability values.
counts (numpy.ndarray) – Array of count values.
total_counts (numpy.ndarray) – Array of total count values.
freqs (numpy.ndarray) – Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
intermediates (tuple, optional) – Used internally to speed up computations.
 Returns
numpy.ndarray – A 1D array of length equal to that of each array argument.
 hlsvec(self, probs, counts, total_counts, freqs, intermediates=None)¶
Compute the 2nd derivatives of the leastsquares vector of this objective function.
Note that because each lsvec element only depends on the corresponding probability, this is just an elementwise 2nd derivative, i.e. the resulting values are the 2ndderivatives of sqrt(local_function) at each (probability, count, totalcount) value.
 Parameters
probs (numpy.ndarray) – Array of probability values.
counts (numpy.ndarray) – Array of count values.
total_counts (numpy.ndarray) – Array of total count values.
freqs (numpy.ndarray) – Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
intermediates (tuple, optional) – Used internally to speed up computations.
 Returns
numpy.ndarray – A 1D array of length equal to that of each array argument.
 hterms_alt(self, probs, counts, total_counts, freqs, intermediates=None)¶
Alternate computation of the 2nd derivatives of the terms of this objective function.
This should give exactly the same results as :method:`hterms`, but may be a little faster.
 Parameters
probs (numpy.ndarray) – Array of probability values.
counts (numpy.ndarray) – Array of count values.
total_counts (numpy.ndarray) – Array of total count values.
freqs (numpy.ndarray) – Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
intermediates (tuple, optional) – Used internally to speed up computations.
 Returns
numpy.ndarray – A 1D array of length equal to that of each array argument.
 zero_freq_terms(self, total_counts, probs)¶
Evaluate objective function terms with zero frequency (where count and frequency are zero).
Such terms are treated specially because, for some objective functions, having zero frequency is a special case and must be handled differently.
 Parameters
total_counts (numpy.ndarray) – The total counts.
probs (numpy.ndarray) – The probabilities.
 Returns
numpy.ndarray – A 1D array of the same length as total_counts and probs.
 zero_freq_dterms(self, total_counts, probs)¶
Evaluate the derivative of zerofrequency objective function terms.
Zero frequency terms are treated specially because, for some objective functions, these are a special case and must be handled differently. Derivatives are evaluated elementwise, i.e. the ith element of the returned array is the derivative of the ith term with respect to the ith probability (derivatives with respect to all other probabilities are zero because of the function structure).
 Parameters
total_counts (numpy.ndarray) – The total counts.
probs (numpy.ndarray) – The probabilities.
 Returns
numpy.ndarray – A 1D array of the same length as total_counts and probs.
 zero_freq_hterms(self, total_counts, probs)¶
Evaluate the 2nd derivative of zerofrequency objective function terms.
Zero frequency terms are treated specially because, for some objective functions, these are a special case and must be handled differently. Derivatives are evaluated elementwise, i.e. the ith element of the returned array is the 2nd derivative of the ith term with respect to the ith probability (derivatives with respect to all other probabilities are zero because of the function structure).
 Parameters
total_counts (numpy.ndarray) – The total counts.
probs (numpy.ndarray) – The probabilities.
 Returns
numpy.ndarray – A 1D array of the same length as total_counts and probs.
 _weights(self, p, f, total_counts)¶
Get the chi2 weighting factor.
 Parameters
p (numpy.ndarray) – The probabilities.
f (numpy.ndarray) – The frequencies
total_counts (numpy.ndarray) – The total counts.
 Returns
numpy.ndarray
 _dweights(self, p, f, wts)¶
Get the derivative of the chi2 weighting factor.
 Parameters
p (numpy.ndarray) – The probabilities.
f (numpy.ndarray) – The frequencies
wts (numpy.ndarray) – The weights, as computed by :method:`_weights`.
 Returns
numpy.ndarray
 _hweights(self, p, f, wts)¶
Get the 2nd derivative of the chi2 weighting factor.
 Parameters
p (numpy.ndarray) – The probabilities.
f (numpy.ndarray) – The frequencies
wts (numpy.ndarray) – The weights, as computed by :method:`_weights`.
 Returns
numpy.ndarray
 class pygsti.objectivefns.objectivefns.RawChiAlphaFunction(regularization=None, resource_alloc=None, name='chialpha', description='Sum of ChiAlpha', verbosity=0, alpha=1)¶
Bases:
RawObjectiveFunction
The function N[x + 1/(alpha * x^alpha)  (1 + 1/alpha)] where x := p/f.
This function interpolates between the loglikelihood function (alpha=>0) and the chi2 function (alpha=1).
 Parameters
regularization (dict, optional) – Regularization values.
resource_alloc (ResourceAllocation, optional) – Available resources and how they should be allocated for computations.
name (str, optional) – A name for this objective function (can be anything).
description (str, optional) – A description for this objective function (can be anything)
verbosity (int, optional) – Level of detail to print to stdout.
alpha (float, optional) – The alpha parameter, which lies in the interval (0,1].
 chi2k_distributed_qty(self, objective_function_value)¶
Convert a value of this objective function to one that is expected to be chi2_k distributed.
 Parameters
objective_function_value (float) – A value of this objective function, i.e. one returned from self.fn(…).
 Returns
float
 set_regularization(self, pfratio_stitchpt=0.01, pfratio_derivpt=0.01, radius=None, fmin=None)¶
Set regularization values.
 Parameters
pfratio_stitchpt (float, optional) – The xvalue (x = probility/frequency ratio) below which the function is replaced with it secondorder Taylor expansion.
pfratio_derivpt (float, optional) – The xvalue at which the Taylor expansion derivatives are evaluated at. If this is the same as pfratio_stitchpt then the function is smooth to 2nd order at this point. However, choosing a larger value of pfratio_derivpt will make the stitched part of the function less steep, which is sometimes more helpful to an optimizer than having the stitchpoint be smooth.
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. Specifically, for p < radius we splice in the cubic polynomial, (1/3)*p^3/r^2 + p^2/r + (1/3)*r (where r == radius). This has the nice properties that 1) it matches the value, firstderivative, and second derivative of N*p at p=r and 2) it, like N*p has a minimum at p=0 with value 0. The radius dictates the amount of curvature or sharpness of this stitching function, with smaller values making the function more pointed. We recommend making this value smaller than the smallest expected frequencies, so as not to alter the objective function in regions we near the ML point. If radius is None, then fmin is used to handle the zerofrequency terms.
fmin (float, optional) – The minimum expected frequency. When radius is None a “relaxed” regularization of the zerofrequency terms is used that stitches the quadratic N * C * p^2 to N*p when p < 1/C, with C = 1/(2 fmin) * (1 + alpha) / pfratio_derivpt^(2 + alpha). This matches the value of the stitch and N*p at p=1/C but not the derivative, but makes up for this by being less steep  the value of C is chosen so that the derivative (steepness) of the zerofrequency terms at the stitch point is similar to the regular nonzerofrequency terms at their stitch points.
 Returns
None
 _intermediates(self, probs, counts, total_counts, freqs)¶
Intermediate values used by both terms(…) and dterms(…)
 terms(self, probs, counts, total_counts, freqs, intermediates=None)¶
Compute the terms of the objective function.
The “terms” are the per(probability, count, totalcount) values that get summed together to result in the objective function value. These are the “local” or “perelement” values of the objective function.
 Parameters
probs (numpy.ndarray) – Array of probability values.
counts (numpy.ndarray) – Array of count values.
total_counts (numpy.ndarray) – Array of total count values.
freqs (numpy.ndarray) – Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
intermediates (tuple, optional) – Used internally to speed up computations.
 Returns
numpy.ndarray – A 1D array of length equal to that of each array argument.
 dterms(self, probs, counts, total_counts, freqs, intermediates=None)¶
Compute the derivatives of the terms of this objective function.
Note that because each term only depends on the corresponding probability, this is just an elementwise derivative (or, the diagonal of a jacobian matrix), i.e. the resulting values are the derivatives of the local_function at each (probability, count, totalcount) value.
 Parameters
probs (numpy.ndarray) – Array of probability values.
counts (numpy.ndarray) – Array of count values.
total_counts (numpy.ndarray) – Array of total count values.
freqs (numpy.ndarray) – Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
intermediates (tuple, optional) – Used internally to speed up computations.
 Returns
numpy.ndarray – A 1D array of length equal to that of each array argument.
 abstract hterms(self, probs, counts, total_counts, freqs, intermediates=None)¶
Compute the 2nd derivatives of the terms of this objective function.
Note that because each term only depends on the corresponding probability, this is just an elementwise 2nd derivative, i.e. the resulting values are the 2ndderivatives of the local_function at each (probability, count, totalcount) value.
 Parameters
probs (numpy.ndarray) – Array of probability values.
counts (numpy.ndarray) – Array of count values.
total_counts (numpy.ndarray) – Array of total count values.
freqs (numpy.ndarray) – Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
intermediates (tuple, optional) – Used internally to speed up computations.
 Returns
numpy.ndarray – A 1D array of length equal to that of each array argument.
 abstract hlsvec(self, probs, counts, total_counts, freqs)¶
Compute the 2nd derivatives of the leastsquares vector of this objective function.
Note that because each lsvec element only depends on the corresponding probability, this is just an elementwise 2nd derivative, i.e. the resulting values are the 2ndderivatives of sqrt(local_function) at each (probability, count, totalcount) value.
 Parameters
probs (numpy.ndarray) – Array of probability values.
counts (numpy.ndarray) – Array of count values.
total_counts (numpy.ndarray) – Array of total count values.
freqs (numpy.ndarray) – Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
intermediates (tuple, optional) – Used internally to speed up computations.
 Returns
numpy.ndarray – A 1D array of length equal to that of each array argument.
 _zero_freq_terms_harsh(self, total_counts, probs)¶
 _zero_freq_dterms_harsh(self, total_counts, probs)¶
 _zero_freq_terms_relaxed(self, total_counts, probs)¶
 _zero_freq_dterms_relaxed(self, total_counts, probs)¶
 class pygsti.objectivefns.objectivefns.RawFreqWeightedChi2Function(regularization=None, resource_alloc=None, name='fwchi2', description='Sum of freqweighted Chi^2', verbosity=0)¶
Bases:
RawChi2Function
The function N(pf)^2 / f
 Parameters
regularization (dict, optional) – Regularization values.
resource_alloc (ResourceAllocation, optional) – Available resources and how they should be allocated for computations.
name (str, optional) – A name for this objective function (can be anything).
description (str, optional) – A description for this objective function (can be anything)
verbosity (int, optional) – Level of detail to print to stdout.
 chi2k_distributed_qty(self, objective_function_value)¶
Convert a value of this objective function to one that is expected to be chi2_k distributed.
 Parameters
objective_function_value (float) – A value of this objective function, i.e. one returned from self.fn(…).
 Returns
float
 set_regularization(self, min_freq_clip_for_weighting=0.0001)¶
Set regularization values.
 Parameters
min_freq_clip_for_weighting (float, optional) – The minimum frequency that will be used in the 1/f weighting factor. That is, the weighting factor is the 1 / max(f, min_freq_clip_for_weighting).
 Returns
None
 _weights(self, p, f, total_counts)¶
Get the chi2 weighting factor.
 Parameters
p (numpy.ndarray) – The probabilities.
f (numpy.ndarray) – The frequencies
total_counts (numpy.ndarray) – The total counts.
 Returns
numpy.ndarray
 _dweights(self, p, f, wts)¶
Get the derivative of the chi2 weighting factor.
 Parameters
p (numpy.ndarray) – The probabilities.
f (numpy.ndarray) – The frequencies
wts (numpy.ndarray) – The weights, as computed by :method:`_weights`.
 Returns
numpy.ndarray
 _hweights(self, p, f, wts)¶
Get the 2nd derivative of the chi2 weighting factor.
 Parameters
p (numpy.ndarray) – The probabilities.
f (numpy.ndarray) – The frequencies
wts (numpy.ndarray) – The weights, as computed by :method:`_weights`.
 Returns
numpy.ndarray
 zero_freq_terms(self, total_counts, probs)¶
Evaluate objective function terms with zero frequency (where count and frequency are zero).
Such terms are treated specially because, for some objective functions, having zero frequency is a special case and must be handled differently.
 Parameters
total_counts (numpy.ndarray) – The total counts.
probs (numpy.ndarray) – The probabilities.
 Returns
numpy.ndarray – A 1D array of the same length as total_counts and probs.
 zero_freq_dterms(self, total_counts, probs)¶
Evaluate the derivative of zerofrequency objective function terms.
Zero frequency terms are treated specially because, for some objective functions, these are a special case and must be handled differently. Derivatives are evaluated elementwise, i.e. the ith element of the returned array is the derivative of the ith term with respect to the ith probability (derivatives with respect to all other probabilities are zero because of the function structure).
 Parameters
total_counts (numpy.ndarray) – The total counts.
probs (numpy.ndarray) – The probabilities.
 Returns
numpy.ndarray – A 1D array of the same length as total_counts and probs.
 zero_freq_hterms(self, total_counts, probs)¶
Evaluate the 2nd derivative of zerofrequency objective function terms.
Zero frequency terms are treated specially because, for some objective functions, these are a special case and must be handled differently. Derivatives are evaluated elementwise, i.e. the ith element of the returned array is the 2nd derivative of the ith term with respect to the ith probability (derivatives with respect to all other probabilities are zero because of the function structure).
 Parameters
total_counts (numpy.ndarray) – The total counts.
probs (numpy.ndarray) – The probabilities.
 Returns
numpy.ndarray – A 1D array of the same length as total_counts and probs.
 class pygsti.objectivefns.objectivefns.RawPoissonPicDeltaLogLFunction(regularization=None, resource_alloc=None, name='dlogl', description='2*Delta(log(L))', verbosity=0)¶
Bases:
RawObjectiveFunction
The function N*f*log(f/p)  N*(fp).
Note that this equals Nf(log(x)  1 + x) where x := p/f.
 Parameters
regularization (dict, optional) – Regularization values.
resource_alloc (ResourceAllocation, optional) – Available resources and how they should be allocated for computations.
name (str, optional) – A name for this objective function (can be anything).
description (str, optional) – A description for this objective function (can be anything)
verbosity (int, optional) – Level of detail to print to stdout.
 chi2k_distributed_qty(self, objective_function_value)¶
Convert a value of this objective function to one that is expected to be chi2_k distributed.
 Parameters
objective_function_value (float) – A value of this objective function, i.e. one returned from self.fn(…).
 Returns
float
 set_regularization(self, min_prob_clip=0.0001, pfratio_stitchpt=None, pfratio_derivpt=None, radius=0.0001, fmin=None)¶
Set regularization values.
 Parameters
min_prob_clip (float, optional) – The probability below which the objective function is replaced with its second order Taylor expansion. This must be None if pfratio_stitchpt is not None, this specifies an alternate stitching method where the stitchpoint is given in x=p/f units.
pfratio_stitchpt (float, optional) – The xvalue (x = probility/frequency ratio) below which the function is replaced with it second order Taylor expansion. Conflicts with min_prob_clip, which specifies an alternate stitching method.
pfratio_derivpt (float, optional) – Specified if and only if pfratio_stitchpt is. The xvalue at which the Taylor expansion derivatives are evaluated at. If this is the same as pfratio_stitchpt then the function is smooth to 2nd order at this point. However, choosing a larger value of pfratio_derivpt will make the stitched part of the function less steep, which is sometimes more helpful to an optimizer than having the stitchpoint be smooth.
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. Specifically, for p < radius we splice in the cubic polynomial, (1/3)*p^3/r^2 + p^2/r + (1/3)*r (where r == radius). This has the nice properties that 1) it matches the value, firstderivative, and second derivative of N*p at p=r and 2) it, like N*p has a minimum at p=0 with value 0. The radius dictates the amount of curvature or sharpness of this stitching function, with smaller values making the function more pointed. We recommend making this value smaller than the smallest expected frequencies, so as not to alter the objective function in regions we near the ML point. If radius is None, then fmin is used to handle the zerofrequency terms.
fmin (float, optional) – The minimum expected frequency. When radius is None a “relaxed” regularization of the zerofrequency terms is used that stitches the quadratic N * C * p^2 to N*p when p < 1/C, with C = 1/(2 fmin) * (1 + alpha) / pfratio_derivpt^(2 + alpha). This matches the value of the stitch and N*p at p=1/C but not the derivative, but makes up for this by being less steep  the value of C is chosen so that the derivative (steepness) of the zerofrequency terms at the stitch point is similar to the regular nonzerofrequency terms at their stitch points.
 Returns
None
 _intermediates(self, probs, counts, total_counts, freqs)¶
Intermediate values used by both terms(…) and dterms(…)
 terms(self, probs, counts, total_counts, freqs, intermediates=None)¶
Compute the terms of the objective function.
The “terms” are the per(probability, count, totalcount) values that get summed together to result in the objective function value. These are the “local” or “perelement” values of the objective function.
 Parameters
probs (numpy.ndarray) – Array of probability values.
counts (numpy.ndarray) – Array of count values.
total_counts (numpy.ndarray) – Array of total count values.
freqs (numpy.ndarray) – Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
intermediates (tuple, optional) – Used internally to speed up computations.
 Returns
numpy.ndarray – A 1D array of length equal to that of each array argument.
 lsvec(self, probs, counts, total_counts, freqs, intermediates=None)¶
Compute the leastsquares vector of the objective function.
This is the squareroot of the termsvector returned from :method:`terms`. This vector is the objective function value used by a leastsquares optimizer when optimizing this objective function. Note that the existence of this quantity requires that the terms be nonnegative. If this is not the case, an error is raised.
 Parameters
probs (numpy.ndarray) – Array of probability values.
counts (numpy.ndarray) – Array of count values.
total_counts (numpy.ndarray) – Array of total count values.
freqs (numpy.ndarray) – Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
intermediates (tuple, optional) – Used internally to speed up computations.
 Returns
numpy.ndarray – A 1D array of length equal to that of each array argument.
 dterms(self, probs, counts, total_counts, freqs, intermediates=None)¶
Compute the derivatives of the terms of this objective function.
Note that because each term only depends on the corresponding probability, this is just an elementwise derivative (or, the diagonal of a jacobian matrix), i.e. the resulting values are the derivatives of the local_function at each (probability, count, totalcount) value.
 Parameters
probs (numpy.ndarray) – Array of probability values.
counts (numpy.ndarray) – Array of count values.
total_counts (numpy.ndarray) – Array of total count values.
freqs (numpy.ndarray) – Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
intermediates (tuple, optional) – Used internally to speed up computations.
 Returns
numpy.ndarray – A 1D array of length equal to that of each array argument.
 hterms(self, probs, counts, total_counts, freqs, intermediates=None)¶
Compute the 2nd derivatives of the terms of this objective function.
Note that because each term only depends on the corresponding probability, this is just an elementwise 2nd derivative, i.e. the resulting values are the 2ndderivatives of the local_function at each (probability, count, totalcount) value.
 Parameters
probs (numpy.ndarray) – Array of probability values.
counts (numpy.ndarray) – Array of count values.
total_counts (numpy.ndarray) – Array of total count values.
freqs (numpy.ndarray) – Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
intermediates (tuple, optional) – Used internally to speed up computations.
 Returns
numpy.ndarray – A 1D array of length equal to that of each array argument.
 _zero_freq_terms_harsh(self, total_counts, probs)¶
 _zero_freq_dterms_harsh(self, total_counts, probs)¶
 _zero_freq_hterms_harsh(self, total_counts, probs)¶
 _zero_freq_terms_relaxed(self, total_counts, probs)¶
 _zero_freq_dterms_relaxed(self, total_counts, probs)¶
 abstract _zero_freq_hterms_relaxed(self, total_counts, probs)¶
 class pygsti.objectivefns.objectivefns.RawDeltaLogLFunction(regularization=None, resource_alloc=None, name='dlogl', description='2*Delta(log(L))', verbosity=0)¶
Bases:
RawObjectiveFunction
The function N*f*log(f/p).
Note that this equals Nf log(x) where x := p/f.
 Parameters
regularization (dict, optional) – Regularization values.
resource_alloc (ResourceAllocation, optional) – Available resources and how they should be allocated for computations.
name (str, optional) – A name for this objective function (can be anything).
description (str, optional) – A description for this objective function (can be anything)
verbosity (int, optional) – Level of detail to print to stdout.
 chi2k_distributed_qty(self, objective_function_value)¶
Convert a value of this objective function to one that is expected to be chi2_k distributed.
 Parameters
objective_function_value (float) – A value of this objective function, i.e. one returned from self.fn(…).
 Returns
float
 set_regularization(self, min_prob_clip=0.0001, pfratio_stitchpt=None, pfratio_derivpt=None)¶
Set regularization values.
 Parameters
min_prob_clip (float, optional) – The probability below which the objective function is replaced with its second order Taylor expansion. This must be None if pfratio_stitchpt is not None, this specifies an alternate stitching method where the stitchpoint is given in x=p/f units.
pfratio_stitchpt (float, optional) – The xvalue (x = probility/frequency ratio) below which the function is replaced with it second order Taylor expansion. Conflicts with min_prob_clip, which specifies an alternate stitching method.
pfratio_derivpt (float, optional) – Specified if and only if pfratio_stitchpt is. The xvalue at which the Taylor expansion derivatives are evaluated at. If this is the same as pfratio_stitchpt then the function is smooth to 2nd order at this point. However, choosing a larger value of pfratio_derivpt will make the stitched part of the function less steep, which is sometimes more helpful to an optimizer than having the stitchpoint be smooth.
 Returns
None
 _intermediates(self, probs, counts, total_counts, freqs)¶
Intermediate values used by both terms(…) and dterms(…)
 terms(self, probs, counts, total_counts, freqs, intermediates=None)¶
Compute the terms of the objective function.
The “terms” are the per(probability, count, totalcount) values that get summed together to result in the objective function value. These are the “local” or “perelement” values of the objective function.
 Parameters
probs (numpy.ndarray) – Array of probability values.
counts (numpy.ndarray) – Array of count values.
total_counts (numpy.ndarray) – Array of total count values.
freqs (numpy.ndarray) – Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
intermediates (tuple, optional) – Used internally to speed up computations.
 Returns
numpy.ndarray – A 1D array of length equal to that of each array argument.
 dterms(self, probs, counts, total_counts, freqs, intermediates=None)¶
Compute the derivatives of the terms of this objective function.
Note that because each term only depends on the corresponding probability, this is just an elementwise derivative (or, the diagonal of a jacobian matrix), i.e. the resulting values are the derivatives of the local_function at each (probability, count, totalcount) value.
 Parameters
probs (numpy.ndarray) – Array of probability values.
counts (numpy.ndarray) – Array of count values.
total_counts (numpy.ndarray) – Array of total count values.
freqs (numpy.ndarray) – Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
intermediates (tuple, optional) – Used internally to speed up computations.
 Returns
numpy.ndarray – A 1D array of length equal to that of each array argument.
 hterms(self, probs, counts, total_counts, freqs, intermediates=None)¶
Compute the 2nd derivatives of the terms of this objective function.
Note that because each term only depends on the corresponding probability, this is just an elementwise 2nd derivative, i.e. the resulting values are the 2ndderivatives of the local_function at each (probability, count, totalcount) value.
 Parameters
probs (numpy.ndarray) – Array of probability values.
counts (numpy.ndarray) – Array of count values.
total_counts (numpy.ndarray) – Array of total count values.
freqs (numpy.ndarray) – Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
intermediates (tuple, optional) – Used internally to speed up computations.
 Returns
numpy.ndarray – A 1D array of length equal to that of each array argument.
 lsvec(self, probs, counts, total_counts, freqs, intermediates=None)¶
Compute the leastsquares vector of the objective function.
This is the squareroot of the termsvector returned from :method:`terms`. This vector is the objective function value used by a leastsquares optimizer when optimizing this objective function. Note that the existence of this quantity requires that the terms be nonnegative. If this is not the case, an error is raised.
 Parameters
probs (numpy.ndarray) – Array of probability values.
counts (numpy.ndarray) – Array of count values.
total_counts (numpy.ndarray) – Array of total count values.
freqs (numpy.ndarray) – Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
intermediates (tuple, optional) – Used internally to speed up computations.
 Returns
numpy.ndarray – A 1D array of length equal to that of each array argument.
 dlsvec(self, probs, counts, total_counts, freqs, intermediates=None)¶
Compute the derivatives of the leastsquares vector of this objective function.
Note that because each lsvec element only depends on the corresponding probability, this is just an elementwise derivative (or, the diagonal of a jacobian matrix), i.e. the resulting values are the derivatives of the local_function at each (probability, count, totalcount) value.
 Parameters
probs (numpy.ndarray) – Array of probability values.
counts (numpy.ndarray) – Array of count values.
total_counts (numpy.ndarray) – Array of total count values.
freqs (numpy.ndarray) – Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
intermediates (tuple, optional) – Used internally to speed up computations.
 Returns
numpy.ndarray – A 1D array of length equal to that of each array argument.
 dlsvec_and_lsvec(self, probs, counts, total_counts, freqs, intermediates=None)¶
Compute the derivatives of the leastsquares vector together with the vector itself.
This is sometimes more computationally efficient than calling :method:`dlsvec` and :method:`lsvec` separately, as the former call may require computing the latter.
 Parameters
probs (numpy.ndarray) – Array of probability values.
counts (numpy.ndarray) – Array of count values.
total_counts (numpy.ndarray) – Array of total count values.
freqs (numpy.ndarray) – Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
intermediates (tuple, optional) – Used internally to speed up computations.
 Returns
dlsvec (numpy.ndarray) – A 1D array of length equal to that of each array argument.
lsvec (numpy.ndarray) – A 1D array of length equal to that of each array argument.
 hlsvec(self, probs, counts, total_counts, freqs, intermediates=None)¶
Compute the 2nd derivatives of the leastsquares vector of this objective function.
Note that because each lsvec element only depends on the corresponding probability, this is just an elementwise 2nd derivative, i.e. the resulting values are the 2ndderivatives of sqrt(local_function) at each (probability, count, totalcount) value.
 Parameters
probs (numpy.ndarray) – Array of probability values.
counts (numpy.ndarray) – Array of count values.
total_counts (numpy.ndarray) – Array of total count values.
freqs (numpy.ndarray) – Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
intermediates (tuple, optional) – Used internally to speed up computations.
 Returns
numpy.ndarray – A 1D array of length equal to that of each array argument.
 zero_freq_terms(self, total_counts, probs)¶
Evaluate objective function terms with zero frequency (where count and frequency are zero).
Such terms are treated specially because, for some objective functions, having zero frequency is a special case and must be handled differently.
 Parameters
total_counts (numpy.ndarray) – The total counts.
probs (numpy.ndarray) – The probabilities.
 Returns
numpy.ndarray – A 1D array of the same length as total_counts and probs.
 zero_freq_dterms(self, total_counts, probs)¶
Evaluate the derivative of zerofrequency objective function terms.
Zero frequency terms are treated specially because, for some objective functions, these are a special case and must be handled differently. Derivatives are evaluated elementwise, i.e. the ith element of the returned array is the derivative of the ith term with respect to the ith probability (derivatives with respect to all other probabilities are zero because of the function structure).
 Parameters
total_counts (numpy.ndarray) – The total counts.
probs (numpy.ndarray) – The probabilities.
 Returns
numpy.ndarray – A 1D array of the same length as total_counts and probs.
 zero_freq_hterms(self, total_counts, probs)¶
Evaluate the 2nd derivative of zerofrequency objective function terms.
Zero frequency terms are treated specially because, for some objective functions, these are a special case and must be handled differently. Derivatives are evaluated elementwise, i.e. the ith element of the returned array is the 2nd derivative of the ith term with respect to the ith probability (derivatives with respect to all other probabilities are zero because of the function structure).
 Parameters
total_counts (numpy.ndarray) – The total counts.
probs (numpy.ndarray) – The probabilities.
 Returns
numpy.ndarray – A 1D array of the same length as total_counts and probs.
 class pygsti.objectivefns.objectivefns.RawMaxLogLFunction(regularization=None, resource_alloc=None, name='maxlogl', description='Max LogL', verbosity=0, poisson_picture=True)¶
Bases:
RawObjectiveFunction
The function N*f*log(f) (note this doesn’t depend on the probability!).
 Parameters
regularization (dict, optional) – Regularization values.
resource_alloc (ResourceAllocation, optional) – Available resources and how they should be allocated for computations.
name (str, optional) – A name for this objective function (can be anything).
description (str, optional) – A description for this objective function (can be anything)
verbosity (int, optional) – Level of detail to print to stdout.
 terms(self, probs, counts, total_counts, freqs, intermediates=None)¶
Compute the terms of the objective function.
The “terms” are the per(probability, count, totalcount) values that get summed together to result in the objective function value. These are the “local” or “perelement” values of the objective function.
 Parameters
probs (numpy.ndarray) – Array of probability values.
counts (numpy.ndarray) – Array of count values.
total_counts (numpy.ndarray) – Array of total count values.
freqs (numpy.ndarray) – Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
intermediates (tuple, optional) – Used internally to speed up computations.
 Returns
numpy.ndarray – A 1D array of length equal to that of each array argument.
 dterms(self, probs, counts, total_counts, freqs, intermediates=None)¶
Compute the derivatives of the terms of this objective function.
Note that because each term only depends on the corresponding probability, this is just an elementwise derivative (or, the diagonal of a jacobian matrix), i.e. the resulting values are the derivatives of the local_function at each (probability, count, totalcount) value.
 Parameters
probs (numpy.ndarray) – Array of probability values.
counts (numpy.ndarray) – Array of count values.
total_counts (numpy.ndarray) – Array of total count values.
freqs (numpy.ndarray) – Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
intermediates (tuple, optional) – Used internally to speed up computations.
 Returns
numpy.ndarray – A 1D array of length equal to that of each array argument.
 hterms(self, probs, counts, total_counts, freqs, intermediates=None)¶
Compute the 2nd derivatives of the terms of this objective function.
Note that because each term only depends on the corresponding probability, this is just an elementwise 2nd derivative, i.e. the resulting values are the 2ndderivatives of the local_function at each (probability, count, totalcount) value.
 Parameters
probs (numpy.ndarray) – Array of probability values.
counts (numpy.ndarray) – Array of count values.
total_counts (numpy.ndarray) – Array of total count values.
freqs (numpy.ndarray) – Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
intermediates (tuple, optional) – Used internally to speed up computations.
 Returns
numpy.ndarray – A 1D array of length equal to that of each array argument.
 lsvec(self, probs, counts, total_counts, freqs, intermediates=None)¶
Compute the leastsquares vector of the objective function.
This is the squareroot of the termsvector returned from :method:`terms`. This vector is the objective function value used by a leastsquares optimizer when optimizing this objective function. Note that the existence of this quantity requires that the terms be nonnegative. If this is not the case, an error is raised.
 Parameters
probs (numpy.ndarray) – Array of probability values.
counts (numpy.ndarray) – Array of count values.
total_counts (numpy.ndarray) – Array of total count values.
freqs (numpy.ndarray) – Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
intermediates (tuple, optional) – Used internally to speed up computations.
 Returns
numpy.ndarray – A 1D array of length equal to that of each array argument.
 dlsvec(self, probs, counts, total_counts, freqs)¶
Compute the derivatives of the leastsquares vector of this objective function.
Note that because each lsvec element only depends on the corresponding probability, this is just an elementwise derivative (or, the diagonal of a jacobian matrix), i.e. the resulting values are the derivatives of the local_function at each (probability, count, totalcount) value.
 Parameters
probs (numpy.ndarray) – Array of probability values.
counts (numpy.ndarray) – Array of count values.
total_counts (numpy.ndarray) – Array of total count values.
freqs (numpy.ndarray) – Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
intermediates (tuple, optional) – Used internally to speed up computations.
 Returns
numpy.ndarray – A 1D array of length equal to that of each array argument.
 dlsvec_and_lsvec(self, probs, counts, total_counts, freqs)¶
Compute the derivatives of the leastsquares vector together with the vector itself.
This is sometimes more computationally efficient than calling :method:`dlsvec` and :method:`lsvec` separately, as the former call may require computing the latter.
 Parameters
probs (numpy.ndarray) – Array of probability values.
counts (numpy.ndarray) – Array of count values.
total_counts (numpy.ndarray) – Array of total count values.
freqs (numpy.ndarray) – Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
intermediates (tuple, optional) – Used internally to speed up computations.
 Returns
dlsvec (numpy.ndarray) – A 1D array of length equal to that of each array argument.
lsvec (numpy.ndarray) – A 1D array of length equal to that of each array argument.
 hlsvec(self, probs, counts, total_counts, freqs)¶
Compute the 2nd derivatives of the leastsquares vector of this objective function.
Note that because each lsvec element only depends on the corresponding probability, this is just an elementwise 2nd derivative, i.e. the resulting values are the 2ndderivatives of sqrt(local_function) at each (probability, count, totalcount) value.
 Parameters
probs (numpy.ndarray) – Array of probability values.
counts (numpy.ndarray) – Array of count values.
total_counts (numpy.ndarray) – Array of total count values.
freqs (numpy.ndarray) – Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
intermediates (tuple, optional) – Used internally to speed up computations.
 Returns
numpy.ndarray – A 1D array of length equal to that of each array argument.
 zero_freq_terms(self, total_counts, probs)¶
Evaluate objective function terms with zero frequency (where count and frequency are zero).
Such terms are treated specially because, for some objective functions, having zero frequency is a special case and must be handled differently.
 Parameters
total_counts (numpy.ndarray) – The total counts.
probs (numpy.ndarray) – The probabilities.
 Returns
numpy.ndarray – A 1D array of the same length as total_counts and probs.
 zero_freq_dterms(self, total_counts, probs)¶
Evaluate the derivative of zerofrequency objective function terms.
Zero frequency terms are treated specially because, for some objective functions, these are a special case and must be handled differently. Derivatives are evaluated elementwise, i.e. the ith element of the returned array is the derivative of the ith term with respect to the ith probability (derivatives with respect to all other probabilities are zero because of the function structure).
 Parameters
total_counts (numpy.ndarray) – The total counts.
probs (numpy.ndarray) – The probabilities.
 Returns
numpy.ndarray – A 1D array of the same length as total_counts and probs.
 zero_freq_hterms(self, total_counts, probs)¶
Evaluate the 2nd derivative of zerofrequency objective function terms.
Zero frequency terms are treated specially because, for some objective functions, these are a special case and must be handled differently. Derivatives are evaluated elementwise, i.e. the ith element of the returned array is the 2nd derivative of the ith term with respect to the ith probability (derivatives with respect to all other probabilities are zero because of the function structure).
 Parameters
total_counts (numpy.ndarray) – The total counts.
probs (numpy.ndarray) – The probabilities.
 Returns
numpy.ndarray – A 1D array of the same length as total_counts and probs.
 class pygsti.objectivefns.objectivefns.RawTVDFunction(regularization=None, resource_alloc=None, name='tvd', description='Total Variational Distance (TVD)', verbosity=0)¶
Bases:
RawObjectiveFunction
The function 0.5 * pf.
 Parameters
regularization (dict, optional) – Regularization values.
resource_alloc (ResourceAllocation, optional) – Available resources and how they should be allocated for computations.
name (str, optional) – A name for this objective function (can be anything).
description (str, optional) – A description for this objective function (can be anything)
verbosity (int, optional) – Level of detail to print to stdout.
 terms(self, probs, counts, total_counts, freqs, intermediates=None)¶
Compute the terms of the objective function.
The “terms” are the per(probability, count, totalcount) values that get summed together to result in the objective function value. These are the “local” or “perelement” values of the objective function.
 Parameters
probs (numpy.ndarray) – Array of probability values.
counts (numpy.ndarray) – Array of count values.
total_counts (numpy.ndarray) – Array of total count values.
freqs (numpy.ndarray) – Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
intermediates (tuple, optional) – Used internally to speed up computations.
 Returns
numpy.ndarray – A 1D array of length equal to that of each array argument.
 abstract dterms(self, probs, counts, total_counts, freqs, intermediates=None)¶
Compute the derivatives of the terms of this objective function.
Note that because each term only depends on the corresponding probability, this is just an elementwise derivative (or, the diagonal of a jacobian matrix), i.e. the resulting values are the derivatives of the local_function at each (probability, count, totalcount) value.
 Parameters
probs (numpy.ndarray) – Array of probability values.
counts (numpy.ndarray) – Array of count values.
total_counts (numpy.ndarray) – Array of total count values.
freqs (numpy.ndarray) – Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
intermediates (tuple, optional) – Used internally to speed up computations.
 Returns
numpy.ndarray – A 1D array of length equal to that of each array argument.
 abstract hterms(self, probs, counts, total_counts, freqs, intermediates=None)¶
Compute the 2nd derivatives of the terms of this objective function.
Note that because each term only depends on the corresponding probability, this is just an elementwise 2nd derivative, i.e. the resulting values are the 2ndderivatives of the local_function at each (probability, count, totalcount) value.
 Parameters
probs (numpy.ndarray) – Array of probability values.
counts (numpy.ndarray) – Array of count values.
total_counts (numpy.ndarray) – Array of total count values.
freqs (numpy.ndarray) – Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
intermediates (tuple, optional) – Used internally to speed up computations.
 Returns
numpy.ndarray – A 1D array of length equal to that of each array argument.
 zero_freq_terms(self, total_counts, probs)¶
Evaluate objective function terms with zero frequency (where count and frequency are zero).
Such terms are treated specially because, for some objective functions, having zero frequency is a special case and must be handled differently.
 Parameters
total_counts (numpy.ndarray) – The total counts.
probs (numpy.ndarray) – The probabilities.
 Returns
numpy.ndarray – A 1D array of the same length as total_counts and probs.
 abstract zero_freq_dterms(self, total_counts, probs)¶
Evaluate the derivative of zerofrequency objective function terms.
Zero frequency terms are treated specially because, for some objective functions, these are a special case and must be handled differently. Derivatives are evaluated elementwise, i.e. the ith element of the returned array is the derivative of the ith term with respect to the ith probability (derivatives with respect to all other probabilities are zero because of the function structure).
 Parameters
total_counts (numpy.ndarray) – The total counts.
probs (numpy.ndarray) – The probabilities.
 Returns
numpy.ndarray – A 1D array of the same length as total_counts and probs.
 abstract zero_freq_hterms(self, total_counts, probs)¶
Evaluate the 2nd derivative of zerofrequency objective function terms.
Zero frequency terms are treated specially because, for some objective functions, these are a special case and must be handled differently. Derivatives are evaluated elementwise, i.e. the ith element of the returned array is the 2nd derivative of the ith term with respect to the ith probability (derivatives with respect to all other probabilities are zero because of the function structure).
 Parameters
total_counts (numpy.ndarray) – The total counts.
probs (numpy.ndarray) – The probabilities.
 Returns
numpy.ndarray – A 1D array of the same length as total_counts and probs.
 class pygsti.objectivefns.objectivefns.TimeIndependentMDCObjectiveFunction(raw_objfn, mdc_store, penalties=None, verbosity=0)¶
Bases:
MDCObjectiveFunction
A timeindependent modelbased (
MDCObjectiveFunction
derived) objective function. Parameters
raw_objfn (RawObjectiveFunction) – The raw objective function  specifies how probability and count values are turned into objective function values.
mdl (Model) – The model  specifies how parameter values are turned into probabilities for each circuit outcome.
dataset (DataSet) – The data set  specifies how counts and total_counts are obtained for each circuit outcome.
circuits (list or CircuitList) – The circuit list  specifies what probabilities and counts this objective function compares. If None, then the keys of dataset are used.
regularization (dict, optional) – Regularization values.
penalties (dict, optional) – Penalty values. Penalties usually add additional (penalty) terms to the sum of percircuitoutcome contributions that evaluate to the objective function.
resource_alloc (ResourceAllocation, optional) – Available resources and how they should be allocated for computations.
name (str, optional) – A name for this objective function (can be anything).
description (str, optional) – A description for this objective function (can be anything)
verbosity (int, optional) – Level of detail to print to stdout.
enable_hessian (bool, optional) – Whether hessian calculations are allowed. If True then more resources are needed. If False, calls to hessianrequiring function will result in an error.
 classmethod builder(cls, name=None, description=None, regularization=None, penalties=None, **kwargs)¶
Create an
ObjectiveFunctionBuilder
that builds an objective function of this type. Parameters
name (str, optional) – A name for the built objective function (can be anything).
description (str, optional) – A description for the built objective function (can be anything)
regularization (dict, optional) – Regularization values.
penalties (dict, optional) – Penalty values.
 Returns
ObjectiveFunctionBuilder
 classmethod _create_mdc_store(cls, model, dataset, circuits, resource_alloc, method_names=('fn',), array_types=(), verbosity=0)¶
 classmethod create_from(cls, raw_objfn, model, dataset, circuits, resource_alloc=None, penalties=None, verbosity=0, method_names=('fn',), array_types=())¶
 classmethod _array_types_for_method(cls, method_name, fsim)¶
 classmethod compute_array_types(cls, method_names, fsim)¶
 __del__(self)¶
 set_penalties(self, regularize_factor=0, cptp_penalty_factor=0, spam_penalty_factor=0, errorgen_penalty_factor=0, forcefn_grad=None, shift_fctr=100, prob_clip_interval=( 10000, 1000))¶
Set penalty terms.
 Parameters
regularize_factor (float, optional) – The prefactor of a L1 regularization term that penalizes parameter vector elements that exceed an absolute value of 1.0. Adds a penalty term: regularize_factor * max(0, parameter_value  1.0) for each model parameter.
cptp_penalty_factor (float, optional) – The prefactor of a term that penalizes nonCPTP operations. Specifically, adds a cptp_penalty_factor * sqrt(tracenorm(choi_matrix)) penalty utilizing each operation’s (gate’s) Choi matrix.
spam_penalty_factor (float, optional) – The prefactor of a term that penalizes invalid SPAM operations. Specifically, adds a spam_penalty_factor * sqrt(tracenorm(spam_op)) penalty where spam_op runs over each state preparation’s density matrix and each effect vector’s matrix.
errorgen_penalty_factor (float, optional) – The prefactor of a term that penalizes nonzero error generators. Specifically, adds a errorgen_penalty_factor * sqrt(sum_i(errorgen_coeff_i)) penalty where the sum ranges over all the error generator coefficients of each model operation.
forcefn_grad (numpy.ndarray, optional) – The gradient of a “forcing function” that is added to the objective function. This is used in the calculation of linearresponse error bars.
shift_fctr (float, optional) – An adjustment prefactor for computing the “shift” that serves as a constant offset of the forcing function, i.e. the forcing function (added to the objective function) is essentially ForceFn = force_shift + dot(forcefn_grad, parameter_vector), and force_shift = shift_fctr * forcefn_grad * (forcefn_grad + parameter_vector). Here  indicates a frobenius norm. The idea behind all this is that ForceFn as given above must remain positive (for leastsquares optimization), and so shift_fctr must be large enough to ensure this is the case. Usually you don’t need to alter the default value.
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.
 Returns
int – The number of penalty terms.
 _lspenaltyvec(self, paramvec)¶
The leastsquares penalty vector, an array of the square roots of the penalty terms.
 Parameters
paramvec (numpy.ndarray) – The vector of (model) parameters to evaluate the objective function at.
 Returns
numpy.ndarray
 _penaltyvec(self, paramvec)¶
The penalty vector, an array of all the penalty terms.
 Parameters
paramvec (numpy.ndarray) – The vector of (model) parameters to evaluate the objective function at.
 Returns
numpy.ndarray
 _fill_lspenaltyvec_jac(self, paramvec, lspenaltyvec_jac)¶
Fill lspenaltyvec_jac with the jacobian of the leastsquares (sqrt of the) penalty vector.
 Parameters
paramvec (numpy.ndarray) – The vector of (model) parameters to evaluate the objective function at.
lspenaltyvec_jac (numpy.ndarray) – The array to fill.
 Returns
None
 _fill_dterms_penalty(self, paramvec, terms_jac)¶
Fill terms_jac with the jacobian of the penalty vector.
 Parameters
paramvec (numpy.ndarray) – The vector of (model) parameters to evaluate the objective function at.
terms_jac (numpy.ndarray) – The array to fill.
 Returns
None
 _omitted_prob_first_terms(self, probs)¶
Extracts the value of the first term for each circuit that has omitted probabilities.
Nonzero probabilities may be predicted for circuit outcomes that never occur in the data, and therefore do not produce “terms” for the objective function sum. Yet, in many objective functions, zero frequency terms that have nonzero probabilities still produce a nonzero contribution and must be included. This is performed by adding these “omittedprobability” contributions to the first (nonzerofrequncy, thus present) term corresponding to the given circuit. This function computes these omitted (zerofrequency) terms and returns them in an array of length equal to the number of circuits with omittedprobability contributions.
 Parameters
probs (numpy.ndarray) – The (full) vector of probabilities. Length is equal to the total number of circuit outcomes (not the length of the returned array).
 Returns
numpy.ndarray
 _update_lsvec_for_omitted_probs(self, lsvec, probs)¶
Updates the leastsquares vector lsvec, adding the omittedprobability contributions.
 Parameters
lsvec (numpy.ndarray) – Vector of leastsquares (sqrt of terms) objective function values before adding omittedprobability contributions. This function updates this array.
probs (numpy.ndarray) – The (full) vector of probabilities. Length is equal to the total number of circuit outcomes.
 Returns
None
 _update_terms_for_omitted_probs(self, terms, probs)¶
Updates the terms vector terms, adding the omittedprobability contributions.
 Parameters
terms (numpy.ndarray) – Vector of objective function term values before adding omittedprobability contributions. This function updates this array.
probs (numpy.ndarray) – The (full) vector of probabilities. Length is equal to the total number of circuit outcomes.
 Returns
None
 _omitted_prob_first_dterms(self, probs)¶
Compute the derivative of the firstterms vector returned by :method:`_omitted_prob_first_terms`.
This derivative is just with respect to the probabilities, not the model parameters, as it anticipates a final dot product with the jacobian of the computed probabilities with respect to the model parameters (see :method:`_update_dterms_for_omitted_probs`).
 Parameters
probs (numpy.ndarray) – The (full) vector of probabilities. Length is equal to the total number of circuit outcomes.
 Returns
numpy.ndarray – Vector of the derivatives of the term values with respect to the corresponding probability. As such, this is a 1D array of length equal to the number of circuits with omitted contributions.
 _update_dterms_for_omitted_probs(self, dterms, probs, dprobs_omitted_rowsum)¶
Updates term jacobian to account for omitted probabilities.
 Parameters
dterms (numpy.ndarray) – Jacobian of terms before and omittedprobability contributions are added. This array is updated by this function.
probs (numpy.ndarray) – The (full) vector of probabilities. Length is equal to the total number of circuit outcomes.
dprobs_omitted_rowsum (numpy.ndarray) – An array of shape (M,N) where M is the number of circuits with omitted contributions and N is the number of model parameters. This matrix results from summing up the jacobian rows of all the present probabilities for the circuit corresponding to the row. That is, the ith row of this matrix contains the summedup derivatives of all the computed probabilities (i.e. present outcomes) for the ith circuit with omitted probabilities. These omitted probabilities are never computed, but are inferred as 1.0 minus the present probabilities, so this matrix gives the negative of the derivative of the omitted probabilities.
 Returns
None
 _update_dlsvec_for_omitted_probs(self, dlsvec, lsvec, probs, dprobs_omitted_rowsum)¶
Updates leastsquares vector’s jacobian to account for omitted probabilities.
 Parameters
dlsvec (numpy.ndarray) – Jacobian of leastsquares vector before and omittedprobability contributions are added. This array is updated by this function.
lsvec (numpy.ndarray) – The leastsquares vector itself, as this is often helpful in this computation. Length is equal to the total number of circuit outcomes.
probs (numpy.ndarray) – The (full) vector of probabilities. Length is equal to the total number of circuit outcomes.
dprobs_omitted_rowsum (numpy.ndarray) – An array of shape (M,N) where M is the number of circuits with omitted contributions and N is the number of model parameters. This matrix results from summing up the jacobian rows of all the present probabilities for the circuit corresponding to the row. That is, the ith row of this matrix contains the summedup derivatives of all the computed probabilities (i.e. present outcomes) for the ith circuit with omitted probabilities. These omitted probabilities are never computed, but are inferred as 1.0 minus the present probabilities, so this matrix gives the negative of the derivative of the omitted probabilities.
 Returns
None
 _clip_probs(self)¶
Clips the potentially sharedmem self.probs according to self.prob_clip_interval
 lsvec(self, paramvec=None, oob_check=False)¶
Compute the leastsquares vector of the objective function.
This is the squareroot of the termsvector returned from :method:`terms`. This vector is the objective function value used by a leastsquares optimizer when optimizing this objective function. Note that the existence of this quantity requires that the terms be nonnegative. If this is not the case, an error is raised.
 Parameters
paramvec (numpy.ndarray, optional) – The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).
oob_check (bool, optional) – Whether the objective function should raise an error if it is being evaluated in an “out of bounds” region.
 Returns
numpy.ndarray – An array of shape (nElements,) where nElements is the number of circuit outcomes.
 terms(self, paramvec=None)¶
Compute the terms of the objective function.
The “terms” are the percircuitoutcome values that get summed together to result in the objective function value.
 Parameters
paramvec (numpy.ndarray, optional) – The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).
 Returns
numpy.ndarray – An array of shape (nElements,) where nElements is the number of circuit outcomes.
 dlsvec(self, paramvec=None)¶
The derivative (jacobian) of the leastsquares vector.
Derivatives are taken with respect to model parameters.
 Parameters
paramvec (numpy.ndarray, optional) – The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).
 Returns
numpy.ndarray – An array of shape (nElements,nParams) where nElements is the number of circuit outcomes and nParams is the number of model parameters.
 dterms(self, paramvec=None)¶
Compute the jacobian of the terms of the objective function.
The “terms” are the percircuitoutcome values that get summed together to result in the objective function value. Differentiation is with respect to model parameters.
 Parameters
paramvec (numpy.ndarray, optional) – The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).
 Returns
numpy.ndarray – An array of shape (nElements,nParams) where nElements is the number of circuit outcomes and nParams is the number of model parameters.
 hessian_brute(self, paramvec=None)¶
Computes the Hessian using a brute force approach.
 Parameters
paramvec (numpy.ndarray, optional) – The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).
 Returns
numpy.ndarray – The hessian of this objective function, of shape (N,N) where N is the number of model parameters.
 approximate_hessian(self, paramvec=None)¶
Compute an approximate Hessian of this objective function.
This is typically much less expensive than :method:`hessian` and does not require that enable_hessian=True was set upon initialization. It computes an approximation to the Hessian that only utilizes the information in the Jacobian. Derivatives are takes with respect to model parameters.
 Parameters
paramvec (numpy.ndarray, optional) – The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).
 Returns
numpy.ndarray – An array of shape (nParams, nParams) where nParams is the number of model parameters.
 hessian(self, paramvec=None)¶
Compute the Hessian of this objective function.
Derivatives are takes with respect to model parameters.
 Parameters
paramvec (numpy.ndarray, optional) – The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).
 Returns
numpy.ndarray – An array of shape (nParams, nParams) where nParams is the number of model parameters.
 _hessian_from_block(self, hprobs, dprobs12, probs, counts, total_counts, freqs, resource_alloc)¶
Factoredout computation of hessian from raw components
 class pygsti.objectivefns.objectivefns.Chi2Function(mdc_store, regularization=None, penalties=None, name=None, description=None, verbosity=0)¶
Bases:
TimeIndependentMDCObjectiveFunction
Modelbased chisquared function: N(pf)^2 / p
 Parameters
mdl (Model) – The model  specifies how parameter values are turned into probabilities for each circuit outcome.
dataset (DataSet) – The data set  specifies how counts and total_counts are obtained for each circuit outcome.
circuits (list or CircuitList) – The circuit list  specifies what probabilities and counts this objective function compares. If None, then the keys of dataset are used.
regularization (dict, optional) – Regularization values.
penalties (dict, optional) – Penalty values. Penalties usually add additional (penalty) terms to the sum of percircuitoutcome contributions that evaluate to the objective function.
resource_alloc (ResourceAllocation, optional) – Available resources and how they should be allocated for computations.
name (str, optional) – A name for this objective function (can be anything).
description (str, optional) – A description for this objective function (can be anything)
verbosity (int, optional) – Level of detail to print to stdout.
enable_hessian (bool, optional) – Whether hessian calculations are allowed. If True then more resources are needed. If False, calls to hessianrequiring function will result in an error.
 classmethod create_from(cls, model, dataset, circuits, regularization=None, penalties=None, resource_alloc=None, name=None, description=None, verbosity=0, method_names=('fn',), array_types=())¶
 class pygsti.objectivefns.objectivefns.ChiAlphaFunction(mdc_store, regularization=None, penalties=None, name=None, description=None, verbosity=0, alpha=1)¶
Bases:
TimeIndependentMDCObjectiveFunction
Modelbased chialpha function: N[x + 1/(alpha * x^alpha)  (1 + 1/alpha)] where x := p/f.
 Parameters
mdl (Model) – The model  specifies how parameter values are turned into probabilities for each circuit outcome.
dataset (DataSet) – The data set  specifies how counts and total_counts are obtained for each circuit outcome.
circuits (list or CircuitList) – The circuit list  specifies what probabilities and counts this objective function compares. If None, then the keys of dataset are used.
regularization (dict, optional) – Regularization values.
penalties (dict, optional) – Penalty values. Penalties usually add additional (penalty) terms to the sum of percircuitoutcome contributions that evaluate to the objective function.
resource_alloc (ResourceAllocation, optional) – Available resources and how they should be allocated for computations.
name (str, optional) – A name for this objective function (can be anything).
description (str, optional) – A description for this objective function (can be anything)
verbosity (int, optional) – Level of detail to print to stdout.
enable_hessian (bool, optional) – Whether hessian calculations are allowed. If True then more resources are needed. If False, calls to hessianrequiring function will result in an error.
alpha (float, optional) – The alpha parameter, which lies in the interval (0,1].
 classmethod create_from(cls, model, dataset, circuits, regularization=None, penalties=None, resource_alloc=None, name=None, description=None, verbosity=0, method_names=('fn',), array_types=(), alpha=1)¶
 class pygsti.objectivefns.objectivefns.FreqWeightedChi2Function(mdc_store, regularization=None, penalties=None, name=None, description=None, verbosity=0)¶
Bases:
TimeIndependentMDCObjectiveFunction
Modelbased frequencyweighted chisquared function: N(pf)^2 / f
 Parameters
mdl (Model) – The model  specifies how parameter values are turned into probabilities for each circuit outcome.
dataset (DataSet) – The data set  specifies how counts and total_counts are obtained for each circuit outcome.
circuits (list or CircuitList) – The circuit list  specifies what probabilities and counts this objective function compares. If None, then the keys of dataset are used.
regularization (dict, optional) – Regularization values.
penalties (dict, optional) – Penalty values. Penalties usually add additional (penalty) terms to the sum of percircuitoutcome contributions that evaluate to the objective function.
resource_alloc (ResourceAllocation, optional) – Available resources and how they should be allocated for computations.
name (str, optional) – A name for this objective function (can be anything).
description (str, optional) – A description for this objective function (can be anything)
verbosity (int, optional) – Level of detail to print to stdout.
enable_hessian (bool, optional) – Whether hessian calculations are allowed. If True then more resources are needed. If False, calls to hessianrequiring function will result in an error.
 classmethod create_from(cls, model, dataset, circuits, regularization=None, penalties=None, resource_alloc=None, name=None, description=None, verbosity=0, method_names=('fn',), array_types=())¶
 class pygsti.objectivefns.objectivefns.PoissonPicDeltaLogLFunction(mdc_store, regularization=None, penalties=None, name=None, description=None, verbosity=0)¶
Bases:
TimeIndependentMDCObjectiveFunction
Modelbased poissonpicture delta loglikelihood function: N*f*log(f/p)  N*(fp).
 Parameters
mdl (Model) – The model  specifies how parameter values are turned into probabilities for each circuit outcome.
dataset (DataSet) – The data set  specifies how counts and total_counts are obtained for each circuit outcome.
circuits (list or CircuitList) – The circuit list  specifies what probabilities and counts this objective function compares. If None, then the keys of dataset are used.
regularization (dict, optional) – Regularization values.
penalties (dict, optional) – Penalty values. Penalties usually add additional (penalty) terms to the sum of percircuitoutcome contributions that evaluate to the objective function.
resource_alloc (ResourceAllocation, optional) – Available resources and how they should be allocated for computations.
name (str, optional) – A name for this objective function (can be anything).
description (str, optional) – A description for this objective function (can be anything)
verbosity (int, optional) – Level of detail to print to stdout.
enable_hessian (bool, optional) – Whether hessian calculations are allowed. If True then more resources are needed. If False, calls to hessianrequiring function will result in an error.
 classmethod create_from(cls, model, dataset, circuits, regularization=None, penalties=None, resource_alloc=None, name=None, description=None, verbosity=0, method_names=('fn',), array_types=())¶
 class pygsti.objectivefns.objectivefns.DeltaLogLFunction(mdc_store, regularization=None, penalties=None, name=None, description=None, verbosity=0)¶
Bases:
TimeIndependentMDCObjectiveFunction
Modelbased delta loglikelihood function: N*f*log(f/p).
 Parameters
mdl (Model) – The model  specifies how parameter values are turned into probabilities for each circuit outcome.
dataset (DataSet) – The data set  specifies how counts and total_counts are obtained for each circuit outcome.
circuits (list or CircuitList) – The circuit list  specifies what probabilities and counts this objective function compares. If None, then the keys of dataset are used.
regularization (dict, optional) – Regularization values.
penalties (dict, optional) – Penalty values. Penalties usually add additional (penalty) terms to the sum of percircuitoutcome contributions that evaluate to the objective function.
resource_alloc (ResourceAllocation, optional) – Available resources and how they should be allocated for computations.
name (str, optional) – A name for this objective function (can be anything).
description (str, optional) – A description for this objective function (can be anything)
verbosity (int, optional) – Level of detail to print to stdout.
enable_hessian (bool, optional) – Whether hessian calculations are allowed. If True then more resources are needed. If False, calls to hessianrequiring function will result in an error.
 classmethod create_from(cls, model, dataset, circuits, regularization=None, penalties=None, resource_alloc=None, name=None, description=None, verbosity=0, method_names=('fn',), array_types=())¶
 class pygsti.objectivefns.objectivefns.MaxLogLFunction(mdc_store, regularization=None, penalties=None, name=None, description=None, verbosity=0, poisson_picture=True)¶
Bases:
TimeIndependentMDCObjectiveFunction
Modelbased maximummodel loglikelihood function: N*f*log(f)
 Parameters
mdl (Model) – The model  specifies how parameter values are turned into probabilities for each circuit outcome.
dataset (DataSet) – The data set  specifies how counts and total_counts are obtained for each circuit outcome.
circuits (list or CircuitList) – The circuit list  specifies what probabilities and counts this objective function compares. If None, then the keys of dataset are used.
regularization (dict, optional) – Regularization values.
penalties (dict, optional) – Penalty values. Penalties usually add additional (penalty) terms to the sum of percircuitoutcome contributions that evaluate to the objective function.
resource_alloc (ResourceAllocation, optional) – Available resources and how they should be allocated for computations.
name (str, optional) – A name for this objective function (can be anything).
description (str, optional) – A description for this objective function (can be anything)
verbosity (int, optional) – Level of detail to print to stdout.
enable_hessian (bool, optional) – Whether hessian calculations are allowed. If True then more resources are needed. If False, calls to hessianrequiring function will result in an error.
 classmethod create_from(cls, model, dataset, circuits, regularization=None, penalties=None, resource_alloc=None, name=None, description=None, verbosity=0, method_names=('fn',), array_types=(), poisson_picture=True)¶
 class pygsti.objectivefns.objectivefns.TVDFunction(mdc_store, regularization=None, penalties=None, name=None, description=None, verbosity=0)¶
Bases:
TimeIndependentMDCObjectiveFunction
Modelbased TVD function: 0.5 * pf.
 Parameters
mdl (Model) – The model  specifies how parameter values are turned into probabilities for each circuit outcome.
dataset (DataSet) – The data set  specifies how counts and total_counts are obtained for each circuit outcome.
circuits (list or CircuitList) – The circuit list  specifies what probabilities and counts this objective function compares. If None, then the keys of dataset are used.
regularization (dict, optional) – Regularization values.
penalties (dict, optional) – Penalty values. Penalties usually add additional (penalty) terms to the sum of percircuitoutcome contributions that evaluate to the objective function.
resource_alloc (ResourceAllocation, optional) – Available resources and how they should be allocated for computations.
name (str, optional) – A name for this objective function (can be anything).
description (str, optional) – A description for this objective function (can be anything)
verbosity (int, optional) – Level of detail to print to stdout.
enable_hessian (bool, optional) – Whether hessian calculations are allowed. If True then more resources are needed. If False, calls to hessianrequiring function will result in an error.
 classmethod create_from(cls, model, dataset, circuits, regularization=None, penalties=None, resource_alloc=None, name=None, description=None, verbosity=0, method_names=('fn',), array_types=())¶
 class pygsti.objectivefns.objectivefns.TimeDependentMDCObjectiveFunction(mdc_store, regularization=None, penalties=None, name=None, description=None, verbosity=0)¶
Bases:
MDCObjectiveFunction
A timedependent modelbased objective function
 Parameters
mdl (Model) – The model  specifies how parameter values are turned into probabilities for each circuit outcome.
dataset (DataSet) – The data set  specifies how counts and total_counts are obtained for each circuit outcome.
circuits (list or CircuitList) – The circuit list  specifies what probabilities and counts this objective function compares. If None, then the keys of dataset are used.
regularization (dict, optional) – Regularization values.
penalties (dict, optional) – Penalty values. Penalties usually add additional (penalty) terms to the sum of percircuitoutcome contributions that evaluate to the objective function.
resource_alloc (ResourceAllocation, optional) – Available resources and how they should be allocated for computations.
name (str, optional) – A name for this objective function (can be anything).
verbosity (int, optional) – Level of detail to print to stdout.
 classmethod builder(cls, name=None, description=None, regularization=None, penalties=None, **kwargs)¶
Create an
ObjectiveFunctionBuilder
that builds an objective function of this type. Parameters
name (str, optional) – A name for the built objective function (can be anything).
description (str, optional) – A description for the built objective function (can be anything)
regularization (dict, optional) – Regularization values.
penalties (dict, optional) – Penalty values.
 Returns
ObjectiveFunctionBuilder
 classmethod create_from(cls, model, dataset, circuits, regularization=None, penalties=None, resource_alloc=None, name=None, description=None, verbosity=0, method_names=('fn',), array_types=())¶
 classmethod compute_array_types(cls, method_names, fsim)¶
 __del__(self)¶
 set_regularization(self)¶
Set regularization values.
 Returns
None
 set_penalties(self)¶
Set penalty terms.
 abstract lsvec(self, paramvec=None)¶
Compute the leastsquares vector of the objective function.
This is the squareroot of the termsvector returned from :method:`terms`. This vector is the objective function value used by a leastsquares optimizer when optimizing this objective function. Note that the existence of this quantity requires that the terms be nonnegative. If this is not the case, an error is raised.
 Parameters
paramvec (numpy.ndarray, optional) – The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).
 Returns
numpy.ndarray – An array of shape (nElements,) where nElements is the number of circuit outcomes.
 abstract dlsvec(self, paramvec=None)¶
The derivative (jacobian) of the leastsquares vector.
Derivatives are taken with respect to model parameters.
 Parameters
paramvec (numpy.ndarray, optional) – The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).
 Returns
numpy.ndarray – An array of shape (nElements,nParams) where nElements is the number of circuit outcomes and nParams is the number of model parameters.
 class pygsti.objectivefns.objectivefns.TimeDependentChi2Function(mdc_store, regularization=None, penalties=None, name=None, description=None, verbosity=0)¶
Bases:
TimeDependentMDCObjectiveFunction
Chisquared function that can handle timedependent circuits and data.
This objective function can handle timedependent circuits  that is, circuits are treated as potentially timedependent and mdl as well. This function currently doesn’t support much regularization or penalization.
 classmethod _array_types_for_method(cls, method_name, fsim)¶
 set_regularization(self, min_prob_clip_for_weighting=0.0001, radius=0.0001)¶
Set regularization values.
 Parameters
min_prob_clip_for_weighting (float, optional) – Cutoff for probability prob in 1 / prob weighting factor (the maximum of prob and min_prob_clip_for_weighting is used in the denominator).
radius (float, optional) – Affects sharpness of the regularization of zerofrequency terms.
 Returns
None
 set_penalties(self, regularize_factor=0, cptp_penalty_factor=0, spam_penalty_factor=0, errorgen_penalty_factor=0, prob_clip_interval=( 10000, 10000))¶
Set penalty terms.
 Parameters
regularize_factor (float, optional) – The prefactor of a L1 regularization term that penalizes parameter vector elements that exceed an absolute value of 1.0. Adds a penalty term: regularize_factor * max(0, parameter_value  1.0) for each model parameter.
cptp_penalty_factor (float, optional) – The prefactor of a term that penalizes nonCPTP operations. Specifically, adds a cptp_penalty_factor * sqrt(tracenorm(choi_matrix)) penalty utilizing each operation’s (gate’s) Choi matrix.
spam_penalty_factor (float, optional) – The prefactor of a term that penalizes invalid SPAM operations. Specifically, adds a spam_penalty_factor * sqrt(tracenorm(spam_op)) penalty where spam_op runs over each state preparation’s density matrix and each effect vector’s matrix.
errorgen_penalty_factor (float, optional) – The prefactor of a term that penalizes nonzero error generators. Specifically, adds a errorgen_penalty_factor * sqrt(sum_i(errorgen_coeff_i)) penalty where the sum ranges over all the error generator coefficients of each model operation.
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.
 Returns
int – The number of penalty terms.
 chi2k_distributed_qty(self, objective_function_value)¶
Convert a value of this objective function to one that is expected to be chi2_k distributed.
 Parameters
objective_function_value (float) – A value of this objective function, i.e. one returned from self.fn(…).
 Returns
float
 lsvec(self, paramvec=None)¶
Compute the leastsquares vector of the objective function.
This is the squareroot of the termsvector returned from :method:`terms`. This vector is the objective function value used by a leastsquares optimizer when optimizing this objective function. Note that the existence of this quantity requires that the terms be nonnegative. If this is not the case, an error is raised.
 Parameters
paramvec (numpy.ndarray, optional) – The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).
 Returns
numpy.ndarray – An array of shape (nElements,) where nElements is the number of circuit outcomes.
 dlsvec(self, paramvec=None)¶
The derivative (jacobian) of the leastsquares vector.
Derivatives are taken with respect to model parameters.
 Parameters
paramvec (numpy.ndarray, optional) – The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).
 Returns
numpy.ndarray – An array of shape (nElements,nParams) where nElements is the number of circuit outcomes and nParams is the number of model parameters.
 class pygsti.objectivefns.objectivefns.TimeDependentPoissonPicLogLFunction(mdc_store, regularization=None, penalties=None, name=None, description=None, verbosity=0)¶
Bases:
TimeDependentMDCObjectiveFunction
Poissonpicture delta loglikelihood function that can handle timedependent circuits and data.
This objective function can handle timedependent circuits  that is, circuits are treated as potentially timedependent and mdl as well. This function currently doesn’t support much regularization or penalization.
 classmethod _array_types_for_method(cls, method_name, fsim)¶
 set_regularization(self, min_prob_clip=0.0001, radius=0.0001)¶
Set regularization values.
 Parameters
min_prob_clip (float, optional) – The probability below which the objective function is replaced with its second order Taylor expansion.
radius (float, optional) – Affects sharpness of the regularization of zerofrequency terms.
 Returns
None
 set_penalties(self, cptp_penalty_factor=0, spam_penalty_factor=0, errorgen_penalty_factor=0, forcefn_grad=None, shift_fctr=100, prob_clip_interval=( 10000, 10000))¶
Set penalties.
 Parameters
cptp_penalty_factor (float, optional) – The prefactor of a term that penalizes nonCPTP operations. Specifically, adds a cptp_penalty_factor * sqrt(tracenorm(choi_matrix)) penalty utilizing each operation’s (gate’s) Choi matrix.
spam_penalty_factor (float, optional) – The prefactor of a term that penalizes invalid SPAM operations. Specifically, adds a spam_penalty_factor * sqrt(tracenorm(spam_op)) penalty where spam_op runs over each state preparation’s density matrix and each effect vector’s matrix.
errorgen_penalty_factor (float, optional) – The prefactor of a term that penalizes nonzero error generators. Specifically, adds a errorgen_penalty_factor * sqrt(sum_i(errorgen_coeff_i)) penalty where the sum ranges over all the error generator coefficients of each model operation.
forcefn_grad (numpy.ndarray, optional) – The gradient of a “forcing function” that is added to the objective function. This is used in the calculation of linearresponse error bars.
shift_fctr (float, optional) – An adjustment prefactor for computing the “shift” that serves as a constant offset of the forcing function, i.e. the forcing function (added to the objective function) is essentially ForceFn = force_shift + dot(forcefn_grad, parameter_vector), and force_shift = shift_fctr * forcefn_grad * (forcefn_grad + parameter_vector). Here  indicates a frobenius norm. The idea behind all this is that ForceFn as given above must remain positive (for leastsquares optimization), and so shift_fctr must be large enough to ensure this is the case. Usually you don’t need to alter the default value.
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.
 Returns
int – The number of penalty terms.
 chi2k_distributed_qty(self, objective_function_value)¶
Convert a value of this objective function to one that is expected to be chi2_k distributed.
 Parameters
objective_function_value (float) – A value of this objective function, i.e. one returned from self.fn(…).
 Returns
float
 lsvec(self, paramvec=None)¶
Compute the leastsquares vector of the objective function.
This is the squareroot of the termsvector returned from :method:`terms`. This vector is the objective function value used by a leastsquares optimizer when optimizing this objective function. Note that the existence of this quantity requires that the terms be nonnegative. If this is not the case, an error is raised.
 Parameters
paramvec (numpy.ndarray, optional) – The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).
 Returns
numpy.ndarray – An array of shape (nElements,) where nElements is the number of circuit outcomes.
 dlsvec(self, paramvec=None)¶
The derivative (jacobian) of the leastsquares vector.
Derivatives are taken with respect to model parameters.
 Parameters
paramvec (numpy.ndarray, optional) – The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).
 Returns
numpy.ndarray – An array of shape (nElements,nParams) where nElements is the number of circuit outcomes and nParams is the number of model parameters.
 pygsti.objectivefns.objectivefns._cptp_penalty_size(mdl)¶
 pygsti.objectivefns.objectivefns._spam_penalty_size(mdl)¶
 pygsti.objectivefns.objectivefns._errorgen_penalty_size(mdl)¶
 pygsti.objectivefns.objectivefns._cptp_penalty(mdl, prefactor, op_basis)¶
Helper function  CPTP penalty: (sum of tracenorms of gates), which in least squares optimization means returning an array of the sqrt(tracenorm) of each gate.
 Returns
numpy array – a (real) 1D array of length len(mdl.operations).
 pygsti.objectivefns.objectivefns._spam_penalty(mdl, prefactor, op_basis)¶
Helper function  CPTP penalty: (sum of tracenorms of gates), which in least squares optimization means returning an array of the sqrt(tracenorm) of each gate.
 Returns
numpy array – a (real) 1D array of length len(mdl.operations).
 pygsti.objectivefns.objectivefns._errorgen_penalty(mdl, prefactor)¶
Helper function  errorgen penalty: sum_i errorgen_coeff_i which in least squares optimization means returning an array of the sqrt(sum_i errorgen_coeff_i) of each gate.
Note: error generator coefficients can be complex.
 pygsti.objectivefns.objectivefns._cptp_penalty_jac_fill(cp_penalty_vec_grad_to_fill, mdl, prefactor, op_basis, wrt_slice)¶
Helper function  jacobian of CPTP penalty (sum of tracenorms of gates) Returns a (real) array of shape (len(mdl.operations), n_params).
 pygsti.objectivefns.objectivefns._spam_penalty_jac_fill(spam_penalty_vec_grad_to_fill, mdl, prefactor, op_basis, wrt_slice)¶
Helper function  jacobian of CPTP penalty (sum of tracenorms of gates) Returns a (real) array of shape ( _spam_penalty_size(mdl), n_params).
 pygsti.objectivefns.objectivefns._errorgen_penalty_jac_fill(errorgen_penalty_vec_grad_to_fill, mdl, prefactor, wrt_slice)¶
 class pygsti.objectivefns.objectivefns.LogLWildcardFunction(logl_objective_fn, base_pt, wildcard)¶
Bases:
ObjectiveFunction
A wildcardbudget bolton to an existing objective function.
Currently, this existing function must be a loglikelihood type function because the computational logic assumes this. The resulting object is an objective function over the space of wildcard budget parameter vectors (not model parameters).
 Parameters
logl_objective_fn (PoissonPicDeltaLogLFunction) – The bare loglikelihood function.
base_pt (numpy.ndarray) – Unused. The modelparamter vector where this objective function is based.
wildcard (WildcardBudget) – The wildcard budget that adjusts the “bare” probabilities of logl_objective_fn before evaluating the rest of the objective function.
 __getattr__(self, attr)¶
 chi2k_distributed_qty(self, objective_function_value)¶
Convert a value of this objective function to one that is expected to be chi2_k distributed.
 Parameters
objective_function_value (float) – A value of this objective function, i.e. one returned from self.fn(…).
 Returns
float
 fn(self, wvec=None)¶
Evaluate this objective function.
 Parameters
wvec (numpy.ndarray, optional) – The vector of (wildcard budget) parameters to evaluate the objective function at. If None, then the budget’s current parameter vector is used (held internally).
 Returns
float
 terms(self, wvec=None)¶
Compute the terms of the objective function.
The “terms” are the percircuitoutcome values that get summed together to result in the objective function value.
 Parameters
wvec (numpy.ndarray, optional) – The vector of (wildcard budget) parameters to evaluate the objective function at. If None, then the budget’s current parameter vector is used (held internally).
 Returns
numpy.ndarray – An array of shape (nElements,) where nElements is the number of circuit outcomes.
 lsvec(self, wvec=None)¶
Compute the leastsquares vector of the objective function.
This is the squareroot of the termsvector returned from :method:`terms`. This vector is the objective function value used by a leastsquares optimizer when optimizing this objective function. Note that the existence of this quantity requires that the terms be nonnegative. If this is not the case, an error is raised.
 Parameters
wvec (numpy.ndarray, optional) – The vector of (wildcard budget) parameters to evaluate the objective function at. If None, then the budget’s current parameter vector is used (held internally).
 Returns
numpy.ndarray – An array of shape (nElements,) where nElements is the number of circuit outcomes.
 abstract dlsvec(self, wvec)¶
The derivative (jacobian) of the leastsquares vector.
Derivatives are taken with respect to wildcard budget parameters.
 Parameters
wvec (numpy.ndarray, optional) – The vector of (wildcard budget) parameters to evaluate the objective function at. If None, then the budget’s current parameter vector is used (held internally).
 Returns
numpy.ndarray – An array of shape (nElements,nParams) where nElements is the number of circuit outcomes and nParams is the number of wildcard budget parameters.
 class pygsti.objectivefns.objectivefns.CachedObjectiveFunction(objective_function)¶
Bases:
pygsti.baseobjs.nicelyserializable.NicelySerializable
Holds various values of an objective function at a particular point.
This object is meant to be serializable, and not to facilitate computing the objective function anywhere else. It doesn’t contain or rely on comm objects. It does contain a serial or “global” layout that allows us to make sense of the elements of various probability vectors, etc., but we demand that this layout not depend on comm objects.
The cache may only have values on the rank0 proc (??)
 classmethod from_dir(cls, dirname, quick_load=False)¶
Initialize a new CachedObjectiveFunction object from dirname.
 quick_loadbool, optional
Setting this to True skips the loading of components that may take a long time to load.
 Parameters
dirname (str) – The directory name.
quick_load (bool, optional) – Setting this to True skips the loading of components that may take a long time to load.
 Returns
CachedObjectiveFunction
 write(self, dirname)¶
Write this CachedObjectiveFunction to a directory.
 Parameters
dirname (str) – The directory name to write. This directory will be created if needed, and the files in an existing directory will be overwritten.
 Returns
None
 _to_nice_serialization(self)¶
 classmethod _from_nice_serialization(cls, state)¶