pygsti.objectivefns.wildcardbudget
Functions related to computation of the loglikelihood.
Module Contents
Classes
A fixed wildcard budget. 

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

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

A wildcard budget containing a single scaling parameter. 
Functions

Attributes
 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. Goodnessoffit quantities such as the loglikelihood 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 oftwo_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
).
 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
 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 “outcomeprobabilityslack” 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 precomputed 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 bestmatch 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 inplace 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 bestmatch 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 inplace 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 reused 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 primitiveoperation 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 1qubit idle gate. If not None, then circuit budgets are computed by considering layers of the circuit as being “padded” with 1qubit 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 “outcomeprobabilityslack” 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 precomputed 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
 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 primitiveoperation 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 wilcardvector. A dictionary can be given whose keys are Labels and whose values are 0based parameter indices. In the nondictionary 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 primitiveoperation 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 wilcardvector. A dictionary can be given whose keys are Labels and whose values are 0based parameter indices. In the nondictionary 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 1qubit idle gate. If not None, then circuit budgets are computed by considering layers of the circuit as being “padded” with 1qubit 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 gaugeoptimized 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 primitiveoperation 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 1qubit idle gate. If not None, then circuit budgets are computed by considering layers of the circuit as being “padded” with 1qubit 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