pygsti.objectivefns.objectivefns.RawFreqWeightedChi2Function

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

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.
hterms_alt(probs, counts, total_counts, freqs)	Alternate computation of 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([min_freq_clip_for_weighting])	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).

Attributes

DEFAULT_MIN_PROB_CLIP_FOR_WEIGHTING

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, 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:

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

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

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(min_freq_clip_for_weighting=None)

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).

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