pygsti.algorithms.fiducialpairreduction
Functions for reducing the number of required fiducial pairs for analysis.
Module Contents
Functions
|
Finds a (global) set of fiducial pairs that are amplificationally complete. |
|
Finds a per-germ set of fiducial pairs that are amplificationally complete. |
|
Finds a per-germ set of fiducial pairs that are amplificationally complete. |
|
Finds a per-germ set of fiducial pairs that are amplificationally complete. |
|
Tests a set of global or per-germ fiducial pairs. |
|
|
|
|
|
Finds a per-germ set of fiducial pairs that are amplificationally complete. |
|
|
|
Function for precomputing the jacobian dictionaries from bulk_dprobs |
- pygsti.algorithms.fiducialpairreduction.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_modelModel
The target model used to determine amplificational completeness.
- prep_fiducialslist of Circuits
Fiducial circuits used to construct an informationally complete effective preparation.
- meas_fiducialslist of Circuits
Fiducial circuits used to construct an informationally complete effective measurement.
- germslist 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_tupleslist 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.
- tolfloat, 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_randomint, optional
The number of random-pair-sets to consider for a given set size.
- seedint, optional
The seed to use for generating random-pair-sets.
- verbosityint, optional
How much detail to print to stdout.
- test_pair_listlist 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_limitint, optional
A memory limit in bytes.
- minimum_pairsint, 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).
- pygsti.algorithms.fiducialpairreduction.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_modelModel
The target model used to determine amplificational completeness.
- prep_fiducialslist of Circuits
Fiducial circuits used to construct an informationally complete effective preparation.
- meas_fiducialslist of Circuits
Fiducial circuits used to construct an informationally complete effective measurement.
- germslist of Circuits
The germ circuits that are repeated to amplify errors.
- prep_povm_tupleslist 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_tpbool, 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_randomint, optional
The number of random-pair-sets to consider for a given set size.
- min_iterationsint, 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_tolfloat, 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.
- seedint, optional
The seed to use for generating random-pair-sets.
- verbosityint, optional
How much detail to print to stdout.
- num_soln_returnedint, optional
The number of candidate solutions to return for each run of the fiducial pair search.
- type_soln_returnedstr, 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_smallerbool, 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_limitint, 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).
- pygsti.algorithms.fiducialpairreduction.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_modelModel
The target model used to determine amplificational completeness.
- prep_fiducialslist of Circuits
Fiducial circuits used to construct an informationally complete effective preparation.
- meas_fiducialslist of Circuits
Fiducial circuits used to construct an informationally complete effective measurement.
- germslist of Circuits
The germ circuits that are repeated to amplify errors.
- prep_povm_tupleslist 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_tpbool, 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_tolfloat, 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_modestr, 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_tolfloat, 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_thresholdfloat, 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 <sensitivity_threshold).
- seedint, optional
The seed to use for generating random-pair-sets.
- verbosityint, optional
How much detail to print to stdout.
- mem_limitint, 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).
- pygsti.algorithms.fiducialpairreduction.find_sufficient_fiducial_pairs_per_germ_power(target_model, prep_fiducials, meas_fiducials, germs, max_lengths, prep_povm_tuples='first', search_mode='random', constrain_to_tp=True, trunc_scheme='whole germ powers', n_random=100, min_iterations=None, base_loweig_tol=0.1, seed=None, verbosity=0, mem_limit=None, per_germ_candidate_set=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:
- Case: trunc_scheme == ‘whole germ powers’:
state_prep + prep_fiducial + pygsti.circuits.repeat_with_max_length(germ,L) + meas_fiducial + meas
- Case: trunc_scheme == ‘truncated germ powers’:
state_prep + prep_fiducial + pygsti.circuits.repeat_and_truncate(germ,L) + meas_fiducial + meas
- Case: trunc_scheme == ‘length as exponent’:
state_prep + prep_fiducial + germ^L + meas_fiducial + meas
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_modelModel
The target model used to determine amplificational completeness.
- prep_fiducialslist of Circuits
Fiducial circuits used to construct an informationally complete effective preparation.
- meas_fiducialslist of Circuits
Fiducial circuits used to construct an informationally complete effective measurement.
- germslist of Circuits
The germ circuits that are repeated to amplify errors.
- max_lengths: list of int
The germ powers (number of repetitions) to be used to amplify errors.
- prep_povm_tupleslist 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_tpbool, 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_randomint, optional
The number of random-pair-sets to consider for a given set size.
- min_iterations: int, optional
The number of random-pair-sets to consider before we allow the algorithm to terminate early if it has found an acceptable candidate fiducial set. If left with the default value of None then this is 1/2 the value of n_random.
- base_loweig_tol: float, optional
A relative tolerance to apply to candidate fiducial pair sets. Gives the multiplicative reduction in the magnitude of the minimum eigenvalue relative to the value for the full fiducial set the user is willing to tolerate.
- seedint, optional
The seed to use for generating random-pair-sets.
- verbosityint, optional
How much detail to print to stdout.
- mem_limitint, optional
A memory limit in bytes.
- per_germ_candidate_setdict, optional
If specified, this is a dictionary with keys given by the germ set. This dictionary is a previously found candidate set of fiducials output from the per-germ FPR function find_sufficient_fiducial_pairs_per_germ.
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).
- pygsti.algorithms.fiducialpairreduction.test_fiducial_pairs(fid_pairs, target_model, prep_fiducials, meas_fiducials, germs, test_lengths=(256, 2048), prep_povm_tuples='first', tol=0.75, verbosity=0, mem_limit=None)
Tests a set of global or per-germ fiducial pairs.
Determines how many model parameters (of target_model) are amplified by the fiducial pairs given by fid_pairs, which can be either a list of 2-tuples (for global-FPR) or a dictionary (for per-germ FPR).
Parameters
- fid_pairslist or dict
Either a single list of fiducial-index pairs (2-tuples) that is applied to every germ (global FPR) OR a per-germ dictionary of lists, each containing the fiducial-index pairs (2-tuples) for that germ (for per-germ FPR).
- target_modelModel
The target model used to determine amplificational completeness.
- prep_fiducialslist of Circuits
Fiducial circuits used to construct an informationally complete effective preparation.
- meas_fiducialslist of Circuits
Fiducial circuits used to construct an informationally complete effective measurement.
- germslist 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_tupleslist 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.
- tolfloat, optional
The tolerance for the fraction of the expected amplification that must be observed to call a parameter “amplified”.
- verbosityint, optional
How much detail to print to stdout.
- mem_limitint, optional
A memory limit in bytes.
Returns
numAmplified : int
- pygsti.algorithms.fiducialpairreduction.construct_compact_evd_cache(fiducial_indices, complete_jacobian, element_map, eigenvalue_tolerance=1e-10)
- pygsti.algorithms.fiducialpairreduction.filter_useless_fid_pairs(fiducial_indices, element_map, complete_jacobian, sensitivity_threshold=1e-10)
- pygsti.algorithms.fiducialpairreduction.find_sufficient_fiducial_pairs_per_germ_global(target_model, prep_fiducials, meas_fiducials, germ_vector_spanning_set=None, germs=None, prep_povm_tuples='first', mem_limit=None, inv_trace_tol=10, initial_seed_mode='greedy', evd_tol=1e-10, seed=None, verbosity=0, float_type=_np.cdouble, germ_set_spanning_kwargs=None, precomputed_jacobians=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 amplified parameter.
Parameters
- target_modelModel
The target model used to determine amplificational completeness.
- prep_fiducialslist of Circuits
Fiducial circuits used to construct an informationally complete effective preparation.
- meas_fiducialslist of Circuits
Fiducial circuits used to construct an informationally complete effective measurement.
- germ_vector_spanning_setdictionary of lists
A dictionary with keys corresponding to germs and values corresponding to lists of parameter vectors (less spam parameters) for which we need sensitivity.
- germslist of circuits
If passed in and germ_vector_spanning_set is None then we’ll use this in the calculation of the germ vector spanning set.
- prep_povm_tupleslist 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.
- verbosityint, optional
How much detail to print to stdout.
- mem_limitint, optional
A memory limit in bytes.
- inv_trace_tolfloat, optional (default 10)
A threshold tolerance value corresponding to the maximum reduction in sensitivity we are willing to tolerate relative to the complete set of fiducial pairs. Specifically the increase in the trace of the inverse/psuedoinverse of the directional derivative matrix for a germ’s specified amplified parameters that we are willing to tolerate.
- initial_seed_modestr, optional (default ‘greedy’)
Specifies the manner in which an initial set of fiducial pairs is selected for a germ to seed the greedy search routine. Currently only supports ‘greedy’ wherein we start from scratch from an empty set of fiducial pairs and select them entirely greedily.
- evd_tolfloat, 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) for directional derivative matrices.
- seedint, optional (default None)
Seed for PRNGs. Not currently used.
- float_typenumpy dtype, optional (default numpy.cdouble)
Numpy data type to use for floating point arrays.
- germ_set_spanning_kwargsdict, optional (default None)
A dictionary of optional kwargs for the function pygsti.algorithms.germselection.germ_set_spanning_vectors. See doctring for that function for more details. Only utilized if the germ_vector_spanning_set argument of this function is None.
- precomputed_jacobiansdict, optional (default None)
An optional dictionary of precomputed jacobian dictionaries for the germ fiducial pair set. The keys are germs and the values are the dictionaries corresponding that that germ-fiducial-pair set’s jacobian.
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).
- pygsti.algorithms.fiducialpairreduction.get_per_germ_fid_pairs_global(prep_fiducials, meas_fiducials, prep_povm_tuples, target_model, germ, germ_vector_list, mem_limit, printer, dof_per_povm, inv_trace_tol=10, initial_seed_mode='greedy', evd_tol=1e-10, float_type=_np.cdouble, dprobs_dict=None)
- pygsti.algorithms.fiducialpairreduction.compute_jacobian_dicts(model, germs, prep_fiducials, meas_fiducials, prep_povm_tuples='first', comm=None, mem_limit=None, verbosity=0)
Function for precomputing the jacobian dictionaries from bulk_dprobs for a model with its SPAM parameters frozen, as needed for certain FPR applications. Can take a comm object for parallelization of the jacobian calculation using MPI.
- modelModel
The model used for calculating the jacobian with respect to.
- germs :list of Circuits
Germs to construct the jacobian dictionaries for.
- prep_fiducialslist of Circuits
A list of preparation fiducials circuits.
- meas_fiducialslist of Circuits
A list of measurement fiducial circuits.
- prep_povm_tuplesstr or list of tuples (default ‘first’)
Either a string or list of tuples. When a list of tuples these correspond to native state prep and native POVM pairs. When the special keyword argument ‘first’ is passed in the first native prep and first native POVM are used.
- commmpi4py.MPI.Comm, optional
When not
None, an MPI communicator for distributing the computation across multiple processors is used for the jacobian calculation.- mem_limitint, optional (default None)
An optional per-worker memory limit, in bytes.
Returns
- jacobian_dictsdictionary of dictionaries
A dictionary whose keys correspond to germs and whose values correspond the jacobian dictionaries for the list of circuits induced by that germ together with the set of fiducials pairs. Format of these correspond to the format returned by bulk_dprobs.