pygsti.algorithms.germselection
Functions for selecting a complete set of germs for a GST analysis.
Module Contents
Functions

Generate a germ set for doing GST with a given target model. 

Calculate the score of a germ set with respect to a model. 

Compute the score for a germ set when it is not AC against a model. 

Applies random unitary perturbations to a model or list of models. 

Check to see if the germs_list is amplificationally complete (AC). 

Test whether a set of germs is able to amplify all nongauge parameters. 

Test whether a set of germs is able to amplify all nongauge parameters. 

Greedy germ selection algorithm starting with 0 germs. 

Greedy algorithm starting with 0 germs. 

Find a locally optimal subset of the germs in germs_list. 

Use GRASP to find a highperforming germ set. 



Function for generating a cache of PTMs for the available fiducials. 

Function for dropping a random fraction of the candidate germ list. 

Generate the compact eigenvalue decomposition of the input matrix. 

Generate the compact eigenvalue decomposition of the input matrix. 

Calculates the parts of the eigenvalue update loop algorithm that we can 

This function performs a lowrank update to the spectrum of 

This function performs a lowrank update to the components of 

Greedy algorithm starting with 0 germs. 

Compute the score for a germ set when it is not AC against a model. 

Compute the score for a germ set when it is not AC against a model. 





Parameters 

Compute the score for a germ set when it is not AC against a model. 

Calculates the parts of the psuedoinverse update loop algorithm that we can 

Helper function for calculating rankone updates to the trace of the psuedoinverse. 

Helper function for calculating rankone psuedoinverse updates. 
Attributes
 pygsti.algorithms.germselection.FLOATSIZE = '8'
 pygsti.algorithms.germselection.find_germs(target_model, randomize=True, randomization_strength=0.01, num_gs_copies=5, seed=None, candidate_germ_counts=None, candidate_seed=None, force='singletons', algorithm='greedy', algorithm_kwargs=None, mem_limit=None, comm=None, profiler=None, verbosity=1, num_nongauge_params=None, assume_real=False, float_type=_np.cdouble, mode='allJac', toss_random_frac=None, force_rank_increase=False, save_cevd_cache_filename=None, load_cevd_cache_filename=None, file_compression=False)
Generate a germ set for doing GST with a given target model.
This function provides a streamlined interface to a variety of germ selection algorithms. It’s goal is to provide a method that typical users can run by simply providing a target model and leaving all other settings at their default values, while providing flexibility for users desiring more control to fine tune some of the general and algorithmspecific details.
Currently, to break troublesome degeneracies and provide some confidence that the chosen germ set is amplificationally complete (AC) for all models in a neighborhood of the target model (rather than only the target model), an ensemble of models with random unitary perturbations to their gates must be provided or generated.
Parameters
 target_modelModel or list of Model
The model you are aiming to implement, or a list of models that are copies of the model you are trying to implement (either with or without random unitary perturbations applied to the models).
 randomizebool, optional
Whether or not to add random unitary perturbations to the model(s) provided.
 randomization_strengthfloat, optional
The size of the random unitary perturbations applied to gates in the model. See
randomize_with_unitary()
for more details. num_gs_copiesint, optional
The number of copies of the original model that should be used.
 seedint, optional
Seed for generating random unitary perturbations to models. Also passed along to stochastic germselection algorithms and to the rng for dropping random fraction of germs.
 candidate_germ_countsdict, optional
A dictionary of germ_length : count keyvalue pairs, specifying the germ “candidate list”  a list of potential germs to draw from. count is either an integer specifying the number of random germs considered at the given germ_length or the special values “all upto” that considers all of the of all nonequivalent germs of length up to the corresponding germ_length. If None, all germs of up to length 6 are used, the equivalent of {6: ‘all upto’}.
 candidate_seedint, optional
A seed value used when randomly selecting candidate germs. For each germ length being randomly selected, the germ length is added to the value of candidate_seed to get the actual seed used.
 forcestr or list, optional
A list of Circuits which must be included in the final germ set. If set to the special string “singletons” then all length1 strings will be included. Seting to None is the same as an empty list.
 algorithm{‘greedy’, ‘grasp’, ‘slack’}, optional
Specifies the algorithm to use to generate the germ set. Current options are: ‘greedy’ : Add germs oneatatime until the set is AC, picking the germ that improves the germset score by the largest amount at each step. See
find_germs_breadthfirst()
for more details.‘grasp’: Use GRASP to generate random greedy germ sets and then locally optimize them. See
find_germs_grasp()
for more details.‘slack’: From a initial set of germs, add or remove a germ at each step in an attempt to improve the germset score. Will allow moves that degrade the score in an attempt to escape local optima as long as the degredation is within some specified amount of “slack”. See
find_germs_integer_slack()
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. mem_limitint, optional
A rough memory limit in bytes which restricts the amount of intermediate values that are computed and stored.
 commmpi4py.MPI.Comm, optional
When not None, an MPI communicator for distributing the computation across multiple processors.
 profilerProfiler, optional
A profiler object used for to track timing and memory usage.
 verbosityint, optional
The verbosity level of the
VerbosityPrinter
used to print log messages. num_nongauge_paramsint, optional
Force the number of nongauge parameters rather than rely on automated gauge optimization.
 float_typenumpy dtype object, optional
Numpy data type to use for floating point arrays.
 toss_random_fracfloat, optional
If specified this is a number between 0 and 1 that indicates the random fraction of candidate germs to drop randomly following the deduping procedure.
 mode{‘allJac’, ‘singleJac’, ‘compactEVD’}, optional (default ‘allJac’)
A flag to indicate the caching scheme used for storing the Jacobians for the candidate germs. Default value of ‘allJac’ caches all of the Jacobians and requires the most memory. ‘singleJac’ doesn’t cache anything and instead generates these Jacobians on the fly. The final option, ‘compactEVD’, is currently only configured to work with the greedy search algorithm. When selected the compact eigenvalue decomposition/compact SVD of each of the Jacobians is constructed and is cached. This uses an intermediate amount of memory between singleJac and allJac. When compactEVD mode is selected perform the greedy search iterations using an alternative method based on lowrank updates to the psuedoinverse. This alternative approach means that this mode also only works with the score function option set to ‘all’.
 force_rank_increasebool, optional (default False)
Optional flag that can be used in conjunction with the greedy search algorithm in compactEVD mode. When set we require that each subsequant addition to the germ set must increase the rank of the experiment design’s composite Jacobian. Can potentially speed up the search when set to True.
 save_cevd_cache_filenamestr, optional (default None)
