pygsti.drivers.longsequence

End-to-end functions for performing long-sequence GST

Module Contents

Functions

run_model_test(model_filename_or_object, data_filename_or_set, processorspec_filename_or_object, prep_fiducial_list_or_filename, meas_fiducial_list_or_filename, germs_list_or_filename, max_lengths, gauge_opt_params=None, advanced_options=None, comm=None, mem_limit=None, output_pkl=None, verbosity=2)

Compares a Model's predictions to a DataSet using GST-like circuits.

run_linear_gst(data_filename_or_set, processorspec_filename_or_object, prep_fiducial_list_or_filename, meas_fiducial_list_or_filename, gauge_opt_params=None, advanced_options=None, comm=None, mem_limit=None, output_pkl=None, verbosity=2)

Perform Linear Gate Set Tomography (LGST).

run_long_sequence_gst(data_filename_or_set, target_model_filename_or_object, prep_fiducial_list_or_filename, meas_fiducial_list_or_filename, germs_list_or_filename, max_lengths, gauge_opt_params=None, advanced_options=None, comm=None, mem_limit=None, output_pkl=None, verbosity=2)

Perform long-sequence GST (LSGST).

run_long_sequence_gst_base(data_filename_or_set, target_model_filename_or_object, lsgst_lists, gauge_opt_params=None, advanced_options=None, comm=None, mem_limit=None, output_pkl=None, verbosity=2)

A more fundamental interface for performing end-to-end GST.

run_stdpractice_gst(data_filename_or_set, processorspec_filename_or_object, prep_fiducial_list_or_filename, meas_fiducial_list_or_filename, germs_list_or_filename, max_lengths, modes='full TP,CPTP,Target', gaugeopt_suite='stdgaugeopt', gaugeopt_target=None, models_to_test=None, comm=None, mem_limit=None, advanced_options=None, output_pkl=None, verbosity=2)

Perform end-to-end GST analysis using standard practices.

_load_model(model_filename_or_object)

_load_dataset(data_filename_or_set, comm, verbosity)

Loads a DataSet from the data_filename_or_set argument of functions in this module.

_update_objfn_builders(builders, advanced_options)

_get_badfit_options(advanced_options)

_output_to_pickle(obj, output_pkl, comm)

_get_gst_initial_model(target_model, advanced_options)

_get_gst_builders(advanced_options)

_get_optimizer(advanced_options, model_being_optimized)

Attributes

ROBUST_SUFFIX_LIST

DEFAULT_BAD_FIT_THRESHOLD

pygsti.drivers.longsequence.ROBUST_SUFFIX_LIST = ['.robust', '.Robust', '.robust+', '.Robust+']
pygsti.drivers.longsequence.DEFAULT_BAD_FIT_THRESHOLD = 2.0
pygsti.drivers.longsequence.run_model_test(model_filename_or_object, data_filename_or_set, processorspec_filename_or_object, prep_fiducial_list_or_filename, meas_fiducial_list_or_filename, germs_list_or_filename, max_lengths, gauge_opt_params=None, advanced_options=None, comm=None, mem_limit=None, output_pkl=None, verbosity=2)

Compares a Model’s predictions to a DataSet using GST-like circuits.

This routine tests a Model model against a DataSet using a specific set of structured, GST-like circuits (given by fiducials, max_lengths and germs). In particular, circuits are constructed by repeating germ strings an integer number of times such that the length of the repeated germ is less than or equal to the maximum length set in max_lengths. Each string thus constructed is sandwiched between all pairs of (preparation, measurement) fiducial sequences.

model_filename_or_object is used directly (without any optimization) as the the model estimate at each maximum-length “iteration”. The model is given a trivial default_gauge_group so that it is not altered during any gauge optimization step.

A ModelEstimateResults object is returned, which encapsulates the model estimate and related parameters, and can be used with report-generation routines.

