pygsti.forwardsims.termforwardsim_calc_generic

Defines generic Python-version of map forward simuator calculations

Module Contents

Functions

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

prs_directly(fwdsim, rholabel, elabels, circuit, repcache, comm=None, mem_limit=None, fastmode=True, wt_tol=0.0, reset_term_weights=True, debug=None)

refresh_magnitudes_in_repcache(repcache, paramvec)

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.

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

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

create_circuitsetup_cacheel(fwdsim, rholabel, elabels, circuit, repcache, min_term_mag, mpv)

_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 spam-tuples of circuit

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

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:

_unitary_sim_pre(complete_factors, comm, mem_limit)

_unitary_sim_post(complete_factors, comm, mem_limit)

Attributes

SMALL

pygsti.forwardsims.termforwardsim_calc_generic.SMALL = 1e-05
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
  • 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 platform-width 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 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
  • 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 non-SPAM operations that make up the circuit that values are computed for.

  • repcache (dict) – 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.

  • 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 pre-path-magnitude threshold that lessens computational overhead by ignoring terms that have a very small magnitude.

Returns

  • achieved_sopm (float) – The achieved sum-of-path-magnitudes.

  • max_sopm (float) – 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
  • 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 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_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 path-magnitude threshold used.

  • target_sopm (float) – 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_sopm (float) – 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
  • 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 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._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 spam-tuples 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 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_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 sum-of-path-magnitudes 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 high-magnitude paths. If compute_polyreps == False, then an empty list is returned.

  • npaths (int) – the number of paths that were included.

  • threshold (float) – the path-magnitude threshold used.

  • target_sopm (float) – 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_sopm (float) – 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.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_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 i-th circuit layer, ordered by increasing term-magnitude.

  • pathmag_threshold (float) – the path-magnitude 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 first-order (Taylor) terms that should therefore always be traversed regardless of their term-magnitude (foat = first-order- always-traverse).

  • 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=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_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 i-th circuit layer, ordered by increasing term-magnitude.

  • e_indices (numpy 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_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 first-order (Taylor) terms that should therefore always be traversed regardless of their term-magnitude (foat = first-order- always-traverse).

  • 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 sum-of-path- 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)