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.

Functions

_array_type_parameter_dimension_letters()

Return all the array-type letters that stand for a parameter dimension

_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')

_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')

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

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 non-zero 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 non-zero 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 circuit-outcome-probability-array (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 string-valued 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 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_dimensions (tuple, 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.

  • 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 pre-computed quantities that make this function run faster.

  • clip_to (2-tuple, 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 pre-computed 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 pre-computed 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 already-allocated 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 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_fill (numpy 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.

  • 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 already-allocated length-len(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 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_fill (numpy 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).

  • 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 already-allocated length-len(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 already-allocated 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 already-allocated 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 rectangle-by-rectangle 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) 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_12 (boolean, 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]

_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 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(self, 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
  • 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 string-valued array types. See :method:`ForwardSimulator.create_layout`.

  • derivative_dimensions (tuple, 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.

  • 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 array-type 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')