pygsti.algorithms.germselection¶

Functions for selecting a complete set of germs for a GST analysis.

Module Contents¶

Functions¶

 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) Generate a germ set for doing GST with a given target model. 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) Calculate the score of a germ set with respect to a model. _get_model_params(model_list) Get the number of gates and gauge parameters of the models in a list. _setup_model_list(model_list, randomize, randomization_strength, num_copies, seed) Sets up a list of randomize models (helper function). 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, num_gauge_params=None, op_penalty=0.0, germ_lengths=None, l1_penalty=0.0) Compute the score for a germ set when it is not AC against a model. _compute_bulk_twirled_ddd(model, germs_list, eps=1e-06, check=False, germ_lengths=None, comm=None) Calculate the positive squares of the germ Jacobians. _compute_twirled_ddd(model, germ, eps=1e-06) Calculate the positive squares of the germ Jacobian. _germ_set_score_slack(weights, model_num, score_func, deriv_dagger_deriv_list, force_indices, force_score, n_gauge_params, op_penalty, germ_lengths, l1_penalty=0.01, score_dict=None) Returns a germ set "score" in which smaller is better. randomize_model_list(model_list, randomization_strength, num_copies, seed=None) Applies random unitary perturbations to a model or list of models. test_germs_list_completeness(model_list, germs_list, score_func, threshold) Check to see if the germs_list is amplificationally complete (AC). _remove_spam_vectors(model) Returns a copy of model with state preparations and effects removed. _num_non_spam_gauge_params(model) Return the number of non-gauge, non-SPAM parameters in model. _super_op_for_perfect_twirl(wrt, eps) Return super operator for doing a perfect twirl with respect to wrt. _sq_sing_vals_from_deriv(deriv, weights=None) Calculate the squared singular values of the Jacobian of the germ set. _twirled_deriv(model, circuit, eps=1e-06) Compute the "Twirled Derivative" of a circuit. _bulk_twirled_deriv(model, circuits, eps=1e-06, check=False, comm=None) Compute the "Twirled Derivative" of a set of circuits. test_germ_set_finitel(model, germs_to_test, length, weights=None, return_spectrum=False, tol=1e-06) Test whether a set of germs is able to amplify all non-gauge parameters. test_germ_set_infl(model, germs_to_test, score_func='all', weights=None, return_spectrum=False, threshold=1000000.0, check=False) Test whether a set of germs is able to amplify all non-gauge parameters. 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=1e-06, threshold=1000000.0, check=False, force='singletons', verbosity=0) Greedy germ selection algorithm starting with 0 germs. 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=1e-06, threshold=1000000.0, check=False, force='singletons', pretest=True, mem_limit=None, comm=None, profiler=None, verbosity=0) Greedy algorithm starting with 0 germs. 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=1e-06, check=False, force='singletons', force_score=1e+100, threshold=1000000.0, verbosity=1) Find a locally optimal subset of the germs in germs_list. _germ_set_score_grasp(germ_set, germs_list, twirled_deriv_dagger_deriv_list, non_ac_kwargs, init_n=1) Score a germ set against a collection of models. 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=1e-06, threshold=1000000.0, check=False, force='singletons', iterations=5, return_all=False, shuffle=False, verbosity=0) Use GRASP to find a high-performing germ set.

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)

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 algorithm-specific 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_model (Model 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).

• randomize (bool, optional) – Whether or not to add random unitary perturbations to the model(s) provided.

• randomization_strength (float, optional) – The size of the random unitary perturbations applied to gates in the model. See randomize_with_unitary() for more details.

• num_gs_copies (int, optional) – The number of copies of the original model that should be used.

• seed (int, optional) – Seed for generating random unitary perturbations to models. Also passed along to stochastic germ-selection algorithms.