Parameters
  • model_filename_or_object (Model or string) – The model model, specified either directly or by the filename of a model file (text format).

  • data_filename_or_set (DataSet or string) – The data set object to use for the analysis, specified either directly or by the filename of a dataset file (assumed to be a pickled DataSet if extension is ‘pkl’ otherwise assumed to be in pyGSTi’s text format).

  • processorspec_filename_or_object (ProcessorSpec or string) – A specification of the processor this model test is to be run on, given either directly or by the filename of a processor-spec file (text format). The processor specification contains basic interface-level information about the processor being tested, e.g., its state space and available gates.

  • prep_fiducial_list_or_filename ((list of Circuits) or string) – The state preparation fiducial circuits, specified either directly or by the filename of a circuit list file (text format).

  • meas_fiducial_list_or_filename ((list of Circuits) or string or None) – The measurement fiducial circuits, specified either directly or by the filename of a circuit list file (text format). If None, then use the same strings as specified by prep_fiducial_list_or_filename.

  • germs_list_or_filename ((list of Circuits) or string) – The germ circuits, specified either directly or by the filename of a circuit list file (text format).

  • max_lengths (list of ints) – List of integers, one per LSGST iteration, which set truncation lengths for repeated germ strings. The list of circuits for the i-th LSGST iteration includes the repeated germs truncated to the L-values up to and including the i-th one.

  • gauge_opt_params (dict, optional) – A dictionary of arguments to gaugeopt_to_target(), specifying how the final gauge optimization should be performed. The keys and values of this dictionary may correspond to any of the arguments of gaugeopt_to_target() except for the first model argument, which is specified internally. The target_model argument, can be set, but is specified internally when it isn’t. If None, then the dictionary {‘item_weights’: {‘gates’:1.0, ‘spam’:0.001}} is used. If False, then then no gauge optimization is performed.

  • advanced_options (dict, optional) – Specifies advanced options most of which deal with numerical details of the objective function or expert-level functionality.

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

  • mem_limit (int or None, optional) – A rough memory limit in bytes which restricts the amount of memory used (per core when run on multi-CPUs).

  • output_pkl (str or file, optional) – If not None, a file(name) to pickle.dump the returned Results object to (only the rank 0 process performs the dump when comm is not None).

  • verbosity (int, optional) – The ‘verbosity’ option is an integer specifying the level of detail printed to stdout during the calculation.

Returns

Results

pygsti.drivers.longsequence.run_linear_gst(data_filename_or_set, processorspec_filename_or_object, prep_fiducial_list_or_filename, meas_fiducial_list_or_filename, gauge_opt_params=None, advanced_options=None, comm=None, mem_limit=None, output_pkl=None, verbosity=2)

Perform Linear Gate Set Tomography (LGST).

This function differs from the lower level :function:`run_lgst` function in that it may perform a post-LGST gauge optimization and this routine returns a Results object containing the LGST estimate.

Overall, this is a high-level driver routine which can be used similarly to :function:`run_long_sequence_gst` whereas run_lgst is a low-level routine used when building your own algorithms.

Parameters
  • data_filename_or_set (DataSet or string) – The data set object to use for the analysis, specified either directly or by the filename of a dataset file (assumed to be a pickled DataSet if extension is ‘pkl’ otherwise assumed to be in pyGSTi’s text format).

  • processorspec_filename_or_object (ProcessorSpec or string) – A specification of the processor that LGST is to be run on, given either directly or by the filename of a processor-spec file (text format). The processor specification contains basic interface-level information about the processor being tested, e.g., its state space and available gates.

  • prep_fiducial_list_or_filename ((list of Circuits) or string) – The state preparation fiducial circuits, specified either directly or by the filename of a circuit list file (text format).

  • meas_fiducial_list_or_filename ((list of Circuits) or string or None) – The measurement fiducial circuits, specified either directly or by the filename of a circuit list file (text format). If None, then use the same strings as specified by prep_fiducial_list_or_filename.

  • gauge_opt_params (dict, optional) – A dictionary of arguments to gaugeopt_to_target(), specifying how the final gauge optimization should be performed. The keys and values of this dictionary may correspond to any of the arguments of gaugeopt_to_target() except for the first model argument, which is specified internally. The target_model argument, can be set, but is specified internally when it isn’t. If None, then the dictionary {‘item_weights’: {‘gates’:1.0, ‘spam’:0.001}} is used. If False, then then no gauge optimization is performed.

  • advanced_options (dict, optional) – Specifies advanced options most of which deal with numerical details of the objective function or expert-level functionality. See :function:`run_long_sequence_gst`.

  • comm (mpi4py.MPI.Comm, optional) – When not None, an MPI communicator for distributing the computation across multiple processors. In this LGST case, this is just the gauge optimization.

  • mem_limit (int or None, optional) – A rough memory limit in bytes which restricts the amount of memory used (per core when run on multi-CPUs).

  • output_pkl (str or file, optional) – If not None, a file(name) to pickle.dump the returned Results object to (only the rank 0 process performs the dump when comm is not None).

  • verbosity (int, optional) – The ‘verbosity’ option is an integer specifying the level of detail printed to stdout during the calculation.

Returns

Results

