pygsti.forwardsims.termforwardsim
Defines the TermForwardSimulator calculator class
Module Contents
Classes
A forward-simulation calculator that uses term-path-integration to compute probabilities. |
|
A path set for a split |
- class pygsti.forwardsims.termforwardsim.TermForwardSimulator(model=None, mode='pruned', max_order=3, desired_perr=0.01, allowed_perr=0.1, min_term_mag=None, max_paths_per_outcome=1000, perr_heuristic='none', max_term_stages=5, path_fraction_threshold=0.9, oob_check_interval=10, cache=None, num_atoms=None, processor_grid=None, param_blk_sizes=None)
Bases:
pygsti.forwardsims.distforwardsim.DistributableForwardSimulatorA forward-simulation calculator that uses term-path-integration to compute probabilities.
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.
- mode{“taylor-order”, “pruned”, “direct”}
Overall method used to compute (approximate) circuit probabilities. The “taylor-order” mode includes all taylor-expansion terms up to a fixed and pre-defined order, fixing a single “path set” at the outset. The “pruned” mode selects a path set based on a heuristic (sometimes a true upper bound) calculation of the error in the approximate probabilities. This method effectively “prunes” the paths to meet a fixed desired accuracy. The “direct” method is still under development. Its intention is to perform path integrals directly without the use of polynomial computation and caching. Initial testing showed the direct method to be much slower for common QCVV tasks, making it less urgent to complete.
- max_orderint
The maximum order of error-rate terms to include in probability computations. When polynomials are computed, the maximum Taylor order to compute polynomials to.
- desired_perrfloat, optional
The desired maximum-error when computing probabilities.. Path sets are selected (heuristically) to target this error, within the bounds set by max_order, etc.
- allowed_perrfloat, optional
The allowed maximum-error when computing probabilities. When rigorous bounds cannot guarantee that probabilities are correct to within this error, additional paths are added to the path set.
- min_term_magfloat, optional
Terms with magnitudes less than this value will be ignored, i.e. not considered candidates for inclusion in paths. If this number is too low, the number of possible paths to consder may be very large, impacting performance. If too high, then not enough paths will be considered to achieve an accurate result. By default this value is set automatically based on the desired error and max_paths_per_outcome. Only adjust this if you know what you’re doing.
- max_paths_per_outcomeint, optional
The maximum number of paths that can be used (summed) to compute a single outcome probability.
- perr_heuristic{“none”, “scaled”, “meanscaled”}
Which heuristic (if any) to use when deciding whether a given path set is sufficient given the allowed error (allowed_perr). - “none”: This is the strictest setting, and is absence of any heuristic. if the path-magnitude gap (the maximum - achieved sum-of-path-magnitudes, a rigorous upper bound on the approximation error for a circuit outcome probability) is greater than allowed_perr for any circuit, the path set is deemed insufficient. - “scaled”: a path set is deemed insufficient when, for any circuit, the path-magnitude gap multiplied by a scaling factor is greater than allowed_perr. This scaling factor is equal to the computed probability divided by the achieved sum-of-path-magnitudes and is always less than 1. This scaling is essentially the ratio of the sum of the path amplitudes without and with an absolute value, and tries to quantify and offset the degree of pessimism in the computed path-magnitude gap. - “meanscaled” : a path set is deemed insufficient when, the mean of all the scaled (as above) path-magnitude gaps is greater than allowed_perr. The mean here is thus over the circuit outcomes. This heuristic is even more permissive of potentially bad path sets than “scaled”, as it allows badly approximated circuits to be offset by well approximated ones.
- max_term_stagesint, optional
The maximum number of “stage”, i.e. re-computations of a path set, are allowed before giving up.
- path_fraction_thresholdfloat, optional
When greater than this fraction of the total available paths (set by other constraints) are considered, no further re-compuation of the path set will occur, as it is expected to give little improvement.
- oob_check_intervalint, optional
The optimizer will check whether the computed probabilities have sufficiently small error every oob_check_interval (outer) optimizer iteration.
- cachedict, optional
A dictionary of pre-computed compact polynomial objects. Keys are (max_order, rholabel, elabel, circuit) tuples, where max_order is an integer, rholabel and elabel are
Labelobjects, and circuit is aCircuit. Computed values are added to any dictionary that is supplied, so supplying an empty dictionary and using this calculator will cause the dictionary to be filled with values.- num_atomsint, optional
The number of atoms (sub-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.
- create_layout(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
- 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_dimensionint, 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.
- verbosityint or VerbosityPrinter
Determines how much output to send to stdout. 0 means no output, higher integers mean more output.
Returns
TermCOPALayout
- find_minimal_paths_set(layout, exit_after_this_many_failures=0)
Find a good, i.e. minimal, path set for the current model-parameter space point.
Parameters
- layoutTermCOPALayout
The layout specifiying the quantities (circuit outcome probabilities) to be computed, and related information.
- exit_after_this_many_failuresint, optional
If > 0, give up after this many circuits fail to meet the desired accuracy criteria. This short-circuits doomed attempts to find a good path set so they don’t take too long.
Returns
TermPathSet
- bulk_test_if_paths_are_sufficient(layout, probs, verbosity=0)
Determine whether layout’s current path set (perhaps heuristically) achieves the desired accuracy.
The current path set is determined by the current (per-circuti) path-magnitude thresholds (stored in the evaluation tree) and the current parameter-space point (also reflected in the terms cached in the evaluation tree).
Parameters
- layoutTermCOPALayout
The layout specifiying the quantities (circuit outcome probabilities) to be computed, and related information.
- probsnumpy.ndarray
The element array of (approximate) circuit outcome probabilities. This is needed because some heuristics take into account an probability’s value when computing an acceptable path-magnitude gap.
- verbosityint or VerbosityPrinter, optional
An integer verbosity level or printer object for displaying messages.
Returns
bool
- bulk_sopm_gaps(layout)
Compute an element array sum-of-path-magnitude gaps (the difference between maximum and achieved).
These values are computed for the current set of paths contained in eval_tree.
Parameters
- layoutTermCOPALayout
The layout specifiying the quantities (circuit outcome probabilities) to be computed, and related information.
Returns
- numpy.ndarray
An array containing the per-circuit-outcome sum-of-path-magnitude gaps.
- bulk_sopm_gaps_jacobian(layout)
Compute the jacobian of the the output of
bulk_sopm_gaps().Parameters
- layoutTermCOPALayout
The layout specifiying the quantities (circuit outcome probabilities) to be computed, and related information.
- resource_allocResourceAllocation, optional
Available resources for this computation. Includes the number of processors (MPI comm) and memory limit.
Returns
- numpy.ndarray
An number-of-elements by number-of-model-parameters array containing the jacobian of the sum-of-path-magnitude gaps.
- class pygsti.forwardsims.termforwardsim.TermPathSet(local_atom_pathsets, comm)
Bases:
_TermPathSetBaseA path set for a split
TermEvalTree.Parameters
- local_atom_pathsetslist
A list of path sets for each of the local layout atom (i.e. the atoms assigned to the current processor).
- commmpi4py.MPI.Comm
When not None, an MPI communicator for distributing the computation across multiple processors.