pygsti.objectivefns

Package of objective functions of a model and data set, which can be optimized.

Submodules

Package Contents

Classes

ObjectiveFunctionBuilder

A factory class for building objective functions.

ObjectiveFunction

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

RawChi2Function

The function N(p-f)^2 / p

RawChiAlphaFunction

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

RawFreqWeightedChi2Function

The function N(p-f)^2 / f

RawPoissonPicDeltaLogLFunction

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

RawDeltaLogLFunction

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

RawMaxLogLFunction

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

RawTVDFunction

The function 0.5 * |p-f|.

Chi2Function

Model-based chi-squared function: N(p-f)^2 / p

ChiAlphaFunction

Model-based chi-alpha function: N[x + 1/(alpha * x^alpha) - (1 + 1/alpha)] where x := p/f.

FreqWeightedChi2Function

Model-based frequency-weighted chi-squared function: N(p-f)^2 / f

PoissonPicDeltaLogLFunction

Model-based poisson-picture delta log-likelihood function: N*f*log(f/p) - N*(f-p).

DeltaLogLFunction

Model-based delta log-likelihood function: N*f*log(f/p).

MaxLogLFunction

Model-based maximum-model log-likelihood function: N*f*log(f)

TVDFunction

Model-based TVD function: 0.5 * |p-f|.

TimeDependentChi2Function

Chi-squared function that can handle time-dependent circuits and data.

TimeDependentPoissonPicLogLFunction

Poisson-picture delta log-likelihood function that can handle time-dependent circuits and data.

LogLWildcardFunction

A wildcard-budget bolt-on to an existing objective function.

ModelDatasetCircuitsStore

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

EvaluatedModelDatasetCircuitsStore

Additionally holds quantities at a specific model-parameter-space point.

class pygsti.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: log-likelihood or chi-squared.

  • 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.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 chi-squared 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.RawChi2Function(regularization=None, resource_alloc=None, name='chi2', description='Sum of Chi^2', verbosity=0)

Bases: RawObjectiveFunction

The function N(p-f)^2 / p

Note that this equals Nf (1-x)^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 least-squares vector of the objective function.

This is the square-root of the terms-vector returned from :method:`terms`. This vector is the objective function value used by a least-squares optimizer when optimizing this objective function. Note that the existence of this quantity requires that the terms be non-negative. 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 least-squares vector of this objective function.

Note that because each lsvec element only depends on the corresponding probability, this is just an element-wise derivative (or, the diagonal of a jacobian matrix), i.e. the resulting values are the derivatives of the local_function at each (probability, count, total-count) 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 least-squares vector of this objective function.

Note that because each lsvec element only depends on the corresponding probability, this is just an element-wise 2nd derivative, i.e. the resulting values are the 2nd-derivatives of sqrt(local_function) at each (probability, count, total-count) 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 zero-frequency 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 element-wise, i.e. the i-th element of the returned array is the derivative of the i-th term with respect to the i-th 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 zero-frequency 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 element-wise, i.e. the i-th element of the returned array is the 2nd derivative of the i-th term with respect to the i-th 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.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 log-likelihood 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 x-value (x = probility/frequency ratio) below which the function is replaced with it second-order Taylor expansion.

  • pfratio_derivpt (float, optional) – The x-value 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 stitch-point be smooth.

  • radius (float, optional) – If radius is not None then a “harsh” method of regularizing the zero-frequency 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, first-derivative, 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 zero-frequency terms.

  • fmin (float, optional) – The minimum expected frequency. When radius is None a “relaxed” regularization of the zero-frequency 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 zero-frequency terms at the stitch point is similar to the regular nonzero-frequency 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, total-count) values that get summed together to result in the objective function value. These are the “local” or “per-element” 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 element-wise derivative (or, the diagonal of a jacobian matrix), i.e. the resulting values are the derivatives of the local_function at each (probability, count, total-count) 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 element-wise 2nd derivative, i.e. the resulting values are the 2nd-derivatives of the local_function at each (probability, count, total-count) 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 least-squares vector of this objective function.

Note that because each lsvec element only depends on the corresponding probability, this is just an element-wise 2nd derivative, i.e. the resulting values are the 2nd-derivatives of sqrt(local_function) at each (probability, count, total-count) 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.RawFreqWeightedChi2Function(regularization=None, resource_alloc=None, name='fwchi2', description='Sum of freq-weighted Chi^2', verbosity=0)

Bases: RawChi2Function

