pygsti.algorithms.fiducialselection
Functions for selecting a complete set of fiducials for a GST analysis.
Module Contents
Functions
|
Generate prep and measurement fiducials for a given target model. |
|
Implements logical xor function for arbitrary number of inputs. |
|
|
|
Function for generating a cache of PTMs for the available fiducials. |
|
Make a dictionary structure mapping native state preps and circuits to numpy |
|
Make a dictionary structure mapping native measurements and circuits to numpy |
|
Make a list of matrices for the model preparation operations. |
|
Make a list of matrices for the model measurement operations. |
|
Compute a composite score for a fiducial list. |
|
Tests a prep or measure fiducial list for informational completeness. |
|
Create an array of all length-n and Hamming weight k binary vectors. |
|
|
|
Parameters |
|
Generate prep and measurement fiducials for a given target model. |
- pygsti.algorithms.fiducialselection.find_fiducials(target_model, omit_identity=True, eq_thresh=1e-06, ops_to_omit=None, force_empty=True, candidate_fid_counts=2, algorithm='grasp', algorithm_kwargs=None, verbosity=1, prep_fids=True, meas_fids=True, candidate_list=None, return_candidate_list=False, final_test=False, assume_clifford=False, candidate_seed=None, max_fid_length=None)
Generate prep and measurement fiducials for a given target model.
Parameters
- target_modelModel
The model you are aiming to implement.
- omit_identitybool, optional
Whether to remove the identity gate from the set of gates with which fiducials are constructed. Identity gates do nothing to alter fiducials, and so should almost always be left out.
- eq_threshfloat, optional
Threshold for determining if a gate is the identity gate. If the square Frobenius distance between a given gate and the identity gate is less than this threshold, the gate is considered to be an identity gate and will be removed from the list of gates from which to construct fiducials if omit_identity is
True.- ops_to_omitlist of string, optional
List of strings identifying gates in the model that should not be used in fiducials. Oftentimes this will include the identity gate, and may also include entangling gates if their fidelity is anticipated to be much worse than that of single-system gates.
- force_emptybool, optional (default is True)
Whether or not to force all fiducial sets to contain the empty gate string as a fiducial.
- candidate_fid_countsint or dic, optional
A dictionary of fid_length : count key-value pairs, specifying the fiducial “candidate list” - a list of potential fiducials to draw from. count is either an integer specifying the number of random fiducials considered at the given fid_length or the special values “all upto” that considers all of the of all the fiducials of length up to the corresponding fid_length. If the keyword ‘all’ is used for the count value then all circuits at that particular length are added. If and integer, all germs of up to length that length are used, the equivalent of {specified_int: ‘all upto’}.
- algorithm{‘slack’, ‘grasp’, ‘greedy’}, optional
Specifies the algorithm to use to generate the fiducials. Current options are:
- ‘slack’
See
_find_fiducials_integer_slack()for more details.- ‘grasp’
Use GRASP to generate random greedy fiducial sets and then locally optimize them. See
_find_fiducials_grasp()for more details.- ‘greedy’
Use a greedy algorithm accelerated using low-rank update techniques. See
_find_fiducials_greedy()for more details.
- algorithm_kwargsdict
Dictionary of
{'keyword': keyword_arg}pairs providing keyword arguments for the specified algorithm function. See the documentation for functions referred to in the algorithm keyword documentation for what options are available for each algorithm.- verbosityint, optional
How much detail to send to stdout.
- candidate_listlist of circuits, optional
A user specified manually selected list of candidate fiducial circuits. Can speed up testing multiple objective function options, for example.
- return_candidate_list: bool, optional (default False)
When True we return the full list of deduped candidate fiducials considered along with the final fiducial lists.
- final_testbool, optional (default False)
When true a final check is performed on the returned solution for the candidate prep and measurement lists using the function test_fiducial_list to verify we have an acceptable candidate set (this uses a different code path in some cases so can be used to detect errors).
- assume_cliffordbool, optional (default False)
When true then we assume that all of the circuits are clifford circuits, which allows us to use a faster deduping routine exploiting the properties of clifford circuits.
- max_fid_lengthint, optional (deprecated)
The maximum number of gates to include in a fiducial. The default is not guaranteed to work for arbitrary models (particularly for quantum systems larger than a single qubit). This keyword is now deprecated. The behavior of the keyword is now equivalent to passing in an int for the candidate_fid_counts argument.
Returns
- prepFidListlist of Circuits
A list containing the circuits for the prep fiducials.
- measFidListlist of Circuits
A list containing the circuits for the measurement fiducials.
- pygsti.algorithms.fiducialselection.xor(*args)
Implements logical xor function for arbitrary number of inputs.
Parameters
- argsbool-likes
All the boolean (or boolean-like) objects to be checked for xor satisfaction.
Returns
- outputbool
True if and only if one and only one element of args is True and the rest are False. False otherwise.
- pygsti.algorithms.fiducialselection.clean_fid_list(model, circuit_cache, available_fid_list, drop_identities=True, drop_duplicates=True, eq_thresh=1e-06, assume_clifford=False)
- pygsti.algorithms.fiducialselection.create_circuit_cache(model, circuit_list)
Function for generating a cache of PTMs for the available fiducials.
Parameters
- modelModel
The model (associates operation matrices with operation labels).
- ckt_listlist of Circuits
Full list of all fiducial circuits avalable for constructing an informationally complete state preparation.
Returns
- dictionary
A dictionary with keys given by circuits with corresponding entries being the PTMs for that circuit.
- pygsti.algorithms.fiducialselection.create_prep_cache(model, available_prep_fid_list, circuit_cache=None)
Make a dictionary structure mapping native state preps and circuits to numpy column vectors for the corresponding effective state prep.
This can then be passed into ‘create_prep_mxs’ to more efficiently generate the matrices for score function evaluation.
Parameters
- modelModel
The model (associates operation matrices with operation labels).
- available_prep_fid_listlist of Circuits
Full list of all fiducial circuits avalable for constructing an informationally complete state preparation.
- circuit_cachedict
dictionary of PTMs for the circuits in the available_prep_fid_list
Returns
- dictionary
A dictionary with keys given be tuples of the form (native_prep, ckt) with corresponding entries being the numpy vectors for that state prep.
- pygsti.algorithms.fiducialselection.create_meas_cache(model, available_meas_fid_list, circuit_cache=None)
Make a dictionary structure mapping native measurements and circuits to numpy column vectors corresponding to the transpose of the effective measurement effects.
This can then be passed into ‘create_meas_mxs’ to more efficiently generate the matrices for score function evaluation.
Parameters
- modelModel
The model (associates operation matrices with operation labels).
- available_meas_fid_listlist of Circuits
Full list of all fiducial circuits avalable for constructing an informationally complete measurements.
- circuit_cachedict
dictionary of PTMs for the circuits in the available_meas_fid_list
Returns
- tuple with dictionary and lists of POVM and Effect Key pairs.
A dictionary with keys given be tuples of the form (native_povm, native_povm_effect, ckt) with corresponding entries being the numpy vectors for the transpose of that effective measurement effect.
- pygsti.algorithms.fiducialselection.create_prep_mxs(model, prep_fid_list, prep_cache=None)
Make a list of matrices for the model preparation operations.
Makes a list of matrices, where each matrix corresponds to a single preparation operation in the model, and the column of each matrix is a fiducial acting on that state preparation.
Parameters
- modelModel
The model (associates operation matrices with operation labels).
- prep_fid_listlist of Circuits
List of fiducial circuits for constructing an informationally complete state preparation.
- prep_cachedictionary of effective state preps
Dictionary of effective state preps cache used to accelerate the generation of the matrices used for score function evaluation. Default value is None.
Returns
- list
A list of matrices, each of shape (dim, len(prep_fid_list)) where dim is the dimension of model (4 for a single qubit). The length of this list is equal to the number of state preparations in model.
- pygsti.algorithms.fiducialselection.create_meas_mxs(model, meas_fid_list, meas_cache=None)
Make a list of matrices for the model measurement operations.
Makes a list of matrices, where each matrix corresponds to a single measurement effect in the model, and the column of each matrix is the transpose of the measurement effect acting on a fiducial.
Parameters
- modelModel
The model (associates operation matrices with operation labels).
- meas_fid_listlist of Circuits
List of fiducial circuits for constructing an informationally complete measurement.
- meas_cachedictionary of effective measurement effects
Dictionary of effective measurement effects cache used to accelerate the generation of the matrices used for score function evaluation. Entries are columns of the transpose of the effects. Default value is None.
Returns
- list
A list of matrices, each of shape (dim, len(meas_fid_list)) where dim is the dimension of model (4 for a single qubit). The length of this list is equal to the number of POVM effects in model.
- pygsti.algorithms.fiducialselection.compute_composite_fiducial_score(model, fid_list, prep_or_meas, score_func='all', threshold=1000000.0, return_all=False, op_penalty=0.0, l1_penalty=0.0, gate_penalty=None, fid_cache=None)
Compute a composite score for a fiducial list.
Parameters
- modelModel
The model (associates operation matrices with operation labels).
- fid_listlist of Circuits
List of fiducial circuits to test.
- prep_or_measstring (“prep” or “meas”)
Are we testing preparation or measurement fiducials?
- score_funcstr (‘all’ or ‘worst’), optional (default is ‘all’)
Sets the objective function for scoring a fiducial set. If ‘all’, score is (number of fiducials) * sum(1/Eigenvalues of score matrix). If ‘worst’, score is (number of fiducials) * 1/min(Eigenvalues of score matrix). Note: Choosing ‘worst’ corresponds to trying to make the optimizer make the “worst” direction (the one we are least sensitive to in Hilbert-Schmidt space) as minimally bad as possible. Choosing ‘all’ corresponds to trying to make the optimizer make us as sensitive as possible to all directions in Hilbert-Schmidt space. (Also note- because we are using a simple integer program to choose fiducials, it is possible to get stuck in a local minimum, and choosing one or the other objective function can help avoid such minima in different circumstances.)
- thresholdfloat, optional (default is 1e6)
Specifies a maximum score for the score matrix, above which the fiducial set is rejected as informationally incomplete.
- return_allbool, optional (default is False)
Whether the spectrum should be returned along with the score.
- op_penaltyfloat, optional (default is 0.0)
Coefficient of a penalty linear in the total number of gates in all fiducials that is added to
score.minor.- l1_penaltyfloat, optional (default is 0.0)
Coefficient of a penalty linear in the number of fiducials that is added to
score.minor.- gate_penaltydict, optional
A dictionary with keys given by individual gates and values corresponding to the penalty to add for each instance of that gate in the fiducial set.
- fid_cachedict, optional (default is None)
A dictionary of either effective state preparations or measurement effects used to accelerate the generation of the matrix used for scoring. It’s assumed that the user will pass in the correct cache based on the type of fiducial set being created (if wrong a fall back will revert to redoing all the matrix multiplication again).
Returns
- scoreCompositeScore
The score of the fiducials.
- spectrumnumpy.array, optional
The eigenvalues of the square of the absolute value of the score matrix.
- pygsti.algorithms.fiducialselection.test_fiducial_list(model, fid_list, prep_or_meas, score_func='all', return_all=False, threshold=1000000.0, l1_penalty=0.0, op_penalty=0.0, fid_cache=None)
Tests a prep or measure fiducial list for informational completeness.
Parameters
- modelModel
The model (associates operation matrices with operation labels).
- fid_listlist of Circuits
List of fiducial circuits to test.
- prep_or_measstring (“prep” or “meas”)
Are we testing preparation or measurement fiducials?
- score_funcstr (‘all’ or ‘worst’), optional (default is ‘all’)
Sets the objective function for scoring a fiducial set. If ‘all’, score is (number of fiducials) * sum(1/Eigenvalues of score matrix). If ‘worst’, score is (number of fiducials) * 1/min(Eigenvalues of score matrix). Note: Choosing ‘worst’ corresponds to trying to make the optimizer make the “worst” direction (the one we are least sensitive to in Hilbert-Schmidt space) as minimally bad as possible. Choosing ‘all’ corresponds to trying to make the optimizer make us as sensitive as possible to all directions in Hilbert-Schmidt space. (Also note- because we are using a simple integer program to choose fiducials, it is possible to get stuck in a local minimum, and choosing one or the other objective function can help avoid such minima in different circumstances.)
- return_allbool, optional (default is False)
If true, function returns reciprocals of eigenvalues of fiducial score matrix, and the score of the fiducial set as specified by score_func, in addition to a boolean specifying whether or not the fiducial set is informationally complete
- thresholdfloat, optional (default is 1e6)
Specifies a maximum score for the score matrix, above which the fiducial set is rejected as informationally incomplete.
- l1_penaltyfloat, optional (default is 0.0)
Coefficient of a penalty linear in the number of fiducials that is added to
score.minor.- op_penaltyfloat, optional (default is 0.0)
Coefficient of a penalty linear in the total number of gates in all fiducials that is added to
score.minor.- fid_cachedict, optional (default is None)
A dictionary of either effective state preparations or measurement effects used to accelerate the generation of the matrix used for scoring. It’s assumed that the user will pass in the correct cache based on the type of fiducial set being created (if wrong a fall back will revert to redoing all the matrix multiplication again).
Returns
- testResultbool
Whether or not the specified fiducial list is informationally complete for the provided model, to within the tolerance specified by threshold.
- spectrumarray, optional
The number of fiducials times the reciprocal of the spectrum of the score matrix. Only returned if return_all == True.
- scorefloat, optional
The score for the fiducial set; only returned if return_all == True.
- pygsti.algorithms.fiducialselection.build_bitvec_mx(n, k)
Create an array of all length-n and Hamming weight k binary vectors.
Parameters
- nint
The length of each bit string.
- kint
The hamming weight of each bit string.
Returns
- numpy.ndarray
An array of shape (binom(n,k), n) whose rows are the sought binary vectors.
- pygsti.algorithms.fiducialselection.construct_compact_evd_cache(model, fids_list, prep_or_meas, fid_cache, eigenvalue_tolerance=1e-10)
- pygsti.algorithms.fiducialselection.add_penalties_greedy(unpenalized_score, fid_list, l1_penalty=0, op_penalty=0, gate_penalty=None)
Parameters
- unpenalized_scorefloat
The score function value to add penalty terms to.
- l1_penaltyfloat, optional (default 0.0)
A penalty term associated with the number of fiducials in a candidate list.
- op_penaltyfloat, optional (default 0.0)
A penalty term associated with the total number of gate operations used in aggregate across all of the fiducials in a candidate set.
- gate_penaltydict, optional (default None)
A dictionary with keys given by gate labels and values corresponding to a penalty term for that gate. This penalty is added for each instance of a gate in the dictionary across all fiducials in a candidate list of fiducials.
- pygsti.algorithms.fiducialselection.create_candidate_fiducial_list(target_model, omit_identity=True, ops_to_omit=None, candidate_fid_counts=2, max_fid_length=None, eq_thresh=1e-06, candidate_seed=None)
Generate prep and measurement fiducials for a given target model.
Parameters
- target_modelModel
The model you are aiming to implement.
- omit_identitybool, optional
Whether to remove the identity gate from the set of gates with which fiducials are constructed. Identity gates do nothing to alter fiducials, and so should almost always be left out.
- ops_to_omitlist of string, optional
List of strings identifying gates in the model that should not be used in fiducials. Oftentimes this will include the identity gate, and may also include entangling gates if their fidelity is anticipated to be much worse than that of single-system gates.
- candidate_fid_countsint or dic, optional
A dictionary of fid_length : count key-value pairs, specifying the fiducial “candidate list” - a list of potential fiducials to draw from. count is either an integer specifying the number of random fiducials considered at the given fid_length or the special values “all upto” that considers all of the of all the fiducials of length up to the corresponding fid_length. If the keyword ‘all’ is used for the count value then all circuits at that particular length are added. If and integer, all germs of up to length that length are used, the equivalent of {specified_int: ‘all upto’}.
- max_fid_lengthint, optional (deprecated)
The maximum number of gates to include in a fiducial. The default is not guaranteed to work for arbitrary models (particularly for quantum systems larger than a single qubit). This keyword is now deprecated. The behavior of the keyword is now equivalent to passing in an int for the candidate_fid_counts argument.
Returns
- availableFidListlist of Circuits
A list containing candidate fiducial circuits.