pygsti.forwardsims.forwardsim

Defines the ForwardSimulator calculator class

Module Contents

Classes

ForwardSimulator	A calculator of circuit outcome probability calculations and their derivatives w.r.t. model parameters.
CacheForwardSimulator	A forward simulator that works with non-distributed CachedCOPALayout layouts.

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 operation-product calculations.

This functionality exists in a class separate from Model to allow for additional model classes (e.g. ones which use entirely different – non-gate-local – 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 non-zero 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 non-zero 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 circuit-outcome-probability-array (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 string-valued 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 derivative-containing 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 parameter-space 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 pre-computed quantities that make this function run faster.

clip_to2-tuple, 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 pre-computed 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 pre-computed 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 already-allocated 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 probability-derivatives 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 already-allocated 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 already-allocated length-len(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 probability-Hessians 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 already-allocated 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 already-allocated length-len(layout) numpy array that is filled with probabilities, just as in bulk_fill_probs().

deriv1_array_to_fillnumpy array, optional

when not None, an already-allocated 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 already-allocated 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 rectangle-by-rectangle 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) 2-tuples, 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 2-tuple: (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 3-tuple (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 non-distributed CachedCOPALayout layouts.

This is just a small addition to ForwardSimulator, adding a persistent cache passed to new derived-class-overridable compute routines.

create_layout(circuits, dataset=None, resource_alloc=None, array_types=(), derivative_dimensions=None, verbosity=0)

Constructs an circuit-outcome-probability-array (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 string-valued array types. See ForwardSimulator.create_layout().

derivative_dimensionstuple, optional

A tuple containing, optionally, the parameter-space 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