The function N(p-f)^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 zero-frequency 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 element-wise, i.e. the i-th element of the returned array is the derivative of the i-th term with respect to the i-th 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 zero-frequency 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 element-wise, i.e. the i-th element of the returned array is the 2nd derivative of the i-th term with respect to the i-th 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.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*(f-p).

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 stitch-point is given in x=p/f units.

  • pfratio_stitchpt (float, optional) – The x-value (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 x-value 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 stitch-point be smooth.

  • radius (float, optional) – If radius is not None then a “harsh” method of regularizing the zero-frequency 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, first-derivative, 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 zero-frequency terms.

  • fmin (float, optional) – The minimum expected frequency. When radius is None a “relaxed” regularization of the zero-frequency 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 zero-frequency terms at the stitch point is similar to the regular nonzero-frequency 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, total-count) values that get summed together to result in the objective function value. These are the “local” or “per-element” 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 least-squares vector of the objective function.

This is the square-root of the terms-vector returned from :method:`terms`. This vector is the objective function value used by a least-squares optimizer when optimizing this objective function. Note that the existence of this quantity requires that the terms be non-negative. 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 element-wise derivative (or, the diagonal of a jacobian matrix), i.e. the resulting values are the derivatives of the local_function at each (probability, count, total-count) 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 element-wise 2nd derivative, i.e. the resulting values are the 2nd-derivatives of the local_function at each (probability, count, total-count) 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.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 stitch-point is given in x=p/f units.

  • pfratio_stitchpt (float, optional) – The x-value (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 x-value 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 stitch-point 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, total-count) values that get summed together to result in the objective function value. These are the “local” or “per-element” 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 element-wise derivative (or, the diagonal of a jacobian matrix), i.e. the resulting values are the derivatives of the local_function at each (probability, count, total-count) 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 element-wise 2nd derivative, i.e. the resulting values are the 2nd-derivatives of the local_function at each (probability, count, total-count) 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 least-squares vector of the objective function.

This is the square-root of the terms-vector returned from :method:`terms`. This vector is the objective function value used by a least-squares optimizer when optimizing this objective function. Note that the existence of this quantity requires that the terms be non-negative. 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 least-squares vector of this objective function.

Note that because each lsvec element only depends on the corresponding probability, this is just an element-wise derivative (or, the diagonal of a jacobian matrix), i.e. the resulting values are the derivatives of the local_function at each (probability, count, total-count) 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 least-squares 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 least-squares vector of this objective function.

Note that because each lsvec element only depends on the corresponding probability, this is just an element-wise 2nd derivative, i.e. the resulting values are the 2nd-derivatives of sqrt(local_function) at each (probability, count, total-count) 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 zero-frequency 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 element-wise, i.e. the i-th element of the returned array is the derivative of the i-th term with respect to the i-th 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 zero-frequency 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 element-wise, i.e. the i-th element of the returned array is the 2nd derivative of the i-th term with respect to the i-th 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.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, total-count) values that get summed together to result in the objective function value. These are the “local” or “per-element” 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 element-wise derivative (or, the diagonal of a jacobian matrix), i.e. the resulting values are the derivatives of the local_function at each (probability, count, total-count) 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 element-wise 2nd derivative, i.e. the resulting values are the 2nd-derivatives of the local_function at each (probability, count, total-count) 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 least-squares vector of the objective function.

This is the square-root of the terms-vector returned from :method:`terms`. This vector is the objective function value used by a least-squares optimizer when optimizing this objective function. Note that the existence of this quantity requires that the terms be non-negative. 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 least-squares vector of this objective function.

Note that because each lsvec element only depends on the corresponding probability, this is just an element-wise derivative (or, the diagonal of a jacobian matrix), i.e. the resulting values are the derivatives of the local_function at each (probability, count, total-count) 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 least-squares 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 least-squares vector of this objective function.

Note that because each lsvec element only depends on the corresponding probability, this is just an element-wise 2nd derivative, i.e. the resulting values are the 2nd-derivatives of sqrt(local_function) at each (probability, count, total-count) 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 zero-frequency 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 element-wise, i.e. the i-th element of the returned array is the derivative of the i-th term with respect to the i-th 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 zero-frequency 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 element-wise, i.e. the i-th element of the returned array is the 2nd derivative of the i-th term with respect to the i-th 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.RawTVDFunction(regularization=None, resource_alloc=None, name='tvd', description='Total Variational Distance (TVD)', verbosity=0)

Bases: RawObjectiveFunction

The function 0.5 * |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.

terms(self, probs, counts, total_counts, freqs, intermediates=None)

Compute the terms of the objective function.

