pygsti.forwardsims.forwardsim
¶
Defines the ForwardSimulator calculator class
Module Contents¶
Classes¶
A calculator of circuit outcome probability calculations and their derivatives w.r.t. model parameters. 

A forward simulator that works with nondistributed 
Functions¶
Return all the arraytype letters that stand for a parameter dimension 




 class pygsti.forwardsims.forwardsim.ForwardSimulator(model=None)¶
Bases:
pygsti.baseobjs.nicelyserializable.NicelySerializable
A calculator of circuit outcome probability calculations and their derivatives w.r.t. model parameters.
Some forward simulators may also be used to perform operationproduct calculations.
This functionality exists in a class separate from Model to allow for additional model classes (e.g. ones which use entirely different – nongatelocal – parameterizations of operation matrices and SPAM vectors) access to these fundamental operations. It also allows for the easier addition of new forward simulators.
Note: a model holds or “contains” a forward simulator instance to perform its computations, and a forward simulator holds a reference to its parent model, so we need to make sure the forward simulator doesn’t serialize the model or we have a circular reference.
 Parameters
model (Model, optional) – The model this forward simulator will use to compute circuit outcome probabilities.
 classmethod cast(cls, obj, num_qubits=None)¶
num_qubits only used if obj == ‘auto’
 classmethod _array_types_for_method(cls, method_name)¶
 _to_nice_serialization(self)¶
 classmethod _from_nice_serialization(cls, state)¶
 __getstate__(self)¶
 property model(self)¶
 _set_evotype(self, evotype)¶
Called when the evotype being used (defined by the parent model) changes. evotype will be None when the current model is None
 abstract _compute_circuit_outcome_probabilities(self, array_to_fill, circuit, outcomes, resource_alloc, time=None)¶
 abstract _compute_sparse_circuit_outcome_probabilities(self, circuit, resource_alloc, time=None)¶
 abstract _compute_circuit_outcome_probability_derivatives(self, array_to_fill, circuit, outcomes, param_slice, resource_alloc)¶
 probs(self, circuit, outcomes=None, time=None, resource_alloc=None)¶
Construct a dictionary containing the outcome probabilities for a single circuit.
 Parameters
circuit (Circuit or tuple of operation labels) – The sequence of operation labels specifying the circuit.
outcomes (list or tuple) – A sequence of outcomes, which can themselves be either tuples (to include intermediate measurements) or simple strings, e.g. ‘010’. If None, only nonzero outcome probabilities will be reported.
time (float, optional) – The start time at which circuit is evaluated.
resource_alloc (ResourceAllocation, optional) – The resources available for computing circuit outcome probabilities.
 Returns
probs (OutcomeLabelDict) – A dictionary with keys equal to outcome labels and values equal to probabilities. If no target outcomes provided, only nonzero probabilities will be reported.
 dprobs(self, circuit, resource_alloc=None)¶
Construct a dictionary containing outcome probability derivatives for a single circuit.
 Parameters
circuit (Circuit or tuple of operation labels) – The sequence of operation labels specifying the circuit.
resource_alloc (ResourceAllocation, optional) – The resources available for computing circuit outcome probability derivatives.
 Returns
dprobs (OutcomeLabelDict) – A dictionary with keys equal to outcome labels and values equal to an array containing the (partial) derivatives of the outcome probability with respect to all model parameters.
 hprobs(self, circuit, resource_alloc=None)¶
Construct a dictionary containing outcome probability Hessians for a single circuit.
 Parameters
circuit (Circuit or tuple of operation labels) – The sequence of operation labels specifying the circuit.
resource_alloc (ResourceAllocation, optional) – The resources available for computing circuit outcome probability Hessians.
 Returns
hprobs (OutcomeLabelDict) – A dictionary with keys equal to outcome labels and values equal to a 2D array that is the Hessian matrix for the corresponding outcome probability (with respect to all model parameters).
 create_layout(self, circuits, dataset=None, resource_alloc=None, array_types=(), derivative_dimensions=None, verbosity=0)¶
Constructs an circuitoutcomeprobabilityarray (COPA) layout for circuits and dataset.
 Parameters
