pygsti.objectivefns.objectivefns
Defines objective-function objects
Module Contents
Classes
A factory class for building objective functions. |
|
So far, this is just a base class for organizational purposes |
|
An objective function that acts on probabilities and counts directly. |
|
Contains all the information that we'd like to persist when performing |
|
Additionally holds quantities at a specific model-parameter-space point. |
|
An objective function whose probabilities and counts are given by a Model and DataSet, respectively. |
|
The function N(p-f)^2 / p |
|
The function N[x + 1/(alpha * x^alpha) - (1 + 1/alpha)] where x := p/f. |
|
The function N(p-f)^2 / f |
|
The function custom_weight^2 (p-f)^2, with custom weights that default to 1. |
|
The function N*f*log(f/p) - N*(f-p). |
|
The function N*f*log(f/p). |
|
The function N*f*log(f) (note this doesn't depend on the probability!). |
|
The function 0.5 * |p-f|. |
|
A time-independent model-based ( |
|
Model-based chi-squared function: N(p-f)^2 / p |
|
Model-based chi-alpha function: N[x + 1/(alpha * x^alpha) - (1 + 1/alpha)] where x := p/f. |
|
Model-based frequency-weighted chi-squared function: N(p-f)^2 / f |
|
Model-based custom-weighted chi-squared function: cw^2 (p-f)^2 |
|
Model-based poisson-picture delta log-likelihood function: N*f*log(f/p) - N*(f-p). |
|
Model-based delta log-likelihood function: N*f*log(f/p). |
|
Model-based maximum-model log-likelihood function: N*f*log(f) |
|
Model-based TVD function: 0.5 * |p-f|. |
|
A time-dependent model-based objective function |
|
Chi-squared function that can handle time-dependent circuits and data. |
|
Poisson-picture delta log-likelihood function that can handle time-dependent circuits and data. |
|
A wildcard-budget bolt-on to an existing objective function. |
|
Holds various values of an objective function at a particular point. |
- class pygsti.objectivefns.objectivefns.ObjectiveFunctionBuilder(cls_to_build, name=None, description=None, regularization=None, penalties=None, **kwargs)
Bases:
pygsti.baseobjs.nicelyserializable.NicelySerializableA 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_buildclass
The
MDCObjectiveFunction-derived objective function class to build.- namestr, optional
A name for the built objective function (can be anything).
- descriptionstr, optional
A description for the built objective function (can be anything)
- regularizationdict, optional
Regularization values (allowed keys depend on cls_to_build).
- penaltiesdict, optional
Penalty values (allowed keys depend on cls_to_build).
- classmethod cast(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
- objNone or str or dict or list or tuple or ObjectiveFunctionBuilder
Object to cast.
Returns
ObjectiveFunctionBuilder
- classmethod create_from(objective='logl', freq_weighted_chi2=False)
Creates common
ObjectiveFunctionBuilderfrom a few arguments.Parameters
- objective{‘logl’, ‘chi2’}, optional
The objective function type: log-likelihood or chi-squared.
- freq_weighted_chi2bool, optional
Whether to use 1/frequency values as the weights in the “chi2” case.
Returns
ObjectiveFunctionBuilder
- compute_array_types(method_names, forwardsim)
- build(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
MDCObjectiveFunctionobject, beyond what is stored in this builder object.Parameters
- modelModel
The model.
- datasetDataSet.
The data set.
- circuitslist
The circuits.
- resource_allocResourceAllocation, optional
Available resources and how they should be allocated for objective function computations.
- verbosityint, optional
Level of detail to print to stdout.
Returns
MDCObjectiveFunction
- build_from_store(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
MDCObjectiveFunctionobject (beyond what is stored in this builder object).Parameters
- mdc_storeModelDatasetCircuitsStore
The store object, which doubles as a cache for reused information.
- verbosityint, optional
Level of detail to print to stdout.
Returns
MDCObjectiveFunction
- class pygsti.objectivefns.objectivefns.ObjectiveFunction
Bases:
objectSo far, this is just a base class for organizational purposes
- chi2k_distributed_qty(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_valuefloat
A value of this objective function, i.e. one returned from self.fn(…).
Returns
float
- class pygsti.objectivefns.objectivefns.RawObjectiveFunction(regularization=None, resource_alloc=None, name=None, description=None, verbosity=0)
Bases:
ObjectiveFunctionAn objective function that acts on probabilities and counts directly.
Every
RawObjectiveFunctionis assumed to perform a “local” function element-wise on the vectors of probabilities, counts (usually for a single outcome), and total-counts (usually for all the outcomes in a group), and sum the results to arrive at the final objective function’s value.That is, the function must be of the form: objective_function = sum_i local_function(probability_i, counts_i, total_counts_i).
Each element of this sum (local_function(probability_i, counts_i, total_counts_i)) is called a term of the objective function. A vector contains the square-roots of the terms is referred to as the least-squares vector (since least-squares optimizers use this vector as their objective function) and is abbreviated “lsvec”.
Parameters
- regularizationdict, optional
Regularization values.
- resource_allocResourceAllocation, optional
Available resources and how they should be allocated for computations.
- namestr, optional
A name for this objective function (can be anything).
- descriptionstr, optional
A description for this objective function (can be anything)
- verbosityint, 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
- regularizationdict, optional
Regularization values.
- resource_allocResourceAllocation, optional
Available resources and how they should be allocated for computations.
- namestr, optional
A name for this objective function (can be anything).
- descriptionstr, optional
A description for this objective function (can be anything)
- verbosityint, optional
Level of detail to print to stdout.
- set_regularization()
Set regularization values.
- fn(probs, counts, total_counts, freqs)
Evaluate the objective function.
Parameters
- probsnumpy.ndarray
Array of probability values.
- countsnumpy.ndarray
Array of count values.
- total_countsnumpy.ndarray
Array of total count values.
- freqsnumpy.ndarray
Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
Returns
float
- jacobian(probs, counts, total_counts, freqs)
Evaluate the derivative of the objective function with respect to the probabilities.
Parameters
- probsnumpy.ndarray
Array of probability values.
- countsnumpy.ndarray
Array of count values.
- total_countsnumpy.ndarray
Array of total count values.
- freqsnumpy.ndarray
Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
Returns
- numpy.ndarray
A 1D array of length equal to that of each argument, corresponding to the derivative with respect to each element of probs.
- hessian(probs, counts, total_counts, freqs)
Evaluate the Hessian of the objective function with respect to the probabilities.
Parameters
- probsnumpy.ndarray
Array of probability values.
- countsnumpy.ndarray
Array of count values.
- total_countsnumpy.ndarray
Array of total count values.
- freqsnumpy.ndarray
Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
Returns
- numpy.ndarray
A 1D array of length equal to that of each argument, corresponding to the 2nd derivative with respect to each element of probs. Note that this is not a 2D matrix because all off-diagonal elements of the Hessian are zero (because only the i-th term depends on the i-th probability).
- 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
- probsnumpy.ndarray
Array of probability values.
- countsnumpy.ndarray
Array of count values.
- total_countsnumpy.ndarray
Array of total count values.
- freqsnumpy.ndarray
Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
- intermediatestuple, optional
Used internally to speed up computations.
Returns
- numpy.ndarray
A 1D array of length equal to that of each array argument.
- 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
- probsnumpy.ndarray
Array of probability values.
- countsnumpy.ndarray
Array of count values.
- total_countsnumpy.ndarray
Array of total count values.
- freqsnumpy.ndarray
Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
- intermediatestuple, optional
Used internally to speed up computations.
Returns
- 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
- probsnumpy.ndarray
Array of probability values.
- countsnumpy.ndarray
Array of count values.
- total_countsnumpy.ndarray
Array of total count values.
- freqsnumpy.ndarray
Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
- intermediatestuple, optional
Used internally to speed up computations.
Returns
- numpy.ndarray
A 1D array of length equal to that of each array argument.
- 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
- probsnumpy.ndarray
Array of probability values.
- countsnumpy.ndarray
Array of count values.
- total_countsnumpy.ndarray
Array of total count values.
- freqsnumpy.ndarray
Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
- intermediatestuple, 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(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()andlsvec()separately, as the former call may require computing the latter.Parameters
- probsnumpy.ndarray
Array of probability values.
- countsnumpy.ndarray
Array of count values.
- total_countsnumpy.ndarray
Array of total count values.
- freqsnumpy.ndarray
Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
- intermediatestuple, optional
Used internally to speed up computations.
Returns
- dlsvec: numpy.ndarray
A 1D array of length equal to that of each array argument.
- lsvec: numpy.ndarray
A 1D array of length equal to that of each array argument.
- hterms(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
- probsnumpy.ndarray
Array of probability values.
- countsnumpy.ndarray
Array of count values.
- total_countsnumpy.ndarray
Array of total count values.
- freqsnumpy.ndarray
Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
- intermediatestuple, optional
Used internally to speed up computations.
Returns
- numpy.ndarray
A 1D array of length equal to that of each array argument.
- 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
- probsnumpy.ndarray
Array of probability values.
- countsnumpy.ndarray
Array of count values.
- total_countsnumpy.ndarray
Array of total count values.
- freqsnumpy.ndarray
Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
- intermediatestuple, optional
Used internally to speed up computations.
Returns
- numpy.ndarray
A 1D array of length equal to that of each array argument.
- abstract zero_freq_terms(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_countsnumpy.ndarray
The total counts.
- probsnumpy.ndarray
The probabilities.
Returns
- numpy.ndarray
A 1D array of the same length as total_counts and probs.
- abstract 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_countsnumpy.ndarray
The total counts.
- probsnumpy.ndarray
The probabilities.
Returns
- numpy.ndarray
A 1D array of the same length as total_counts and probs.
- abstract 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_countsnumpy.ndarray
The total counts.
- probsnumpy.ndarray
The probabilities.
Returns
- numpy.ndarray
A 1D array of the same length as total_counts and probs.
- class pygsti.objectivefns.objectivefns.ModelDatasetCircuitsStore(model, dataset, circuits=None, resource_alloc=None, array_types=(), precomp_layout=None, verbosity=0)
Bases:
objectContains 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
EvaluatedObjectiveFunctionfor a class (TODO??) that holds the values of an objective function at a certain parameter-space point.- property opBasis
- num_data_params()
The number of degrees of freedom in the data used by this objective function.
Returns
int
- add_omitted_freqs(printer=None, force=False)
Detect omitted frequences (assumed to be 0) so we can compute objective fn correctly
- add_count_vectors(force=False)
Ensure this store contains count and total-count vectors.
- class pygsti.objectivefns.objectivefns.EvaluatedModelDatasetCircuitsStore(mdc_store, verbosity)
Bases:
ModelDatasetCircuitsStoreAdditionally holds quantities at a specific model-parameter-space point.
- class pygsti.objectivefns.objectivefns.MDCObjectiveFunction(raw_objfn, mdc_store, verbosity=0)
Bases:
ObjectiveFunction,EvaluatedModelDatasetCircuitsStoreAn objective function whose probabilities and counts are given by a Model and DataSet, respectively.
Instances of this class glue a model, dataset, and circuit list to a “raw” objective function, resulting in an objective function that is a function of model-parameters and contains counts based on a data set.
The model is treated as a function that computes probabilities (as a function of the model’s parameters) for each circuit outcome, and the data set as a function that similarly computes counts (and total-counts).
Parameters
- raw_objfnRawObjectiveFunction
The raw objective function - specifies how probability and count values are turned into objective function values.
- mdlModel
The model - specifies how parameter values are turned into probabilities for each circuit outcome.
- datasetDataSet
The data set - specifies how counts and total_counts are obtained for each circuit outcome.
- circuitslist or CircuitList
The circuit list - specifies what probabilities and counts this objective function compares. If None, then the keys of dataset are used.
- enable_hessianbool, 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.
Attributes
- namestr
The name of this objective function.
- descriptionstr
A description of this objective function.
Create a new MDCObjectiveFunction.
mdc_store is thought to be a normal MDC store, but could also be an evaluated one, in which case should we take enable_hessian from it?
- property name
Name of this objective function.
- property description
A description of this objective function.
- classmethod create_from(raw_objfn, model, dataset, circuits, resource_alloc=None, verbosity=0, array_types=())
- chi2k_distributed_qty(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_valuefloat
A value of this objective function, i.e. one returned from self.fn(…).
Returns
float
- abstract lsvec(paramvec=None, oob_check=False)
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
- paramvecnumpy.ndarray, optional
The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).
- oob_checkbool, optional
Whether the objective function should raise an error if it is being evaluated in an “out of bounds” region.
Returns
- numpy.ndarray
An array of shape (nElements,) where nElements is the number of circuit outcomes.
- abstract dlsvec(paramvec=None)
The derivative (jacobian) of the least-squares vector.
Derivatives are taken with respect to model parameters.
Parameters
- paramvecnumpy.ndarray, optional
The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).
Returns
- numpy.ndarray
An array of shape (nElements,nParams) where nElements is the number of circuit outcomes and nParams is the number of model parameters.
- terms(paramvec=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
- paramvecnumpy.ndarray, optional
The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).
Returns
- numpy.ndarray
An array of shape (nElements,) where nElements is the number of circuit outcomes.
- dterms(paramvec=None)
Compute the jacobian of 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. Differentiation is with respect to model parameters.
Parameters
- paramvecnumpy.ndarray, optional
The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).
Returns
- numpy.ndarray
An array of shape (nElements,nParams) where nElements is the number of circuit outcomes and nParams is the number of model parameters.
- percircuit(paramvec=None)
Compute the per-circuit contributions to this objective function.
These values collect (sum) together the contributions of the outcomes of a single circuit.
Parameters
- paramvecnumpy.ndarray, optional
The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).
Returns
- numpy.ndarray
An array of shape (nCircuits,) where nCircuits is the number of circuits (specified when this objective function was constructed).
- dpercircuit(paramvec=None)
Compute the jacobian of the per-circuit contributions of this objective function.
Parameters
- paramvecnumpy.ndarray, optional
The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).
Returns
- numpy.ndarray
An array of shape (nCircuits, nParams) where nCircuits is the number of circuits and nParams is the number of model parameters (the circuits and model were specified when this objective function was constructed).
- lsvec_percircuit(paramvec=None)
Compute the square root of per-circuit contributions to this objective function.
These values are primarily useful for interfacing with a least-squares optimizer.
Parameters
- paramvecnumpy.ndarray, optional
The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).
Returns
- numpy.ndarray
An array of shape (nCircuits,) where nCircuits is the number of circuits (specified when this objective function was constructed).
- dlsvec_percircuit(paramvec=None)
Compute the jacobian of the sqrt(per-circuit) values given by
lsvec_percircuit().This jacobian is primarily useful for interfacing with a least-squares optimizer.
Parameters
- paramvecnumpy.ndarray, optional
The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).
Returns
- numpy.ndarray
An array of shape (nCircuits, nParams) where nCircuits is the number of circuits and nParams is the number of model parameters (the circuits and model were specified when this objective function was constructed).
- fn_local(paramvec=None)
Evaluate the local value of this objective function.
When the objective function’s layout is distributed, each processor only holds a portion of the objective function terms, and this function returns only the sum of these local terms. See
fn()for the global objective function value.Parameters
- paramvecnumpy.ndarray, optional
The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).
Returns
float
- fn(paramvec=None)
Evaluate the value of this objective function.
Parameters
- paramvecnumpy.ndarray, optional
The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).
Returns
float
- jacobian(paramvec=None)
Compute the Jacobian of this objective function.
Derivatives are takes with respect to model parameters.
Parameters
- paramvecnumpy.ndarray, optional
The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).
Returns
- numpy.ndarray
An array of shape (nParams,) where nParams is the number of model parameters.
- abstract hessian(paramvec=None)
Compute the Hessian of this objective function.
Derivatives are takes with respect to model parameters.
Parameters
- paramvecnumpy.ndarray, optional
The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).
Returns
- numpy.ndarray
An array of shape (nParams, nParams) where nParams is the number of model parameters.
- abstract approximate_hessian(paramvec=None)
Compute an approximate Hessian of this objective function.
This is typically much less expensive than
hessian()and does not require that enable_hessian=True was set upon initialization. It computes an approximation to the Hessian that only utilizes the information in the Jacobian. Derivatives are takes with respect to model parameters.Parameters
- paramvecnumpy.ndarray, optional
The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).
Returns
- numpy.ndarray
An array of shape (nParams, nParams) where nParams is the number of model parameters.
- class pygsti.objectivefns.objectivefns.RawChi2Function(regularization=None, resource_alloc=None, name='chi2', description='Sum of Chi^2', verbosity=0)
Bases:
RawObjectiveFunctionThe function N(p-f)^2 / p
Note that this equals Nf (1-x)^2 / x where x := p/f.
Parameters
- regularizationdict, optional
Regularization values.
- resource_allocResourceAllocation, optional
Available resources and how they should be allocated for computations.
- namestr, optional
A name for this objective function (can be anything).
- descriptionstr, optional
A description for this objective function (can be anything)
- verbosityint, 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
- regularizationdict, optional
Regularization values.
- resource_allocResourceAllocation, optional
Available resources and how they should be allocated for computations.
- namestr, optional
A name for this objective function (can be anything).
- descriptionstr, optional
A description for this objective function (can be anything)
- verbosityint, optional
Level of detail to print to stdout.
- 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_valuefloat
A value of this objective function, i.e. one returned from self.fn(…).
Returns
float
- set_regularization(min_prob_clip_for_weighting=0.0001)
Set regularization values.
Parameters
- min_prob_clip_for_weightingfloat, 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(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
- probsnumpy.ndarray
Array of probability values.
- countsnumpy.ndarray
Array of count values.
- total_countsnumpy.ndarray
Array of total count values.
- freqsnumpy.ndarray
Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
- intermediatestuple, optional
Used internally to speed up computations.
Returns
- numpy.ndarray
A 1D array of length equal to that of each array argument.
- 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
- probsnumpy.ndarray
Array of probability values.
- countsnumpy.ndarray
Array of count values.
- total_countsnumpy.ndarray
Array of total count values.
- freqsnumpy.ndarray
Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
- intermediatestuple, optional
Used internally to speed up computations.
Returns
- numpy.ndarray
A 1D array of length equal to that of each array argument.
- 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
- probsnumpy.ndarray
Array of probability values.
- countsnumpy.ndarray
Array of count values.
- total_countsnumpy.ndarray
Array of total count values.
- freqsnumpy.ndarray
Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
- intermediatestuple, optional
Used internally to speed up computations.
Returns
- numpy.ndarray
A 1D array of length equal to that of each array argument.
- 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
- probsnumpy.ndarray
Array of probability values.
- countsnumpy.ndarray
Array of count values.
- total_countsnumpy.ndarray
Array of total count values.
- freqsnumpy.ndarray
Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
- intermediatestuple, 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(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_countsnumpy.ndarray
The total counts.
- probsnumpy.ndarray
The probabilities.
Returns
- numpy.ndarray
A 1D array of the same length as total_counts and probs.
- 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_countsnumpy.ndarray
The total counts.
- probsnumpy.ndarray
The probabilities.
Returns
- numpy.ndarray
A 1D array of the same length as total_counts and probs.
- 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_countsnumpy.ndarray
The total counts.
- probsnumpy.ndarray
The probabilities.
Returns
- numpy.ndarray
A 1D array of the same length as total_counts and probs.
- class pygsti.objectivefns.objectivefns.RawChiAlphaFunction(regularization=None, resource_alloc=None, name='chialpha', description='Sum of ChiAlpha', verbosity=0, alpha=1)
Bases:
RawObjectiveFunctionThe 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
- regularizationdict, optional
Regularization values.
- resource_allocResourceAllocation, optional
Available resources and how they should be allocated for computations.
- namestr, optional
A name for this objective function (can be anything).
- descriptionstr, optional
A description for this objective function (can be anything)
- verbosityint, optional
Level of detail to print to stdout.
- alphafloat, 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
- regularizationdict, optional
Regularization values.
- resource_allocResourceAllocation, optional
Available resources and how they should be allocated for computations.
- namestr, optional
A name for this objective function (can be anything).
- descriptionstr, optional
A description for this objective function (can be anything)
- verbosityint, optional
Level of detail to print to stdout.
- 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_valuefloat
A value of this objective function, i.e. one returned from self.fn(…).
Returns
float
- set_regularization(pfratio_stitchpt=0.01, pfratio_derivpt=0.01, radius=None, fmin=None)
Set regularization values.
Parameters
- pfratio_stitchptfloat, optional
The x-value (x = probility/frequency ratio) below which the function is replaced with it second-order Taylor expansion.
- pfratio_derivptfloat, 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.
- radiusfloat, 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.
- fminfloat, 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
- 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
- probsnumpy.ndarray
Array of probability values.
- countsnumpy.ndarray
Array of count values.
- total_countsnumpy.ndarray
Array of total count values.
- freqsnumpy.ndarray
Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
- intermediatestuple, optional
Used internally to speed up computations.
Returns
- 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
- probsnumpy.ndarray
Array of probability values.
- countsnumpy.ndarray
Array of count values.
- total_countsnumpy.ndarray
Array of total count values.
- freqsnumpy.ndarray
Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
- intermediatestuple, optional
Used internally to speed up computations.
Returns
- numpy.ndarray
A 1D array of length equal to that of each array argument.
- abstract 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
- probsnumpy.ndarray
Array of probability values.
- countsnumpy.ndarray
Array of count values.
- total_countsnumpy.ndarray
Array of total count values.
- freqsnumpy.ndarray
Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
- intermediatestuple, optional
Used internally to speed up computations.
Returns
- numpy.ndarray
A 1D array of length equal to that of each array argument.
- abstract 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
- probsnumpy.ndarray
Array of probability values.
- countsnumpy.ndarray
Array of count values.
- total_countsnumpy.ndarray
Array of total count values.
- freqsnumpy.ndarray
Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
- intermediatestuple, optional
Used internally to speed up computations.
Returns
- numpy.ndarray
A 1D array of length equal to that of each array argument.
- class pygsti.objectivefns.objectivefns.RawFreqWeightedChi2Function(regularization=None, resource_alloc=None, name='fwchi2', description='Sum of freq-weighted Chi^2', verbosity=0)
Bases:
RawChi2FunctionThe function N(p-f)^2 / f
Parameters
- regularizationdict, optional
Regularization values.
- resource_allocResourceAllocation, optional
Available resources and how they should be allocated for computations.
- namestr, optional
A name for this objective function (can be anything).
- descriptionstr, optional
A description for this objective function (can be anything)
- verbosityint, 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
- regularizationdict, optional
Regularization values.
- resource_allocResourceAllocation, optional
Available resources and how they should be allocated for computations.
- namestr, optional
A name for this objective function (can be anything).
- descriptionstr, optional
A description for this objective function (can be anything)
- verbosityint, optional
Level of detail to print to stdout.
- 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_valuefloat
A value of this objective function, i.e. one returned from self.fn(…).
Returns
float
- set_regularization(min_freq_clip_for_weighting=0.0001)
Set regularization values.
Parameters
- min_freq_clip_for_weightingfloat, 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
- 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_countsnumpy.ndarray
The total counts.
- probsnumpy.ndarray
The probabilities.
Returns
- numpy.ndarray
A 1D array of the same length as total_counts and probs.
- 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_countsnumpy.ndarray
The total counts.
- probsnumpy.ndarray
The probabilities.
Returns
- numpy.ndarray
A 1D array of the same length as total_counts and probs.
- 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_countsnumpy.ndarray
The total counts.
- probsnumpy.ndarray
The probabilities.
Returns
- numpy.ndarray
A 1D array of the same length as total_counts and probs.
- class pygsti.objectivefns.objectivefns.RawCustomWeightedChi2Function(regularization=None, resource_alloc=None, name='cwchi2', description='Sum of custom-weighted Chi^2', verbosity=0, custom_weights=None)
Bases:
RawChi2FunctionThe function custom_weight^2 (p-f)^2, with custom weights that default to 1.
Parameters
- regularizationdict, optional
Regularization values.
- resource_allocResourceAllocation, optional
Available resources and how they should be allocated for computations.
- namestr, optional
A name for this objective function (can be anything).
- descriptionstr, optional
A description for this objective function (can be anything)
- verbosityint, optional
Level of detail to print to stdout.
- custom_weightsnumpy.ndarray, optional
One-dimensional array of the custom weights, which linearly multiply the least-squares terms, i.e. (p - f). If None, then unit weights are used and the objective function computes the sum of unweighted squares.
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
- regularizationdict, optional
Regularization values.
- resource_allocResourceAllocation, optional
Available resources and how they should be allocated for computations.
- namestr, optional
A name for this objective function (can be anything).
- descriptionstr, optional
A description for this objective function (can be anything)
- verbosityint, optional
Level of detail to print to stdout.
- 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_countsnumpy.ndarray
The total counts.
- probsnumpy.ndarray
The probabilities.
Returns
- numpy.ndarray
A 1D array of the same length as total_counts and probs.
- 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_countsnumpy.ndarray
The total counts.
- probsnumpy.ndarray
The probabilities.
Returns
- numpy.ndarray
A 1D array of the same length as total_counts and probs.
- 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_countsnumpy.ndarray
The total counts.
- probsnumpy.ndarray
The probabilities.
Returns
- numpy.ndarray
A 1D array of the same length as total_counts and probs.
- class pygsti.objectivefns.objectivefns.RawPoissonPicDeltaLogLFunction(regularization=None, resource_alloc=None, name='dlogl', description='2*Delta(log(L))', verbosity=0)
Bases:
RawObjectiveFunctionThe function N*f*log(f/p) - N*(f-p).
Note that this equals Nf(-log(x) - 1 + x) where x := p/f.
Parameters
- regularizationdict, optional
Regularization values.
- resource_allocResourceAllocation, optional
Available resources and how they should be allocated for computations.
- namestr, optional
A name for this objective function (can be anything).
- descriptionstr, optional
A description for this objective function (can be anything)
- verbosityint, 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
- regularizationdict, optional
Regularization values.
- resource_allocResourceAllocation, optional
Available resources and how they should be allocated for computations.
- namestr, optional
A name for this objective function (can be anything).
- descriptionstr, optional
A description for this objective function (can be anything)
- verbosityint, optional
Level of detail to print to stdout.
- 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_valuefloat
A value of this objective function, i.e. one returned from self.fn(…).
Returns
float
- set_regularization(min_prob_clip=0.0001, pfratio_stitchpt=None, pfratio_derivpt=None, radius=0.0001, fmin=None)
Set regularization values.
Parameters
- min_prob_clipfloat, 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_stitchptfloat, 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_derivptfloat, 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.
- radiusfloat, 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.
- fminfloat, 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
- 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
- probsnumpy.ndarray
Array of probability values.
- countsnumpy.ndarray
Array of count values.
- total_countsnumpy.ndarray
Array of total count values.
- freqsnumpy.ndarray
Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
- intermediatestuple, optional
Used internally to speed up computations.
Returns
- numpy.ndarray
A 1D array of length equal to that of each array argument.
- 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
- probsnumpy.ndarray
Array of probability values.
- countsnumpy.ndarray
Array of count values.
- total_countsnumpy.ndarray
Array of total count values.
- freqsnumpy.ndarray
Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
- intermediatestuple, optional
Used internally to speed up computations.
Returns
- 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
- probsnumpy.ndarray
Array of probability values.
- countsnumpy.ndarray
Array of count values.
- total_countsnumpy.ndarray
Array of total count values.
- freqsnumpy.ndarray
Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
- intermediatestuple, optional
Used internally to speed up computations.
Returns
- numpy.ndarray
A 1D array of length equal to that of each array argument.
- 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
- probsnumpy.ndarray
Array of probability values.
- countsnumpy.ndarray
Array of count values.
- total_countsnumpy.ndarray
Array of total count values.
- freqsnumpy.ndarray
Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
- intermediatestuple, optional
Used internally to speed up computations.
Returns
- numpy.ndarray
A 1D array of length equal to that of each array argument.
- class pygsti.objectivefns.objectivefns.RawDeltaLogLFunction(regularization=None, resource_alloc=None, name='dlogl', description='2*Delta(log(L))', verbosity=0)
Bases:
RawObjectiveFunctionThe function N*f*log(f/p).
Note that this equals -Nf log(x) where x := p/f.
Parameters
- regularizationdict, optional
Regularization values.
- resource_allocResourceAllocation, optional
Available resources and how they should be allocated for computations.
- namestr, optional
A name for this objective function (can be anything).
- descriptionstr, optional
A description for this objective function (can be anything)
- verbosityint, 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
- regularizationdict, optional
Regularization values.
- resource_allocResourceAllocation, optional
Available resources and how they should be allocated for computations.
- namestr, optional
A name for this objective function (can be anything).
- descriptionstr, optional
A description for this objective function (can be anything)
- verbosityint, optional
Level of detail to print to stdout.
- 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_valuefloat
A value of this objective function, i.e. one returned from self.fn(…).
Returns
float
- set_regularization(min_prob_clip=0.0001, pfratio_stitchpt=None, pfratio_derivpt=None)
Set regularization values.
Parameters
- min_prob_clipfloat, 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_stitchptfloat, 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_derivptfloat, 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
- 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
- probsnumpy.ndarray
Array of probability values.
- countsnumpy.ndarray
Array of count values.
- total_countsnumpy.ndarray
Array of total count values.
- freqsnumpy.ndarray
Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
- intermediatestuple, optional
Used internally to speed up computations.
Returns
- 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
- probsnumpy.ndarray
Array of probability values.
- countsnumpy.ndarray
Array of count values.
- total_countsnumpy.ndarray
Array of total count values.
- freqsnumpy.ndarray
Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
- intermediatestuple, optional
Used internally to speed up computations.
Returns
- numpy.ndarray
A 1D array of length equal to that of each array argument.
- 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
- probsnumpy.ndarray
Array of probability values.
- countsnumpy.ndarray
Array of count values.
- total_countsnumpy.ndarray
Array of total count values.
- freqsnumpy.ndarray
Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
- intermediatestuple, optional
Used internally to speed up computations.
Returns
- numpy.ndarray
A 1D array of length equal to that of each array argument.
- 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
- probsnumpy.ndarray
Array of probability values.
- countsnumpy.ndarray
Array of count values.
- total_countsnumpy.ndarray
Array of total count values.
- freqsnumpy.ndarray
Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
- intermediatestuple, optional
Used internally to speed up computations.
Returns
- numpy.ndarray
A 1D array of length equal to that of each array argument.
- 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
- probsnumpy.ndarray
Array of probability values.
- countsnumpy.ndarray
Array of count values.
- total_countsnumpy.ndarray
Array of total count values.
- freqsnumpy.ndarray
Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
- intermediatestuple, 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(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()andlsvec()separately, as the former call may require computing the latter.Parameters
- probsnumpy.ndarray
Array of probability values.
- countsnumpy.ndarray
Array of count values.
- total_countsnumpy.ndarray
Array of total count values.
- freqsnumpy.ndarray
Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
- intermediatestuple, 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(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
- probsnumpy.ndarray
Array of probability values.
- countsnumpy.ndarray
Array of count values.
- total_countsnumpy.ndarray
Array of total count values.
- freqsnumpy.ndarray
Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
- intermediatestuple, 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(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_countsnumpy.ndarray
The total counts.
- probsnumpy.ndarray
The probabilities.
Returns
- numpy.ndarray
A 1D array of the same length as total_counts and probs.
- 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_countsnumpy.ndarray
The total counts.
- probsnumpy.ndarray
The probabilities.
Returns
- numpy.ndarray
A 1D array of the same length as total_counts and probs.
- 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_countsnumpy.ndarray
The total counts.
- probsnumpy.ndarray
The probabilities.
Returns
- numpy.ndarray
A 1D array of the same length as total_counts and probs.
- class pygsti.objectivefns.objectivefns.RawMaxLogLFunction(regularization=None, resource_alloc=None, name='maxlogl', description='Max LogL', verbosity=0, poisson_picture=True)
Bases:
RawObjectiveFunctionThe function N*f*log(f) (note this doesn’t depend on the probability!).
Parameters
- regularizationdict, optional
Regularization values.
- resource_allocResourceAllocation, optional
Available resources and how they should be allocated for computations.
- namestr, optional
A name for this objective function (can be anything).
- descriptionstr, optional
A description for this objective function (can be anything)
- verbosityint, 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
- regularizationdict, optional
Regularization values.
- resource_allocResourceAllocation, optional
Available resources and how they should be allocated for computations.
- namestr, optional
A name for this objective function (can be anything).
- descriptionstr, optional
A description for this objective function (can be anything)
- verbosityint, optional
Level of detail to print to stdout.
- 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
- probsnumpy.ndarray
Array of probability values.
- countsnumpy.ndarray
Array of count values.
- total_countsnumpy.ndarray
Array of total count values.
- freqsnumpy.ndarray
Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
- intermediatestuple, optional
Used internally to speed up computations.
Returns
- 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
- probsnumpy.ndarray
Array of probability values.
- countsnumpy.ndarray
Array of count values.
- total_countsnumpy.ndarray
Array of total count values.
- freqsnumpy.ndarray
Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
- intermediatestuple, optional
Used internally to speed up computations.
Returns
- numpy.ndarray
A 1D array of length equal to that of each array argument.
- 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
- probsnumpy.ndarray
Array of probability values.
- countsnumpy.ndarray
Array of count values.
- total_countsnumpy.ndarray
Array of total count values.
- freqsnumpy.ndarray
Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
- intermediatestuple, optional
Used internally to speed up computations.
Returns
- numpy.ndarray
A 1D array of length equal to that of each array argument.
- 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
- probsnumpy.ndarray
Array of probability values.
- countsnumpy.ndarray
Array of count values.
- total_countsnumpy.ndarray
Array of total count values.
- freqsnumpy.ndarray
Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
- intermediatestuple, optional
Used internally to speed up computations.
Returns
- numpy.ndarray
A 1D array of length equal to that of each array argument.
- dlsvec(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
- probsnumpy.ndarray
Array of probability values.
- countsnumpy.ndarray
Array of count values.
- total_countsnumpy.ndarray
Array of total count values.
- freqsnumpy.ndarray
Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
- intermediatestuple, 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(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
dlsvec()andlsvec()separately, as the former call may require computing the latter.Parameters
- probsnumpy.ndarray
Array of probability values.
- countsnumpy.ndarray
Array of count values.
- total_countsnumpy.ndarray
Array of total count values.
- freqsnumpy.ndarray
Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
- intermediatestuple, 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(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
- probsnumpy.ndarray
Array of probability values.
- countsnumpy.ndarray
Array of count values.
- total_countsnumpy.ndarray
Array of total count values.
- freqsnumpy.ndarray
Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
- intermediatestuple, 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(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_countsnumpy.ndarray
The total counts.
- probsnumpy.ndarray
The probabilities.
Returns
- numpy.ndarray
A 1D array of the same length as total_counts and probs.
- 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_countsnumpy.ndarray
The total counts.
- probsnumpy.ndarray
The probabilities.
Returns
- numpy.ndarray
A 1D array of the same length as total_counts and probs.
- 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_countsnumpy.ndarray
The total counts.
- probsnumpy.ndarray
The probabilities.
Returns
- numpy.ndarray
A 1D array of the same length as total_counts and probs.
- class pygsti.objectivefns.objectivefns.RawTVDFunction(regularization=None, resource_alloc=None, name='tvd', description='Total Variational Distance (TVD)', verbosity=0)
Bases:
RawObjectiveFunctionThe function 0.5 * |p-f|.
Parameters
- regularizationdict, optional
Regularization values.
- resource_allocResourceAllocation, optional
Available resources and how they should be allocated for computations.
- namestr, optional
A name for this objective function (can be anything).
- descriptionstr, optional
A description for this objective function (can be anything)
- verbosityint, 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
- regularizationdict, optional
Regularization values.
- resource_allocResourceAllocation, optional
Available resources and how they should be allocated for computations.
- namestr, optional
A name for this objective function (can be anything).
- descriptionstr, optional
A description for this objective function (can be anything)
- verbosityint, optional
Level of detail to print to stdout.
- 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
- probsnumpy.ndarray
Array of probability values.
- countsnumpy.ndarray
Array of count values.
- total_countsnumpy.ndarray
Array of total count values.
- freqsnumpy.ndarray
Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
- intermediatestuple, optional
Used internally to speed up computations.
Returns
- numpy.ndarray
A 1D array of length equal to that of each array argument.
- abstract 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
- probsnumpy.ndarray
Array of probability values.
- countsnumpy.ndarray
Array of count values.
- total_countsnumpy.ndarray
Array of total count values.
- freqsnumpy.ndarray
Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
- intermediatestuple, optional
Used internally to speed up computations.
Returns
- numpy.ndarray
A 1D array of length equal to that of each array argument.
- abstract 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
- probsnumpy.ndarray
Array of probability values.
- countsnumpy.ndarray
Array of count values.
- total_countsnumpy.ndarray
Array of total count values.
- freqsnumpy.ndarray
Array of frequency values. This should always equal counts / total_counts but is supplied separately to increase performance.
- intermediatestuple, 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(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_countsnumpy.ndarray
The total counts.
- probsnumpy.ndarray
The probabilities.
Returns
- numpy.ndarray
A 1D array of the same length as total_counts and probs.
- abstract 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_countsnumpy.ndarray
The total counts.
- probsnumpy.ndarray
The probabilities.
Returns
- numpy.ndarray
A 1D array of the same length as total_counts and probs.
- abstract 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_countsnumpy.ndarray
The total counts.
- probsnumpy.ndarray
The probabilities.
Returns
- numpy.ndarray
A 1D array of the same length as total_counts and probs.
- class pygsti.objectivefns.objectivefns.TimeIndependentMDCObjectiveFunction(raw_objfn, mdc_store, penalties=None, verbosity=0)
Bases:
MDCObjectiveFunctionA time-independent model-based (
MDCObjectiveFunction-derived) objective function.Parameters
- raw_objfnRawObjectiveFunction
The raw objective function - specifies how probability and count values are turned into objective function values.
- mdlModel
The model - specifies how parameter values are turned into probabilities for each circuit outcome.
- datasetDataSet
The data set - specifies how counts and total_counts are obtained for each circuit outcome.
- circuitslist or CircuitList
The circuit list - specifies what probabilities and counts this objective function compares. If None, then the keys of dataset are used.
- regularizationdict, optional
Regularization values.
- penaltiesdict, optional
Penalty values. Penalties usually add additional (penalty) terms to the sum of per-circuit-outcome contributions that evaluate to the objective function.
- resource_allocResourceAllocation, optional
Available resources and how they should be allocated for computations.
- namestr, optional
A name for this objective function (can be anything).
- descriptionstr, optional
A description for this objective function (can be anything)
- verbosityint, optional
Level of detail to print to stdout.
- enable_hessianbool, 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.
Create a new MDCObjectiveFunction.
mdc_store is thought to be a normal MDC store, but could also be an evaluated one, in which case should we take enable_hessian from it?
- classmethod builder(name=None, description=None, regularization=None, penalties=None, **kwargs)
Create an
ObjectiveFunctionBuilderthat builds an objective function of this type.Parameters
- namestr, optional
A name for the built objective function (can be anything).
- descriptionstr, optional
A description for the built objective function (can be anything)
- regularizationdict, optional
Regularization values.
- penaltiesdict, optional
Penalty values.
Returns
ObjectiveFunctionBuilder
- classmethod create_from(raw_objfn, model, dataset, circuits, resource_alloc=None, penalties=None, verbosity=0, method_names=('fn',), array_types=())
- classmethod compute_array_types(method_names, fsim)
- set_penalties(regularize_factor=0, cptp_penalty_factor=0, spam_penalty_factor=0, errorgen_penalty_factor=0, forcefn_grad=None, shift_fctr=100, prob_clip_interval=(-10000, 1000))
Set penalty terms.
Parameters
- regularize_factorfloat, 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_factorfloat, 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_factorfloat, 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_factorfloat, 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_gradnumpy.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_fctrfloat, 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_intervaltuple, 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.
- lsvec(paramvec=None, oob_check=False)
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
- paramvecnumpy.ndarray, optional
The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).
- oob_checkbool, optional
Whether the objective function should raise an error if it is being evaluated in an “out of bounds” region.
Returns
- numpy.ndarray
An array of shape (nElements,) where nElements is the number of circuit outcomes.
- terms(paramvec=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
- paramvecnumpy.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(paramvec=None)
The derivative (jacobian) of the least-squares vector.
Derivatives are taken with respect to model parameters.
Parameters
- paramvecnumpy.ndarray, optional
The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).
Returns
- numpy.ndarray
An array of shape (nElements,nParams) where nElements is the number of circuit outcomes and nParams is the number of model parameters.
- dterms(paramvec=None)
Compute the jacobian of 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. Differentiation is with respect to model parameters.
Parameters
- paramvecnumpy.ndarray, optional
The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).
Returns
- numpy.ndarray
An array of shape (nElements,nParams) where nElements is the number of circuit outcomes and nParams is the number of model parameters.
- hessian_brute(paramvec=None)
Computes the Hessian using a brute force approach.
Parameters
- paramvecnumpy.ndarray, optional
The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).
Returns
- numpy.ndarray
The hessian of this objective function, of shape (N,N) where N is the number of model parameters.
- approximate_hessian(paramvec=None)
Compute an approximate Hessian of this objective function.
This is typically much less expensive than
hessian()and does not require that enable_hessian=True was set upon initialization. It computes an approximation to the Hessian that only utilizes the information in the Jacobian. Derivatives are takes with respect to model parameters.Parameters
- paramvecnumpy.ndarray, optional
The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).
Returns
- numpy.ndarray
An array of shape (nParams, nParams) where nParams is the number of model parameters.
- hessian(paramvec=None)
Compute the Hessian of this objective function.
Derivatives are takes with respect to model parameters.
Parameters
- paramvecnumpy.ndarray, optional
The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).
Returns
- numpy.ndarray
An array of shape (nParams, nParams) where nParams is the number of model parameters.
- class pygsti.objectivefns.objectivefns.Chi2Function(mdc_store, regularization=None, penalties=None, name=None, description=None, verbosity=0)
Bases:
TimeIndependentMDCObjectiveFunctionModel-based chi-squared function: N(p-f)^2 / p
Parameters
- mdlModel
The model - specifies how parameter values are turned into probabilities for each circuit outcome.
- datasetDataSet
The data set - specifies how counts and total_counts are obtained for each circuit outcome.
- circuitslist or CircuitList
The circuit list - specifies what probabilities and counts this objective function compares. If None, then the keys of dataset are used.
- regularizationdict, optional
Regularization values.
- penaltiesdict, optional
Penalty values. Penalties usually add additional (penalty) terms to the sum of per-circuit-outcome contributions that evaluate to the objective function.
- resource_allocResourceAllocation, optional
Available resources and how they should be allocated for computations.
- namestr, optional
A name for this objective function (can be anything).
- descriptionstr, optional
A description for this objective function (can be anything)
- verbosityint, optional
Level of detail to print to stdout.
- enable_hessianbool, 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.
Create a new MDCObjectiveFunction.
mdc_store is thought to be a normal MDC store, but could also be an evaluated one, in which case should we take enable_hessian from it?
- classmethod create_from(model, dataset, circuits, regularization=None, penalties=None, resource_alloc=None, name=None, description=None, verbosity=0, method_names=('fn',), array_types=())
- class pygsti.objectivefns.objectivefns.ChiAlphaFunction(mdc_store, regularization=None, penalties=None, name=None, description=None, verbosity=0, alpha=1)
Bases:
TimeIndependentMDCObjectiveFunctionModel-based chi-alpha function: N[x + 1/(alpha * x^alpha) - (1 + 1/alpha)] where x := p/f.
Parameters
- mdlModel
The model - specifies how parameter values are turned into probabilities for each circuit outcome.
- datasetDataSet
The data set - specifies how counts and total_counts are obtained for each circuit outcome.
- circuitslist or CircuitList
The circuit list - specifies what probabilities and counts this objective function compares. If None, then the keys of dataset are used.
- regularizationdict, optional
Regularization values.
- penaltiesdict, optional
Penalty values. Penalties usually add additional (penalty) terms to the sum of per-circuit-outcome contributions that evaluate to the objective function.
- resource_allocResourceAllocation, optional
Available resources and how they should be allocated for computations.
- namestr, optional
A name for this objective function (can be anything).
- descriptionstr, optional
A description for this objective function (can be anything)
- verbosityint, optional
Level of detail to print to stdout.
- enable_hessianbool, 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.
- alphafloat, optional
The alpha parameter, which lies in the interval (0,1].
Create a new MDCObjectiveFunction.
mdc_store is thought to be a normal MDC store, but could also be an evaluated one, in which case should we take enable_hessian from it?
- classmethod create_from(model, dataset, circuits, regularization=None, penalties=None, resource_alloc=None, name=None, description=None, verbosity=0, method_names=('fn',), array_types=(), alpha=1)
- class pygsti.objectivefns.objectivefns.FreqWeightedChi2Function(mdc_store, regularization=None, penalties=None, name=None, description=None, verbosity=0)
Bases:
TimeIndependentMDCObjectiveFunctionModel-based frequency-weighted chi-squared function: N(p-f)^2 / f
Parameters
- mdlModel
The model - specifies how parameter values are turned into probabilities for each circuit outcome.
- datasetDataSet
The data set - specifies how counts and total_counts are obtained for each circuit outcome.
- circuitslist or CircuitList
The circuit list - specifies what probabilities and counts this objective function compares. If None, then the keys of dataset are used.
- regularizationdict, optional
Regularization values.
- penaltiesdict, optional
Penalty values. Penalties usually add additional (penalty) terms to the sum of per-circuit-outcome contributions that evaluate to the objective function.
- resource_allocResourceAllocation, optional
Available resources and how they should be allocated for computations.
- namestr, optional
A name for this objective function (can be anything).
- descriptionstr, optional
A description for this objective function (can be anything)
- verbosityint, optional
Level of detail to print to stdout.
- enable_hessianbool, 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.
Create a new MDCObjectiveFunction.
mdc_store is thought to be a normal MDC store, but could also be an evaluated one, in which case should we take enable_hessian from it?
- classmethod create_from(model, dataset, circuits, regularization=None, penalties=None, resource_alloc=None, name=None, description=None, verbosity=0, method_names=('fn',), array_types=())
- class pygsti.objectivefns.objectivefns.CustomWeightedChi2Function(mdc_store, regularization=None, penalties=None, name=None, description=None, verbosity=0, custom_weights=None)
Bases:
TimeIndependentMDCObjectiveFunctionModel-based custom-weighted chi-squared function: cw^2 (p-f)^2
Parameters
- mdlModel
The model - specifies how parameter values are turned into probabilities for each circuit outcome.
- datasetDataSet
The data set - specifies how counts and total_counts are obtained for each circuit outcome.
- circuitslist or CircuitList
The circuit list - specifies what probabilities and counts this objective function compares. If None, then the keys of dataset are used.
- regularizationdict, optional
Regularization values.
- penaltiesdict, optional
Penalty values. Penalties usually add additional (penalty) terms to the sum of per-circuit-outcome contributions that evaluate to the objective function.
- resource_allocResourceAllocation, optional
Available resources and how they should be allocated for computations.
- namestr, optional
A name for this objective function (can be anything).
- descriptionstr, optional
A description for this objective function (can be anything)
- verbosityint, optional
Level of detail to print to stdout.
- enable_hessianbool, 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.
- custom_weightsnumpy.ndarray, optional
One-dimensional array of the custom weights, which linearly multiply the least-squares terms, i.e. (p - f). If None, then unit weights are used and the objective function computes the sum of unweighted squares.
Create a new MDCObjectiveFunction.
mdc_store is thought to be a normal MDC store, but could also be an evaluated one, in which case should we take enable_hessian from it?
- classmethod create_from(model, dataset, circuits, regularization=None, penalties=None, resource_alloc=None, name=None, description=None, verbosity=0, method_names=('fn',), array_types=(), custom_weights=None)
- class pygsti.objectivefns.objectivefns.PoissonPicDeltaLogLFunction(mdc_store, regularization=None, penalties=None, name=None, description=None, verbosity=0)
Bases:
TimeIndependentMDCObjectiveFunctionModel-based poisson-picture delta log-likelihood function: N*f*log(f/p) - N*(f-p).
Parameters
- mdlModel
The model - specifies how parameter values are turned into probabilities for each circuit outcome.
- datasetDataSet
The data set - specifies how counts and total_counts are obtained for each circuit outcome.
- circuitslist or CircuitList
The circuit list - specifies what probabilities and counts this objective function compares. If None, then the keys of dataset are used.
- regularizationdict, optional
Regularization values.
- penaltiesdict, optional
Penalty values. Penalties usually add additional (penalty) terms to the sum of per-circuit-outcome contributions that evaluate to the objective function.
- resource_allocResourceAllocation, optional
Available resources and how they should be allocated for computations.
- namestr, optional
A name for this objective function (can be anything).
- descriptionstr, optional
A description for this objective function (can be anything)
- verbosityint, optional
Level of detail to print to stdout.
- enable_hessianbool, 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.
Create a new MDCObjectiveFunction.
mdc_store is thought to be a normal MDC store, but could also be an evaluated one, in which case should we take enable_hessian from it?
- classmethod create_from(model, dataset, circuits, regularization=None, penalties=None, resource_alloc=None, name=None, description=None, verbosity=0, method_names=('fn',), array_types=())
- class pygsti.objectivefns.objectivefns.DeltaLogLFunction(mdc_store, regularization=None, penalties=None, name=None, description=None, verbosity=0)
Bases:
TimeIndependentMDCObjectiveFunctionModel-based delta log-likelihood function: N*f*log(f/p).
Parameters
- mdlModel
The model - specifies how parameter values are turned into probabilities for each circuit outcome.
- datasetDataSet
The data set - specifies how counts and total_counts are obtained for each circuit outcome.
- circuitslist or CircuitList
The circuit list - specifies what probabilities and counts this objective function compares. If None, then the keys of dataset are used.
- regularizationdict, optional
Regularization values.
- penaltiesdict, optional
Penalty values. Penalties usually add additional (penalty) terms to the sum of per-circuit-outcome contributions that evaluate to the objective function.
- resource_allocResourceAllocation, optional
Available resources and how they should be allocated for computations.
- namestr, optional
A name for this objective function (can be anything).
- descriptionstr, optional
A description for this objective function (can be anything)
- verbosityint, optional
Level of detail to print to stdout.
- enable_hessianbool, 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.
Create a new MDCObjectiveFunction.
mdc_store is thought to be a normal MDC store, but could also be an evaluated one, in which case should we take enable_hessian from it?
- classmethod create_from(model, dataset, circuits, regularization=None, penalties=None, resource_alloc=None, name=None, description=None, verbosity=0, method_names=('fn',), array_types=())
- class pygsti.objectivefns.objectivefns.MaxLogLFunction(mdc_store, regularization=None, penalties=None, name=None, description=None, verbosity=0, poisson_picture=True)
Bases:
TimeIndependentMDCObjectiveFunctionModel-based maximum-model log-likelihood function: N*f*log(f)
Parameters
- mdlModel
The model - specifies how parameter values are turned into probabilities for each circuit outcome.
- datasetDataSet
The data set - specifies how counts and total_counts are obtained for each circuit outcome.
- circuitslist or CircuitList
The circuit list - specifies what probabilities and counts this objective function compares. If None, then the keys of dataset are used.
- regularizationdict, optional
Regularization values.
- penaltiesdict, optional
Penalty values. Penalties usually add additional (penalty) terms to the sum of per-circuit-outcome contributions that evaluate to the objective function.
- resource_allocResourceAllocation, optional
Available resources and how they should be allocated for computations.
- namestr, optional
A name for this objective function (can be anything).
- descriptionstr, optional
A description for this objective function (can be anything)
- verbosityint, optional
Level of detail to print to stdout.
- enable_hessianbool, 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.
Create a new MDCObjectiveFunction.
mdc_store is thought to be a normal MDC store, but could also be an evaluated one, in which case should we take enable_hessian from it?
- classmethod create_from(model, dataset, circuits, regularization=None, penalties=None, resource_alloc=None, name=None, description=None, verbosity=0, method_names=('fn',), array_types=(), poisson_picture=True)
- class pygsti.objectivefns.objectivefns.TVDFunction(mdc_store, regularization=None, penalties=None, name=None, description=None, verbosity=0)
Bases:
TimeIndependentMDCObjectiveFunctionModel-based TVD function: 0.5 * |p-f|.
Parameters
- mdlModel
The model - specifies how parameter values are turned into probabilities for each circuit outcome.
- datasetDataSet
The data set - specifies how counts and total_counts are obtained for each circuit outcome.
- circuitslist or CircuitList
The circuit list - specifies what probabilities and counts this objective function compares. If None, then the keys of dataset are used.
- regularizationdict, optional
Regularization values.
- penaltiesdict, optional
Penalty values. Penalties usually add additional (penalty) terms to the sum of per-circuit-outcome contributions that evaluate to the objective function.
- resource_allocResourceAllocation, optional
Available resources and how they should be allocated for computations.
- namestr, optional
A name for this objective function (can be anything).
- descriptionstr, optional
A description for this objective function (can be anything)
- verbosityint, optional
Level of detail to print to stdout.
- enable_hessianbool, 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.
Create a new MDCObjectiveFunction.
mdc_store is thought to be a normal MDC store, but could also be an evaluated one, in which case should we take enable_hessian from it?
- classmethod create_from(model, dataset, circuits, regularization=None, penalties=None, resource_alloc=None, name=None, description=None, verbosity=0, method_names=('fn',), array_types=())
- class pygsti.objectivefns.objectivefns.TimeDependentMDCObjectiveFunction(mdc_store, regularization=None, penalties=None, name=None, description=None, verbosity=0)
Bases:
MDCObjectiveFunctionA time-dependent model-based objective function
Parameters
- mdlModel
The model - specifies how parameter values are turned into probabilities for each circuit outcome.
- datasetDataSet
The data set - specifies how counts and total_counts are obtained for each circuit outcome.
- circuitslist or CircuitList
The circuit list - specifies what probabilities and counts this objective function compares. If None, then the keys of dataset are used.
- regularizationdict, optional
Regularization values.
- penaltiesdict, optional
Penalty values. Penalties usually add additional (penalty) terms to the sum of per-circuit-outcome contributions that evaluate to the objective function.
- resource_allocResourceAllocation, optional
Available resources and how they should be allocated for computations.
- namestr, optional
A name for this objective function (can be anything).
- verbosityint, optional
Level of detail to print to stdout.
Create a new MDCObjectiveFunction.
mdc_store is thought to be a normal MDC store, but could also be an evaluated one, in which case should we take enable_hessian from it?
- classmethod builder(name=None, description=None, regularization=None, penalties=None, **kwargs)
Create an
ObjectiveFunctionBuilderthat builds an objective function of this type.Parameters
- namestr, optional
A name for the built objective function (can be anything).
- descriptionstr, optional
A description for the built objective function (can be anything)
- regularizationdict, optional
Regularization values.
- penaltiesdict, optional
Penalty values.
Returns
ObjectiveFunctionBuilder
- classmethod create_from(model, dataset, circuits, regularization=None, penalties=None, resource_alloc=None, name=None, description=None, verbosity=0, method_names=('fn',), array_types=())
- classmethod compute_array_types(method_names, fsim)
- set_penalties()
Set penalty terms.
- abstract lsvec(paramvec=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
- paramvecnumpy.ndarray, optional
The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).
Returns
- numpy.ndarray
An array of shape (nElements,) where nElements is the number of circuit outcomes.
- abstract dlsvec(paramvec=None)
The derivative (jacobian) of the least-squares vector.
Derivatives are taken with respect to model parameters.
Parameters
- paramvecnumpy.ndarray, optional
The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).
Returns
- numpy.ndarray
An array of shape (nElements,nParams) where nElements is the number of circuit outcomes and nParams is the number of model parameters.
- class pygsti.objectivefns.objectivefns.TimeDependentChi2Function(mdc_store, regularization=None, penalties=None, name=None, description=None, verbosity=0)
Bases:
TimeDependentMDCObjectiveFunctionChi-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.
Create a new MDCObjectiveFunction.
mdc_store is thought to be a normal MDC store, but could also be an evaluated one, in which case should we take enable_hessian from it?
- set_regularization(min_prob_clip_for_weighting=0.0001, radius=0.0001)
Set regularization values.
Parameters
- min_prob_clip_for_weightingfloat, 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).
- radiusfloat, optional
Affects sharpness of the regularization of zero-frequency terms.
Returns
None
- set_penalties(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_factorfloat, 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_factorfloat, 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_factorfloat, 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_factorfloat, 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_intervaltuple, 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(objective_function_value)
Convert a value of this objective function to one that is expected to be chi2_k distributed.
Parameters
- objective_function_valuefloat
A value of this objective function, i.e. one returned from self.fn(…).
Returns
float
- lsvec(paramvec=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
- paramvecnumpy.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(paramvec=None)
The derivative (jacobian) of the least-squares vector.
Derivatives are taken with respect to model parameters.
Parameters
- paramvecnumpy.ndarray, optional
The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).
Returns
- numpy.ndarray
An array of shape (nElements,nParams) where nElements is the number of circuit outcomes and nParams is the number of model parameters.
- class pygsti.objectivefns.objectivefns.TimeDependentPoissonPicLogLFunction(mdc_store, regularization=None, penalties=None, name=None, description=None, verbosity=0)
Bases:
TimeDependentMDCObjectiveFunctionPoisson-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.
Create a new MDCObjectiveFunction.
mdc_store is thought to be a normal MDC store, but could also be an evaluated one, in which case should we take enable_hessian from it?
- set_regularization(min_prob_clip=0.0001, radius=0.0001)
Set regularization values.
Parameters
- min_prob_clipfloat, optional
The probability below which the objective function is replaced with its second order Taylor expansion.
- radiusfloat, optional
Affects sharpness of the regularization of zero-frequency terms.
Returns
None
- set_penalties(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_factorfloat, 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_factorfloat, 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_factorfloat, 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_gradnumpy.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_fctrfloat, 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_intervaltuple, 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(objective_function_value)
Convert a value of this objective function to one that is expected to be chi2_k distributed.
Parameters
- objective_function_valuefloat
A value of this objective function, i.e. one returned from self.fn(…).
Returns
float
- lsvec(paramvec=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
- paramvecnumpy.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(paramvec=None)
The derivative (jacobian) of the least-squares vector.
Derivatives are taken with respect to model parameters.
Parameters
- paramvecnumpy.ndarray, optional
The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).
Returns
- numpy.ndarray
An array of shape (nElements,nParams) where nElements is the number of circuit outcomes and nParams is the number of model parameters.
- class pygsti.objectivefns.objectivefns.LogLWildcardFunction(logl_objective_fn, base_pt, wildcard)
Bases:
ObjectiveFunctionA 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_fnPoissonPicDeltaLogLFunction
The bare log-likelihood function.
- base_ptnumpy.ndarray
Unused. The model-paramter vector where this objective function is based.
- wildcardWildcardBudget
The wildcard budget that adjusts the “bare” probabilities of logl_objective_fn before evaluating the rest of the 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.
Parameters
- objective_function_valuefloat
A value of this objective function, i.e. one returned from self.fn(…).
Returns
float
- fn(wvec=None)
Evaluate this objective function.
Parameters
- wvecnumpy.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(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
- wvecnumpy.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(wvec=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
- wvecnumpy.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(wvec)
The derivative (jacobian) of the least-squares vector.
Derivatives are taken with respect to wildcard budget parameters.
Parameters
- wvecnumpy.ndarray, optional
The vector of (wildcard budget) parameters to evaluate the objective function at. If None, then the budget’s current parameter vector is used (held internally).
Returns
- numpy.ndarray
An array of shape (nElements,nParams) where nElements is the number of circuit outcomes and nParams is the number of wildcard budget parameters.
- class pygsti.objectivefns.objectivefns.CachedObjectiveFunction(objective_function)
Bases:
pygsti.baseobjs.nicelyserializable.NicelySerializableHolds various values of an objective function at a particular point.
This object is meant to be serializable, and not to facilitate computing the objective function anywhere else. It doesn’t contain or rely on comm objects. It does contain a serial or “global” layout that allows us to make sense of the elements of various probability vectors, etc., but we demand that this layout not depend on comm objects.
The cache may only have values on the rank-0 proc (??)
- collection_name = 'pygsti_cached_objective_fns'
- classmethod from_dir(dirname, quick_load=False)
Initialize a new CachedObjectiveFunction object from dirname.
- quick_loadbool, optional
Setting this to True skips the loading of components that may take a long time to load.
Parameters
- dirnamestr
The directory name.
- quick_loadbool, optional
Setting this to True skips the loading of components that may take a long time to load.
Returns
CachedObjectiveFunction