:py:mod:`pygsti.forwardsims.termforwardsim_calc_generic` ======================================================== .. py:module:: pygsti.forwardsims.termforwardsim_calc_generic .. autoapi-nested-parse:: Defines generic Python-version of map forward simuator calculations Module Contents --------------- Functions ~~~~~~~~~ .. autoapisummary:: pygsti.forwardsims.termforwardsim_calc_generic.prs_as_polynomials pygsti.forwardsims.termforwardsim_calc_generic.prs_directly pygsti.forwardsims.termforwardsim_calc_generic.refresh_magnitudes_in_repcache pygsti.forwardsims.termforwardsim_calc_generic.circuit_achieved_and_max_sopm pygsti.forwardsims.termforwardsim_calc_generic.find_best_pathmagnitude_threshold pygsti.forwardsims.termforwardsim_calc_generic.compute_pruned_path_polynomials_given_threshold pygsti.forwardsims.termforwardsim_calc_generic.create_circuitsetup_cacheel pygsti.forwardsims.termforwardsim_calc_generic.traverse_paths_upto_threshold pygsti.forwardsims.termforwardsim_calc_generic.pathmagnitude_threshold Attributes ~~~~~~~~~~ .. autoapisummary:: pygsti.forwardsims.termforwardsim_calc_generic.SMALL pygsti.forwardsims.termforwardsim_calc_generic.LOGSMALL .. py:data:: SMALL :value: '1e-05' .. py:data:: LOGSMALL :value: '-5' .. py:function:: 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`. .. py:function:: prs_directly(fwdsim, rholabel, elabels, circuit, repcache, comm=None, mem_limit=None, fastmode=True, wt_tol=0.0, reset_term_weights=True, debug=None) .. py:function:: refresh_magnitudes_in_repcache(repcache, paramvec) .. py:function:: 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. .. py:function:: 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.) .. py:function:: 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. .. py:function:: create_circuitsetup_cacheel(fwdsim, rholabel, elabels, circuit, repcache, min_term_mag, mpv) .. py:function:: 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 .. py:function:: 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.