pygsti.objectivefns.wildcardbudget
Functions related to computation of the log-likelihood.
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. 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 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
- wildcard_vector
- 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.
- primitive_op_labels
- primitive_op_index
- per_op_wildcard_vector
- 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
- 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.
- trivial_param_mapping
- 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.
- reference_values
- reference_name