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 
 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
 modelModel, optional
The model this forward simulator will use to compute circuit outcome probabilities.
 property model
 Castable
 classmethod cast(obj: ForwardSimulator, num_qubits=None)
num_qubits only used if obj == ‘auto’
 probs(circuit, outcomes=None, time=None, resource_alloc=None)
Construct a dictionary containing the outcome probabilities for a single circuit.
Parameters
 circuitCircuit or tuple of operation labels
The sequence of operation labels specifying the circuit.
 outcomeslist 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.
 timefloat, optional
The start time at which circuit is evaluated.
 resource_allocResourceAllocation, optional
The resources available for computing circuit outcome probabilities.
Returns
 probsOutcomeLabelDict
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(circuit, resource_alloc=None)
Construct a dictionary containing outcome probability derivatives for a single circuit.
Parameters
 circuitCircuit or tuple of operation labels
The sequence of operation labels specifying the circuit.
 resource_allocResourceAllocation, optional
The resources available for computing circuit outcome probability derivatives.
Returns
 dprobsOutcomeLabelDict
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(circuit, resource_alloc=None)
Construct a dictionary containing outcome probability Hessians for a single circuit.
Parameters
 circuitCircuit or tuple of operation labels
The sequence of operation labels specifying the circuit.
 resource_allocResourceAllocation, optional
The resources available for computing circuit outcome probability Hessians.
Returns
 hprobsOutcomeLabelDict
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(circuits, dataset=None, resource_alloc=None, array_types=(), derivative_dimensions=None, verbosity=0)
Constructs an circuitoutcomeprobabilityarray (COPA) layout for circuits and dataset.
Parameters
 circuitslist
The circuits whose outcome probabilities should be computed.
 datasetDataSet
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_allocResourceAllocation
A available resources and allocation information. These factors influence how the layout (evaluation strategy) is constructed.
 array_typestuple, optional
A tuple of stringvalued array types, as given by
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_dimensionstuple, optional
A tuple containing, optionally, the parameterspace dimension used when taking first and second derivatives with respect to the cirucit outcome probabilities. This should have minimally 1 or 2 elements when array_types contains ‘ep’ or ‘epp’ types, respectively. If array_types contains either of these strings and derivative_dimensions is None on input then we automatically set derivative_dimensions based on self.model.
 verbosityint or VerbosityPrinter
Determines how much output to send to stdout. 0 means no output, higher integers mean more output.
Returns
CircuitOutcomeProbabilityArrayLayout
 bulk_probs(circuits, clip_to=None, resource_alloc=None, smartc=None)
Construct a dictionary containing the probabilities for an entire list of circuits.
Parameters
 circuitslist of Circuits
The list of circuits. May also be a
CircuitOutcomeProbabilityArrayLayout
object containing precomputed quantities that make this function run faster. clip_to2tuple, optional
(min,max) to clip return value if not None.
 resource_allocResourceAllocation, optional
A resource allocation object describing the available resources and a strategy for partitioning them.
 smartcSmartCache, optional
A cache object to cache & use previously cached values inside this function.
Returns
 probsdictionary
A dictionary such that probs[circuit] is an ordered dictionary of outcome probabilities whose keys are outcome labels.
 bulk_dprobs(circuits, resource_alloc=None, smartc=None)
Construct a dictionary containing the probability derivatives for an entire list of circuits.
Parameters
 circuitslist of Circuits
The list of circuits. May also be a
CircuitOutcomeProbabilityArrayLayout
object containing precomputed quantities that make this function run faster. resource_allocResourceAllocation, optional
A resource allocation object describing the available resources and a strategy for partitioning them.
 smartcSmartCache, optional
A cache object to cache & use previously cached values inside this function.
Returns
 dprobsdictionary
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(circuits, resource_alloc=None, smartc=None)
Construct a dictionary containing the probability Hessians for an entire list of circuits.
Parameters
 circuitslist of Circuits
The list of circuits. May also be a
CircuitOutcomeProbabilityArrayLayout
object containing precomputed quantities that make this function run faster. resource_allocResourceAllocation, optional
A resource allocation object describing the available resources and a strategy for partitioning them.
 smartcSmartCache, optional
A cache object to cache & use previously cached values inside this function.
Returns
 hprobsdictionary
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(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_fillnumpy ndarray
an alreadyallocated 1D numpy array of length equal to the total number of computed elements (i.e. len(layout)).
 layoutCircuitOutcomeProbabilityArrayLayout
A layout for array_to_fill, describing what circuit outcome each element corresponds to. Usually given by a prior call to
create_layout()
.
Returns
None
 bulk_fill_dprobs(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_fillnumpy ndarray
an alreadyallocated 2D numpy array of shape (len(layout), Np), where Np is the number of model parameters being differentiated with respect to.
 layoutCircuitOutcomeProbabilityArrayLayout
A layout for array_to_fill, describing what circuit outcome each element corresponds to. Usually given by a prior call to
create_layout()
. pr_mx_to_fillnumpy array, optional
when not None, an alreadyallocated lengthlen(layout) numpy array that is filled with probabilities, just as in
bulk_fill_probs()
.
Returns
None
 bulk_fill_hprobs(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_fillnumpy 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).
 layoutCircuitOutcomeProbabilityArrayLayout
A layout for array_to_fill, describing what circuit outcome each element corresponds to. Usually given by a prior call to
create_layout()
. pr_mx_to_fillnumpy array, optional
when not None, an alreadyallocated lengthlen(layout) numpy array that is filled with probabilities, just as in
bulk_fill_probs()
. deriv1_array_to_fillnumpy array, optional
when not None, an alreadyallocated numpy array of shape (len(layout),M1) that is filled with probability derivatives, similar to
bulk_fill_dprobs()
(see array_to_fill for a definition of M1). deriv2_array_to_fillnumpy array, optional
when not None, an alreadyallocated numpy array of shape (len(layout),M2) that is filled with probability derivatives, similar to
bulk_fill_dprobs()
(see array_to_fill for a definition of M2).
Returns
None
 iter_hprobs_by_rectangle(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
 layoutCircuitOutcomeProbabilityArrayLayout
A layout for generated arrays, describing what circuit outcome each element corresponds to. Usually given by a prior call to
create_layout()
. wrt_slices_listlist
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_12boolean, 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]
 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(circuits, dataset=None, resource_alloc=None, array_types=(), derivative_dimensions=None, verbosity=0)
Constructs an circuitoutcomeprobabilityarray (COPA) layout for a list of circuits.
Parameters
 circuitslist
The circuits whose outcome probabilities should be included in the layout.
 datasetDataSet
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_allocResourceAllocation
A available resources and allocation information. These factors influence how the layout (evaluation strategy) is constructed.
 array_typestuple, optional
A tuple of stringvalued array types. See
ForwardSimulator.create_layout()
. derivative_dimensionstuple, 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.
 verbosityint or VerbosityPrinter
Determines how much output to send to stdout. 0 means no output, higher integers mean more output.
Returns
CachedCOPALayout