When set and using the greedy search algorithm in ‘compactEVD’ mode this writes the compact EVD cache to disk using the specified filename.
 load_cevd_cache_filenamestr, optional (default None)
A filename/path to load an existing compact EVD cache from. Useful for warmstarting a germ set search with various cost function parameters, or for restarting a search that failed/crashed/ran out of memory. Note that there are no safety checks to confirm that the compact EVD cache indeed corresponds to that for of currently specified candidate circuit list, so care must be take to confirm that the candidate germ lists are consistent across runs.
 file_compressionbool, optional (default False)
When True and a filename is given for the save_cevd_cache_filename the corresponding numpy arrays are stored in a compressed format using numpy’s savez_compressed. Can significantly decrease the storage requirements on disk at the expense of some additional computational cost writing and loading the files.
Returns
 list of Circuit
A list containing the germs making up the germ set.
 pygsti.algorithms.germselection.compute_germ_set_score(germs, target_model=None, neighborhood=None, neighborhood_size=5, randomization_strength=0.01, score_func='all', op_penalty=0.0, l1_penalty=0.0, num_nongauge_params=None, float_type=_np.cdouble)
Calculate the score of a germ set with respect to a model.
More precisely, this function computes the maximum score (roughly equal to the number of amplified parameters) for a cloud of models. If target_model is given, it serves as the center of the cloud, otherwise the cloud must be supplied directly via neighborhood.
Parameters
 germslist
The germ set
 target_modelModel, optional
The target model, used to generate a neighborhood of randomized models.
 neighborhoodlist of Models, optional
The “cloud” of models for which scores are computed. If not None, this overrides target_model, neighborhood_size, and randomization_strength.
 neighborhood_sizeint, optional
Number of randomized models to construct around target_model.
 randomization_strengthfloat, optional
Strength of unitary randomizations, as passed to
target_model.randomize_with_unitary()
. score_func{‘all’, ‘worst’}
Sets the objective function for scoring the eigenvalues. If ‘all’, score is
sum(1/input_array)
. If ‘worst’, score is1/min(input_array)
. op_penaltyfloat, optional
Coefficient for a penalty linear in the sum of the germ lengths.
 l1_penaltyfloat, optional
Coefficient for a penalty linear in the number of germs.
 num_nongauge_paramsint, optional
Force the number of nongauge parameters rather than rely on automated gauge optimization.
 float_typenumpy dtype object, optional
Numpy data type to use for floating point arrays.
Returns
 CompositeScore
The maximum score for germs, indicating how many parameters it amplifies.
 pygsti.algorithms.germselection.compute_composite_germ_set_score(score_fn, threshold_ac=1000000.0, init_n=1, partial_deriv_dagger_deriv=None, model=None, partial_germs_list=None, eps=None, germ_lengths=None, op_penalty=0.0, l1_penalty=0.0, num_nongauge_params=None, float_type=_np.cdouble)
Compute the score for a germ set when it is not AC against a model.
Normally scores computed for germ sets against models for which they are not AC will simply be astronomically large. This is fine if AC is all you care about, but not so useful if you want to compare partial germ sets against one another to see which is closer to being AC. This function will see if the germ set is AC for the parameters corresponding to the largest N eigenvalues for increasing N until it finds a value of N for which the germ set is not AC or all the non gauge parameters are accounted for and report the value of N as well as the score. This allows partial germ set scores to be compared against oneanother sensibly, where a larger value of N always beats a smaller value of N, and ties in the value of N are broken by the score for that value of N.
Parameters
 score_fncallable
A function that takes as input a list of sorted eigenvalues and returns a score for the partial germ set based on those eigenvalues, with lower scores indicating better germ sets. Usually some flavor of
list_score()
. threshold_acfloat, optional
Value which the score (before penalties are applied) must be lower than for the germ set to be considered AC.
 init_nint
The number of largest eigenvalues to begin with checking.
 partial_deriv_dagger_derivnumpy.array, optional
Array with three axes, where the first axis indexes individual germs within the partial germ set and the remaining axes index entries in the positive square of the Jacobian of each individual germ’s parameters with respect to the model parameters. If this array is not supplied it will need to be computed from germs_list and model, which will take longer, so it is recommended to precompute this array if this routine will be called multiple times.
 modelModel, optional
The model against which the germ set is to be scored. Not needed if partial_deriv_dagger_deriv is provided.
 partial_germs_listlist of Circuit, optional
The list of germs in the partial germ set to be evaluated. Not needed if partial_deriv_dagger_deriv (and germ_lengths when
op_penalty > 0
) are provided. epsfloat, optional
Used when calculating partial_deriv_dagger_deriv to determine if two eigenvalues are equal (see
_bulk_twirled_deriv()
for details). Not used if partial_deriv_dagger_deriv is provided. op_penaltyfloat, optional
Coefficient for a penalty linear in the sum of the germ lengths.
 germ_lengthsnumpy.array, optional
The length of each germ. Not needed if op_penalty is
0.0
or partial_germs_list is provided. l1_penaltyfloat, optional
Coefficient for a penalty linear in the number of germs.
 num_nongauge_paramsint, optional
Force the number of nongauge parameters rather than rely on automated gauge optimization.
Returns
 CompositeScore
The score for the germ set indicating how many parameters it amplifies and its numerical score restricted to those parameters.
 pygsti.algorithms.germselection.randomize_model_list(model_list, randomization_strength, num_copies, seed=None)
Applies random unitary perturbations to a model or list of models.
If model_list is a length1 list, then num_copies determines how many randomizations to create. If model_list containes multiple models, then num_copies must be None and each model is randomized once to create the corresponding returned model.
Parameters
 model_listModel or list
A list of Model objects.
 randomization_strengthfloat, optional
Strength of unitary randomizations, as passed to
Model.randomize_with_unitary()
. num_copiesint
The number of random perturbations of model_list[0] to generate when len(model_list) == 1. A value of None will result in 1 copy. If len(model_list) > 1 then num_copies must be set to None.
 seedint, optional
Starting seed for randomization. Successive randomizations receive successive seeds. None results in random seeds.
Returns
 list
A list of the randomized Models.
 pygsti.algorithms.germselection.test_germs_list_completeness(model_list, germs_list, score_func, threshold, float_type=_np.cdouble, comm=None, num_gauge_params=None)
Check to see if the germs_list is amplificationally complete (AC).
Checks for AC with respect to all the Models in model_list, returning the index of the first Model for which it is not AC or 1 if it is AC for all Models.
Parameters
 model_listlist
