`pygsti.forwardsims.termforwardsim_calc_generic`

Defines generic Python-version of map forward simuator calculations

Module Contents

Functions

 `prs_as_polynomials`(fwdsim, rholabel, elabels, circuit, ...) Computes polynomials of the probabilities for multiple spam-tuples of circuit `prs_directly`(fwdsim, rholabel, elabels, circuit, repcache) `refresh_magnitudes_in_repcache`(repcache, paramvec) `circuit_achieved_and_max_sopm`(fwdsim, rholabel, ...) Compute the achieved and maximum sum-of-path-magnitudes (SOPM) for a given circuit and model. `find_best_pathmagnitude_threshold`(fwdsim, rholabel, ...) Computes probabilities for multiple spam-tuples of circuit Computes probabilities for multiple spam-tuples of circuit `create_circuitsetup_cacheel`(fwdsim, rholabel, elabels, ...) `traverse_paths_upto_threshold`(oprep_lists, ...[, debug]) Traverse all the paths up to some path-magnitude threshold, calling `pathmagnitude_threshold`(oprep_lists, e_indices, ...[, ...]) Find the pathmagnitude-threshold needed to achieve some target sum-of-path-magnitudes:

Attributes

pygsti.forwardsims.termforwardsim_calc_generic.SMALL = '1e-05'
pygsti.forwardsims.termforwardsim_calc_generic.LOGSMALL
pygsti.forwardsims.termforwardsim_calc_generic.prs_as_polynomials(fwdsim, rholabel, elabels, circuit, polynomial_vindices_per_int, comm=None, mem_limit=None, fastmode=True)

Computes polynomials of the probabilities for multiple spam-tuples of circuit

Parameters

fwdsimTermForwardSimulator

The calculator object holding vital information for the computation.

rholabelLabel

Prep label for all the probabilities to compute.

elabelslist

List of effect labels, one per probability to compute. The ordering of elabels determines the ordering of the returned probability polynomials.

circuitCircuit

The gate sequence to sandwich between the prep and effect labels.

polynomial_vindices_per_intint

The number of variable indices that can fit into a single platform-width integer (can be computed from number of model params, but passed in for performance).

commmpi4py.MPI.Comm, optional

When not None, an MPI communicator for distributing the computation across multiple processors.

mem_limitint, optional

A rough memory limit in bytes.

fastmodebool, optional

A switch between a faster, slighty more memory hungry mode of computation (fastmode=True)and a simpler slower one (=False).

Returns

list

A list of PolynomialRep objects, one per element of elabels.

pygsti.forwardsims.termforwardsim_calc_generic.prs_directly(fwdsim, rholabel, elabels, circuit, repcache, comm=None, mem_limit=None, fastmode=True, wt_tol=0.0, reset_term_weights=True, debug=None)
pygsti.forwardsims.termforwardsim_calc_generic.refresh_magnitudes_in_repcache(repcache, paramvec)
pygsti.forwardsims.termforwardsim_calc_generic.circuit_achieved_and_max_sopm(fwdsim, rholabel, elabels, circuit, repcache, threshold, min_term_mag)

Compute the achieved and maximum sum-of-path-magnitudes (SOPM) for a given circuit and model.

This is a helper function for a TermForwardSimulator, and not typically called independently.

A path-integral forward simulator specifies a model and path criteria (e.g. the max Taylor order). The model’s operations can construct Taylor terms with coefficients based on the current model parameters. The magnitudes of these coefficients are used to estimate the error incurred by a given path truncation as follows: term coefficient magnitudes are multiplied together to get path magnitudes, and these are added to get an “achieved” sum-of-path-magnitudes. This can be compared with a second quantity, the “maximum” sum- of-path-magnitudes based on estimates (ideally upper bounds) of the magnitudes for all paths.

Parameters

fwdsimTermForwardSimulator

The forward simulator. Contains the model that is used.

rholabelLabel

The preparation label, which precedes the layers in circuit. Note that circuit should not contain any preparation or POVM labels - only the operation labels.

elabelslist or tuple

A list of POVM effect labels, which follow the layers in circuit. Note that circuit should not contain any preparation or POVM labels - only the operation labels.

