pygsti.forwardsims.matrixforwardsim

Defines the MatrixForwardSimulator calculator class

Module Contents

Classes

SimpleMatrixForwardSimulator

A forward simulator that uses matrix-matrix products to compute circuit outcome probabilities.

MatrixForwardSimulator

Computes circuit outcome probabilities by multiplying together circuit-layer process matrices.

Attributes

_dummy_profiler

_PSMALL

_DSMALL

_HSMALL

pygsti.forwardsims.matrixforwardsim._dummy_profiler
pygsti.forwardsims.matrixforwardsim._PSMALL = 1e-100
pygsti.forwardsims.matrixforwardsim._DSMALL = 1e-100
pygsti.forwardsims.matrixforwardsim._HSMALL = 1e-100
class pygsti.forwardsims.matrixforwardsim.SimpleMatrixForwardSimulator(model=None)

Bases: pygsti.forwardsims.forwardsim.ForwardSimulator

A forward simulator that uses matrix-matrix products to compute circuit outcome probabilities.

This is “simple” in that it adds a minimal implementation to its ForwardSimulator base class. Because of this, it lacks some of the efficiency of a MatrixForwardSimulator object, and is mainly useful as a reference implementation and check for other simulators.

product(self, circuit, scale=False)

Compute the product of a specified sequence of operation labels.

Note: LinearOperator matrices are multiplied in the reversed order of the tuple. That is, the first element of circuit can be thought of as the first gate operation performed, which is on the far right of the product of matrices.

Parameters
  • circuit (Circuit or tuple of operation labels) – The sequence of operation labels.

  • scale (bool, optional) – When True, return a scaling factor (see below).

Returns

  • product (numpy array) – The product or scaled product of the operation matrices.

  • scale (float) – Only returned when scale == True, in which case the actual product == product * scale. The purpose of this is to allow a trace or other linear operation to be done prior to the scaling.

_rho_es_from_spam_tuples(self, rholabel, elabels)
_process_wrt_filter(self, wrt_filter, obj)

Helper function for doperation and hoperation below: pulls out pieces of a wrt_filter argument relevant for a single object (gate or spam vec)

_doperation(self, op_label, flat=False, wrt_filter=None)

Return the derivative of a length-1 (single-gate) sequence

_hoperation(self, op_label, flat=False, wrt_filter1=None, wrt_filter2=None)

Return the hessian of a length-1 (single-gate) sequence

dproduct(self, circuit, flat=False, wrt_filter=None)

Compute the derivative of a specified sequence of operation labels.

Parameters
  • circuit (Circuit or tuple of operation labels) – The sequence of operation labels.

  • flat (bool, optional) – Affects the shape of the returned derivative array (see below).

  • wrt_filter (list of ints, optional) – If not None, a list of integers specifying which gate parameters to include in the derivative. Each element is an index into an array of gate parameters ordered by concatenating each gate’s parameters (in the order specified by the model). This argument is used internally for distributing derivative calculations across multiple processors.

Returns

deriv (numpy array) –

  • if flat == False, a M x G x G array, where:

    • M == length of the vectorized model (number of model parameters)

    • G == the linear dimension of a operation matrix (G x G operation matrices).

    and deriv[i,j,k] holds the derivative of the (j,k)-th entry of the product with respect to the i-th model parameter.

  • if flat == True, a N x M array, where:

    • N == the number of entries in a single flattened gate (ordering as numpy.flatten)

    • M == length of the vectorized model (number of model parameters)

    and deriv[i,j] holds the derivative of the i-th entry of the flattened product with respect to the j-th model parameter.

hproduct(self, circuit, flat=False, wrt_filter1=None, wrt_filter2=None)

Compute the hessian of a specified sequence of operation labels.

Parameters
  • circuit (Circuit or tuple of operation labels) – The sequence of operation labels.

  • flat (bool, optional) – Affects the shape of the returned derivative array (see below).

  • wrt_filter1 (list of ints, optional) – If not None, a list of integers specifying which parameters to differentiate with respect to in the first (row) derivative operations. Each element is an model-parameter index. This argument is used internally for distributing derivative calculations across multiple processors.

  • wrt_filter2 (list of ints, optional) – If not None, a list of integers specifying which parameters to differentiate with respect to in the second (col) derivative operations. Each element is an model-parameter index. This argument is used internally for distributing derivative calculations across multiple processors.