A list of models to test. Often this list is a neighborhood (“cloud”) of models around a model of interest.
 germs_listlist
A list of the germ
Circuit
objects (the “germ set”) to test for completeness. score_func{‘all’, ‘worst’}
Sets the objective function for scoring the eigenvalues. If ‘all’, score is
sum(1/eigval_array)
. If ‘worst’, score is1/min(eigval_array)
. thresholdfloat, optional
An eigenvalue of jacobian^T*jacobian is considered zero and thus a parameter unamplified when its reciprocal is greater than threshold. Also used for eigenvector degeneracy testing in twirling operation.
 float_typenumpy dtype object, optional
Numpy data type to use for floating point arrays.
 commmpi4py.MPI.Comm, optional
When not None, an MPI communicator for distributing the computation across multiple processors.
 num_gauge_paramsint, optional (default None)
A optional kwarg for specifying the number of gauge parameters. Specifying this if already precomputed can save on computation.
Returns
 int
The index of the first model in model_list to fail the amplficational completeness test. Returns 1 if germ set is AC for all tested models.
 pygsti.algorithms.germselection.test_germ_set_finitel(model, germs_to_test, length, weights=None, return_spectrum=False, tol=1e06)
Test whether a set of germs is able to amplify all nongauge parameters.
Parameters
 modelModel
The Model (associates operation matrices with operation labels).
 germs_to_testlist of Circuits
List of germ circuits to test for completeness.
 lengthint
The finite length to use in amplification testing. Larger values take longer to compute but give more robust results.
 weightsnumpy array, optional
A 1D array of weights with length equal len(germs_to_test), which multiply the contribution of each germ to the total jacobian matrix determining parameter amplification. If None, a uniform weighting of 1.0/len(germs_to_test) is applied.
 return_spectrumbool, optional
If True, return the jacobian^T*jacobian spectrum in addition to the success flag.
 tolfloat, optional
Tolerance: an eigenvalue of jacobian^T*jacobian is considered zero and thus a parameter unamplified when it is less than tol.
Returns
 successbool
Whether all nongauge parameters were amplified.
 spectrumnumpy array
Only returned when return_spectrum is
True
. Sorted array of eigenvalues (from small to large) of the jacobian^T * jacobian matrix used to determine parameter amplification.
 pygsti.algorithms.germselection.test_germ_set_infl(model, germs_to_test, score_func='all', weights=None, return_spectrum=False, threshold=1000000.0, check=False, float_type=_np.cdouble, comm=None, nGaugeParams=None)
Test whether a set of germs is able to amplify all nongauge parameters.
Parameters
 modelModel
The Model (associates operation matrices with operation labels).
 germs_to_testlist of Circuit
List of germ circuits to test for completeness.
 score_funcstring
Label to indicate how a germ set is scored. See
list_score()
for details. weightsnumpy array, optional
A 1D array of weights with length equal len(germs_to_test), which multiply the contribution of each germ to the total jacobian matrix determining parameter amplification. If None, a uniform weighting of 1.0/len(germs_to_test) is applied.
 return_spectrumbool, optional
If
True
, return the jacobian^T*jacobian spectrum in addition to the success flag. thresholdfloat, optional
An eigenvalue of jacobian^T*jacobian is considered zero and thus a parameter unamplified when its reciprocal is greater than threshold. Also used for eigenvector degeneracy testing in twirling operation.
 checkbool, optional
Whether to perform internal consistency checks, at the expense of making the function slower.
 float_type: numpy dtype object, optional
Optional numpy data type to use for internal numpy array calculations.
 commmpi4py.MPI.Comm, optional
When not None, an MPI communicator for distributing the computation across multiple processors.
 nGaugeParamsint, optional (default None)
A optional kwarg for specifying the number of gauge parameters. Specifying this if already precomputed can save on computation.
Returns
 successbool
Whether all nongauge parameters were amplified.
 spectrumnumpy array
Only returned when return_spectrum is
True
. Sorted array of eigenvalues (from small to large) of the jacobian^T * jacobian matrix used to determine parameter amplification.
 pygsti.algorithms.germselection.find_germs_depthfirst(model_list, germs_list, randomize=True, randomization_strength=0.001, num_copies=None, seed=0, op_penalty=0, score_func='all', tol=1e06, threshold=1000000.0, check=False, force='singletons', verbosity=0, float_type=_np.cdouble)
Greedy germ selection algorithm starting with 0 germs.
Tries to minimize the number of germs needed to achieve amplificational completeness (AC). Begins with 0 germs and adds the germ that increases the score used to check for AC by the largest amount at each step, stopping when the threshold for AC is achieved.
Parameters
 model_listModel or list
The model or list of Models to select germs for.
 germs_listlist of Circuit
The list of germs to contruct a germ set from.
 randomizebool, optional
Whether or not to randomize model_list (usually just a single Model) with small (see randomizationStrengh) unitary maps in order to avoid “accidental” symmetries which could allow for fewer germs but only for that particular model. Setting this to True will increase the run time by a factor equal to the numer of randomized copies (num_copies).
 randomization_strengthfloat, optional
The strength of the unitary noise used to randomize input Model(s); is passed to
randomize_with_unitary()
. num_copiesint, optional
The number of randomized models to create when only a single gate set is passed via model_list. Otherwise, num_copies must be set to None.
 seedint, optional
Seed for generating random unitary perturbations to models.
 op_penaltyfloat, optional
Coefficient for a penalty linear in the sum of the germ lengths.
 score_func{‘all’, ‘worst’}, optional
Sets the objective function for scoring the eigenvalues. If ‘all’, score is
sum(1/eigenvalues)
. If ‘worst’, score is1/min(eiganvalues)
. tolfloat, optional
Tolerance (eps arg) for
_compute_bulk_twirled_ddd()
, which sets the differece between eigenvalues below which they’re treated as degenerate. thresholdfloat, optional
Value which the score (before penalties are applied) must be lower than for a germ set to be considered AC.
 checkbool, optional
Whether to perform internal checks (will slow down run time substantially).
 forcelist of Circuits
A list of Circuit objects which must be included in the final germ set. If the special string “singletons” is given, then all of the single gates (length1 sequences) must be included.
 verbosityint, optional
Level of detail printed to stdout.
Returns
 list