The “terms” are the per-(probability, count, total-count) values that get summed together to result in the objective function value. These are the “local” or “per-element” 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 element-wise derivative (or, the diagonal of a jacobian matrix), i.e. the resulting values are the derivatives of the local_function at each (probability, count, total-count) 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 element-wise 2nd derivative, i.e. the resulting values are the 2nd-derivatives of the local_function at each (probability, count, total-count) 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 zero-frequency 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 element-wise, i.e. the i-th element of the returned array is the derivative of the i-th term with respect to the i-th 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 zero-frequency 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 element-wise, i.e. the i-th element of the returned array is the 2nd derivative of the i-th term with respect to the i-th 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.Chi2Function(mdc_store, regularization=None, penalties=None, name=None, description=None, verbosity=0)

Bases: TimeIndependentMDCObjectiveFunction

Model-based chi-squared function: N(p-f)^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 per-circuit-outcome 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 hessian-requiring 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.ChiAlphaFunction(mdc_store, regularization=None, penalties=None, name=None, description=None, verbosity=0, alpha=1)

Bases: TimeIndependentMDCObjectiveFunction

Model-based chi-alpha 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 per-circuit-outcome 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 hessian-requiring 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.FreqWeightedChi2Function(mdc_store, regularization=None, penalties=None, name=None, description=None, verbosity=0)

Bases: TimeIndependentMDCObjectiveFunction

Model-based frequency-weighted chi-squared function: N(p-f)^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 per-circuit-outcome 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 hessian-requiring 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.PoissonPicDeltaLogLFunction(mdc_store, regularization=None, penalties=None, name=None, description=None, verbosity=0)

Bases: TimeIndependentMDCObjectiveFunction

Model-based poisson-picture delta log-likelihood function: N*f*log(f/p) - N*(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 per-circuit-outcome 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 hessian-requiring 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.DeltaLogLFunction(mdc_store, regularization=None, penalties=None, name=None, description=None, verbosity=0)

Bases: TimeIndependentMDCObjectiveFunction

Model-based delta log-likelihood 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 per-circuit-outcome 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 hessian-requiring 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.MaxLogLFunction(mdc_store, regularization=None, penalties=None, name=None, description=None, verbosity=0, poisson_picture=True)

Bases: TimeIndependentMDCObjectiveFunction

Model-based maximum-model log-likelihood 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 per-circuit-outcome 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 hessian-requiring 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.TVDFunction(mdc_store, regularization=None, penalties=None, name=None, description=None, verbosity=0)

Bases: TimeIndependentMDCObjectiveFunction

Model-based TVD function: 0.5 * |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 per-circuit-outcome 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 hessian-requiring 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.TimeDependentChi2Function(mdc_store, regularization=None, penalties=None, name=None, description=None, verbosity=0)

Bases: TimeDependentMDCObjectiveFunction

Chi-squared function that can handle time-dependent circuits and data.

This objective function can handle time-dependent circuits - that is, circuits are treated as potentially time-dependent 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 zero-frequency 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 non-CPTP 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 least-squares vector of the objective function.

This is the square-root of the terms-vector returned from :method:`terms`. This vector is the objective function value used by a least-squares optimizer when optimizing this objective function. Note that the existence of this quantity requires that the terms be non-negative. 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 least-squares 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.TimeDependentPoissonPicLogLFunction(mdc_store, regularization=None, penalties=None, name=None, description=None, verbosity=0)

Bases: TimeDependentMDCObjectiveFunction

Poisson-picture delta log-likelihood function that can handle time-dependent circuits and data.

This objective function can handle time-dependent circuits - that is, circuits are treated as potentially time-dependent 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 zero-frequency 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 non-CPTP 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 linear-response 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 least-squares 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 least-squares vector of the objective function.

This is the square-root of the terms-vector returned from :method:`terms`. This vector is the objective function value used by a least-squares optimizer when optimizing this objective function. Note that the existence of this quantity requires that the terms be non-negative. 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 least-squares 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.LogLWildcardFunction(logl_objective_fn, base_pt, wildcard)

Bases: ObjectiveFunction

A wildcard-budget bolt-on to an existing objective function.

Currently, this existing function must be a log-likelihood 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 log-likelihood function.

  • base_pt (numpy.ndarray) – Unused. The model-paramter 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 per-circuit-outcome 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 least-squares vector of the objective function.

This is the square-root of the terms-vector returned from :method:`terms`. This vector is the objective function value used by a least-squares optimizer when optimizing this objective function. Note that the existence of this quantity requires that the terms be non-negative. 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 least-squares 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.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 parameter-space 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 total-count vectors.

class pygsti.objectivefns.EvaluatedModelDatasetCircuitsStore(mdc_store, verbosity)

Bases: ModelDatasetCircuitsStore

Additionally holds quantities at a specific model-parameter-space point.