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 



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.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
fwdsim (TermForwardSimulator) – The calculator object holding vital information for the computation.
rholabel (Label) – Prep label for all the probabilities to compute.
elabels (list) – List of effect labels, one per probability to compute. The ordering of elabels determines the ordering of the returned probability polynomials.
circuit (Circuit) – The gate sequence to sandwich between the prep and effect labels.
polynomial_vindices_per_int (int) – 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).
comm (mpi4py.MPI.Comm, optional) – When not None, an MPI communicator for distributing the computation across multiple processors.
mem_limit (int, optional) – A rough memory limit in bytes.
fastmode (bool, 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
fwdsim (TermForwardSimulator) – The forward simulator. Contains the model that is used.
rholabel (Label) – The preparation label, which precedes the layers in circuit. Note that circuit should not contain any preparation or POVM labels  only the operation labels.
elabels (list 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.
circuit (Circuit) – The nonSPAM operations that make up the circuit that values are computed for.
repcache (dict) – 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.
threshold (float) – 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_mag (float) – 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_sopm (float) – The achieved sumofpathmagnitudes.
max_sopm (float) – 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
fwdsim (TermForwardSimulator) – The calculator object holding vital information for the computation.
rholabel (Label) – Prep label for all the probabilities to compute.
elabels (list) – List of effect labels, one per probability to compute. The ordering of elabels determines the ordering of the returned probability polynomials.
circuit (Circuit) – The gate sequence to sandwich between the prep and effect labels.
repcache (dict, optional) – Dictionary used to cache operator representations to speed up future calls to this function that would use the same set of operations.
circuitsetup_cache (dict, 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.
comm (mpi4py.MPI.Comm, optional) – When not None, an MPI communicator for distributing the computation across multiple processors.
mem_limit (int, optional) – A rough memory limit in bytes.
pathmagnitude_gap (float, 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_mag (float, 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_paths (int, optional) – The maximum number of paths allowed per circuit outcome.
threshold_guess (float, 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
npaths (int) – the number of paths that were included.
threshold (float) – the pathmagnitude threshold used.
target_sopm (float) – The desired sumofpathmagnitudes. This is pathmagnitude_gap less than the perfect “allpaths” sum. This sums together the contributions of different effects.
achieved_sopm (float) – 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
fwdsim (TermForwardSimulator) – The calculator object holding vital information for the computation.
rholabel (Label) – Prep label for all the probabilities to compute.
elabels (list) – List of effect labels, one per probability to compute. The ordering of elabels determines the ordering of the returned probability polynomials.
circuit (Circuit) – The gate sequence to sandwich between the prep and effect labels.
repcache (dict, optional) – Dictionary used to cache operator representations to speed up future calls to this function that would use the same set of operations.
circuitsetup_cache (dict, 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.
comm (mpi4py.MPI.Comm, optional) – When not None, an MPI communicator for distributing the computation across multiple processors.
mem_limit (int, optional) – A rough memory limit in bytes.
fastmode (bool, optional) – A switch between a faster, slighty more memory hungry mode of computation (fastmode=True)and a simpler slower one (=False).
 Returns
prps (list 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._prs_as_pruned_polys(fwdsim, rholabel, elabels, circuit, repcache, comm=None, mem_limit=None, fastmode=True, pathmagnitude_gap=0.0, min_term_mag=0.01, max_paths=500, current_threshold=None, compute_polyreps=True)¶
Computes probabilities for multiple spamtuples of circuit
 Parameters
fwdsim (TermForwardSimulator) – The calculator object holding vital information for the computation.
rholabel (Label) – Prep label for all the probabilities to compute.
elabels (list) – List of effect labels, one per probability to compute. The ordering of elabels determines the ordering of the returned probability polynomials.
circuit (Circuit) – The gate sequence to sandwich between the prep and effect labels.
repcache (dict, optional) – Dictionary used to cache operator representations to speed up future calls to this function that would use the same set of operations.
comm (mpi4py.MPI.Comm, optional) – When not None, an MPI communicator for distributing the computation across multiple processors.
mem_limit (int, optional) – A rough memory limit in bytes.
fastmode (bool, optional) – A switch between a faster, slighty more memory hungry mode of computation (fastmode=True)and a simpler slower one (=False).
pathmagnitude_gap (float, 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_mag (float, 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.
current_threshold (float, optional) – If the threshold needed to achieve the desired pathmagnitude_gap is greater than this value (i.e. if using current_threshold would result in more paths being computed) then this function will not compute any paths and exit early, returning None in place of the usual list of polynomial representations.
max_paths (int, optional) – The maximum number of paths that will be summed to compute the polynomials for this circuit.
compute_polyreps (bool, optional) – If False, then the polynomials are not actually constructed – only the sumofpathmagnitudes are computed. This is useful when testing a given threshold to see if the paths are sufficient, before committing to building all of the polynomials (which can be time consuming).
 Returns
prps (list of PolynomialRep objects) – the polynomials for the requested circuit probabilities, computed by selectively summing up highmagnitude paths. If compute_polyreps == False, then an empty list is returned.
npaths (int) – the number of paths that were included.
threshold (float) – the pathmagnitude threshold used.
target_sopm (float) – The desired sumofpathmagnitudes. This is pathmagnitude_gap less than the perfect “allpaths” sum. This sums together the contributions of different effects.
achieved_sopm (float) – The achieved sumofpathmagnitudes. Ideally this would equal target_sopm. (This also sums together the contributions of different effects.)
 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_lists (list 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_threshold (float) – the pathmagnitude threshold to use.
num_elabels (int) – 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_op (list) – 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_visitpath (function) – 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_npaths (int, 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.
debug (bool, 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_lists (list 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_indices (numpy array) – The effectvector index for each element of oprep_lists[1] (representations for all effect vectors exist all together in oprep_lists[1]).
num_elabels (int) – 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_pathmags (array) – An array of floats of length num_elabels giving the target sum of path magnitudes desired for each effect (separately).
foat_indices_per_op (list) – 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_threshold (float) – The starting pathmagnitude threshold to try (this function uses an iterative procedure to find a threshold).
min_threshold (float) – The smallest threshold allowed. If this amount is reached, it is just returned and searching stops.
max_npaths (int, optional) – The maximum number of paths allowed per effect.
 Returns
threshold (float) – The obtained pathmagnitude threshold.
npaths (numpy array) – An array of length num_elabels giving the number of paths selected for each of the effect vectors.
achieved_sopm (numpy array) – An array of length num_elabels giving the achieved sumofpath magnitudes for each of the effect vectors.
 pygsti.forwardsims.termforwardsim_calc_generic._unitary_sim_pre(complete_factors, comm, mem_limit)¶
 pygsti.forwardsims.termforwardsim_calc_generic._unitary_sim_post(complete_factors, comm, mem_limit)¶