A list of the builtup germ set (a list of
Circuit
objects).
 pygsti.algorithms.germselection.find_germs_breadthfirst(model_list, germs_list, randomize=True, randomization_strength=0.001, num_copies=None, seed=0, op_penalty=0, score_func='all', tol=1e06, threshold=1000000.0, check=False, force='singletons', pretest=True, mem_limit=None, comm=None, profiler=None, verbosity=0, num_nongauge_params=None, float_type=_np.cdouble, mode='allJac')
Greedy algorithm starting with 0 germs.
Tries to minimize the number of germs needed to achieve amplificational completeness (AC). Begins with 0 germs and adds the germ that increases the score used to check for AC by the largest amount (for the model that currently has the lowest score) at each step, stopping when the threshold for AC is achieved. This strategy is something of a “breadthfirst” approach, in contrast to
find_germs_depthfirst()
, which only looks at the scores for one model at a time until that model achieves AC, then turning it’s attention to the remaining models.Parameters
 model_listModel or list
The model or list of Model objects to select germs for.
 germs_listlist of Circuit
The list of germs to contruct a germ set from.
 randomizebool, optional
Whether or not to randomize model_list (usually just a single Model) with small (see randomizationStrengh) unitary maps in order to avoid “accidental” symmetries which could allow for fewer germs but only for that particular model. Setting this to True will increase the run time by a factor equal to the numer of randomized copies (num_copies).
 randomization_strengthfloat, optional
The strength of the unitary noise used to randomize input Model(s); is passed to
randomize_with_unitary()
. num_copiesint, optional
The number of randomized models to create when only a single gate set is passed via model_list. Otherwise, num_copies must be set to None.
 seedint, optional
Seed for generating random unitary perturbations to models.
 op_penaltyfloat, optional
Coefficient for a penalty linear in the sum of the germ lengths.
 score_func{‘all’, ‘worst’}, optional
Sets the objective function for scoring the eigenvalues. If ‘all’, score is
sum(1/eigenvalues)
. If ‘worst’, score is1/min(eiganvalues)
. tolfloat, optional
Tolerance (eps arg) for
_compute_bulk_twirled_ddd()
, which sets the differece between eigenvalues below which they’re treated as degenerate. thresholdfloat, optional
Value which the score (before penalties are applied) must be lower than for a germ set to be considered AC.
 checkbool, optional
Whether to perform internal checks (will slow down run time substantially).
 forcelist of Circuits
A list of Circuit objects which must be included in the final germ set. If the special string “singletons” is given, then all of the single gates (length1 sequences) must be included.
 pretestboolean, optional
Whether germ list should be initially checked for completeness.
 mem_limitint, optional
A rough memory limit in bytes which restricts the amount of intermediate values that are computed and stored.
 commmpi4py.MPI.Comm, optional
When not None, an MPI communicator for distributing the computation across multiple processors.
 profilerProfiler, optional
A profiler object used for to track timing and memory usage.
 verbosityint, optional
Level of detail printed to stdout.
 num_nongauge_paramsint, optional
Force the number of nongauge parameters rather than rely on automated gauge optimization.
 float_typenumpy dtype object, optional
Use an alternative data type for the values of the numpy arrays generated.
Returns
 list
A list of the builtup germ set (a list of
Circuit
objects).
 pygsti.algorithms.germselection.find_germs_integer_slack(model_list, germs_list, randomize=True, randomization_strength=0.001, num_copies=None, seed=0, l1_penalty=0.01, op_penalty=0, initial_weights=None, score_func='all', max_iter=100, fixed_slack=False, slack_frac=False, return_all=False, tol=1e06, check=False, force='singletons', force_score=1e+100, threshold=1000000.0, verbosity=1, float_type=_np.cdouble)
Find a locally optimal subset of the germs in germs_list.
Locally optimal here means that no single germ can be excluded without making the smallest nongauge eigenvalue of the Jacobian.H*Jacobian matrix smaller, i.e. less amplified, by more than a fixed or variable amount of “slack”, as specified by fixed_slack or slack_frac.
Parameters
 model_listModel or list of Model
The list of Models to be tested. To ensure that the returned germ set is amplficationally complete, it is a good idea to score potential germ sets against a collection (~510) of similar models. The user may specify a single Model and a number of unitarily close copies to be made (set by the kwarg num_copies), or the user may specify their own list of Models, each of which in turn may or may not be randomized (set by the kwarg randomize).
 germs_listlist of Circuit
List of all germ circuits to consider.
 randomizeBool, optional
Whether or not the input Model(s) are first subject to unitary randomization. If
False
, the user should perform the unitary randomization themselves. Note: If the Model(s) are perfect (e.g.std1Q_XYI.target_model()
), then the germ selection output should not be trusted, due to accidental degeneracies in the Model. If the Model(s) include stochastic (nonunitary) error, then germ selection will fail, as we score amplificational completeness in the limit of infinite sequence length (so any stochastic noise will completely depolarize any sequence in that limit). Default isTrue
. randomization_strengthfloat, optional
The strength of the unitary noise used to randomize input Model(s); is passed to
randomize_with_unitary()
. Default is1e3
. num_copiesint, optional
The number of Model copies to be made of the input Model (prior to unitary randomization). If more than one Model is passed in, num_copies should be
None
. If only one Model is passed in and num_copies isNone
, no extra copies are made. seedfloat, optional
The starting seed used for unitary randomization. If multiple Models are to be randomized,
model_list[i]
is randomized withseed + i
. Default is 0. l1_penaltyfloat, optional
How strong the penalty should be for increasing the germ set list by a single germ. Default is 1e2.
 op_penaltyfloat, optional
How strong the penalty should be for increasing a germ in the germ set list by a single gate. Default is 0.
 initial_weightslistlike
List or array of either booleans or (0 or 1) integers specifying which germs in germ_list comprise the initial germ set. If
None
, then starting point includes all germs. score_funcstring
Label to indicate how a germ set is scored. See
list_score()
for details. max_iterint, optional
The maximum number of iterations before giving up.
 fixed_slackfloat, optional
If not
None
, a floating point number which specifies that excluding a germ is allowed to increase 1.0/smallestnongaugeeigenvalue by fixed_slack. You must specify either fixed_slack or slack_frac. slack_fracfloat, optional
If not
None
, a floating point number which specifies that excluding a germ is allowed to increase 1.0/smallestnongaugeeigenvalue by fixedFrac`*100 percent. You must specify *either* `fixed_slack or slack_frac. return_allbool, optional
If
True
, return the finalweights
vector and score dictionary in addition to the optimal germ list (see below). tolfloat, optional
Tolerance used for eigenvector degeneracy testing in twirling operation.
 checkbool, optional