circuitCircuit

The non-SPAM operations that make up the circuit that values are computed for.

repcachedict

A dictionary of already-build preparation, operation, and POVM effect representations. Keys are labels and values are the representation objects. Use of a representation cache can significantly speed up multiple calls to this function.

thresholdfloat

A threshold giving the minimum path magnitude that should be included in the “achieved” sum of path magnitudes. As this number gets smaller, more paths are included.

min_term_magfloat

The minimum magnitude a single term can have and still be considered in paths. This essentially specifies a pre-path-magnitude threshold that lessens computational overhead by ignoring terms that have a very small magnitude.

Returns

achieved_sopmfloat

The achieved sum-of-path-magnitudes.

max_sopmfloat

The approximate maximum sum-of-path-magnitudes.

pygsti.forwardsims.termforwardsim_calc_generic.find_best_pathmagnitude_threshold(fwdsim, rholabel, elabels, circuit, polynomial_vindices_per_int, repcache, circuitsetup_cache, comm, mem_limit, pathmagnitude_gap, min_term_mag, max_paths, threshold_guess)

Computes probabilities for multiple spam-tuples of circuit

Parameters

fwdsimTermForwardSimulator

The calculator object holding vital information for the computation.

rholabelLabel

Prep label for all the probabilities to compute.

elabelslist

List of effect labels, one per probability to compute. The ordering of elabels determines the ordering of the returned probability polynomials.

circuitCircuit

The gate sequence to sandwich between the prep and effect labels.

repcachedict, optional

Dictionary used to cache operator representations to speed up future calls to this function that would use the same set of operations.

circuitsetup_cachedict, optional

Dictionary used to cache preparation specific to this function, to speed up repeated calls using the same circuit and set of parameters, including the same repcache.

commmpi4py.MPI.Comm, optional

When not None, an MPI communicator for distributing the computation across multiple processors.

mem_limitint, optional

A rough memory limit in bytes.

pathmagnitude_gapfloat, optional

The amount less than the perfect sum-of-path-magnitudes that is desired. This sets the target sum-of-path-magnitudes for each circuit – the threshold that determines how many paths are added.

min_term_magfloat, optional

A technical parameter to the path pruning algorithm; this value sets a threshold for how small a term magnitude (one factor in a path magnitude) must be before it is removed from consideration entirely (to limit the number of even potential paths). Terms with a magnitude lower than this values are neglected.

max_pathsint, optional

The maximum number of paths allowed per circuit outcome.

threshold_guessfloat, optional

In the search for a good pathmagnitude threshold, this value is used as the starting point. If 0.0 is given, a default value is used.

Returns

npathsint

the number of paths that were included.

thresholdfloat

the path-magnitude threshold used.

target_sopmfloat

The desired sum-of-path-magnitudes. This is pathmagnitude_gap less than the perfect “all-paths” sum. This sums together the contributions of different effects.

achieved_sopmfloat

The achieved sum-of-path-magnitudes. Ideally this would equal target_sopm. (This also sums together the contributions of different effects.)

pygsti.forwardsims.termforwardsim_calc_generic.compute_pruned_path_polynomials_given_threshold(threshold, fwdsim, rholabel, elabels, circuit, polynomial_vindices_per_int, repcache, circuitsetup_cache, comm, mem_limit, fastmode)

Computes probabilities for multiple spam-tuples of circuit

Parameters

fwdsimTermForwardSimulator

The calculator object holding vital information for the computation.

rholabelLabel

Prep label for all the probabilities to compute.

elabelslist

List of effect labels, one per probability to compute. The ordering of elabels determines the ordering of the returned probability polynomials.

circuitCircuit

The gate sequence to sandwich between the prep and effect labels.

repcachedict, optional

Dictionary used to cache operator representations to speed up future calls to this function that would use the same set of operations.

circuitsetup_cachedict, optional

Dictionary used to cache preparation specific to this function, to speed up repeated calls using the same circuit and set of parameters, including the same repcache.

commmpi4py.MPI.Comm, optional

When not None, an MPI communicator for distributing the computation across multiple processors.

mem_limitint, optional