Returns

hessian (numpy array) –

  • if flat == False, a M x M x G x G numpy array, where:

    • M == length of the vectorized model (number of model parameters)

    • G == the linear dimension of a operation matrix (G x G operation matrices).

    and hessian[i,j,k,l] holds the derivative of the (k,l)-th entry of the product with respect to the j-th then i-th model parameters.

  • if flat == True, a N x M x M numpy array, where:

    • N == the number of entries in a single flattened gate (ordered as numpy.flatten)

    • M == length of the vectorized model (number of model parameters)

    and hessian[i,j,k] holds the derivative of the i-th entry of the flattened product with respect to the k-th then k-th model parameters.

_compute_circuit_outcome_probabilities(self, array_to_fill, circuit, outcomes, resource_alloc, time=None)

Compute probabilities of a multiple “outcomes” for a single circuit.

The outcomes correspond to circuit sandwiched between rholabel (a state preparation) and the multiple effect labels in elabels.

Parameters
  • rholabel (Label) – The state preparation label.

  • elabels (list) – A list of Label objects giving the simplified effect labels.

  • circuit (Circuit or tuple) – A tuple-like object of simplified gates (e.g. may include instrument elements like ‘Imyinst_0’)

  • use_scaling (bool, optional) – Whether to use a post-scaled product internally. If False, this routine will run slightly faster, but with a chance that the product will overflow and the subsequent trace operation will yield nan as the returned probability.

  • time (float, optional) – The start time at which circuit is evaluated.

Returns

numpy.ndarray – An array of floating-point probabilities, corresponding to the elements of elabels.

class pygsti.forwardsims.matrixforwardsim.MatrixForwardSimulator(model=None, distribute_by_timestamp=False, num_atoms=None, processor_grid=None, param_blk_sizes=None)

Bases: pygsti.forwardsims.distforwardsim.DistributableForwardSimulator, SimpleMatrixForwardSimulator

Computes circuit outcome probabilities by multiplying together circuit-layer process matrices.

Interfaces with a model via its circuit_layer_operator method and extracts a dense matrix representation of operators by calling their to_dense method. An “evaluation tree” that composes all of the circuits using pairwise “joins” is constructed by a MatrixCOPALayout layout object, and this tree then directs pairwise multiplications of process matrices to compute circuit outcome probabilities. Derivatives are computed analytically, using operators’ deriv_wrt_params methods.

