pygsti.objectivefns.objectivefns.MDCObjectiveFunction

class MDCObjectiveFunction(raw_objfn, mdc_store, verbosity=0, **kwargs)

Bases: ObjectiveFunction, EvaluatedModelDatasetCircuitsStore

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

Instances of this class glue a model, dataset, and circuit list to a “raw” objective function, resulting in an objective function that is a function of 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_objfn (RawObjectiveFunction) – The raw objective function - specifies how probability and count values are turned into objective function values.

• mdl (Model) – The model - specifies how parameter values are turned into probabilities for each circuit outcome.

• dataset (DataSet) – The data set - specifies how counts and total_counts are obtained for each circuit outcome.

• circuits (list or CircuitList) – The circuit list - specifies what probabilities and counts this objective function compares. If None, then the keys of dataset are used.

• enable_hessian (bool, optional) – Whether hessian calculations are allowed. If True then more resources are needed. If False, calls to hessian-requiring function will result in an error.

name

The name of this objective function.

Type:

str

description

A description of this objective function.

Type:

str

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?

Methods

__init__(raw_objfn, mdc_store[, verbosity])	Create a new MDCObjectiveFunction.
add_count_vectors([force])	Ensure this store contains count and total-count vectors.
add_omitted_freqs([printer, force])	Detect omitted frequencies (assumed to be 0) so we can compute objective fn correctly
approximate_hessian([paramvec])	Compute an approximate Hessian of this 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.
create_from(raw_objfn, model, dataset, circuits)
dlsvec([paramvec])	The derivative (jacobian) of the least-squares vector.
dlsvec_percircuit([paramvec])	Compute the jacobian of the sqrt(per-circuit) values given by lsvec_percircuit().
dpercircuit([paramvec])	Compute the jacobian of the per-circuit contributions of this objective function.
dterms([paramvec])	Compute the jacobian of the terms of the objective function.
fn([paramvec, stateless])	Evaluate the value of this objective function.
fn_from_model(model)	Evaluate this objective function when self.model is replaced by model, and then restore self.model before returning.
fn_local([paramvec, stateless])	Evaluate the local value of this objective function.
hessian([paramvec])	Compute the Hessian of this objective function.
jacobian([paramvec])	Compute the Jacobian of this objective function.
lsvec([paramvec, oob_check])	Compute the least-squares vector of the objective function.
lsvec_percircuit([paramvec])	Compute the square root of per-circuit contributions to this objective function.
num_data_params()	The number of degrees of freedom in the data used by this objective function.
percircuit([paramvec])	Compute the per-circuit contributions to this objective function.
terms([paramvec])	Compute the terms of the objective function.

Attributes

description	A description of this objective function.
name	Name of this objective function.
opBasis

add_count_vectors(force=False)

Ensure this store contains count and total-count vectors.

add_omitted_freqs(printer=None, force=False)

Detect omitted frequencies (assumed to be 0) so we can compute objective fn correctly

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:

paramvec (numpy.ndarray, optional) – The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).

Returns:

An array of shape (nParams, nParams) where nParams is the number of model parameters.

Return type:

numpy.ndarray

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_value (float) – A value of this objective function, i.e. one returned from self.fn(…).

Return type:

float

dlsvec(paramvec=None)

The derivative (jacobian) of the least-squares vector.

Derivatives are taken with respect to model parameters.

Parameters:

paramvec (numpy.ndarray, optional) – The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).

Returns:

An array of shape (nElements,nParams) where nElements is the number of circuit outcomes and nParams is the number of model parameters.

Return type:

numpy.ndarray

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:

paramvec (numpy.ndarray, optional) – The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).

Returns:

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

Return type:

numpy.ndarray

dpercircuit(paramvec=None)

Compute the jacobian of the per-circuit contributions of this objective function.

Parameters:

paramvec (numpy.ndarray, optional) – The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).

Returns:

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

Return type:

numpy.ndarray

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:

paramvec (numpy.ndarray, optional) – The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).

Returns:

An array of shape (nElements,nParams) where nElements is the number of circuit outcomes and nParams is the number of model parameters.

Return type:

numpy.ndarray

fn(paramvec=None, stateless=False)

Evaluate the value of this objective function.

Parameters:

• paramvec (numpy.ndarray, optional) – The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).

• stateless (bool) – The callsequence triggered by this function can modify self.model. If stateless=True, then we restore self.model’s state before returning.

Return type:

float

fn_from_model(model)

Evaluate this objective function when self.model is replaced by model, and then restore self.model before returning.

Return type:

float

fn_local(paramvec=None, stateless=False)

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:

• paramvec (numpy.ndarray, optional) – The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).

• stateless (bool) – The callsequence triggered by this function can modify self.model. If stateless=True, then we restore self.model’s state before returning.

Return type:

float

hessian(paramvec=None)

Compute the Hessian of this objective function.

Derivatives are takes with respect to model parameters.

Parameters:

paramvec (numpy.ndarray, optional) – The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).

Returns:

An array of shape (nParams, nParams) where nParams is the number of model parameters.

Return type:

numpy.ndarray

jacobian(paramvec=None)

Compute the Jacobian of this objective function.

Derivatives are takes with respect to model parameters.

Parameters:

paramvec (numpy.ndarray, optional) – The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).

Returns:

An array of shape (nParams,) where nParams is the number of model parameters.

Return type:

numpy.ndarray

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:

• paramvec (numpy.ndarray, optional) – The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).

• oob_check (bool, optional) – Whether the objective function should raise an error if it is being evaluated in an “out of bounds” region.

Returns:

An array of shape (nElements,) where nElements is the number of circuit outcomes.

Return type:

numpy.ndarray

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:

paramvec (numpy.ndarray, optional) – The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).

Returns:

An array of shape (nCircuits,) where nCircuits is the number of circuits (specified when this objective function was constructed).

Return type:

numpy.ndarray

num_data_params()

The number of degrees of freedom in the data used by this objective function.

Return type:

int

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:

paramvec (numpy.ndarray, optional) – The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).

Returns:

An array of shape (nCircuits,) where nCircuits is the number of circuits (specified when this objective function was constructed).

Return type:

numpy.ndarray

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:

paramvec (numpy.ndarray, optional) – The vector of (model) parameters to evaluate the objective function at. If None, then the model’s current parameter vector is used (held internally).

Returns:

An array of shape (nElements,) where nElements is the number of circuit outcomes.

Return type:

numpy.ndarray

property description

A description of this objective function.

property name

Name of this objective function.