A rough memory limit in bytes.

fastmodebool, optional

A switch between a faster, slighty more memory hungry mode of computation (fastmode=True)and a simpler slower one (=False).

Returns

prpslist of PolynomialRep objects

the polynomials for the requested circuit probabilities, computed by selectively summing up high-magnitude paths.

pygsti.forwardsims.termforwardsim_calc_generic.create_circuitsetup_cacheel(fwdsim, rholabel, elabels, circuit, repcache, min_term_mag, mpv)
pygsti.forwardsims.termforwardsim_calc_generic.traverse_paths_upto_threshold(oprep_lists, pathmag_threshold, num_elabels, foat_indices_per_op, fn_visitpath, debug=False)

Traverse all the paths up to some path-magnitude threshold, calling fn_visitpath for each one.

Parameters

oprep_listslist of lists

representations for the terms of each layer of the circuit whose outcome probability we’re computing, including prep and POVM layers. oprep_lists[i] is a list of the terms available to choose from for the i-th circuit layer, ordered by increasing term-magnitude.

pathmag_thresholdfloat

the path-magnitude threshold to use.

num_elabelsint

The number of effect labels corresponding whose terms are all amassed in the in final oprep_lists[-1] list (knowing which elements of oprep_lists[-1] correspond to which effect isn’t necessary for this function).

foat_indices_per_oplist

A list of lists of integers, such that foat_indices_per_op[i] is a list of indices into oprep_lists[-1] that marks out which terms are first-order (Taylor) terms that should therefore always be traversed regardless of their term-magnitude (foat = first-order- always-traverse).

fn_visitpathfunction

A function called for each path that is traversed. Arguments are (term_indices, magnitude, incd) where term_indices is an array of integers giving the index into each oprep_lists[i] list, magnitude is the path magnitude, and incd is the index of the circuit layer that was just incremented (all elements of term_indices less than this index are guaranteed to be the same as they were in the last call to fn_visitpath, and this can be used for faster path evaluation.

max_npathsint, optional

The maximum number of paths to traverse. If this is 0, then there is no limit. Otherwise this function will return as soon as max_npaths paths are traversed.

debugbool, optional

Whether to print additional debug info.

Returns

None

pygsti.forwardsims.termforwardsim_calc_generic.pathmagnitude_threshold(oprep_lists, e_indices, num_elabels, target_sum_of_pathmags, foat_indices_per_op=None, initial_threshold=0.1, min_threshold=1e-10, max_npaths=1000000)

Find the pathmagnitude-threshold needed to achieve some target sum-of-path-magnitudes: so that the sum of all the path-magnitudes greater than this threshold achieve the target (or get as close as we can).

Parameters

oprep_listslist of lists

representations for the terms of each layer of the circuit whose outcome probability we’re computing, including prep and POVM layers. oprep_lists[i] is a list of the terms available to choose from for the i-th circuit layer, ordered by increasing term-magnitude.

e_indicesnumpy array

The effect-vector index for each element of oprep_lists[-1] (representations for all effect vectors exist all together in oprep_lists[-1]).

num_elabelsint

The total number of different effects whose reps appear in oprep_lists[-1] (also one more than the largest index in e_indices.

target_sum_of_pathmagsarray

An array of floats of length num_elabels giving the target sum of path magnitudes desired for each effect (separately).

foat_indices_per_oplist

A list of lists of integers, such that foat_indices_per_op[i] is a list of indices into oprep_lists[-1] that marks out which terms are first-order (Taylor) terms that should therefore always be traversed regardless of their term-magnitude (foat = first-order- always-traverse).

initial_thresholdfloat

The starting pathmagnitude threshold to try (this function uses an iterative procedure to find a threshold).

min_thresholdfloat

The smallest threshold allowed. If this amount is reached, it is just returned and searching stops.

max_npathsint, optional

The maximum number of paths allowed per effect.

Returns

thresholdfloat

The obtained pathmagnitude threshold.

npathsnumpy array

An array of length num_elabels giving the number of paths selected for each of the effect vectors.

achieved_sopmnumpy array

An array of length num_elabels giving the achieved sum-of-path- magnitudes for each of the effect vectors.