Whether to perform internal consistency checks, at the expense of making the function slower.
 forcestr or list, optional
A list of Circuits which must be included in the final germ set. If set to the special string “singletons” then all length1 strings will be included. Seting to None is the same as an empty list.
 force_scorefloat, optional (default is 1e100)
When force designates a nonempty set of circuits, the score to assign any germ set that does not contain each and every required germ.
 thresholdfloat, optional (default is 1e6)
Specifies a maximum score for the score matrix, above which the germ set is rejected as amplificationally incomplete.
 verbosityint, optional
Integer >= 0 indicating the amount of detail to print.
See Also
Model
Circuit
 pygsti.algorithms.germselection.find_germs_grasp(model_list, germs_list, alpha, randomize=True, randomization_strength=0.001, num_copies=None, seed=None, l1_penalty=0.01, op_penalty=0.0, score_func='all', tol=1e06, threshold=1000000.0, check=False, force='singletons', iterations=5, return_all=False, shuffle=False, verbosity=0, num_nongauge_params=None, float_type=_np.cdouble)
Use GRASP to find a highperforming germ set.
Parameters
 model_listModel or list of Model
The list of Models to be tested. To ensure that the returned germ set is amplficationally complete, it is a good idea to score potential germ sets against a collection (~510) of similar models. The user may specify a single Model and a number of unitarily close copies to be made (set by the kwarg num_copies, or the user may specify their own list of Models, each of which in turn may or may not be randomized (set by the kwarg randomize).
 germs_listlist of Circuit
List of all germ circuits to consider.
 alphafloat
A number between 0 and 1 that roughly specifies a score theshold 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 germ set is included in the RCL), while a value of 1 for alpha will include all germs in the RCL. See
pygsti.algorithms.scoring.filter_composite_rcl()
for more details. randomizeBool, optional
Whether or not the input Model(s) are first subject to unitary randomization. If
False
, the user should perform the unitary randomization themselves. Note: If the Model(s) are perfect (e.g.std1Q_XYI.target_model()
), then the germ selection output should not be trusted, due to accidental degeneracies in the Model. If the Model(s) include stochastic (nonunitary) error, then germ selection will fail, as we score amplificational completeness in the limit of infinite sequence length (so any stochastic noise will completely depolarize any sequence in that limit). randomization_strengthfloat, optional
The strength of the unitary noise used to randomize input Model(s); is passed to
randomize_with_unitary()
. Default is1e3
. num_copiesint, optional
The number of Model copies to be made of the input Model (prior to unitary randomization). If more than one Model is passed in, num_copies should be
None
. If only one Model is passed in and num_copies isNone
, no extra copies are made. seedfloat, optional
The starting seed used for unitary randomization. If multiple Models are to be randomized,
model_list[i]
is randomized withseed + i
. l1_penaltyfloat, optional
How strong the penalty should be for increasing the germ set list by a single germ. Used for choosing between outputs of various GRASP iterations.
 op_penaltyfloat, optional
How strong the penalty should be for increasing a germ in the germ set list by a single gate.
 score_funcstring
Label to indicate how a germ set is scored. See
list_score()
for details. tolfloat, optional
Tolerance used for eigenvector degeneracy testing in twirling operation.
 thresholdfloat, optional (default is 1e6)
Specifies a maximum score for the score matrix, above which the germ set is rejected as amplificationally incomplete.
 checkbool, optional
Whether to perform internal consistency checks, at the expense of making the function slower.
 forcestr or list, optional
A list of Circuits which must be included in the final germ set. If set to the special string “singletons” then all length1 strings will be included. Seting to None is the same as an empty list.
 iterationsint, optional
The number of GRASP iterations to perform.
 return_allbool, optional
Flag set to tell the routine if it should return lists of all initial constructions and local optimizations in addition to the optimal solution (useful for diagnostic purposes or if you’re not sure what your finalScoreFn should really be).
 shufflebool, optional
Whether the neighborhood should be presented to the optimizer in a random order (important since currently the local optimizer updates the solution to the first better solution it finds in the neighborhood).
 verbosityint, optional
Integer >= 0 indicating the amount of detail to print.
 num_nongauge_paramsint, optional
Force the number of nongauge parameters rather than rely on automated gauge optimization.
 float_typeNumpy dtype object, optional
Numpy data type to use for floating point arrays
Returns
 finalGermListlist of Circuit
Sublist of germs_list specifying the final, optimal set of germs.
 pygsti.algorithms.germselection.clean_germ_list(model, circuit_cache, eq_thresh=1e06)
 pygsti.algorithms.germselection.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.germselection.drop_random_germs(candidate_list, rand_frac, target_model, keep_bare=True, seed=None)
Function for dropping a random fraction of the candidate germ list.
Parameters
 candidate_listlist of Circuits
List of candidate germs
 target_modelModel
The model (associates operation matrices with operation labels)
 rand_fracfloat between 0 and 1
random fraction of candidate germs to drop
 keep_barebool
Whether to always include the bare germs in the returned set.
Returns
 availableGermsListList
list of candidate germs with random fraction dropped.
 pygsti.algorithms.germselection.compact_EVD(mat, threshold=1e10)
Generate the compact eigenvalue decomposition of the input matrix. Assumes of course that the user has specified a diagonalizable matrix, there are no safety checks for that made a priori.
input:
 matndarray
input matrix we want the compact EVD for. Assumed to be diagonalizable.
 thresholdfloat, optional
threshold value for deciding if an eigenvalue is zero.
output:
 endarray
1D numpy array of the nonzero eigenvalues of mat.
 Undarray
Matrix such that U@diag(s)@U.conj().T=mat.
 pygsti.algorithms.germselection.compact_EVD_via_SVD(mat, threshold=1e10)
Generate the compact eigenvalue decomposition of the input matrix. Assumes of course that the user has specified a diagonalizable matrix, there are no safety checks for that made a priori.
input:
 matndarray
input matrix we want the compact EVD for. Assumed to be diagonalizable.
 thresholdfloat, optional
threshold value for deciding if an eigenvalue is zero.
output:
 endarray
1D numpy array of the nonzero eigenvalues of mat.
 Undarray
Matrix such that U@diag(s)@U.conj().T=mat.
 pygsti.algorithms.germselection.construct_update_cache(mat, evd_tol=1e10)
Calculates the parts of the eigenvalue update loop algorithm that we can precompute and reuse throughout all of the potential updates.
Input:
 matndarray
The matrix to construct a set of reusable objects for performing the updates. mat is assumed to be a symmetric square matrix.
 evd_tolfloat (optional)
