pygsti.forwardsims.mapforwardsim
Defines the MapForwardSimulator calculator class
Module Contents
Classes
A forward simulator that uses matrix-vector products to compute circuit outcome probabilities. |
|
Computes circuit outcome probabilities using circuit layer maps that act on a state. |
Attributes
- pygsti.forwardsims.mapforwardsim.CLIFFORD = '2'
- class pygsti.forwardsims.mapforwardsim.SimpleMapForwardSimulator(model=None)
Bases:
pygsti.forwardsims.forwardsim.ForwardSimulator
A forward simulator that uses matrix-vector 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 aMapForwardSimulator
object, and is mainly useful as a reference implementation and check for other simulators.
- class pygsti.forwardsims.mapforwardsim.MapForwardSimulator(model=None, max_cache_size=None, num_atoms=None, processor_grid=None, param_blk_sizes=None, derivative_eps=1e-07, hessian_eps=1e-05)
Bases:
pygsti.forwardsims.distforwardsim.DistributableForwardSimulator
,SimpleMapForwardSimulator
Computes circuit outcome probabilities using circuit layer maps that act on a state.
Interfaces with a model via its circuit_layer_operator method and applies the resulting operators in order to propagate states and finally compute outcome probabilities. Derivatives are computed using finite-differences, and the prefix tables construbed by
MapCOPALayout
layout object are used to avoid duplicating (some) computation.Parameters
- modelModel, 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.
- max_cache_sizeint, optional
The maximum number of “prefix” quantum states that may be cached for performance (within the layout). If None, there is no limit to how large the cache may be.
- num_atomsint, optional
The number of atoms (sub-prefix-tables) to use when creating the layout (i.e. when calling
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_gridtuple 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_sizestuple, 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.
- derivative_eps = '1e-07'
- hessian_eps = '1e-05'
- create_layout(circuits, dataset=None, resource_alloc=None, array_types=('E',), derivative_dimensions=None, verbosity=0, layout_creation_circuit_cache=None, circuit_partition_cost_functions=('size', 'propagations'), load_balancing_parameters=(1.15, 0.1))
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_dimensionsint or tuple[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. If a tuple, then must be length 1.
- verbosityint or VerbosityPrinter
Determines how much output to send to stdout. 0 means no output, higher integers mean more output.
- layout_creation_circuit_cachedict, optional (default None)
A precomputed dictionary serving as a cache for completed circuits. I.e. circuits with prep labels and POVM labels appended. Along with other useful pre-computed circuit structures used in layout creation.
- circuit_partition_cost_functionstuple of str, optional (default (‘size’, ‘propagations’))
A tuple of strings denoting cost function to use in each of the two stages of the algorithm for determining the partitions of the complete circuit set amongst atoms. Allowed options are ‘size’, which corresponds to balancing the number of circuits, and ‘propagations’, which corresponds to balancing the number of state propagations.
- load_balancing_parameterstuple of floats, optional (default (1.15, .1))
A tuple of floats used as load balancing parameters when splitting a layout across atoms, as in the multi-processor setting when using MPI. These parameters correspond to the imbalance_threshold and minimum_improvement_threshold parameters described in the method find_splitting_new of the PrefixTable class.
Returns
MapCOPALayout
- static create_copa_layout_circuit_cache(circuits, model, dataset=None)
Helper function for pre-computing/pre-processing circuits structures used in matrix layout creation.
- bulk_fill_timedep_chi2(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_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
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 chi2 contributions.
- min_prob_clip_for_weightingfloat, 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_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_dchi2(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
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_fillnumpy 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.
- layoutCircuitOutcomeProbabilityArrayLayout
A layout for array_to_fill, describing what circuit outcome each element corresponds to. Usually given by a prior call to
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 chi2 contributions.
- min_prob_clip_for_weightingfloat, 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_interval2-tuple or None, optional
(min,max) values used to clip the predicted probabilities to. If None, no clipping is performed.
- chi2_array_to_fillnumpy 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(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
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(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
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_fillnumpy 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.
- layoutCircuitOutcomeProbabilityArrayLayout
A layout for array_to_fill, describing what circuit outcome each element corresponds to. Usually given by a prior call to
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
a regularization parameter for the log-likelihood objective function.
- radiusfloat
a regularization parameter for the log-likelihood objective function.
- prob_clip_interval2-tuple or None, optional
(min,max) values used to clip the predicted probabilities to. If None, no clipping is performed.
- logl_array_to_fillnumpy 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
- product(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
- circuitCircuit or tuple of operation labels
The sequence of operation labels.
- scalebool, optional
When True, return a scaling factor (see below).
Returns
- productnumpy array
The product or scaled product of the operation matrices.
- scalefloat
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.