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. 

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 lengthn and Hamming weight k binary vectors. 

Find a locally optimal subset of the fiducials in fid_list. 

Use GRASP to find a highperforming set of fiducials. 
 pygsti.algorithms.fiducialselection.find_fiducials(target_model, omit_identity=True, eq_thresh=1e06, ops_to_omit=None, force_empty=True, max_fid_length=2, algorithm='grasp', algorithm_kwargs=None, verbosity=1)¶
Generate prep and measurement fiducials for a given target model.
 Parameters
target_model (Model) – The model you are aiming to implement.
omit_identity (bool, 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_thresh (float, 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_omit (list 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 singlesystem gates.
force_empty (bool, optional (default is True)) – Whether or not to force all fiducial sets to contain the empty gate string as a fiducial.
max_fid_length (int, optional) – 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).
algorithm ({'slack', 'grasp'}, 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.
algorithm_kwargs (dict) – 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.verbosity (int, optional) – How much detail to send to stdout.
 Returns
prepFidList (list of Circuits) – A list containing the circuits for the prep fiducials.
measFidList (list 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
args (boollikes) – All the boolean (or booleanlike) objects to be checked for xor satisfaction.
 Returns
output (bool) – True if and only if one and only one element of args is True and the rest are False. False otherwise.
 pygsti.algorithms.fiducialselection.create_prep_mxs(model, prep_fid_list)¶
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
model (Model) – The model (associates operation matrices with operation labels).
prep_fid_list (list of Circuits) – List of fiducial circuits for constructing an informationally complete state preparation.
 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)¶
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
model (Model) – The model (associates operation matrices with operation labels).
meas_fid_list (list of Circuits) – List of fiducial circuits for constructing an informationally complete measurement.
 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)¶
Compute a composite score for a fiducial list.
 Parameters
model (Model) – The model (associates operation matrices with operation labels).
fid_list (list of Circuits) – List of fiducial circuits to test.
prep_or_meas (string ("prep" or "meas")) – Are we testing preparation or measurement fiducials?
score_func (str ('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 HilbertSchmidt 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 HilbertSchmidt 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.)
threshold (float, optional (default is 1e6)) – Specifies a maximum score for the score matrix, above which the fiducial set is rejected as informationally incomplete.
return_all (bool, optional (default is False)) – Whether the spectrum should be returned along with the score.
op_penalty (float, optional (defailt is 0.0)) – Coefficient of a penalty linear in the total number of gates in all fiducials that is added to
score.minor
.l1_penalty (float, optional (defailt is 0.0)) – Coefficient of a penalty linear in the number of fiducials that is added to
score.minor
.
 Returns
score (CompositeScore) – The score of the fiducials.
spectrum (numpy.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)¶
Tests a prep or measure fiducial list for informational completeness.
 Parameters
model (Model) – The model (associates operation matrices with operation labels).
fid_list (list of Circuits) – List of fiducial circuits to test.
prep_or_meas (string ("prep" or "meas")) – Are we testing preparation or measurement fiducials?
score_func (str ('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 HilbertSchmidt 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 HilbertSchmidt 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_all (bool, 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
threshold (float, optional (default is 1e6)) – Specifies a maximum score for the score matrix, above which the fiducial set is rejected as informationally incomplete.
l1_penalty (float, optional (defailt is 0.0)) – Coefficient of a penalty linear in the number of fiducials that is added to
score.minor
.op_penalty (float, optional (defailt is 0.0)) – Coefficient of a penalty linear in the total number of gates in all fiducials that is added to
score.minor
.
 Returns
testResult (bool) – Whether or not the specified fiducial list is informationally complete for the provided model, to within the tolerance specified by threshold.
spectrum (array, optional) – The number of fiducials times the reciprocal of the spectrum of the score matrix. Only returned if return_all == True.
score (float, 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 lengthn and Hamming weight k binary vectors.
 Parameters
n (int) – The length of each bit string.
k (int) – 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._find_fiducials_integer_slack(model, fid_list, prep_or_meas=None, initial_weights=None, score_func='all', max_iter=100, fixed_slack=None, slack_frac=None, return_all=False, force_empty=True, force_empty_score=1e+100, fixed_num=None, threshold=1000000.0, verbosity=1)¶
Find a locally optimal subset of the fiducials in fid_list.
Locally optimal here means that no single fiducial can be excluded without increasing the sum of the reciprocals of the singular values of the “score matrix” (the matrix whose columns are the fiducials acting on the preparation, or the transpose of the measurement acting on the fiducials), by more than a fixed or variable amount of “slack”, as specified by fixed_slack or slack_frac.
 Parameters
model (Model) – The model (associates operation matrices with operation labels).
fid_list (list of Circuits) – List of all fiducials circuits to consider.
prep_or_meas ({'prep', 'meas'}) – Whether preparation or measturement fiducials are being selected.
initial_weights (listlike) – List or array of either booleans or (0 or 1) integers specifying which fiducials in fid_list comprise the initial fiduial set. If None, then starting point includes all fiducials.
score_func (str ('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 HilbertSchmidt 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 HilbertSchmidt 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.)
max_iter (int, optional) – The maximum number of iterations before stopping.
fixed_slack (float, optional) – If not None, a floating point number which specifies that excluding a fiducial is allowed to increase the fiducial set score additively by fixed_slack. You must specify either fixed_slack or slack_frac.
slack_frac (float, optional) – If not None, a floating point number which specifies that excluding a fiducial is allowed to increase the fiducial set score multiplicatively by (1+slack_frac). You must specify either fixed_slack or slack_frac.
return_all (bool, optional) – If True, return the final “weights” vector and score dictionary in addition to the optimal fiducial list (see below).
force_empty (bool, optional (default is True)) –
Whether or not to force all fiducial sets to contain the empty gate string as a fiducial.
IMPORTANT: This only works if the first element of fid_list is the empty circuit.
force_empty_score (float, optional (default is 1e100)) – When force_empty is True, what score to assign any fiducial set that does not contain the empty circuit as a fiducial.
fixed_num (int, optional) – Require the output list of fiducials to contain exactly fixed_num elements.
threshold (float, optional (default is 1e6)) – Entire fiducial list is first scored before attempting to select fiducials; if score is above threshold, then fiducial selection will autofail. If final fiducial set selected is above threshold, then fiducial selection will print a warning, but return selected set.
verbosity (int, optional) – Integer >= 0 indicating the amount of detail to print.
 Returns
fiducial_list (list) – A list of the selected (optimized) fiducial circuits.
weights (list) – Only returned if return_all=True. The internal weights for each candidate germ.
score (dict) – Only returned if return_all=True. The internal dictionary mapping weights (as a tuple) to scores.
 pygsti.algorithms.fiducialselection._find_fiducials_grasp(model, fids_list, prep_or_meas, alpha, iterations=5, score_func='all', op_penalty=0.0, l1_penalty=0.0, return_all=False, force_empty=True, threshold=1000000.0, seed=None, verbosity=0)¶
Use GRASP to find a highperforming set of fiducials.
 Parameters
model (Model) – The model (associates operation matrices with operation labels).
fids_list (list of Circuits) – List of fiducial circuits to test.
prep_or_meas (string ("prep" or "meas")) – Are we testing preparation or measurement fiducials?
alpha (float) – A number between 0 and 1 that roughly specifies a score threshold relative to the spread of scores that a germ must score better than in order to be included in the RCL. A value of 0 for alpha corresponds to a purely greedy algorithm (only the bestscoring element is included in the RCL), while a value of 1 for alpha will include all elements in the RCL.
iterations (int, optional) – Number of GRASP iterations.
score_func (str ('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 HilbertSchmidt 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 HilbertSchmidt 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.)
op_penalty (float, optional (defailt is 0.0)) – Coefficient of a penalty linear in the total number of gates in all fiducials that is added to
score.minor
.l1_penalty (float, optional (defailt is 0.0)) – Coefficient of a penalty linear in the number of fiducials that is added to
score.minor
.return_all (bool, 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
force_empty (bool, optional) – When True, the empty circuit must be a member of the chosen set.
threshold (float, optional (default is 1e6)) – Specifies a maximum score for the score matrix, above which the fiducial set is rejected as informationally incomplete.
seed (int, optional) – The seed value used for each individual iteration.
verbosity (int, optional) – How much detail to send to stdout.
 Returns
best_fiducials (list) – The bestscoring list of fiducial circuits.
initial_fiducials (list of lists) – Only returned if return_all=True. A list of the initial solution (a solution is a list of fiducial circuits) for each grasp iteration.
local_solutions (list of lists) – Only returned if return_all=True. A list of the best solution (a solution is a list of fiducial circuits) for each grasp iteration.