:py:mod:`pygsti.algorithms.fiducialpairreduction` ================================================= .. py:module:: pygsti.algorithms.fiducialpairreduction .. autoapi-nested-parse:: Functions for reducing the number of required fiducial pairs for analysis. Module Contents --------------- Functions ~~~~~~~~~ .. autoapisummary:: pygsti.algorithms.fiducialpairreduction.find_sufficient_fiducial_pairs pygsti.algorithms.fiducialpairreduction.find_sufficient_fiducial_pairs_per_germ pygsti.algorithms.fiducialpairreduction.find_sufficient_fiducial_pairs_per_germ_greedy pygsti.algorithms.fiducialpairreduction.find_sufficient_fiducial_pairs_per_germ_power pygsti.algorithms.fiducialpairreduction.test_fiducial_pairs pygsti.algorithms.fiducialpairreduction.construct_compact_evd_cache pygsti.algorithms.fiducialpairreduction.filter_useless_fid_pairs pygsti.algorithms.fiducialpairreduction.find_sufficient_fiducial_pairs_per_germ_global pygsti.algorithms.fiducialpairreduction.get_per_germ_fid_pairs_global pygsti.algorithms.fiducialpairreduction.compute_jacobian_dicts .. py:function:: find_sufficient_fiducial_pairs(target_model, prep_fiducials, meas_fiducials, germs, test_lengths=(256, 2048), prep_povm_tuples='first', tol=0.75, search_mode='sequential', n_random=100, seed=None, verbosity=0, test_pair_list=None, mem_limit=None, minimum_pairs=1) Finds a (global) set of fiducial pairs that are amplificationally complete. A "standard" set of GST circuits consists of all circuits of the form: statePrep + prepFiducial + germPower + measureFiducial + measurement This set is typically over-complete, and it is possible to restrict the (prepFiducial, measureFiducial) pairs to a subset of all the possible pairs given the separate `prep_fiducials` and `meas_fiducials` lists. This function attempts to find a set of fiducial pairs that still amplify all of the model's parameters (i.e. is "amplificationally complete"). The test for amplification is performed using the two germ-power lengths given by `test_lengths`, and tests whether the magnitudes of the Jacobian's singular values scale linearly with the germ-power length. In the special case when `test_pair_list` is not None, the function *tests* the given set of fiducial pairs for amplificational completeness, and does not perform any search. Parameters ---------- target_model : Model The target model used to determine amplificational completeness. prep_fiducials : list of Circuits Fiducial circuits used to construct an informationally complete effective preparation. meas_fiducials : list of Circuits Fiducial circuits used to construct an informationally complete effective measurement. germs : list of Circuits The germ circuits that are repeated to amplify errors. test_lengths : (L1,L2) tuple of ints, optional A tuple of integers specifying the germ-power lengths to use when checking for amplificational completeness. prep_povm_tuples : list or "first", optional A list of `(prepLabel, povmLabel)` tuples to consider when checking for completeness. Usually this should be left as the special (and default) value "first", which considers the first prep and POVM contained in `target_model`. tol : float, optional The tolerance for the fraction of the expected amplification that must be observed to call a parameter "amplified". search_mode : {"sequential","random"}, optional If "sequential", then all potential fiducial pair sets of a given length are considered in sequence before moving to sets of a larger size. This can take a long time when there are many possible fiducial pairs. If "random", then only `n_random` randomly chosen fiducial pair sets are considered for each set size before the set is enlarged. n_random : int, optional The number of random-pair-sets to consider for a given set size. seed : int, optional The seed to use for generating random-pair-sets. verbosity : int, optional How much detail to print to stdout. test_pair_list : list or None, optional If not None, a list of (prepfid_index,measfid_index) tuples of integers, specifying a list of fiducial pairs (indices are into `prep_fiducials` and `meas_fiducials`, respectively). These pairs are then tested for amplificational completeness and the number of amplified parameters is printed to stdout. (This is a special debugging functionality.) mem_limit : int, optional A memory limit in bytes. minimum_pairs : int, optional The minimium number of fiducial pairs to try (default == 1). Set this to integers larger than 1 to avoid trying pair sets that are known to be too small. Returns ------- list A list of (prepfid_index,measfid_index) tuples of integers, specifying a list of fiducial pairs (indices are into `prep_fiducials` and `meas_fiducials`). .. py:function:: find_sufficient_fiducial_pairs_per_germ(target_model, prep_fiducials, meas_fiducials, germs, prep_povm_tuples='first', search_mode='random', constrain_to_tp=True, n_random=100, min_iterations=None, base_loweig_tol=0.1, seed=None, verbosity=0, num_soln_returned=1, type_soln_returned='best', retry_for_smaller=True, mem_limit=None) Finds a per-germ set of fiducial pairs that are amplificationally complete. A "standard" set of GST circuits consists of all circuits of the form: statePrep + prepFiducial + germPower + measureFiducial + measurement This set is typically over-complete, and it is possible to restrict the (prepFiducial, measureFiducial) pairs to a subset of all the possible pairs given the separate `prep_fiducials` and `meas_fiducials` lists. This function attempts to find sets of fiducial pairs, one set per germ, that still amplify all of the model's parameters (i.e. is "amplificationally complete"). For each germ, a fiducial pair set is found that amplifies all of the "parameters" (really linear combinations of them) that the particular germ amplifies. To test whether a set of fiducial pairs satisfies this condition, the sum of projectors `P_i = dot(J_i,J_i^T)`, where `J_i` is a matrix of the derivatives of each of the selected (prepFiducial+germ+effectFiducial) sequence probabilities with respect to the i-th germ eigenvalue (or more generally, amplified parameter), is computed. If the fiducial-pair set is sufficient, the rank of the resulting sum (an operator) will be equal to the total (maximal) number of parameters the germ can amplify. Parameters ---------- target_model : Model The target model used to determine amplificational completeness. prep_fiducials : list of Circuits Fiducial circuits used to construct an informationally complete effective preparation. meas_fiducials : list of Circuits Fiducial circuits used to construct an informationally complete effective measurement. germs : list of Circuits The germ circuits that are repeated to amplify errors. prep_povm_tuples : list or "first", optional A list of `(prepLabel, povmLabel)` tuples to consider when checking for completeness. Usually this should be left as the special (and default) value "first", which considers the first prep and POVM contained in `target_model`. search_mode : {"sequential","random"}, optional If "sequential", then all potential fiducial pair sets of a given length are considered in sequence (per germ) before moving to sets of a larger size. This can take a long time when there are many possible fiducial pairs. If "random", then only `n_random` randomly chosen fiducial pair sets are considered for each set size before the set is enlarged. constrain_to_tp : bool, optional Whether or not to consider non-TP parameters the the germs amplify. If the fiducal pairs will be used in a GST estimation where the model is constrained to being trace-preserving (TP), this should be set to True. n_random : int, optional The number of random-pair-sets to consider for a given set size. min_iterations : int, optional A minimum number of candidate fiducial sets to try for a given set size before allowing the search to exit early in the event an acceptable candidate solution has already been found. base_loweig_tol : float, optional (default 1e-1) A relative threshold value for determining if a fiducial set is an acceptable candidate solution. The tolerance value indicates the decrease in the magnitude of the smallest eigenvalue of the Jacobian we're will to accept relative to that of the full fiducial set. seed : int, optional The seed to use for generating random-pair-sets. verbosity : int, optional How much detail to print to stdout. num_soln_returned : int, optional The number of candidate solutions to return for each run of the fiducial pair search. type_soln_returned : str, optional Which type of criteria to use when selecting which of potentially many candidate fiducial pairs to search through. Currently only "best" supported which returns the num_soln_returned best candidates as measured by minimum eigenvalue. retry_for_smaller : bool, optional If true then a second search is performed seeded by the candidate solution sets found in the first pass. The search routine then randomly subsamples sets of fiducial pairs from these candidate solutions to see if a smaller subset will suffice. mem_limit : int, optional A memory limit in bytes. Returns ------- dict A dictionary whose keys are the germ circuits and whose values are lists of (iRhoFid,iMeasFid) tuples of integers, each specifying the list of fiducial pairs for a particular germ (indices are into `prep_fiducials` and `meas_fiducials`). .. py:function:: find_sufficient_fiducial_pairs_per_germ_greedy(target_model, prep_fiducials, meas_fiducials, germs, prep_povm_tuples='first', constrain_to_tp=True, inv_trace_tol=10, initial_seed_mode='random', evd_tol=1e-10, sensitivity_threshold=1e-10, seed=None, verbosity=0, check_complete_fid_set=True, mem_limit=None) Finds a per-germ set of fiducial pairs that are amplificationally complete. A "standard" set of GST circuits consists of all circuits of the form: statePrep + prepFiducial + germPower + measureFiducial + measurement This set is typically over-complete, and it is possible to restrict the (prepFiducial, measureFiducial) pairs to a subset of all the possible pairs given the separate `prep_fiducials` and `meas_fiducials` lists. This function attempts to find sets of fiducial pairs, one set per germ, that still amplify all of the model's parameters (i.e. is "amplificationally complete"). For each germ, a fiducial pair set is found that amplifies all of the "parameters" (really linear combinations of them) that the particular germ amplifies. To test whether a set of fiducial pairs satisfies this condition, the sum of projectors `P_i = dot(J_i,J_i^T)`, where `J_i` is a matrix of the derivatives of each of the selected (prepFiducial+germ+effectFiducial) sequence probabilities with respect to the i-th germ eigenvalue (or more generally, amplified parameter), is computed. If the fiducial-pair set is sufficient, the rank of the resulting sum (an operator) will be equal to the total (maximal) number of parameters the germ can amplify. Parameters ---------- target_model : Model The target model used to determine amplificational completeness. prep_fiducials : list of Circuits Fiducial circuits used to construct an informationally complete effective preparation. meas_fiducials : list of Circuits Fiducial circuits used to construct an informationally complete effective measurement. germs : list of Circuits The germ circuits that are repeated to amplify errors. prep_povm_tuples : list or "first", optional A list of `(prepLabel, povmLabel)` tuples to consider when checking for completeness. Usually this should be left as the special (and default) value "first", which considers the first prep and POVM contained in `target_model`. constrain_to_tp : bool, optional (default True) Whether or not to consider non-TP parameters the the germs amplify. If the fiducal pairs will be used in a GST estimation where the model is constrained to being trace-preserving (TP), this should be set to True. inv_trace_tol : float, optional (default 10) Tolerance used to identify whether a candidate fiducial set has a feasible cost function value and for comparing among both complete and incomplete candidate sets. The cost function corresonds to trace(pinv(sum_i(dot(J_i,J_i^T)))), where the J_i's are described above, which is related to a condition in optimal design theory called a-optimality. The tolerance is a relative tolerance compared to the complete fiducial set. This essentially measures the relative sensitivity loss we're willing to accept as part of applying FPR. initial_seed_mode : str, optional (default 'random') A string corresponding to the method used to seed an initial set of fiducial pairs in starting the greedy search routine. The default 'random' identifies the minimum number of fiducial pairs required for sensitivity to every parameter of a given germ and then randomly samples that number of fiducial pairs to use as an initial seed. Also supports the option 'greedy' in which case we start the greedy search from scratch using an empty seed set and select every fiducial pair greedily. Random is generally faster computationally, but greedy has been fount to often (but not always) find a smaller solution. evd_tol : float, optional (default 1e-10) Threshold value for eigenvalues below which they are treated as zero. Used in the construction of compact eigenvalue decompositions (technically rank-decompositions) of jacobians. If encountering an error related to failing Cholesky decompositions consider increasing the value of this tolerance. sensitivity_threshold : float, optional (default 1e-10) Threshold used for determing is a fiducial pair is useless for measuring a given germ's amplified parameters due to trivial sensitivity to the germ kite parameters (norm of jacobian w.r.t. the kite parameters is