:py:mod:`pygsti.drivers.longsequence` ===================================== .. py:module:: pygsti.drivers.longsequence .. autoapi-nested-parse:: End-to-end functions for performing long-sequence GST Module Contents --------------- Functions ~~~~~~~~~ .. autoapisummary:: pygsti.drivers.longsequence.run_model_test pygsti.drivers.longsequence.run_linear_gst pygsti.drivers.longsequence.run_long_sequence_gst pygsti.drivers.longsequence.run_long_sequence_gst_base pygsti.drivers.longsequence.run_stdpractice_gst Attributes ~~~~~~~~~~ .. autoapisummary:: pygsti.drivers.longsequence.ROBUST_SUFFIX_LIST pygsti.drivers.longsequence.DEFAULT_BAD_FIT_THRESHOLD .. py:data:: ROBUST_SUFFIX_LIST :value: "['.robust', '.Robust', '.robust+', '.Robust+']" .. py:data:: DEFAULT_BAD_FIT_THRESHOLD :value: '2.0' .. py:function:: 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, checkpoint=None, checkpoint_path=None, disable_checkpointing=False, simulator: Optional[pygsti.forwardsims.ForwardSimulator.Castable] = None) Compares a :class:`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 :class:`~pygsti.protocols.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 :func:`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 :func:`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. checkpoint : ModelTestCheckpoint, optional (default None) If specified use a previously generated checkpoint object to restart or warm start this run part way through. checkpoint_path : str, optional (default None) A string for the path/name to use for writing intermediate checkpoint files to disk. Format is {path}/{name}, without inclusion of the json file extension. This {path}/{name} combination will have the latest completed iteration number appended to it before writing it to disk. If none, the value of {name} will be set to the name of the protocol being run. disable_checkpointing : bool, optional (default False) When set to True checkpoint objects will not be constructed and written to disk during the course of this protocol. It is strongly recommended that this be kept set to False without good reason to disable the checkpoints. simulator : ForwardSimulator.Castable or None Ignored if None. If not None, then we call fwdsim = ForwardSimulator.cast(simulator), and we set the .sim attribute of every Model we encounter to fwdsim. Returns ------- Results .. py:function:: run_linear_gst(data_filename_or_set, target_model_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 :func:`run_lgst` function in that it may perform a post-LGST gauge optimization and this routine returns a :class:`Results` object containing the LGST estimate. Overall, this is a high-level driver routine which can be used similarly to :func:`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). target_model_filename_or_object : Model or string The target model specifying the gates and SPAM elements that LGST is to be run on, given 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. gauge_opt_params : dict, optional A dictionary of arguments to :func:`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 :func:`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 :func:`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 .. py:function:: 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, checkpoint=None, checkpoint_path=None, disable_checkpointing=False, simulator: Optional[pygsti.forwardsims.ForwardSimulator.Castable] = None, gauge_opt_suite_name: str = 'stdgaugeopt') 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 :class:`~pygsti.protocols.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 :func:`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 :func:`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. 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. checkpoint : GateSetTomographyCheckpoint, optional (default None) If specified use a previously generated checkpoint object to restart or warm start this run part way through. checkpoint_path : str, optional (default None) A string for the path/name to use for writing intermediate checkpoint files to disk. Format is {path}/{name}, without inclusion of the json file extension. This {path}/{name} combination will have the latest completed iteration number appended to it before writing it to disk. If none, the value of {name} will be set to the name of the protocol being run. disable_checkpointing : bool, optional (default False) When set to True checkpoint objects will not be constructed and written to disk during the course of this protocol. It is strongly recommended that this be kept set to False without good reason to disable the checkpoints. simulator : ForwardSimulator.Castable or None Ignored if None. If not None, then we call fwdsim = ForwardSimulator.cast(simulator), and we set the .sim attribute of every Model we encounter to fwdsim. gauge_opt_suite_name : str, optional (default 'stdgaugeopt') An optional string specifying a named gauge optimization suite. Returns ------- Results .. py:function:: 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, checkpoint=None, checkpoint_path=None, disable_checkpointing=False, simulator: Optional[pygsti.forwardsims.ForwardSimulator.Castable] = None, gauge_opt_suite_name: Optional[str] = 'stdgaugeopt') A more fundamental interface for performing end-to-end GST. Similar to :func:`run_long_sequence_gst` except this function takes `lsgst_lists`, a list of either raw circuit lists or of :class:`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 :class:`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 :func:`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 :func:`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 :func:`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. checkpoint : GateSetTomographyCheckpoint, optional (default None) If specified use a previously generated checkpoint object to restart or warm start this run part way through. checkpoint_path : str, optional (default None) A string for the path/name to use for writing intermediate checkpoint files to disk. Format is {path}/{name}, without inclusion of the json file extension. This {path}/{name} combination will have the latest completed iteration number appended to it before writing it to disk. If none, the value of {name} will be set to the name of the protocol being run. disable_checkpointing : bool, optional (default False) When set to True checkpoint objects will not be constructed and written to disk during the course of this protocol. It is strongly recommended that this be kept set to False without good reason to disable the checkpoints. simulator : ForwardSimulator.Castable or None Ignored if None. If not None, then we call fwdsim = ForwardSimulator.cast(simulator), and we set the .sim attribute of every Model we encounter to fwdsim. gauge_opt_suite_name : str, optional (default 'stdgaugeopt') An optional string specifying a named gauge optimization suite. Returns ------- Results .. py:function:: run_stdpractice_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, modes=('full TP', 'CPTPLND', 'Target'), gaugeopt_suite='stdgaugeopt', gaugeopt_target=None, models_to_test=None, comm=None, mem_limit=None, advanced_options=None, output_pkl=None, verbosity=2, checkpoint=None, checkpoint_path=None, disable_checkpointing=False, simulator: Optional[pygsti.forwardsims.ForwardSimulator.Castable] = None) Perform end-to-end GST analysis using standard practices. This routines is an even higher-level driver than :func:`run_long_sequence_gst`. It performs bottled, typically-useful, runs of long sequence GST on a dataset. This essentially boils down to running :func:`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). target_model_filename_or_object : Model or string A specification of the target model that GST is to be run on, given either directly or by the filename of a model (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. modes : iterable of strs, optional (default ('full TP','CPTPLND','Target') An iterable strings corresponding to 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 - : 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 :func:`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 :func:`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. checkpoint : StandardGSTCheckpoint, optional (default None) If specified use a previously generated checkpoint object to restart or warm start this run part way through. checkpoint_path : str, optional (default None) A string for the path/name to use for writing intermediate checkpoint files to disk. Format is {path}/{name}, without inclusion of the json file extension. This {path}/{name} combination will have the latest completed iteration number appended to it before writing it to disk. If none, the value of {name} will be set to the name of the protocol being run. disable_checkpointing : bool, optional (default False) When set to True checkpoint objects will not be constructed and written to disk during the course of this protocol. It is strongly recommended that this be kept set to False without good reason to disable the checkpoints. simulator : ForwardSimulator.Castable or None Ignored if None. If not None, then we call fwdsim = ForwardSimulator.cast(simulator), and we set the .sim attribute of every Model we encounter to fwdsim. Returns ------- Results