circuits (list) – The circuits whose outcome probabilities should be computed.
dataset (DataSet) – The source of data counts that will be compared to the circuit outcome probabilities. The computed outcome probabilities are limited to those with counts present in dataset.
resource_alloc (ResourceAllocation) – A available resources and allocation information. These factors influence how the layout (evaluation strategy) is constructed.
array_types (tuple, optional) – A tuple of stringvalued array types, as given by :method:`CircuitOutcomeProbabilityArrayLayout.allocate_local_array`. These types determine what types of arrays we anticipate computing using this layout (and forward simulator). These are used to check available memory against the limit (if it exists) within resource_alloc. The array types also determine the number of derivatives that this layout is able to compute. So, for example, if you ever want to compute derivatives or Hessians of element arrays then array_types must contain at least one ‘ep’ or ‘epp’ type, respectively or the layout will not allocate needed intermediate storage for derivativecontaining types. If you don’t care about accurate memory limits, use (‘e’,) when you only ever compute probabilities and never their derivatives, and (‘e’,’ep’) or (‘e’,’ep’,’epp’) if you need to compute Jacobians or Hessians too.
derivative_dimensions (tuple, optional) – A tuple containing, optionally, the parameterspace dimension used when taking first and second derivatives with respect to the cirucit outcome probabilities. This must be have minimally 1 or 2 elements when array_types contains ‘ep’ or ‘epp’ types, respectively.
verbosity (int or VerbosityPrinter) – Determines how much output to send to stdout. 0 means no output, higher integers mean more output.
 Returns
CircuitOutcomeProbabilityArrayLayout
 bulk_probs(self, circuits, clip_to=None, resource_alloc=None, smartc=None)¶
Construct a dictionary containing the probabilities for an entire list of circuits.
 Parameters
circuits (list of Circuits) – The list of circuits. May also be a
CircuitOutcomeProbabilityArrayLayout
object containing precomputed quantities that make this function run faster.clip_to (2tuple, optional) – (min,max) to clip return value if not None.
resource_alloc (ResourceAllocation, optional) – A resource allocation object describing the available resources and a strategy for partitioning them.
smartc (SmartCache, optional) – A cache object to cache & use previously cached values inside this function.
 Returns
probs (dictionary) – A dictionary such that probs[circuit] is an ordered dictionary of outcome probabilities whose keys are outcome labels.
 bulk_dprobs(self, circuits, resource_alloc=None, smartc=None)¶
Construct a dictionary containing the probability derivatives for an entire list of circuits.
 Parameters
circuits (list of Circuits) – The list of circuits. May also be a
CircuitOutcomeProbabilityArrayLayout
object containing precomputed quantities that make this function run faster.resource_alloc (ResourceAllocation, optional) – A resource allocation object describing the available resources and a strategy for partitioning them.
smartc (SmartCache, optional) – A cache object to cache & use previously cached values inside this function.
 Returns
dprobs (dictionary) – A dictionary such that dprobs[circuit] is an ordered dictionary of derivative arrays (one element per differentiated parameter) whose keys are outcome labels
 bulk_hprobs(self, circuits, resource_alloc=None, smartc=None)¶
Construct a dictionary containing the probability Hessians for an entire list of circuits.
 Parameters
circuits (list of Circuits) – The list of circuits. May also be a
CircuitOutcomeProbabilityArrayLayout
object containing precomputed quantities that make this function run faster.resource_alloc (ResourceAllocation, optional) – A resource allocation object describing the available resources and a strategy for partitioning them.
smartc (SmartCache, optional) – A cache object to cache & use previously cached values inside this function.
 Returns
hprobs (dictionary) – A dictionary such that hprobs[circuit] is an ordered dictionary of Hessian arrays (a square matrix with one row/column per differentiated parameter) whose keys are outcome labels
 bulk_fill_probs(self, array_to_fill, layout)¶
Compute the outcome probabilities for a list circuits.
This routine fills a 1D array, array_to_fill with circuit outcome probabilities as dictated by a
CircuitOutcomeProbabilityArrayLayout
(“COPA layout”) object, which is usually specifically tailored for efficiency.The array_to_fill array must have length equal to the number of elements in layout, and the meanings of each element are given by layout.
 Parameters
array_to_fill (numpy ndarray) – an alreadyallocated 1D numpy array of length equal to the total number of computed elements (i.e. len(layout)).
layout (CircuitOutcomeProbabilityArrayLayout) – A layout for array_to_fill, describing what circuit outcome each element corresponds to. Usually given by a prior call to :method:`create_layout`.
 Returns