Parameters
  • model (Model, optional) – The parent model of this simulator. It’s fine if this is None at first, but it will need to be set (by assigning self.model before using this simulator.

  • distribute_by_timestamp (bool, optional) – When True, treat the data as time dependent, and distribute the computation of outcome probabilitiesby assigning groups of processors to the distinct time stamps within the dataset. This means of distribution be used only when the circuits themselves contain no time delay infomation (all circuit layer durations are 0), as operators are cached at the “start” time of each circuit, i.e., the timestamp in the data set. If False, then the data is treated in a time-independent way, and the overall counts for each outcome are used. If support for intra-circuit time dependence is needed, you must use a different forward simulator (e.g. MapForwardSimulator).

  • num_atoms (int, optional) – The number of atoms (sub-evaluation-trees) to use when creating the layout (i.e. when calling :method:`create_layout`). This determines how many units the element (circuit outcome probability) dimension is divided into, and doesn’t have to correclate with the number of processors. When multiple processors are used, if num_atoms is less than the number of processors then num_atoms should divide the number of processors evenly, so that num_atoms // num_procs groups of processors can be used to divide the computation over parameter dimensions.

  • processor_grid (tuple optional) – Specifies how the total number of processors should be divided into a number of atom-processors, 1st-parameter-deriv-processors, and 2nd-parameter-deriv-processors. Each level of specification is optional, so this can be a 1-, 2-, or 3- tuple of integers (or None). Multiplying the elements of processor_grid together should give at most the total number of processors.

  • param_blk_sizes (tuple, optional) – The parameter block sizes along the first or first & second parameter dimensions - so this can be a 0-, 1- or 2-tuple of integers or None values. A block size of None means that there should be no division into blocks, and that each block processor computes all of its parameter indices at once.

classmethod _array_types_for_method(cls, method_name)
_to_nice_serialization(self)
classmethod _from_nice_serialization(cls, state)
copy(self)

Return a shallow copy of this MatrixForwardSimulator

Returns

MatrixForwardSimulator

_compute_product_cache(self, layout_atom_tree, resource_alloc)

Computes an array of operation sequence products (process matrices).

Note: will not parallelize computation: parallelization should be done at a higher level.

_compute_dproduct_cache(self, layout_atom_tree, prod_cache, scale_cache, resource_alloc=None, wrt_slice=None, profiler=None)

Computes a tree of product derivatives in a linear cache space. Will use derivative columns to parallelize computation.

_compute_hproduct_cache(self, layout_atom_tree, prod_cache, d_prod_cache1, d_prod_cache2, scale_cache, resource_alloc=None, wrt_slice1=None, wrt_slice2=None)

Computes a tree of product 2nd derivatives in a linear cache space. Will use derivative rows and columns to parallelize computation.

create_layout(self, circuits, dataset=None, resource_alloc=None, array_types=('E',), derivative_dimension=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_dimension (int, optional) – Optionally, the parameter-space dimension used when taking first and second derivatives with respect to the cirucit outcome probabilities. This must be non-None when array_types contains ‘ep’ or ‘epp’ types.

  • verbosity (int or VerbosityPrinter) – Determines how much output to send to stdout. 0 means no output, higher integers mean more output.

Returns

MatrixCOPALayout

_scale_exp(self, scale_exps)
_rho_e_from_spam_tuple(self, spam_tuple)
_probs_from_rho_e(self, rho, e, gs, scale_vals)
_dprobs_from_rho_e(self, spam_tuple, rho, e, gs, d_gs, scale_vals, wrt_slice=None)
_hprobs_from_rho_e(self, spam_tuple, rho, e, gs, d_gs1, d_gs2, h_gs, scale_vals, wrt_slice1=None, wrt_slice2=None)
_bulk_fill_probs_atom(self, array_to_fill, layout_atom, resource_alloc)
_bulk_fill_dprobs_atom(self, array_to_fill, dest_param_slice, layout_atom, param_slice, resource_alloc)
_bulk_fill_hprobs_atom(self, array_to_fill, dest_param_slice1, dest_param_slice2, layout_atom, param_slice1, param_slice2, resource_alloc)
bulk_product(self, circuits, scale=False, resource_alloc=None)

Compute the products of many circuits at once.

Parameters
  • circuits (list of Circuits) – The circuits to compute products for. These should not have any preparation or measurement layers.

  • scale (bool, optional) – When True, return a scaling factor (see below).

  • resource_alloc (ResourceAllocation) – Available resources for this computation. Includes the number of processors (MPI comm) and memory limit.

Returns

  • prods (numpy array) – Array of shape S x G x G, where: - S == the number of operation sequences - G == the linear dimension of a operation matrix (G x G operation matrices).

  • scaleValues (numpy array) – Only returned when scale == True. A length-S array specifying the scaling that needs to be applied to the resulting products (final_product[i] = scaleValues[i] * prods[i]).

bulk_dproduct(self, circuits, flat=False, return_prods=False, scale=False, resource_alloc=None, wrt_filter=None)

Compute the derivative of a many operation sequences at once.

Parameters
  • circuits (list of Circuits) – The circuits to compute products for. These should not have any preparation or measurement layers.

  • flat (bool, optional) – Affects the shape of the returned derivative array (see below).

  • return_prods (bool, optional) – when set to True, additionally return the probabilities.

  • scale (bool, optional) – When True, return a scaling factor (see below).

  • resource_alloc (ResourceAllocation) – Available resources for this computation. Includes the number of processors (MPI comm) and memory limit.

  • wrt_filter (list of ints, optional) – If not None, a list of integers specifying which gate parameters to include in the derivative. Each element is an index into an array of gate parameters ordered by concatenating each gate’s parameters (in the order specified by the model). This argument is used internally for distributing derivative calculations across multiple processors.

Returns

  • derivs (numpy array) –

    • if flat == False, an array of shape S x M x G x G, where: - S == len(circuits) - M == the length of the vectorized model - G == the linear dimension of a operation matrix (G x G operation matrices) and derivs[i,j,k,l] holds the derivative of the (k,l)-th entry of the i-th operation sequence product with respect to the j-th model parameter.

    • if flat == True, an array of shape S*N x M where: - N == the number of entries in a single flattened gate (ordering same as numpy.flatten), - S,M == as above, and deriv[i,j] holds the derivative of the (i % G^2)-th entry of the (i / G^2)-th flattened operation sequence product with respect to the j-th model parameter.

  • products (numpy array) – Only returned when return_prods == True. An array of shape S x G x G; products[i] is the i-th operation sequence product.

  • scaleVals (numpy array) – Only returned when scale == True. An array of shape S such that scaleVals[i] contains the multiplicative scaling needed for the derivatives and/or products for the i-th operation sequence.

_ds_quantities(self, timestamp, ds_cache, layout, dataset, TIMETOL=1e-06)
_bulk_fill_timedep_objfn(self, raw_objective, array_to_fill, layout, ds_circuits, num_total_outcomes, dataset, ds_cache=None)
_bulk_fill_timedep_dobjfn(self, raw_objective, array_to_fill, layout, ds_circuits, num_total_outcomes, dataset, ds_cache=None)
bulk_fill_timedep_chi2(self, array_to_fill, layout, ds_circuits, num_total_outcomes, dataset, min_prob_clip_for_weighting, prob_clip_interval, ds_cache=None)

Compute the chi2 contributions for an entire tree of circuits, allowing for time dependent operations.

Computation is performed by summing together the contributions for each time the circuit is run, as given by the timestamps in dataset.

Parameters
  • array_to_fill (numpy ndarray) – an already-allocated 1D numpy array of length equal to the total number of computed elements (i.e. layout.num_elements)

  • 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`.

  • ds_circuits (list of Circuits) – the circuits to use as they should be queried from dataset (see below). This is typically the same list of circuits used to construct layout potentially with some aliases applied.

  • num_total_outcomes (list or array) – a list of the total number of possible outcomes for each circuit (so len(num_total_outcomes) == len(ds_circuits_to_use)). This is needed for handling sparse data, where dataset may not contain counts for all the possible outcomes of each circuit.

  • dataset (DataSet) – the data set used to compute the chi2 contributions.

  • min_prob_clip_for_weighting (float, optional) – Sets the minimum and maximum probability p allowed in the chi^2 weights: N/(p*(1-p)) by clipping probability p values to lie within the interval [ min_prob_clip_for_weighting, 1-min_prob_clip_for_weighting ].

  • prob_clip_interval (2-tuple or None, optional) – (min,max) values used to clip the predicted probabilities to. If None, no clipping is performed.

Returns

None

bulk_fill_timedep_dchi2(self, array_to_fill, layout, ds_circuits, num_total_outcomes, dataset, min_prob_clip_for_weighting, prob_clip_interval, chi2_array_to_fill=None, ds_cache=None)

Compute the chi2 jacobian contributions for an entire tree of circuits, allowing for time dependent operations.

Similar to :method:`bulk_fill_timedep_chi2` but compute the jacobian of the summed chi2 contributions for each circuit with respect to the model’s parameters.

Parameters
  • array_to_fill (numpy ndarray) – an already-allocated ExM numpy array where E is the total number of computed elements (i.e. layout.num_elements) and M is the number of model parameters.

  • 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`.

  • ds_circuits (list of Circuits) – the circuits to use as they should be queried from dataset (see below). This is typically the same list of circuits used to construct layout potentially with some aliases applied.

  • num_total_outcomes (list or array) – a list of the total number of possible outcomes for each circuit (so len(num_total_outcomes) == len(ds_circuits_to_use)). This is needed for handling sparse data, where dataset may not contain counts for all the possible outcomes of each circuit.

  • dataset (DataSet) – the data set used to compute the chi2 contributions.

  • min_prob_clip_for_weighting (float, optional) – Sets the minimum and maximum probability p allowed in the chi^2 weights: N/(p*(1-p)) by clipping probability p values to lie within the interval [ min_prob_clip_for_weighting, 1-min_prob_clip_for_weighting ].

  • prob_clip_interval (2-tuple or None, optional) – (min,max) values used to clip the predicted probabilities to. If None, no clipping is performed.

  • chi2_array_to_fill (numpy array, optional) – when not None, an already-allocated length-E numpy array that is filled with the per-circuit chi2 contributions, just like in bulk_fill_timedep_chi2(…).

Returns

None

bulk_fill_timedep_loglpp(self, array_to_fill, layout, ds_circuits, num_total_outcomes, dataset, min_prob_clip, radius, prob_clip_interval, ds_cache=None)

Compute the log-likelihood contributions (within the “poisson picture”) for an entire tree of circuits.

Computation is performed by summing together the contributions for each time the circuit is run, as given by the timestamps in dataset.

Parameters
array_to_fillnumpy ndarray

an already-allocated 1D numpy array of length equal to the total number of computed elements (i.e. layout.num_elements)

layoutCircuitOutcomeProbabilityArrayLayout

A layout for array_to_fill, describing what circuit outcome each element corresponds to. Usually given by a prior call to :method:`create_layout`.

ds_circuitslist of Circuits

the circuits to use as they should be queried from dataset (see below). This is typically the same list of circuits used to construct layout potentially with some aliases applied.

num_total_outcomeslist or array

a list of the total number of possible outcomes for each circuit (so len(num_total_outcomes) == len(ds_circuits_to_use)). This is needed for handling sparse data, where dataset may not contain counts for all the possible outcomes of each circuit.

datasetDataSet

the data set used to compute the logl contributions.

min_prob_clipfloat, optional

The minimum probability treated normally in the evaluation of the log-likelihood. A penalty function replaces the true log-likelihood for probabilities that lie below this threshold so that the log-likelihood never becomes undefined (which improves optimizer performance).

radiusfloat, optional

Specifies the severity of rounding used to “patch” the zero-frequency terms of the log-likelihood.

prob_clip_interval2-tuple or None, optional

(min,max) values used to clip the predicted probabilities to. If None, no clipping is performed.

Returns
None
bulk_fill_timedep_dloglpp(self, array_to_fill, layout, ds_circuits, num_total_outcomes, dataset, min_prob_clip, radius, prob_clip_interval, logl_array_to_fill=None, ds_cache=None)

Compute the (“poisson picture”)log-likelihood jacobian contributions for an entire tree of circuits.

Similar to :method:`bulk_fill_timedep_loglpp` but compute the jacobian of the summed logl (in posison picture) contributions for each circuit with respect to the model’s parameters.

Parameters
  • array_to_fill (numpy ndarray) – an already-allocated ExM numpy array where E is the total number of computed elements (i.e. layout.num_elements) and M is the number of model parameters.

  • 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`.

  • ds_circuits (list of Circuits) – the circuits to use as they should be queried from dataset (see below). This is typically the same list of circuits used to construct layout potentially with some aliases applied.

  • num_total_outcomes (list or array) – a list of the total number of possible outcomes for each circuit (so len(num_total_outcomes) == len(ds_circuits_to_use)). This is needed for handling sparse data, where dataset may not contain counts for all the possible outcomes of each circuit.

  • dataset (DataSet) – the data set used to compute the logl contributions.

  • min_prob_clip (float) – a regularization parameter for the log-likelihood objective function.

  • radius (float) – a regularization parameter for the log-likelihood objective function.

  • prob_clip_interval (2-tuple or None, optional) – (min,max) values used to clip the predicted probabilities to. If None, no clipping is performed.

  • logl_array_to_fill (numpy array, optional) – when not None, an already-allocated length-E numpy array that is filled with the per-circuit logl contributions, just like in bulk_fill_timedep_loglpp(…).

Returns

None