A threshold value for setting eigenvalues to zero.
Output:
 U, endarrays
The components of the compact eigenvalue decomposition of mat such that U@diag(s)@U.conj().T= mat e in this case is a 1D array of the nonzero eigenvalues.
 projUndarray
A projector onto the complement of the column space of U Corresponds to (IU@U.T)
 pygsti.algorithms.germselection.symmetric_low_rank_spectrum_update(update, orig_e, U, proj_U, force_rank_increase=False)
This function performs a lowrank update to the spectrum of a matrix. It takes as input a symmetric update of the form: A@A.T, in other words a symmetric rankdecomposition of the update matrix. Since the update is symmetric we only pass as input one half (i.e. we only need A, since A.T in numpy is treated simply as a different view of A). We also pass in the original spectrum as well as a projector onto the complement of the column space of the original matrix’s eigenvector matrix.
input:
 updatendarray
symmetric lowrank update to perform. This is the first half the symmetric rank decomposition s.t. update@update.T= the full update matrix.
 orig_endarray
Spectrum of the original matrix. This is a 1D array.
 proj_Undarray
Projector onto the complement of the column space of the original matrix’s eigenvectors.
 force_rank_increasebool
A flag to indicate whether we are looking to force a rank increase. If so, then after the rrqr calculation we can check the rank of the projection of the update onto the complement of the column space of the base matrix and abort early if that is zero.
 pygsti.algorithms.germselection.minamide_style_inverse_trace(update, orig_e, U, proj_U, force_rank_increase=False)
This function performs a lowrank update to the components of the psuedo inverse of a matrix relevant to the calculation of that matrix’s updated trace. It takes as input a symmetric update of the form: A@A.T, in other words a symmetric rankdecomposition of the update matrix. Since the update is symmetric we only pass as input one half (i.e. we only need A, since A.T in numpy is treated simply as a different view of A). We also pass in the original spectrum as well as a projector onto the complement of the column space of the original matrix’s eigenvector matrix.
Based on an update formula for psuedoinverses by minamide combined with a result on updating compact SVDs by M. Brand.
input:
 updatendarray
symmetric lowrank update to perform. This is the first half the symmetric rank decomposition s.t. update@update.T= the full update matrix.
 orig_endarray
Spectrum of the original matrix. This is a 1D array.
 proj_Undarray
Projector onto the complement of the column space of the original matrix’s eigenvectors.
 updated_tracefloat
Value of the trace of the updated psuedoinverse matrix.
 updated_rankint
total rank of the updated matrix.
 rank_increase_flagbool
a flag that is returned to indicate is a candidate germ failed to amplify additional parameters. This indicates things short circuited and so the scoring function should skip this germ.
 pygsti.algorithms.germselection.find_germs_breadthfirst_greedy(model_list, germs_list, randomize=True, randomization_strength=0.001, num_copies=None, seed=0, op_penalty=0, score_func='all', tol=1e06, threshold=1000000.0, check=False, force='singletons', pretest=True, mem_limit=None, comm=None, profiler=None, verbosity=0, num_nongauge_params=None, float_type=_np.cdouble, mode='allJac', force_rank_increase=False, save_cevd_cache_filename=None, load_cevd_cache_filename=None, file_compression=False, evd_tol=1e10, initial_germ_set_test=True)
Greedy algorithm starting with 0 germs.
Tries to minimize the number of germs needed to achieve amplificational completeness (AC). Begins with 0 germs and adds the germ that increases the score used to check for AC by the largest amount (for the model that currently has the lowest score) at each step, stopping when the threshold for AC is achieved. This strategy is something of a “breadthfirst” approach, in contrast to
find_germs_depthfirst()
, which only looks at the scores for one model at a time until that model achieves AC, then turning it’s attention to the remaining models.Parameters
 model_listModel or list
The model or list of Models to select germs for.
 germs_listlist of Circuit
The list of germs to contruct a germ set from.
 randomizebool, optional
Whether or not to randomize model_list (usually just a single Model) with small (see randomizationStrengh) unitary maps in order to avoid “accidental” symmetries which could allow for fewer germs but only for that particular model. Setting this to True will increase the run time by a factor equal to the numer of randomized copies (num_copies).
 randomization_strengthfloat, optional
The strength of the unitary noise used to randomize input Model(s); is passed to
randomize_with_unitary()
. num_copiesint, optional
The number of randomized models to create when only a single gate set is passed via model_list. Otherwise, num_copies must be set to None.
 seedint, optional
Seed for generating random unitary perturbations to models.
 op_penaltyfloat, optional
Coefficient for a penalty linear in the sum of the germ lengths.
 score_func{‘all’, ‘worst’}, optional
Sets the objective function for scoring the eigenvalues. If ‘all’, score is
sum(1/eigenvalues)
. If ‘worst’, score is1/min(eiganvalues)
. tolfloat, optional
Tolerance (eps arg) for
_compute_bulk_twirled_ddd()
, which sets the differece between eigenvalues below which they’re treated as degenerate. thresholdfloat, optional
Value which the score (before penalties are applied) must be lower than for a germ set to be considered AC.
 checkbool, optional
Whether to perform internal checks (will slow down run time substantially).
 forcestr or list of Circuits, optional (default ‘singletons’)
A list of Circuit objects which must be included in the final germ set. If the special string “singletons” is given, then all of the single gates (length1 sequences) must be included. If none then not circuits are forcibly included.
 pretestboolean, optional
Whether germ list should be initially checked for completeness.
 mem_limitint, optional
A rough memory limit in bytes which restricts the amount of intermediate values that are computed and stored.
 commmpi4py.MPI.Comm, optional
When not None, an MPI communicator for distributing the computation across multiple processors.
 profilerProfiler, optional
A profiler object used for to track timing and memory usage.
 verbosityint, optional
Level of detail printed to stdout.
 num_nongauge_paramsint, optional
Force the number of nongauge parameters rather than rely on automated gauge optimization.
 float_typenumpy dtype object, optional
Use an alternative data type for the values of the numpy arrays generated.
 force_rank_increasebool, optional
Whether to force the greedy iteration to select a new germ that increases the rank of the jacobian at each iteration (this may result in choosing a germ that is suboptimal with respect to the chosen score function). Also results in pruning in subsequent optimization iterations. Defaults to False.
 evd_tolfloat, optional
A threshold value to use when taking eigenvalue decompositions/SVDs such that values below this are set to zero.
 initial_germ_set_testbool, optional (default True)
