pygsti.objectivefns.wildcardbudget

Functions related to computation of the log-likelihood.

Module Contents

Classes

WildcardBudget

A fixed wildcard budget.

PrimitiveOpsWildcardBudgetBase

A base class for wildcard budget objects that allocate wildcard error per "primitive operation".

PrimitiveOpsWildcardBudget

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

PrimitiveOpsSingleScaleWildcardBudget

A wildcard budget containing a single scaling parameter.

Functions

update_circuit_probs(probs, freqs, circuit_budget[, ...])

Attributes

pos

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

Bases: pygsti.baseobjs.NicelySerializable

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 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 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_vecnumpy.array

vector of wildcard budget components.

Create a new WildcardBudget.

Parameters

w_vecnumpy array

The “wildcard vector” which stores the parameters of this budget which can be varied when trying to find an optimal budget (similar to the parameters of a Model).

property num_params

The number of parameters of this wildcard budget.

Returns

int

abstract property description

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

to_vector()

Get the parameters of this wildcard budget.

Returns

numpy array

from_vector(w_vec)

Set the parameters of this wildcard budget.

Parameters
w_vecnumpy array

A vector of parameter values.

Returns

None

abstract circuit_budget(circuit)

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

Parameters
circuitCircuit

the circuit to get the budget for.

Returns

float

circuit_budgets(circuits, precomp=None)

Get the wildcard budgets for a list of circuits.

Parameters
circuitslist

The list of circuits to act on.

precompnumpy.ndarray, optional

A precomputed quantity that speeds up the computation of circuit budgets. Given by precompute_for_same_circuits().

Returns

numpy.ndarray

abstract precompute_for_same_circuits(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
circuitslist

A list of Circuit objects.

Returns

object

slow_update_probs(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_innumpy array

The input probabilities, usually computed by a Model.

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

freqsnumpy array

An array of frequencies corresponding to each of the outcome probabilites in probs_in or probs_out.

layoutCircuitOutcomeProbabilityArrayLayout

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

precompnumpy.ndarray, optional

A precomputed quantity for speeding up this calculation.

Returns

None

precompute_for_same_probs_freqs(probs_in, freqs, layout)
update_probs(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_innumpy array

The input probabilities, usually computed by a Model.

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

freqsnumpy array

An array of frequencies corresponding to each of the outcome probabilites in probs_in or probs_out.

layoutCircuitOutcomeProbabilityArrayLayout

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

precompnumpy.ndarray, optional

A precomputed quantity for speeding up this calculation.

probs_freqs_precomplist, optional

A precomputed list of quantities re-used when calling update_probs using the same probs_in, freqs, and layout. Generate by calling precompute_for_same_probs_freqs().

return_derivbool, 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.PrimitiveOpsWildcardBudgetBase(primitive_op_labels, wildcard_vector, idle_name=None)

Bases: WildcardBudget

A base class for wildcard budget objects that allocate wildcard error per “primitive operation”.

The amount of wildcard error for a primitive operation gives the amount of “slack” that is allocated per that particular operation.

Primitive operations are the components of circuit layers, and so the wilcard budget for a circuit is just the sum of the wildcard errors corresponding to each primitive operation in the circuit.

Parameters

primitive_op_labelsiterable

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.

wildcard_vectornumpy.ndarray

An initial wildcard vector of the parameter values of this budget.

idle_namestr, optional

The gate name to be used for the 1-qubit idle gate. If not None, then circuit budgets are computed by considering layers of the circuit as being “padded” with 1-qubit idles gates on any empty lines.

Create a new WildcardBudget.

Parameters

w_vecnumpy array

The “wildcard vector” which stores the parameters of this budget which can be varied when trying to find an optimal budget (similar to the parameters of a Model).

property num_primitive_ops
property wildcard_error_per_op
property description

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.

from_vector(w_vec)

Set the parameters of this wildcard budget.

Parameters
w_vecnumpy array

A vector of parameter values.

Returns

None

circuit_budget(circuit)

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

Parameters
circuitCircuit

the circuit to get the budget for.

Returns

float

circuit_budgets(circuits, precomp=None)

Get the wildcard budgets for a list of circuits.

Parameters
circuitslist

The list of circuits to act on.

precompnumpy.ndarray, optional

A precomputed quantity that speeds up the computation of circuit budgets. Given by precompute_for_same_circuits().

Returns

numpy.ndarray

precompute_for_same_circuits(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
circuitslist

A list of Circuit objects.

Returns

object

budget_for(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_labelLabel

The operation label to extract a budget for.

Returns

float

pygsti.objectivefns.wildcardbudget.update_circuit_probs(probs, freqs, circuit_budget, circuit=None)
class pygsti.objectivefns.wildcardbudget.PrimitiveOpsWildcardBudget(primitive_op_labels, start_budget=0.0, idle_name=None)

Bases: PrimitiveOpsWildcardBudgetBase

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_labelsiterable 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_budgetfloat 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.

Create a new PrimitiveOpsWildcardBudget.

Parameters

primitive_op_labelsiterable 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_budgetfloat 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.

idle_namestr, optional

The gate name to be used for the 1-qubit idle gate. If not None, then circuit budgets are computed by considering layers of the circuit as being “padded” with 1-qubit idles gates on any empty lines.

class pygsti.objectivefns.wildcardbudget.PrimitiveOpsSingleScaleWildcardBudget(primitive_op_labels, reference_values=None, alpha=0, idle_name=None, reference_name=None)

Bases: PrimitiveOpsWildcardBudgetBase

A wildcard budget containing a single scaling parameter.

This type of wildcard budget has a single parameter, and sets the wildcard error of each primitive op to be this scale parameter multiplied by a fixed reference value for the primitive op.

Typically, the reference values are chosen to be a modeled metric of gate quality, such as a gate’s gauge-optimized diamond distance to its target gate. Then, once a feasible wildcard error vector is found, the scaling parameter is the fractional increase of the metric (e.g. the diamond distance) of each primitive op needed to reconcile the model and data.

Parameters

primitive_op_labelslist

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.

reference_valueslist, optional

A list of the reference values for each primitive op, in the same order as primitive_op_list.

alphafloat, optional

The initial value of the single scaling parameter that multiplies the reference values of each op to give the wildcard error that op.

idle_namestr, optional

The gate name to be used for the 1-qubit idle gate. If not None, then circuit budgets are computed by considering layers of the circuit as being “padded” with 1-qubit idles gates on any empty lines.

Create a new WildcardBudget.

Parameters

w_vecnumpy array

The “wildcard vector” which stores the parameters of this budget which can be varied when trying to find an optimal budget (similar to the parameters of a Model).

property alpha
property description

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.