• candidate_germ_counts (dict, optional) – A dictionary of germ_length : count key-value 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 non-equivalent 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_seed (int, 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.

• force (str 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 length-1 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 one-at-a-time until the set is AC, picking the germ that improves the germ-set 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 germ-set 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_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.

• mem_limit (int, optional) – A rough memory limit in bytes which restricts the amount of intermediate values that are computed and stored.

• comm (mpi4py.MPI.Comm, optional) – When not None, an MPI communicator for distributing the computation across multiple processors.

• profiler (Profiler, optional) – A profiler object used for to track timing and memory usage.

• verbosity (int, optional) – The verbosity level of the VerbosityPrinter used to print log messages.

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)

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
• germs (list) – The germ set

• target_model (Model, optional) – The target model, used to generate a neighborhood of randomized models.

• neighborhood (list 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_size (int, optional) – Number of randomized models to construct around target_model.

• randomization_strength (float, optional) – Strength of unitary randomizations, as passed to :method:`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 is 1/min(input_array).

• op_penalty (float, optional) – Coefficient for a penalty linear in the sum of the germ lengths.

• l1_penalty (float, optional) – Coefficient for a penalty linear in the number of germs.

Returns

CompositeScore – The maximum score for germs, indicating how many parameters it amplifies.

pygsti.algorithms.germselection._get_model_params(model_list)

Get the number of gates and gauge parameters of the models in a list.

Also verifies all models have the same number of gates and gauge parameters.

Parameters

model_list (list of Model) – A list of models for which you want an AC germ set.

Returns

• reducedModelList (list of Model) – The original list of models with SPAM removed

• numGaugeParams (int) – The number of non-SPAM gauge parameters for all models.

• numNonGaugeParams (int) – The number of non-SPAM non-gauge parameters for all models.

• numOps (int) – The number of gates for all models.

Raises

ValueError – If the number of gauge parameters or gates varies among the models.

pygsti.algorithms.germselection._setup_model_list(model_list, randomize, randomization_strength, num_copies, seed)

Sets up a list of randomize models (helper function).

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, num_gauge_params=None, op_penalty=0.0, germ_lengths=None, l1_penalty=0.0)

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 one-another 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_fn (callable) – 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_ac (float, optional) – Value which the score (before penalties are applied) must be lower than for the germ set to be considered AC.

• init_n (int) – The number of largest eigenvalues to begin with checking.

• partial_deriv_dagger_deriv (numpy.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.

• model (Model, optional) – The model against which the germ set is to be scored. Not needed if partial_deriv_dagger_deriv is provided.

• partial_germs_list (list 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.

• eps (float, 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.

• num_gauge_params (int) – The number of gauge parameters of the model. Not needed if model is provided.

• op_penalty (float, optional) – Coefficient for a penalty linear in the sum of the germ lengths.

• germ_lengths (numpy.array, optional) – The length of each germ. Not needed if op_penalty is 0.0 or partial_germs_list is provided.

• l1_penalty (float, optional) – Coefficient for a penalty linear in the number of germs.

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_bulk_twirled_ddd(model, germs_list, eps=1e-06, check=False, germ_lengths=None, comm=None)

Calculate the positive squares of the germ Jacobians.

twirledDerivDaggerDeriv == array J.H*J contributions from each germ (J=Jacobian) indexed by (iGerm, iModelParam1, iModelParam2) size (nGerms, vec_model_dim, vec_model_dim)

Parameters
• model (Model) – The model defining the parameters to differentiate with respect to.

• germs_list (list) – The germ set

• eps (float, optional) – Tolerance used for testing whether two eigenvectors are degenerate (i.e. abs(eval1 - eval2) < eps ? )

• check (bool, optional) – Whether to perform internal consistency checks, at the expense of making the function slower.

• germ_lengths (numpy.ndarray, optional) – A pre-computed array of the length (depth) of each germ.

• comm (mpi4py.MPI.Comm, optional) – When not None, an MPI communicator for distributing the computation across multiple processors.

Returns

twirledDerivDaggerDeriv (numpy.ndarray) – A complex array of shape (len(germs), model.num_params, model.num_params).

pygsti.algorithms.germselection._compute_twirled_ddd(model, germ, eps=1e-06)

Calculate the positive squares of the germ Jacobian.

twirledDerivDaggerDeriv == array J.H*J contributions from germ (J=Jacobian) indexed by (iModelParam1, iModelParam2) size (vec_model_dim, vec_model_dim)

Parameters
• model (Model) – The model defining the parameters to differentiate with respect to.

• germ (Circuit) – The (single) germ circuit to consider. J above is the twirled derivative of this circuit’s action (process matrix).

• eps (float, optional) – Tolerance used for testing whether two eigenvectors are degenerate (i.e. abs(eval1 - eval2) < eps ? )

Returns

numpy.ndarray

pygsti.algorithms.germselection._germ_set_score_slack(weights, model_num, score_func, deriv_dagger_deriv_list, force_indices, force_score, n_gauge_params, op_penalty, germ_lengths, l1_penalty=0.01, score_dict=None)

Returns a germ set “score” in which smaller is better.

Also returns intentionally bad score (force_score) if weights is zero on any of the “forced” germs (i.e. at any index in forcedIndices). This function is included for use by find_germs_integer_slack(), but is not convenient for just computing the score of a germ set. For that, use compute_germ_set_score().

Parameters
• weights (list) – The per-germ “selection weight”, indicating whether the germ is present in the selected germ set or not.

• model_num (int) – index into deriv_dagger_deriv_list indicating which model (typically in a neighborhood) we’re computing scores for.

• score_func ({'all', 'worst'}) – Sets the objective function for scoring the eigenvalues. If ‘all’, score is sum(1/input_array). If ‘worst’, score is 1/min(input_array).

• deriv_dagger_deriv_list (numpy.ndarray) – Array of J.T * J contributions for each model.

• force_indices (list of ints) – Indices marking the germs that must be in the final set (or else force_score will be returned).

• force_score (float) – The score that is returned when any of the germs indexed by force_indices are not present (i.e. their weights are <= 0).

• n_gauge_params (int) – The number of gauge (not amplifiable) parameters in the model.

• op_penalty (float) – Coefficient for a penalty linear in the sum of the germ lengths.

• germ_lengths (numpy.ndarray) – A pre-computed array of the length (depth) of each germ.

• l1_penalty (float) – Coefficient for a penalty linear in the number of germs.

• score_dict (dict, optional) – A dictionary to cache the score valies for the given model_num and weights, i.e. score_dict[model_num, tuple(weights)] is set to the returned value.

Returns

float

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 length-1 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_list (Model or list) – A list of Model objects.

• randomization_strength (float, optional) – Strength of unitary randomizations, as passed to :method:`Model.randomize_with_unitary`.

• num_copies (int) – The number of random perturbations of model_list 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.

• seed (int, 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)

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_list (list) – A list of models to test. Often this list is a neighborhood (“cloud”) of models around a model of interest.

• germs_list (list) – A list of the germ :class:`Circuit`s (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 is 1/min(eigval_array).

• threshold (float, optional) – An eigenvalue of jacobian^T*jacobian is considered zero and thus a parameter un-amplified when its reciprocal is greater than threshold. Also used for eigenvector degeneracy testing in twirling operation.

Returns

int – The index of the first model in model_list to fail the amplficational completeness test.

pygsti.algorithms.germselection._remove_spam_vectors(model)

Returns a copy of model with state preparations and effects removed.

Parameters

model (Model) – The model to act on.

Returns

Model

pygsti.algorithms.germselection._num_non_spam_gauge_params(model)

Return the number of non-gauge, non-SPAM parameters in model.

Equivalent to _remove_spam_vectors(model).num_gauge_params.

Parameters
• model (Model) –

• model – The model to act on.

Returns

int

pygsti.algorithms.germselection._super_op_for_perfect_twirl(wrt, eps)

Return super operator for doing a perfect twirl with respect to wrt.

pygsti.algorithms.germselection._sq_sing_vals_from_deriv(deriv, weights=None)

Calculate the squared singular values of the Jacobian of the germ set.

Parameters
• deriv (numpy.array) – Array of shape (nGerms, flattened_op_dim, vec_model_dim). Each sub-array corresponding to an individual germ is the Jacobian of the vectorized gate representation of that germ raised to some power with respect to the model parameters, normalized by dividing by the length of each germ after repetition.

• weights (numpy.array) – Array of length nGerms, giving the relative contributions of each individual germ’s Jacobian to the combined Jacobian (which is calculated as a convex combination of the individual Jacobians).

Returns

numpy.array – The sorted squared singular values of the combined Jacobian of the germ set.

pygsti.algorithms.germselection._twirled_deriv(model, circuit, eps=1e-06)

Compute the “Twirled Derivative” of a circuit.

The twirled derivative is obtained by acting on the standard derivative of a circuit with the twirling superoperator.

Parameters
• model (Model object) – The Model which associates operation labels with operators.

• circuit (Circuit object) – A twirled derivative of this circuit’s action (process matrix) is taken.

• eps (float, optional) – Tolerance used for testing whether two eigenvectors are degenerate (i.e. abs(eval1 - eval2) < eps ? )

Returns

numpy array – An array of shape (op_dim^2, num_model_params)

pygsti.algorithms.germselection._bulk_twirled_deriv(model, circuits, eps=1e-06, check=False, comm=None)

Compute the “Twirled Derivative” of a set of circuits.

The twirled derivative is obtained by acting on the standard derivative of a circuit with the twirling superoperator.

Parameters
• model (Model object) – The Model which associates operation labels with operators.

• circuits (list of Circuit objects) – A twirled derivative of this circuit’s action (process matrix) is taken.

• eps (float, optional) – Tolerance used for testing whether two eigenvectors are degenerate (i.e. abs(eval1 - eval2) < eps ? )

• check (bool, optional) – Whether to perform internal consistency checks, at the expense of making the function slower.

• comm (mpi4py.MPI.Comm, optional) – When not None, an MPI communicator for distributing the computation across multiple processors.

Returns

numpy array – An array of shape (num_simplified_circuits, op_dim^2, num_model_params)

pygsti.algorithms.germselection.test_germ_set_finitel(model, germs_to_test, length, weights=None, return_spectrum=False, tol=1e-06)

Test whether a set of germs is able to amplify all non-gauge parameters.

Parameters
• model (Model) – The Model (associates operation matrices with operation labels).

• germs_to_test (list of Circuits) – List of germ circuits to test for completeness.

• length (int) – The finite length to use in amplification testing. Larger values take longer to compute but give more robust results.

• weights (numpy array, optional) – A 1-D 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_spectrum (bool, optional) – If True, return the jacobian^T*jacobian spectrum in addition to the success flag.

• tol (float, optional) – Tolerance: an eigenvalue of jacobian^T*jacobian is considered zero and thus a parameter un-amplified when it is less than tol.

Returns

• success (bool) – Whether all non-gauge parameters were amplified.

• spectrum (numpy 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)

Test whether a set of germs is able to amplify all non-gauge parameters.

Parameters
• model (Model) – The Model (associates operation matrices with operation labels).

• germs_to_test (list of Circuit) – List of germ circuits to test for completeness.

• score_func (string) – Label to indicate how a germ set is scored. See list_score() for details.

• weights (numpy array, optional) – A 1-D 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_spectrum (bool, optional) – If True, return the jacobian^T*jacobian spectrum in addition to the success flag.

• threshold (float, optional) – An eigenvalue of jacobian^T*jacobian is considered zero and thus a parameter un-amplified when its reciprocal is greater than threshold. Also used for eigenvector degeneracy testing in twirling operation.

• check (bool, optional) – Whether to perform internal consistency checks, at the expense of making the function slower.

Returns

• success (bool) – Whether all non-gauge parameters were amplified.

• spectrum (numpy 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=1e-06, threshold=1000000.0, check=False, force='singletons', verbosity=0)

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_list (Model or list) – The model or list of `Model`s to select germs for.

• germs_list (list of Circuit) – The list of germs to contruct a germ set from.

• randomize (bool, 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_strength (float, optional) – The strength of the unitary noise used to randomize input Model(s); is passed to randomize_with_unitary().

• num_copies (int, 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.

• seed (int, optional) – Seed for generating random unitary perturbations to models.

• op_penalty (float, 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 is 1/min(eiganvalues).

• tol (float, optional) – Tolerance (eps arg) for _compute_bulk_twirled_ddd(), which sets the differece between eigenvalues below which they’re treated as degenerate.

• threshold (float, optional) – Value which the score (before penalties are applied) must be lower than for a germ set to be considered AC.

• check (bool, optional) – Whether to perform internal checks (will slow down run time substantially).

• force (list 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 (length-1 sequences) must be included.

• verbosity (int, optional) – Level of detail printed to stdout.

Returns

list – A list of the built-up 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=1e-06, threshold=1000000.0, check=False, force='singletons', pretest=True, mem_limit=None, comm=None, profiler=None, verbosity=0)

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 “breadth-first” 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_list (Model or list) – The model or list of `Model`s to select germs for.

• germs_list (list of Circuit) – The list of germs to contruct a germ set from.

• randomize (bool, 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_strength (float, optional) – The strength of the unitary noise used to randomize input Model(s); is passed to randomize_with_unitary().

• num_copies (int, 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.

• seed (int, optional) – Seed for generating random unitary perturbations to models.

• op_penalty (float, 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 is 1/min(eiganvalues).

• tol (float, optional) – Tolerance (eps arg) for _compute_bulk_twirled_ddd(), which sets the differece between eigenvalues below which they’re treated as degenerate.

• threshold (float, optional) – Value which the score (before penalties are applied) must be lower than for a germ set to be considered AC.

• check (bool, optional) – Whether to perform internal checks (will slow down run time substantially).

• force (list 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 (length-1 sequences) must be included.

• pretest (boolean, optional) – Whether germ list should be initially checked for completeness.

• mem_limit (int, optional) – A rough memory limit in bytes which restricts the amount of intermediate values that are computed and stored.

• comm (mpi4py.MPI.Comm, optional) – When not None, an MPI communicator for distributing the computation across multiple processors.

• profiler (Profiler, optional) – A profiler object used for to track timing and memory usage.

• verbosity (int, optional) – Level of detail printed to stdout.

Returns

list – A list of the built-up 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=1e-06, check=False, force='singletons', force_score=1e+100, threshold=1000000.0, verbosity=1)

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 non-gauge 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_list (Model 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 (~5-10) 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_list (list of Circuit) – List of all germ circuits to consider.

• randomize (Bool, 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 (non-unitary) 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 is True.

• randomization_strength (float, optional) – The strength of the unitary noise used to randomize input Model(s); is passed to randomize_with_unitary(). Default is 1e-3.

• num_copies (int, 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 is None, no extra copies are made.

• seed (float, optional) – The starting seed used for unitary randomization. If multiple Models are to be randomized, model_list[i] is randomized with seed + i. Default is 0.

• l1_penalty (float, optional) – How strong the penalty should be for increasing the germ set list by a single germ. Default is 1e-2.

• op_penalty (float, optional) – How strong the penalty should be for increasing a germ in the germ set list by a single gate. Default is 0.

• initial_weights (list-like) – 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_func (string) – Label to indicate how a germ set is scored. See list_score() for details.

• max_iter (int, optional) – The maximum number of iterations before giving up.

• fixed_slack (float, optional) – If not None, a floating point number which specifies that excluding a germ is allowed to increase 1.0/smallest-non-gauge-eigenvalue 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 germ is allowed to increase 1.0/smallest-non-gauge-eigenvalue by fixedFrac`*100 percent. 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 germ list (see below).

• tol (float, optional) – Tolerance used for eigenvector degeneracy testing in twirling operation.

• check (bool, optional) – Whether to perform internal consistency checks, at the expense of making the function slower.

• force (str 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 length-1 strings will be included. Seting to None is the same as an empty list.

• force_score (float, optional (default is 1e100)) – When force designates a non-empty set of circuits, the score to assign any germ set that does not contain each and every required germ.

• threshold (float, optional (default is 1e6)) – Specifies a maximum score for the score matrix, above which the germ set is rejected as amplificationally incomplete.

• verbosity (int, optional) – Integer >= 0 indicating the amount of detail to print.

Model, Circuit

pygsti.algorithms.germselection._germ_set_score_grasp(germ_set, germs_list, twirled_deriv_dagger_deriv_list, non_ac_kwargs, init_n=1)

Score a germ set against a collection of models.

Calculate the score of the germ set with respect to each member of a collection of models and return the worst score among that collection.

Parameters
• germ_set (list of Circuit) – The set of germs to score.

• germs_list (list of Circuit) – The list of all germs whose Jacobians are provided in twirled_deriv_dagger_deriv_list.

• twirled_deriv_dagger_deriv_list (numpy.array) – Jacobians for all the germs in germs_list stored as a 3-dimensional array, where the first index indexes the particular germ.

• non_ac_kwargs (dict) – Dictionary containing further arguments to pass to compute_composite_germ_set_score() for the scoring of the germ set against individual models.

• init_n (int) – The number of eigenvalues to begin checking for amplificational completeness with respect to. Passed as an argument to compute_composite_germ_set_score().

Returns

CompositeScore – The worst score over all models of the germ set.

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=1e-06, threshold=1000000.0, check=False, force='singletons', iterations=5, return_all=False, shuffle=False, verbosity=0)

Use GRASP to find a high-performing germ set.

Parameters
• model_list (Model 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 (~5-10) 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_list (list of Circuit) – List of all germ circuits to consider.

• alpha (float) – 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 best-scoring 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.

• randomize (Bool, 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 (non-unitary) 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_strength (float, optional) – The strength of the unitary noise used to randomize input Model(s); is passed to randomize_with_unitary(). Default is 1e-3.

• num_copies (int, 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 is None, no extra copies are made.

• seed (float, optional) – The starting seed used for unitary randomization. If multiple Models are to be randomized, model_list[i] is randomized with seed + i.

• l1_penalty (float, 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_penalty (float, optional) – How strong the penalty should be for increasing a germ in the germ set list by a single gate.

• score_func (string) – Label to indicate how a germ set is scored. See list_score() for details.

• tol (float, optional) – Tolerance used for eigenvector degeneracy testing in twirling operation.

• threshold (float, optional (default is 1e6)) – Specifies a maximum score for the score matrix, above which the germ set is rejected as amplificationally incomplete.

• check (bool, optional) – Whether to perform internal consistency checks, at the expense of making the function slower.

• force (str 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 length-1 strings will be included. Seting to None is the same as an empty list.

• iterations (int, optional) – The number of GRASP iterations to perform.

• return_all (bool, 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).

• shuffle (bool, 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).

• verbosity (int, optional) – Integer >= 0 indicating the amount of detail to print.

Returns

finalGermList (list of Circuit) – Sublist of germs_list specifying the final, optimal set of germs.