pygsti.objectivefns.objectivefns.MaxLogLFunction

class MaxLogLFunction(mdc_store, regularization=None, penalties=None, name=None, description=None, verbosity=0, poisson_picture=True, **kwargs)

Bases: TimeIndependentMDCObjectiveFunction

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

Parameters:

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

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

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

• regularization (dict, optional) – Regularization values.

• penalties (dict, optional) – Penalty values. Penalties usually add additional (penalty) terms to the sum of per-circuit-outcome contributions that evaluate to the objective function.

• resource_alloc (ResourceAllocation, optional) – Available resources and how they should be allocated for computations.

• name (str, optional) – A name for this objective function (can be anything).

• description (str, optional) – A description for this objective function (can be anything)

• verbosity (int, optional) – Level of detail to print to stdout.

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

Methods

__init__(mdc_store[, regularization, ...])	Model-based maximum-model log-likelihood function: N*f*log(f)
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.
compute_array_types(method_names, fsim)
create_from(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.
hessian_brute([paramvec])	Computes the Hessian using a brute force approach.
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.
set_penalties([regularize_factor, ...])	Set penalty terms.
terms([paramvec, oob_check, profiler_str])	Compute the terms of the objective function.

Attributes

DOCSTR_TEMPLATE
TEMPLATE_FIELDS
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

hessian_brute(paramvec=None)

Computes the Hessian using a brute force approach.

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:

The hessian of this objective function, of shape (N,N) where N 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, raw_objfn_lsvec_signs=True)

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

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_factor (float, optional) – The prefactor of a L1 regularization term that penalizes parameter vector elements that exceed an absolute value of 1.0. Adds a penalty term: regularize_factor * max(0, |parameter_value| - 1.0) for each model parameter.

• cptp_penalty_factor (float, optional) – The prefactor of a term that penalizes non-CPTP operations. Specifically, adds a cptp_penalty_factor * sqrt(tracenorm(choi_matrix)) penalty utilizing each operation’s (gate’s) Choi matrix.

• spam_penalty_factor (float, optional) – The prefactor of a term that penalizes invalid SPAM operations. Specifically, adds a spam_penalty_factor * sqrt(tracenorm(spam_op)) penalty where spam_op runs over each state preparation’s density matrix and each effect vector’s matrix.

• errorgen_penalty_factor (float, optional) – The prefactor of a term that penalizes nonzero error generators. Specifically, adds a errorgen_penalty_factor * sqrt(sum_i(|errorgen_coeff_i|)) penalty where the sum ranges over all the error generator coefficients of each model operation.

• forcefn_grad (numpy.ndarray, optional) – The gradient of a “forcing function” that is added to the objective function. This is used in the calculation of linear-response error bars.

• shift_fctr (float, optional) – An adjustment prefactor for computing the “shift” that serves as a constant offset of the forcing function, i.e. the forcing function (added to the objective function) is essentially ForceFn = force_shift + dot(forcefn_grad, parameter_vector), and force_shift = shift_fctr * ||forcefn_grad|| * (||forcefn_grad|| + ||parameter_vector||). Here || indicates a frobenius norm. The idea behind all this is that ForceFn as given above must remain positive (for least-squares optimization), and so shift_fctr must be large enough to ensure this is the case. Usually you don’t need to alter the default value.

• prob_clip_interval (tuple, optional) – A (min, max) tuple that specifies the minimum (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:

The number of penalty terms.

Return type:

int

terms(paramvec=None, oob_check=False, profiler_str='TERMS OBJECTIVE')

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.