A flag indicating whether or not to check the initially constructed germ set, which is either the list of singleton germs (if force=’singletons’), a user specified list of circuits is such a list if passed in for the value of force, or a greedily selected initial germ if force=None. This can be skipped to save computational time (the test can be expensive) if the user has reason to believe this initial set won’t be AC. Most of the time this initial set won’t be.
Returns
 list
A list of the builtup germ set (a list of
Circuit
objects).
 pygsti.algorithms.germselection.compute_composite_germ_set_score_compactevd(current_update_cache, germ_update, score_fn='all', threshold_ac=1000000.0, init_n=1, model=None, partial_germs_list=None, eps=None, num_germs=None, op_penalty=0.0, l1_penalty=0.0, num_nongauge_params=None, num_params=None, force_rank_increase=False, germ_lengths=None, float_type=_np.cdouble)
Compute the score for a germ set when it is not AC against a model.
Normally scores computed for germ sets against models for which they are not AC will simply be astronomically large. This is fine if AC is all you care about, but not so useful if you want to compare partial germ sets against one another to see which is closer to being AC. This function will see if the germ set is AC for the parameters corresponding to the largest N eigenvalues for increasing N until it finds a value of N for which the germ set is not AC or all the non gauge parameters are accounted for and report the value of N as well as the score. This allows partial germ set scores to be compared against oneanother sensibly, where a larger value of N always beats a smaller value of N, and ties in the value of N are broken by the score for that value of N.
Parameters
 current_update_cachetuple
A tuple whose elements are the components of the current update cache for performing a lowrank update. Elements are (e, U , projU).
 germ_updatendarray
A numpy array corresponding to one half of the lowrank symmetric update to to perform.
 score_fncallable
A function that takes as input a list of sorted eigenvalues and returns a score for the partial germ set based on those eigenvalues, with lower scores indicating better germ sets. Usually some flavor of
list_score()
. threshold_acfloat, optional
Value which the score (before penalties are applied) must be lower than for the germ set to be considered AC.
 init_nint
The number of largest eigenvalues to begin with checking.
 modelModel, optional
The model against which the germ set is to be scored. Not needed if partial_deriv_dagger_deriv is provided.
 partial_germs_listlist of Circuit, optional
The list of germs in the partial germ set to be evaluated. Not needed if partial_deriv_dagger_deriv (and germ_lengths when
op_penalty > 0
) are provided. epsfloat, optional
Used when calculating partial_deriv_dagger_deriv to determine if two eigenvalues are equal (see
_bulk_twirled_deriv()
for details). Not used if partial_deriv_dagger_deriv is provided. op_penaltyfloat, optional
Coefficient for a penalty linear in the sum of the germ lengths.
 germ_lengthsnumpy.array, optional
The length of each germ. Not needed if op_penalty is
0.0
or partial_germs_list is provided. l1_penaltyfloat, optional
Coefficient for a penalty linear in the number of germs.
 num_nongauge_paramsint, optional
Force the number of nongauge parameters rather than rely on automated gauge optimization.
 num_paramsint
Total number of model parameters.
 force_rank_increasebool, optional
Whether to force the greedy iteration to select a new germ that increases the rank of the jacobian at each iteration (this may result in choosing a germ that is suboptimal with respect to the chosen score function). Also results in pruning in subsequent optimization iterations. Defaults to False.
Returns
 CompositeScore
The score for the germ set indicating how many parameters it amplifies and its numerical score restricted to those parameters.
 pygsti.algorithms.germselection.compute_composite_germ_set_score_low_rank_trace(current_update_cache, germ_update, score_fn='all', threshold_ac=1000000.0, init_n=1, model=None, partial_germs_list=None, eps=None, num_germs=None, op_penalty=0.0, l1_penalty=0.0, num_nongauge_params=None, num_params=None, force_rank_increase=False, germ_lengths=None, float_type=_np.cdouble)
Compute the score for a germ set when it is not AC against a model.
Normally scores computed for germ sets against models for which they are not AC will simply be astronomically large. This is fine if AC is all you care about, but not so useful if you want to compare partial germ sets against one another to see which is closer to being AC. This function will see if the germ set is AC for the parameters corresponding to the largest N eigenvalues for increasing N until it finds a value of N for which the germ set is not AC or all the non gauge parameters are accounted for and report the value of N as well as the score. This allows partial germ set scores to be compared against oneanother sensibly, where a larger value of N always beats a smaller value of N, and ties in the value of N are broken by the score for that value of N.
Parameters
 current_update_cachetuple
A tuple whose elements are the components of the current update cache for performing a lowrank update. Elements are (e, U , projU).
 germ_updatendarray
A numpy array corresponding to one half of the lowrank symmetric update to to perform.
 score_fncallable
A function that takes as input a list of sorted eigenvalues and returns a score for the partial germ set based on those eigenvalues, with lower scores indicating better germ sets. Usually some flavor of
list_score()
. threshold_acfloat, optional
Value which the score (before penalties are applied) must be lower than for the germ set to be considered AC.
 init_nint
The number of largest eigenvalues to begin with checking.
 modelModel, optional
The model against which the germ set is to be scored. Not needed if partial_deriv_dagger_deriv is provided.
 partial_germs_listlist of Circuit, optional
The list of germs in the partial germ set to be evaluated. Not needed if partial_deriv_dagger_deriv (and germ_lengths when
op_penalty > 0
) are provided. epsfloat, optional
Used when calculating partial_deriv_dagger_deriv to determine if two eigenvalues are equal (see
_bulk_twirled_deriv()
for details). Not used if partial_deriv_dagger_deriv is provided. op_penaltyfloat, optional
Coefficient for a penalty linear in the sum of the germ lengths.
 germ_lengthsnumpy.array, optional
The length of each germ. Not needed if op_penalty is
0.0
or partial_germs_list is provided. l1_penaltyfloat, optional
Coefficient for a penalty linear in the number of germs.
 num_nongauge_paramsint, optional
Force the number of nongauge parameters rather than rely on automated gauge optimization.
 num_paramsint
Total number of model parameters.
 force_rank_increasebool, optional
Whether to force the greedy iteration to select a new germ that increases the rank of the jacobian at each iteration (this may result in choosing a germ that is suboptimal with respect to the chosen score function). Also results in pruning in subsequent optimization iterations. Defaults to False.
Returns
 CompositeScore
The score for the germ set indicating how many parameters it amplifies and its numerical score restricted to those parameters.
 rank_increase_flagbool