None
 _bulk_fill_probs(self, array_to_fill, layout)¶
 _bulk_fill_probs_block(self, array_to_fill, layout)¶
 _bulk_fill_probs_at_times(self, array_to_fill, layout, times)¶
 _bulk_fill_probs_block_at_times(self, array_to_fill, layout, times)¶
 bulk_fill_dprobs(self, array_to_fill, layout, pr_array_to_fill=None)¶
Compute the outcome probabilityderivatives for an entire tree of circuits.
This routine fills a 2D array, array_to_fill with circuit outcome probabilities as dictated by a
CircuitOutcomeProbabilityArrayLayout
(“COPA layout”) object, which is usually specifically tailored for efficiency.The array_to_fill array must have length equal to the number of elements in layout, and the meanings of each element are given by layout.
 Parameters
array_to_fill (numpy ndarray) – an alreadyallocated 2D numpy array of shape (len(layout), Np), where Np is the number of model parameters being differentiated with respect to.
layout (CircuitOutcomeProbabilityArrayLayout) – A layout for array_to_fill, describing what circuit outcome each element corresponds to. Usually given by a prior call to :method:`create_layout`.
pr_mx_to_fill (numpy array, optional) – when not None, an alreadyallocated lengthlen(layout) numpy array that is filled with probabilities, just as in :method:`bulk_fill_probs`.
 Returns
None
 _bulk_fill_dprobs(self, array_to_fill, layout, pr_array_to_fill)¶
 _bulk_fill_dprobs_block(self, array_to_fill, dest_param_slice, layout, param_slice)¶
 bulk_fill_hprobs(self, array_to_fill, layout, pr_array_to_fill=None, deriv1_array_to_fill=None, deriv2_array_to_fill=None)¶
Compute the outcome probabilityHessians for an entire list of circuits.
Similar to bulk_fill_probs(…), but fills a 3D array with the Hessians for each circuit outcome probability.
 Parameters
array_to_fill (numpy ndarray) – an alreadyallocated numpy array of shape (len(layout),M1,M2) where M1 and M2 are the number of selected model parameters (by wrt_filter1 and wrt_filter2).
layout (CircuitOutcomeProbabilityArrayLayout) – A layout for array_to_fill, describing what circuit outcome each element corresponds to. Usually given by a prior call to :method:`create_layout`.
pr_mx_to_fill (numpy array, optional) – when not None, an alreadyallocated lengthlen(layout) numpy array that is filled with probabilities, just as in :method:`bulk_fill_probs`.
deriv1_array_to_fill (numpy array, optional) – when not None, an alreadyallocated numpy array of shape (len(layout),M1) that is filled with probability derivatives, similar to :method:`bulk_fill_dprobs` (see array_to_fill for a definition of M1).
deriv2_array_to_fill (numpy array, optional) – when not None, an alreadyallocated numpy array of shape (len(layout),M2) that is filled with probability derivatives, similar to :method:`bulk_fill_dprobs` (see array_to_fill for a definition of M2).
 Returns
None
 _bulk_fill_hprobs(self, array_to_fill, layout, pr_array_to_fill, deriv1_array_to_fill, deriv2_array_to_fill)¶
 _bulk_fill_hprobs_block(self, array_to_fill, dest_param_slice1, dest_param_slice2, layout, param_slice1, param_slice2)¶
 iter_hprobs_by_rectangle(self, layout, wrt_slices_list, return_dprobs_12=False)¶
Iterates over the 2nd derivatives of a layout’s circuit probabilities one rectangle at a time.
This routine can be useful when memory constraints make constructing the entire Hessian at once impractical, and as it only computes a subset of the Hessian’s rows and colums (a “rectangle”) at once. For example, the Hessian of a function of many circuit probabilities can often be computed rectanglebyrectangle and without the need to ever store the entire Hessian at once.
 Parameters
