pygsti.algorithms.germselection.find_germs

Contents

pygsti.algorithms.germselection.find_germs#

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, float_type=None, mode='compactEVD', 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 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) – The model you are aiming to implement.

  • 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 and to the rng for dropping random fraction of germs.

  • 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. Setting 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_greedy() 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 degradation 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.

  • num_nongauge_params (int, optional) – Force the number of nongauge parameters rather than rely on automated gauge optimization.

  • float_type (numpy dtype object, optional) – Numpy data type to use for floating point arrays. Automatically resolved based on whether the model’s basis is real-valued. Can be manually specified by user, which can be useful for controlling memory footprint.

  • toss_random_frac (float, 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 low-rank updates to the pseudoinverse. This alternative approach means that this mode also only works with the score function option set to ‘all’.

  • force_rank_increase (bool, 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 subsequent 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_filename (str, 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_filename (str, 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_compression (bool, 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:

A list containing the germs making up the germ set.

Return type:

list of Circuit

Contents