pygsti.objectivefns.objectivefns.RawChiAlphaFunction

class 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].

Create a raw objective function.

A raw objective function acts on “raw” probabilities and counts, and is usually a statistic comparing the probabilities to count data.

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.

Methods

__init__([regularization, resource_alloc, ...])	Create a raw objective function.
chi2k_distributed_qty(objective_function_value)	Convert a value of this objective function to one that is expected to be chi2_k distributed.
dlsvec(probs, counts, total_counts, freqs[, ...])	Compute the derivatives of the least-squares vector of this objective function.
dlsvec_and_lsvec(probs, counts, ...[, ...])	Compute the derivatives of the least-squares vector together with the vector itself.
dterms(probs, counts, total_counts, freqs[, ...])	Compute the derivatives of the terms of this objective function.
fn(probs, counts, total_counts, freqs)	Evaluate the objective function.
hessian(probs, counts, total_counts, freqs)	Evaluate the Hessian of the objective function with respect to the probabilities.
hlsvec(probs, counts, total_counts, freqs)	Compute the 2nd derivatives of the least-squares vector of this objective function.
hterms(probs, counts, total_counts, freqs[, ...])	Compute the 2nd derivatives of the terms of this objective function.
jacobian(probs, counts, total_counts, freqs)	Evaluate the derivative of the objective function with respect to the probabilities.
lsvec(probs, counts, total_counts, freqs[, ...])	Compute the least-squares vector of the objective function.
set_regularization([pfratio_stitchpt, ...])	Set regularization values.
terms(probs, counts, total_counts, freqs[, ...])	Compute the terms of the objective function.
zero_freq_dterms(total_counts, probs)	Evaluate the derivative of zero-frequency objective function terms.
zero_freq_hterms(total_counts, probs)	Evaluate the 2nd derivative of zero-frequency objective function terms.
zero_freq_terms(total_counts, probs)	Evaluate objective function terms with zero frequency (where count and frequency are zero).

chi2k_distributed_qty(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(…).

Return type:

float

dlsvec(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:

A 1D array of length equal to that of each array argument.

Return type:

numpy.ndarray

dlsvec_and_lsvec(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 dlsvec() and 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.

dterms(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:

A 1D array of length equal to that of each array argument.

Return type:

numpy.ndarray

fn(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.

Return type:

float

hessian(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:

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 off-diagonal elements of the Hessian are zero (because only the i-th term depends on the i-th probability).

Return type:

numpy.ndarray

hlsvec(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:

A 1D array of length equal to that of each array argument.

Return type:

numpy.ndarray

hterms(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:

A 1D array of length equal to that of each array argument.

Return type:

numpy.ndarray

jacobian(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:

A 1D array of length equal to that of each argument, corresponding to the derivative with respect to each element of probs.

Return type:

numpy.ndarray

lsvec(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 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:

A 1D array of length equal to that of each array argument.

Return type:

numpy.ndarray

set_regularization(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.

Return type:

None

terms(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:

A 1D array of length equal to that of each array argument.

Return type:

numpy.ndarray

zero_freq_dterms(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:

A 1D array of the same length as total_counts and probs.

Return type:

numpy.ndarray

zero_freq_hterms(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:

A 1D array of the same length as total_counts and probs.

Return type:

numpy.ndarray

zero_freq_terms(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:

A 1D array of the same length as total_counts and probs.

Return type:

numpy.ndarray