pygsti.forwardsims.termforwardsim_calc_generic
Defines generic Pythonversion of map forward simuator calculations
Module Contents
Functions

Computes polynomials of the probabilities for multiple spamtuples of circuit 





Compute the achieved and maximum sumofpathmagnitudes (SOPM) for a given circuit and model. 

Computes probabilities for multiple spamtuples of circuit 
Computes probabilities for multiple spamtuples of circuit 




Traverse all the paths up to some pathmagnitude threshold, calling 

Find the pathmagnitudethreshold needed to achieve some target sumofpathmagnitudes: 
Attributes
 pygsti.forwardsims.termforwardsim_calc_generic.SMALL = '1e05'
 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 spamtuples 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 platformwidth 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 sumofpathmagnitudes (SOPM) for a given circuit and model.
This is a helper function for a TermForwardSimulator, and not typically called independently.
A pathintegral 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” sumofpathmagnitudes. This can be compared with a second quantity, the “maximum” sum ofpathmagnitudes 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 nonSPAM operations that make up the circuit that values are computed for.
 repcachedict
A dictionary of alreadybuild 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 prepathmagnitude threshold that lessens computational overhead by ignoring terms that have a very small magnitude.
Returns
 achieved_sopmfloat
The achieved sumofpathmagnitudes.
 max_sopmfloat
The approximate maximum sumofpathmagnitudes.
 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 spamtuples 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 sumofpathmagnitudes that is desired. This sets the target sumofpathmagnitudes 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 pathmagnitude threshold used.
 target_sopmfloat
The desired sumofpathmagnitudes. This is pathmagnitude_gap less than the perfect “allpaths” sum. This sums together the contributions of different effects.
 achieved_sopmfloat
The achieved sumofpathmagnitudes. 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 spamtuples 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 highmagnitude 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 pathmagnitude 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 ith circuit layer, ordered by increasing termmagnitude.
 pathmag_thresholdfloat
the pathmagnitude 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 firstorder (Taylor) terms that should therefore always be traversed regardless of their termmagnitude (foat = firstorder alwaystraverse).
 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=1e10, max_npaths=1000000)
Find the pathmagnitudethreshold needed to achieve some target sumofpathmagnitudes: so that the sum of all the pathmagnitudes 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 ith circuit layer, ordered by increasing termmagnitude.
 e_indicesnumpy array
The effectvector 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 firstorder (Taylor) terms that should therefore always be traversed regardless of their termmagnitude (foat = firstorder alwaystraverse).
 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 sumofpath magnitudes for each of the effect vectors.