pygsti.drivers.longsequence.run_long_sequence_gst(data_filename_or_set, target_model_filename_or_object, prep_fiducial_list_or_filename, meas_fiducial_list_or_filename, germs_list_or_filename, max_lengths, gauge_opt_params=None, advanced_options=None, comm=None, mem_limit=None, output_pkl=None, verbosity=2)

Perform long-sequence GST (LSGST).

This analysis fits a model (target_model_filename_or_object) to data (data_filename_or_set) using the outcomes from periodic GST circuits constructed by repeating germ strings an integer number of times such that the length of the repeated germ is less than or equal to the maximum length set in max_lengths. When LGST is applicable (i.e. for explicit models with full or TP parameterizations), the LGST estimate of the gates is computed, gauge optimized, and used as a starting seed for the remaining optimizations.

LSGST iterates len(max_lengths) times, optimizing the chi2 using successively larger sets of circuits. On the i-th iteration, the repeated germs sequences limited by max_lengths[i] are included in the growing set of circuits used by LSGST. The final iteration maximizes the log-likelihood.

Once computed, the model estimates are optionally gauge optimized as directed by gauge_opt_params. A ModelEstimateResults object is returned, which encapsulates the input and outputs of this GST analysis, and can generate final end-user output such as reports and presentations.

Parameters
  • data_filename_or_set (DataSet or string) – The data set object to use for the analysis, specified either directly or by the filename of a dataset file (assumed to be a pickled DataSet if extension is ‘pkl’ otherwise assumed to be in pyGSTi’s text format).

  • target_model_filename_or_object (Model or string) – The target model, specified either directly or by the filename of a model file (text format).

  • prep_fiducial_list_or_filename ((list of Circuits) or string) – The state preparation fiducial circuits, specified either directly or by the filename of a circuit list file (text format).

  • meas_fiducial_list_or_filename ((list of Circuits) or string or None) – The measurement fiducial circuits, specified either directly or by the filename of a circuit list file (text format). If None, then use the same strings as specified by prep_fiducial_list_or_filename.

  • germs_list_or_filename ((list of Circuits) or string) – The germ circuits, specified either directly or by the filename of a circuit list file (text format).

  • max_lengths (list of ints) – List of integers, one per LSGST iteration, which set truncation lengths for repeated germ strings. The list of circuits for the i-th LSGST iteration includes the repeated germs truncated to the L-values up to and including the i-th one.

  • gauge_opt_params (dict, optional) – A dictionary of arguments to gaugeopt_to_target(), specifying how the final gauge optimization should be performed. The keys and values of this dictionary may correspond to any of the arguments of gaugeopt_to_target() except for the first model argument, which is specified internally. The target_model argument, can be set, but is specified internally when it isn’t. If None, then the dictionary {‘item_weights’: {‘gates’:1.0, ‘spam’:0.001}} is used. If False, then then no gauge optimization is performed.

  • advanced_options (dict, optional) –

    Specifies advanced options most of which deal with numerical details of the objective function or expert-level functionality. The allowed keys and values include: - objective = {‘chi2’, ‘logl’} - op_labels = list of strings - circuit_weights = dict or None - starting_point = “LGST-if-possible” (default), “LGST”, or “target” - depolarize_start = float (default == 0) - randomize_start = float (default == 0) - contract_start_to_cptp = True / False (default) - cptpPenaltyFactor = float (default = 0) - tolerance = float or dict w/’relx’,’relf’,’f’,’jac’,’maxdx’ keys - max_iterations = int - finitediff_iterations = int - min_prob_clip = float - min_prob_clip_for_weighting = float (default == 1e-4) - prob_clip_interval = tuple (default == (-1e6,1e6) - radius = float (default == 1e-4) - use_freq_weighted_chi2 = True / False (default) - XX nested_circuit_lists = True (default) / False - XX include_lgst = True / False (default is True) - distribute_method = “default”, “circuits” or “deriv” - profile = int (default == 1) - check = True / False (default) - XX op_label_aliases = dict (default = None) - always_perform_mle = bool (default = False) - only_perform_mle = bool (default = False) - XX truncScheme = “whole germ powers” (default) or “truncated germ powers”

    or “length as exponent”

    • appendTo = Results (default = None)

    • estimateLabel = str (default = “default”)

    • XX missingDataAction = {‘drop’,’raise’} (default = ‘drop’)

    • XX string_manipulation_rules = list of (find,replace) tuples

    • germ_length_limits = dict of form {germ: maxlength}

    • record_output = bool (default = True)

    • timeDependent = bool (default = False)

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

  • mem_limit (int or None, optional) – A rough memory limit in bytes which restricts the amount of memory used (per core when run on multi-CPUs).

  • output_pkl (str or file, optional) – If not None, a file(name) to pickle.dump the returned Results object to (only the rank 0 process performs the dump when comm is not None).

  • verbosity (int, optional) –

    The ‘verbosity’ option is an integer specifying the level of detail printed to stdout during the calculation. - 0 – prints nothing - 1 – shows progress bar for entire iterative GST - 2 – show summary details about each individual iteration - 3 – also shows outer iterations of LM algorithm - 4 – also shows inner iterations of LM algorithm - 5 – also shows detailed info from within jacobian

    and objective function calls.

Returns

Results

pygsti.drivers.longsequence.run_long_sequence_gst_base(data_filename_or_set, target_model_filename_or_object, lsgst_lists, gauge_opt_params=None, advanced_options=None, comm=None, mem_limit=None, output_pkl=None, verbosity=2)

A more fundamental interface for performing end-to-end GST.

Similar to run_long_sequence_gst() except this function takes lsgst_lists, a list of either raw circuit lists or of PlaquetteGridCircuitStructure objects to define which circuits are used on each GST iteration.

Parameters
  • data_filename_or_set (DataSet or string) – The data set object to use for the analysis, specified either directly or by the filename of a dataset file (assumed to be a pickled DataSet if extension is ‘pkl’ otherwise assumed to be in pyGSTi’s text format).

  • target_model_filename_or_object (Model or string) – The target model, specified either directly or by the filename of a model file (text format).

  • lsgst_lists (list of lists or PlaquetteGridCircuitStructure(s)) – An explicit list of either the raw circuit lists to be used in the analysis or of PlaquetteGridCircuitStructure objects, which additionally contain the structure of a set of circuits. A single PlaquetteGridCircuitStructure object can also be given, which is equivalent to passing a list of successive L-value truncations of this object (e.g. if the object has Ls = [1,2,4] then this is like passing a list of three PlaquetteGridCircuitStructure objects w/truncations [1], [1,2], and [1,2,4]).

  • gauge_opt_params (dict, optional) – A dictionary of arguments to gaugeopt_to_target(), specifying how the final gauge optimization should be performed. The keys and values of this dictionary may correspond to any of the arguments of gaugeopt_to_target() except for the first model argument, which is specified internally. The target_model argument, can be set, but is specified internally when it isn’t. If None, then the dictionary {‘item_weights’: {‘gates’:1.0, ‘spam’:0.001}} is used. If False, then then no gauge optimization is performed.

  • advanced_options (dict, optional) – Specifies advanced options most of which deal with numerical details of the objective function or expert-level functionality. See run_long_sequence_gst() for a list of the allowed keys, with the exception “nested_circuit_lists”, “op_label_aliases”, “include_lgst”, and “truncScheme”.

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

  • mem_limit (int or None, optional) – A rough memory limit in bytes which restricts the amount of memory used (per core when run on multi-CPUs).

  • output_pkl (str or file, optional) – If not None, a file(name) to pickle.dump the returned Results object to (only the rank 0 process performs the dump when comm is not None).

  • verbosity (int, optional) –

    The ‘verbosity’ option is an integer specifying the level of detail printed to stdout during the calculation. - 0 – prints nothing - 1 – shows progress bar for entire iterative GST - 2 – show summary details about each individual iteration - 3 – also shows outer iterations of LM algorithm - 4 – also shows inner iterations of LM algorithm - 5 – also shows detailed info from within jacobian

    and objective function calls.

Returns

Results

pygsti.drivers.longsequence.run_stdpractice_gst(data_filename_or_set, processorspec_filename_or_object, prep_fiducial_list_or_filename, meas_fiducial_list_or_filename, germs_list_or_filename, max_lengths, modes='full TP,CPTP,Target', gaugeopt_suite='stdgaugeopt', gaugeopt_target=None, models_to_test=None, comm=None, mem_limit=None, advanced_options=None, output_pkl=None, verbosity=2)

Perform end-to-end GST analysis using standard practices.

This routines is an even higher-level driver than run_long_sequence_gst(). It performs bottled, typically-useful, runs of long sequence GST on a dataset. This essentially boils down to running run_long_sequence_gst() one or more times using different model parameterizations, and performing commonly-useful gauge optimizations, based only on the high-level modes argument.

Parameters
  • data_filename_or_set (DataSet or string) – The data set object to use for the analysis, specified either directly or by the filename of a dataset file (assumed to be a pickled DataSet if extension is ‘pkl’ otherwise assumed to be in pyGSTi’s text format).

  • processorspec_filename_or_object (ProcessorSpec or string) – A specification of the processor that GST is to be run on, given either directly or by the filename of a processor-spec file (text format). The processor specification contains basic interface-level information about the processor being tested, e.g., its state space and available gates.

  • prep_fiducial_list_or_filename ((list of Circuits) or string) – The state preparation fiducial circuits, specified either directly or by the filename of a circuit list file (text format).

  • meas_fiducial_list_or_filename ((list of Circuits) or string or None) – The measurement fiducial circuits, specified either directly or by the filename of a circuit list file (text format). If None, then use the same strings as specified by prep_fiducial_list_or_filename.

  • germs_list_or_filename ((list of Circuits) or string) – The germ circuits, specified either directly or by the filename of a circuit list file (text format).

  • max_lengths (list of ints) – List of integers, one per LSGST iteration, which set truncation lengths for repeated germ strings. The list of circuits for the i-th LSGST iteration includes the repeated germs truncated to the L-values up to and including the i-th one.

  • modes (str, optional) –

    A comma-separated list of modes which dictate what types of analyses are performed. Currently, these correspond to different types of parameterizations/constraints to apply to the estimated model. The default value is usually fine. Allowed values are:

    • ”full” : full (completely unconstrained)

    • ”TP” : TP-constrained

    • ”CPTP” : Lindbladian CPTP-constrained

    • ”H+S” : Only Hamiltonian + Stochastic errors allowed (CPTP)

    • ”S” : Only Stochastic errors allowed (CPTP)

    • ”Target” : use the target (ideal) gates as the estimate

    • <model> : any key in the models_to_test argument

  • gaugeopt_suite (str or list or dict, optional) –

    Specifies which gauge optimizations to perform on each estimate. A string or list of strings (see below) specifies built-in sets of gauge optimizations, otherwise gaugeopt_suite should be a dictionary of gauge-optimization parameter dictionaries, as specified by the gauge_opt_params argument of run_long_sequence_gst(). The key names of gaugeopt_suite then label the gauge optimizations within the resuling Estimate objects. The built-in suites are:

    • ”single” : performs only a single “best guess” gauge optimization.

    • ”varySpam” : varies spam weight and toggles SPAM penalty (0 or 1).

    • ”varySpamWt” : varies spam weight but no SPAM penalty.

    • ”varyValidSpamWt” : varies spam weight with SPAM penalty == 1.

    • ”toggleValidSpam” : toggles spame penalty (0 or 1); fixed SPAM wt.

    • ”unreliable2Q” : adds branch to a spam suite that weights 2Q gates less

    • ”none” : no gauge optimizations are performed.

  • gaugeopt_target (Model, optional) – If not None, a model to be used as the “target” for gauge- optimization (only). This argument is useful when you want to gauge optimize toward something other than the ideal target gates given by target_model_filename_or_object, which are used as the default when gaugeopt_target is None.

  • models_to_test (dict, optional) – A dictionary of Model objects representing (gate-set) models to test against the data. These Models are essentially hypotheses for which (if any) model generated the data. The keys of this dictionary can (and must, to actually test the models) be used within the comma- separate list given by the modes argument.

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

  • mem_limit (int or None, optional) – A rough memory limit in bytes which restricts the amount of memory used (per core when run on multi-CPUs).

  • advanced_options (dict, optional) – Specifies advanced options most of which deal with numerical details of the objective function or expert-level functionality. See run_long_sequence_gst() for a list of the allowed keys for each such dictionary.

  • output_pkl (str or file, optional) – If not None, a file(name) to pickle.dump the returned Results object to (only the rank 0 process performs the dump when comm is not None).

  • verbosity (int, optional) – The ‘verbosity’ option is an integer specifying the level of detail printed to stdout during the calculation.

Returns

Results

pygsti.drivers.longsequence._load_model(model_filename_or_object)
pygsti.drivers.longsequence._load_dataset(data_filename_or_set, comm, verbosity)

Loads a DataSet from the data_filename_or_set argument of functions in this module.

pygsti.drivers.longsequence._update_objfn_builders(builders, advanced_options)
pygsti.drivers.longsequence._get_badfit_options(advanced_options)
pygsti.drivers.longsequence._output_to_pickle(obj, output_pkl, comm)
pygsti.drivers.longsequence._get_gst_initial_model(target_model, advanced_options)
pygsti.drivers.longsequence._get_gst_builders(advanced_options)
pygsti.drivers.longsequence._get_optimizer(advanced_options, model_being_optimized)