pygsti.objectivefns.wildcardbudget

Functions related to computation of the log-likelihood.

Module Contents

Classes

WildcardBudget

A fixed wildcard budget.

PrimitiveOpsWildcardBudget

A wildcard budget containing one parameter per "primitive operation".

Functions

_compute_tvd(a, b, d, alpha, beta, pushedD, q, f)

_compute_alpha(a, b, c, d, tvd, q, f)

_compute_beta(a, b, c, d, tvd, q, f)

_compute_pvec(alpha, beta, pushedD, a, b, c, d, q, f)

_alpha_fn(beta, a, b, c, q, f, empty_val=1.0)

_beta_fn(alpha, a, b, c, q, f, empty_val=1.0)

_pushedD_fn(beta, b, c, q, f)

_get_nextalpha_breakpoint(remaining_ratios)

_chk_sum(alpha, beta, fvec, A, B, C)

_adjust_qvec_to_be_nonnegative_and_unit_sum(qvec, W, min_qvec, circ=None)

update_circuit_probs(probs, freqs, circuit_budget)

Attributes

pos

pygsti.objectivefns.wildcardbudget.pos
class pygsti.objectivefns.wildcardbudget.WildcardBudget(w_vec)

Bases: object

A fixed wildcard budget.

Encapsulates a fixed amount of “wildcard budget” that allows each circuit an amount “slack” in its outcomes probabilities. The way in which this slack is computed - or “distributed”, though it need not necessarily sum to a fixed total - per circuit depends on each derived class’s implementation of the :method:`circuit_budget` method. Goodness-of-fit quantities such as the log-likelihood or chi2 can utilize a WildcardBudget object to compute a value that shifts the circuit outcome probabilities within their allowed slack (so |p_used - p_actual| <= slack) to achieve the best goodness of fit. For example, see the wildcard argument of :function:`two_delta_logl_terms`.

This is a base class, which must be inherited from in order to obtain a full functional wildcard budge (the circuit_budget method must be implemented and usually __init__ should accept more customized args).

Parameters

w_vec (numpy.array) – vector of wildcard budget components.

to_vector(self)

Get the parameters of this wildcard budget.

Returns

numpy array

from_vector(self, w_vec)

Set the parameters of this wildcard budge.

Parameters

w_vec (numpy array) – A vector of parameter values.

Returns

None

property num_params(self)

The number of parameters of this wildcard budget.

Returns

int

abstract circuit_budget(self, circuit)

Get the amount of wildcard budget, or “outcome-probability-slack” for circuit.

Parameters

circuit (Circuit) – the circuit to get the budget for.

Returns

float

circuit_budgets(self, circuits, precomp=None)

Get the wildcard budgets for a list of circuits.

Parameters
  • circuits (list) – The list of circuits to act on.

  • precomp (numpy.ndarray, optional) – A precomputed quantity that speeds up the computation of circuit budgets. Given by :method:`precompute_for_same_circuits`.

Returns

numpy.ndarray

property description(self)

A dictionary of quantities describing this budget.

Return the contents of this budget in a dictionary containing (description, value) pairs for each element name.

Returns

dict

abstract precompute_for_same_circuits(self, circuits)

Compute a pre-computed quantity for speeding up circuit calculations.

This value can be passed to update_probs or circuit_budgets whenever this same circuits list is passed to update_probs to speed things up.

Parameters

circuits (list) – A list of Circuit objects.

Returns

object

slow_update_probs(self, probs_in, probs_out, freqs, layout, precomp=None)

Updates probs_in to probs_out by applying this wildcard budget.

Update a set of circuit outcome probabilities, probs_in, into a corresponding set, probs_out, which uses the slack alloted to each outcome probability to match (as best as possible) the data frequencies in freqs. In particular, it computes this best-match in a way that maximizes the likelihood between probs_out and freqs. This method is the core function of a WildcardBudget.

Parameters
  • probs_in (numpy array) – The input probabilities, usually computed by a Model.

  • probs_out (numpy array) – The output probabilities: probs_in, adjusted according to the slack allowed by this wildcard budget, in order to maximize logl(probs_out, freqs). Note that probs_out may be the same array as probs_in for in-place updating.

  • freqs (numpy array) – An array of frequencies corresponding to each of the outcome probabilites in probs_in or probs_out.

  • layout (CircuitOutcomeProbabilityArrayLayout) – The layout for probs_in, probs_out, and freqs, specifying how array indices correspond to circuit outcomes, as well as the list of circuits.

  • precomp (numpy.ndarray, optional) – A precomputed quantity for speeding up this calculation.

Returns

None

precompute_for_same_probs_freqs(self, probs_in, freqs, layout)
update_probs(self, probs_in, probs_out, freqs, layout, precomp=None, probs_freqs_precomp=None, return_deriv=False)

Updates probs_in to probs_out by applying this wildcard budget.

Update a set of circuit outcome probabilities, probs_in, into a corresponding set, probs_out, which uses the slack alloted to each outcome probability to match (as best as possible) the data frequencies in freqs. In particular, it computes this best-match in a way that maximizes the likelihood between probs_out and freqs. This method is the core function of a WildcardBudget.