A flag that indicates whether the candidate update germ increases the rank of the overall Jacobian.
 pygsti.algorithms.germselection.fast_kron(a, b)
 pygsti.algorithms.germselection.stable_pinv(mat)
 pygsti.algorithms.germselection.germ_set_spanning_vectors(target_model, germ_list, assume_real=False, float_type=_np.cdouble, num_nongauge_params=None, tol=1e06, pretest=False, evd_tol=1e10, verbosity=1, threshold=1000000.0, mode='greedy', update_cache_low_rank=False, final_test=True, comm=None)
Parameters
 target_modelModel or list of Model
The model you are aiming to implement, or a list of models that are copies of the model you are trying to implement (either with or without random unitary perturbations applied to the models).
 num_nongauge_paramsint, optional
Force the number of nongauge parameters rather than rely on automated gauge optimization.
 float_typenumpy dtype object, optional
Numpy data type to use for floating point arrays.
 tolfloat, optional
Tolerance (eps arg) for
_compute_bulk_twirled_ddd()
, which sets the differece between eigenvalues below which they’re treated as degenerate. pretestboolean, optional
Whether germ list should be initially checked for completeness.
 evd_tolfloat, optional
A threshold value to use when taking eigenvalue decompositions/SVDs such that values below this are set to zero.
 verbosityint, optional
Level of detail printed to stdout.
 thresholdfloat, optional
Value which the score (before penalties are applied) must be lower than for a germ set to be considered AC
 modestring, optional (default ‘greedy)’
An optional mode string for specifying the search heuristic used for constructing the germ vector set. If ‘greedy’ we use a greedy search algorithm based on lowrank updates. If ‘RRQR’ we use a heuristic for the subset selection problem due to Golub, Klema and Stewart (1976), detailed in chapter 12 of the book “Matrix Computations” by Golub and Van Loan.
 update_cache_low_rankbool, optional (default = False)
A flag indicating whether the psuedoinverses in the update cache used as part of the lowrank update routine should themselves be updated between iterations using lowrank updates. Setting this to True gives a notable performance boost, but I have found that this can also give rise to numerical stability issues, so caveat emptor. Only set to True if you’re sure of what you’re doing.
 final_testbool, optional (default True)
A flag indicating whether a final test should be performed to validate the final score of the germvector set found using either the greedy or RRQR based search heuristics. Can be useful in conjunction with the use of update_cache_low_rank, as this can help detect numerical stability problems in the use of lowrank updates for cache construction.
 commmpi4py.MPI.Comm, optional
When not None, an MPI communicator for distributing the computation across multiple processors.
Returns
 germ_vec_dictdict
A dictionary whose keys are germs and whose elements are numpy arrays whose columns correspond to the amplified directions in parameter space identified for that germ such that when combined with the amplified directions selected for each other germ in the set we maintain amplificational completeness.
 currentDDDndarray
The J^T@J matrix for subset of twirled derivative columns selected accross all of the germs. The spectrum of this matrix provides information about the amplificational properties of the reduced vector set.
 pygsti.algorithms.germselection.compute_composite_vector_set_score(current_update_cache, vector_update, model=None, num_nongauge_params=None, force_rank_increase=False, float_type=_np.cdouble)
Compute the score for a germ set when it is not AC against a model.
Normally scores computed for germ sets against models for which they are not AC will simply be astronomically large. This is fine if AC is all you care about, but not so useful if you want to compare partial germ sets against one another to see which is closer to being AC. This function will see if the germ set is AC for the parameters corresponding to the largest N eigenvalues for increasing N until it finds a value of N for which the germ set is not AC or all the non gauge parameters are accounted for and report the value of N as well as the score. This allows partial germ set scores to be compared against oneanother sensibly, where a larger value of N always beats a smaller value of N, and ties in the value of N are broken by the score for that value of N.
Parameters
 current_update_cachetuple
A tuple whose elements are the components of the current update cache for performing a lowrank update. Elements are (pinv(A), proj_A).
 vector_updatendarray
A numpy array corresponding to one half of the lowrank symmetric update to to perform.
 modelModel, optional
The model against which the germ set is to be scored. Not needed if partial_deriv_dagger_deriv is provided.
 num_nongauge_paramsint, optional
Force the number of nongauge parameters rather than rely on automated gauge optimization.
 force_rank_increasebool, optional
Whether to force the greedy iteration to select a new germ that increases the rank of the jacobian at each iteration (this may result in choosing a germ that is suboptimal with respect to the chosen score function). Also results in pruning in subsequent optimization iterations. Defaults to False.
Returns
 CompositeScore
The score for the germ set indicating how many parameters it amplifies and its numerical score restricted to those parameters.
 rank_increase_flagbool
A flag that indicates whether the candidate update germ increases the rank of the overall Jacobian.
 pygsti.algorithms.germselection.construct_update_cache_rank_one(mat, evd_tol=1e10, prev_update_cache=None, rank_one_update=None)
Calculates the parts of the psuedoinverse update loop algorithm that we can precompute and reuse throughout all of the potential updates.
This is based on a result from Carl Meyer in Generalized Inversion of Modified Matrices, and summarized in 3.2.7 of the matrix cookbook.
quantities we can precompute are (for initial matrix A): pinv(A) IA@pinv(A)
Input:
 matndarray
The matrix to construct a set of reusable objects for performing the updates. mat is assumed to be a symmetric square matrix.
 evd_tolfloat (optional)
A threshold value for setting eigenvalues to zero.
Output:
 pinv_Andarray
The psuedoinverse of the input matrix
 proj_Andarray
A projectors onto the orthogonal complement of the column space of the input matrix.
 pinv_A_tracefloat
The trace of pinv_A.
 rankint
The current rank of A/pinv_A
 pygsti.algorithms.germselection.rank_one_inverse_trace_update(vector_update, pinv_A, proj_A, pinv_A_trace, force_rank_increase=False)
Helper function for calculating rankone updates to the trace of the psuedoinverse. Takes as input a rankone update, the psuedoinverse of the matrix we’re updating, the projector onto the column space for the matrix whose psuedoinverse we are updating and a flag for specifying if we’re requiring the rank to increase.
 pygsti.algorithms.germselection.rank_one_psuedoinverse_update(vector_update, pinv_A, proj_A, force_rank_increase=False)
Helper function for calculating rankone psuedoinverse updates. Takes as input a rankone update, the psuedoinverse of the matrix we’re updating, the projector onto the column space for the matrix whose psuedoinverse we are updating and a flag for specifying if we’re requiring the rank to increase.