layout (CircuitOutcomeProbabilityArrayLayout) – A layout for generated arrays, describing what circuit outcome each element corresponds to. Usually given by a prior call to :method:`create_layout`.
wrt_slices_list (list) – A list of (rowSlice,colSlice) 2tuples, each of which specify a “rectangle” of the Hessian to compute. Iterating over the output of this function iterates over these computed rectangles, in the order given by wrt_slices_list. rowSlice and colSlice must by Python slice objects.
return_dprobs_12 (boolean, optional) – If true, the generator computes a 2tuple: (hessian_col, d12_col), where d12_col is a column of the matrix d12 defined by: d12[iSpamLabel,iOpStr,p1,p2] = dP/d(p1)*dP/d(p2) where P is is the probability generated by the sequence and spam label indexed by iOpStr and iSpamLabel. d12 has the same dimensions as the Hessian, and turns out to be useful when computing the Hessian of functions of the probabilities.
 Returns
rectangle_generator – A generator which, when iterated, yields the 3tuple (rowSlice, colSlice, hprobs) or (rowSlice, colSlice, hprobs, dprobs12) (the latter if return_dprobs_12 == True). rowSlice and colSlice are slices directly from wrt_slices_list. hprobs and dprobs12 are arrays of shape E x B x B’, where:
E is the length of layout elements
B is the number of parameter rows (the length of rowSlice)
B’ is the number of parameter columns (the length of colSlice)
If mx, dp1, and dp2 are the outputs of
bulk_fill_hprobs()
(i.e. args mx_to_fill, deriv1_mx_to_fill, and deriv2_mx_to_fill), then:hprobs == mx[:,rowSlice,colSlice]
dprobs12 == dp1[:,rowSlice,None] * dp2[:,None,colSlice]
 _iter_hprobs_by_rectangle(self, layout, wrt_slices_list, return_dprobs_12)¶
 __str__(self)¶
Return str(self).
 class pygsti.forwardsims.forwardsim.CacheForwardSimulator(model=None)¶
Bases:
ForwardSimulator
A forward simulator that works with nondistributed
CachedCOPALayout
layouts.This is just a small addition to
ForwardSimulator
, adding a persistent cache passed to new derivedclassoverridable compute routines. create_layout(self, circuits, dataset=None, resource_alloc=None, array_types=(), derivative_dimensions=None, verbosity=0)¶
Constructs an circuitoutcomeprobabilityarray (COPA) layout for a list of circuits.
 Parameters
circuits (list) – The circuits whose outcome probabilities should be included in the layout.
dataset (DataSet) – The source of data counts that will be compared to the circuit outcome probabilities. The computed outcome probabilities are limited to those with counts present in dataset.
resource_alloc (ResourceAllocation) – A available resources and allocation information. These factors influence how the layout (evaluation strategy) is constructed.
array_types (tuple, optional) – A tuple of stringvalued array types. See :method:`ForwardSimulator.create_layout`.
derivative_dimensions (tuple, optional) – A tuple containing, optionally, the parameterspace dimension used when taking first and second derivatives with respect to the cirucit outcome probabilities. This must be have minimally 1 or 2 elements when array_types contains ‘ep’ or ‘epp’ types, respectively.
verbosity (int or VerbosityPrinter) – Determines how much output to send to stdout. 0 means no output, higher integers mean more output.
 Returns
CachedCOPALayout
 _bulk_fill_probs_block(self, array_to_fill, layout)¶
 _bulk_fill_dprobs_block(self, array_to_fill, dest_param_slice, layout, param_slice)¶
 abstract _compute_circuit_outcome_probabilities_with_cache(self, array_to_fill, circuit, outcomes, resource_alloc, cache, time=None)¶
 abstract _compute_circuit_outcome_probability_derivatives_with_cache(self, array_to_fill, circuit, outcomes, param_slice, resource_alloc, cache)¶
 pygsti.forwardsims.forwardsim._array_type_parameter_dimension_letters()¶
Return all the arraytype letters that stand for a parameter dimension
 pygsti.forwardsims.forwardsim._bytes_for_array_type(array_type, global_elements, max_local_elements, max_atom_size, total_circuits, max_local_circuits, global_num_params, max_local_num_params, max_param_block_size, max_per_processor_cachesize, dim, dtype='d')¶
 pygsti.forwardsims.forwardsim._bytes_for_array_types(array_types, global_elements, max_local_elements, max_atom_size, total_circuits, max_local_circuits, global_num_params, max_local_num_params, max_param_block_size, max_per_processor_cachesize, dim, dtype='d')¶