Parameters
  • probs_in (numpy array) – The input probabilities, usually computed by a Model.

  • probs_out (numpy array) – The output probabilities: probs_in, adjusted according to the slack allowed by this wildcard budget, in order to maximize logl(probs_out, freqs). Note that probs_out may be the same array as probs_in for in-place updating.

  • freqs (numpy array) – An array of frequencies corresponding to each of the outcome probabilites in probs_in or probs_out.

  • layout (CircuitOutcomeProbabilityArrayLayout) – The layout for probs_in, probs_out, and freqs, specifying how array indices correspond to circuit outcomes, as well as the list of circuits.

  • precomp (numpy.ndarray, optional) – A precomputed quantity for speeding up this calculation.

  • probs_freqs_precomp (list, optional) – A precomputed list of quantities re-used when calling update_probs using the same probs_in, freqs, and layout. Generate by calling :method:`precompute_for_same_probs_freqs`.

  • return_deriv (bool, optional) – When True, returns the derivative of each updated probability with respect to its circuit budget as a numpy array. Useful for internal methods.

Returns

None

class pygsti.objectivefns.wildcardbudget.PrimitiveOpsWildcardBudget(primitive_op_labels, start_budget=0.0, idle_name=None)

Bases: WildcardBudget

A wildcard budget containing one parameter per “primitive operation”.

A parameter’s absolute value gives the amount of “slack”, or “wildcard budget” that is allocated per that particular primitive operation.

Primitive operations are the components of circuit layers, and so the wilcard budget for a circuit is just the sum of the (abs vals of) the parameters corresponding to each primitive operation in the circuit.

Parameters
  • primitive_op_labels (iterable or dict) – A list of primitive-operation labels, e.g. Label(‘Gx’,(0,)), which give all the possible primitive ops (components of circuit layers) that will appear in circuits. Each one of these operations will be assigned it’s own independent element in the wilcard-vector. A dictionary can be given whose keys are Labels and whose values are 0-based parameter indices. In the non-dictionary case, each label gets it’s own parameter. Dictionaries allow multiple labels to be associated with the same wildcard budget parameter, e.g. {Label(‘Gx’,(0,)): 0, Label(‘Gy’,(0,)): 0}. If ‘SPAM’ is included as a primitive op, this value correspond to a uniform “SPAM budget” added to each circuit.

  • start_budget (float or dict, optional) – An initial value to set all the parameters to (if a float), or a dictionary mapping primitive operation labels to initial values.

circuit_budget(self, circuit)

Get the amount of wildcard budget, or “outcome-probability-slack” for circuit.

Parameters

circuit (Circuit) – the circuit to get the budget for.

Returns

float

circuit_budgets(self, circuits, precomp=None)

Get the wildcard budgets for a list of circuits.

Parameters
  • circuits (list) – The list of circuits to act on.

  • precomp (numpy.ndarray, optional) – A precomputed quantity that speeds up the computation of circuit budgets. Given by :method:`precompute_for_same_circuits`.

Returns

numpy.ndarray

precompute_for_same_circuits(self, circuits)

Compute a pre-computed quantity for speeding up circuit calculations.

This value can be passed to update_probs or circuit_budgets whenever this same circuits list is passed to update_probs to speed things up.

Parameters

circuits (list) – A list of Circuit objects.

Returns

object

property description(self)

A dictionary of quantities describing this budget.

Return the contents of this budget in a dictionary containing (description, value) pairs for each element name.

Returns

dict – Keys are primitive op labels and values are (description_string, value) tuples.

budget_for(self, op_label)

Retrieve the budget amount correponding to primitive op op_label.

This is just the absolute value of this wildcard budget’s parameter that corresponds to op_label.

Parameters

op_label (Label) – The operation label to extract a budget for.

Returns

float

__str__(self)

Return str(self).

pygsti.objectivefns.wildcardbudget._compute_tvd(a, b, d, alpha, beta, pushedD, q, f)
pygsti.objectivefns.wildcardbudget._compute_alpha(a, b, c, d, tvd, q, f)
pygsti.objectivefns.wildcardbudget._compute_beta(a, b, c, d, tvd, q, f)
pygsti.objectivefns.wildcardbudget._compute_pvec(alpha, beta, pushedD, a, b, c, d, q, f)
pygsti.objectivefns.wildcardbudget._alpha_fn(beta, a, b, c, q, f, empty_val=1.0)
pygsti.objectivefns.wildcardbudget._beta_fn(alpha, a, b, c, q, f, empty_val=1.0)
pygsti.objectivefns.wildcardbudget._pushedD_fn(beta, b, c, q, f)
pygsti.objectivefns.wildcardbudget._get_nextalpha_breakpoint(remaining_ratios)
pygsti.objectivefns.wildcardbudget._chk_sum(alpha, beta, fvec, A, B, C)
pygsti.objectivefns.wildcardbudget._adjust_qvec_to_be_nonnegative_and_unit_sum(qvec, W, min_qvec, circ=None)
pygsti.objectivefns.wildcardbudget.update_circuit_probs(probs, freqs, circuit_budget)