pygsti.drivers

pyGSTi High-Level Drivers Python Package

Submodules

Package Contents

Classes

_DataSet

An association between Circuits and outcome counts, serving as the input data for many QCVV protocols.

_GSTAdvancedOptions

Advanced options for GST driver functions.

_QubitProcessorSpec

The device specification for a one or more qubit quantum computer.

_Model

A predictive model for a Quantum Information Processor (QIP).

Functions

create_bootstrap_dataset(input_data_set, generation_method, input_model=None, seed=None, outcome_labels=None, verbosity=1)

Creates a DataSet used for generating bootstrapped error bars.

create_bootstrap_models(num_models, input_data_set, generation_method, fiducial_prep, fiducial_measure, germs, max_lengths, input_model=None, target_model=None, start_seed=0, outcome_labels=None, lsgst_lists=None, return_data=False, verbosity=2)

Creates a series of "bootstrapped" Models.

gauge_optimize_models(gs_list, target_model, gate_metric='frobenius', spam_metric='frobenius', plot=True)

Optimizes the "spam weight" parameter used when gauge optimizing a set of models.

_model_stdev(gs_func, gs_ensemble, ddof=1, axis=None, **kwargs)

Standard deviation of gs_func over an ensemble of models.

_model_mean(gs_func, gs_ensemble, axis=None, **kwargs)

Mean of gs_func over an ensemble of models.

_to_mean_model(gs_list, target_gs)

Take the per-gate-element mean of a set of models.

_to_std_model(gs_list, target_gs, ddof=1)

Take the per-gate-element standard deviation of a list of models.

_to_rms_model(gs_list, target_gs)

Take the per-gate-element RMS of a set of models.

_create_explicit_model(processor_spec, modelnoise, custom_gates=None, evotype='default', simulator='auto', ideal_gate_type='auto', ideal_prep_type='auto', ideal_povm_type='auto', embed_gates=False, basis='pp')

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

class pygsti.drivers._DataSet(oli_data=None, time_data=None, rep_data=None, circuits=None, circuit_indices=None, outcome_labels=None, outcome_label_indices=None, static=False, file_to_load_from=None, collision_action='aggregate', comment=None, aux_info=None)

Bases: object

An association between Circuits and outcome counts, serving as the input data for many QCVV protocols.

The DataSet class associates circuits with counts or time series of counts for each outcome label, and can be thought of as a table with gate strings labeling the rows and outcome labels and/or time labeling the columns. It is designed to behave similarly to a dictionary of dictionaries, so that counts are accessed by:

count = dataset[circuit][outcomeLabel]

in the time-independent case, and in the time-dependent case, for integer time index i >= 0,

outcomeLabel = dataset[circuit][i].outcome count = dataset[circuit][i].count time = dataset[circuit][i].time

Parameters
  • oli_data (list or numpy.ndarray) – When static == True, a 1D numpy array containing outcome label indices (integers), concatenated for all sequences. Otherwise, a list of 1D numpy arrays, one array per gate sequence. In either case, this quantity is indexed by the values of circuit_indices or the index of circuits.

  • time_data (list or numpy.ndarray) – Same format at oli_data except stores floating-point timestamp values.

  • rep_data (list or numpy.ndarray) – Same format at oli_data except stores integer repetition counts for each “data bin” (i.e. (outcome,time) pair). If all repetitions equal 1 (“single-shot” timestampted data), then rep_data can be None (no repetitions).

  • circuits (list of (tuples or Circuits)) – Each element is a tuple of operation labels or a Circuit object. Indices for these strings are assumed to ascend from 0. These indices must correspond to the time series of spam-label indices (above). Only specify this argument OR circuit_indices, not both.

  • circuit_indices (ordered dictionary) – An OrderedDict with keys equal to circuits (tuples of operation labels) and values equal to integer indices associating a row/element of counts with the circuit. Only specify this argument OR circuits, not both.

  • outcome_labels (list of strings or int) – Specifies the set of spam labels for the DataSet. Indices for the spam labels are assumed to ascend from 0, starting with the first element of this list. These indices will associate each elememtn of timeseries with a spam label. Only specify this argument OR outcome_label_indices, not both. If an int, specifies that the outcome labels should be those for a standard set of this many qubits.

  • outcome_label_indices (ordered dictionary) – An OrderedDict with keys equal to spam labels (strings) and value equal to integer indices associating a spam label with given index. Only specify this argument OR outcome_labels, not both.

  • static (bool) –

    When True, create a read-only, i.e. “static” DataSet which cannot be modified. In

    this case you must specify the timeseries data, circuits, and spam labels.

    When False, create a DataSet that can have time series data added to it. In this case,

    you only need to specify the spam labels.

  • file_to_load_from (string or file object) – Specify this argument and no others to create a static DataSet by loading from a file (just like using the load(…) function).

  • collision_action ({"aggregate","overwrite","keepseparate"}) – Specifies how duplicate circuits should be handled. “aggregate” adds duplicate-circuit counts to the same circuit’s data at the next integer timestamp. “overwrite” only keeps the latest given data for a circuit. “keepseparate” tags duplicate-circuits by setting the .occurrence ID of added circuits that are already contained in this data set to the next available positive integer.

  • comment (string, optional) – A user-specified comment string that gets carried around with the data. A common use for this field is to attach to the data details regarding its collection.

  • aux_info (dict, optional) – A user-specified dictionary of per-circuit auxiliary information. Keys should be the circuits in this DataSet and value should be Python dictionaries.

__iter__(self)
__len__(self)
__contains__(self, circuit)

Test whether data set contains a given circuit.

Parameters

circuit (tuple or Circuit) – A tuple of operation labels or a Circuit instance which specifies the the circuit to check for.

Returns

bool – whether circuit was found.

__hash__(self)

Return hash(self).

__getitem__(self, circuit)
__setitem__(self, circuit, outcome_dict_or_series)
__delitem__(self, circuit)
_get_row(self, circuit)

Get a row of data from this DataSet.

Parameters

circuit (Circuit or tuple) – The gate sequence to extract data for.

Returns

_DataSetRow

_set_row(self, circuit, outcome_dict_or_series)

Set the counts for a row of this DataSet.

Parameters
  • circuit (Circuit or tuple) – The gate sequence to extract data for.

  • outcome_dict_or_series (dict or tuple) – The outcome count data, either a dictionary of outcome counts (with keys as outcome labels) or a tuple of lists. In the latter case this can be a 2-tuple: (outcome-label-list, timestamp-list) or a 3-tuple: (outcome-label-list, timestamp-list, repetition-count-list).

Returns

None

keys(self)

Returns the circuits used as keys of this DataSet.

Returns

list – A list of Circuit objects which index the data counts within this data set.

items(self)

Iterator over (circuit, timeSeries) pairs.

Here circuit is a tuple of operation labels and timeSeries is a _DataSetRow instance, which behaves similarly to a list of spam labels whose index corresponds to the time step.

Returns

_DataSetKVIterator

values(self)

Iterator over _DataSetRow instances corresponding to the time series data for each circuit.

Returns

_DataSetValueIterator

property outcome_labels(self)

Get a list of all the outcome labels contained in this DataSet.

Returns

list of strings or tuples – A list where each element is an outcome label (which can be a string or a tuple of strings).

property timestamps(self)

Get a list of all the (unique) timestamps contained in this DataSet.

Returns

list of floats – A list where each element is a timestamp.

gate_labels(self, prefix='G')

Get a list of all the distinct operation labels used in the circuits of this dataset.

Parameters

prefix (str) – Filter the circuit labels so that only elements beginning with this prefix are returned. None performs no filtering.

Returns

list of strings – A list where each element is a operation label.

degrees_of_freedom(self, circuits=None, method='present_outcomes-1', aggregate_times=True)

Returns the number of independent degrees of freedom in the data for the circuits in circuits.

Parameters
  • circuits (list of Circuits) – The list of circuits to count degrees of freedom for. If None then all of the DataSet’s strings are used.

  • method ({'all_outcomes-1', 'present_outcomes-1', 'tuned'}) – How the degrees of freedom should be computed. ‘all_outcomes-1’ takes the number of circuits and multiplies this by the total number of outcomes (the length of what is returned by outcome_labels()) minus one. ‘present_outcomes-1’ counts on a per-circuit basis the number of present (usually = non-zero) outcomes recorded minus one. ‘tuned’ should be the most accurate, as it accounts for low-N “Poisson bump” behavior, but it is not the default because it is still under development. For timestamped data, see aggreate_times below.

  • aggregate_times (bool, optional) – Whether counts that occur at different times should be tallied separately. If True, then even when counts occur at different times degrees of freedom are tallied on a per-circuit basis. If False, then counts occuring at distinct times are treated as independent of those an any other time, and are tallied separately. So, for example, if aggregate_times is False and a data row has 0- and 1-counts of 45 & 55 at time=0 and 42 and 58 at time=1 this row would contribute 2 degrees of freedom, not 1. It can sometimes be useful to set this to False when the DataSet holds coarse-grained data, but usually you want this to be left as True (especially for time-series data).

Returns

int

_collisionaction_update_circuit(self, circuit)
_add_explicit_repetition_counts(self)

Build internal repetition counts if they don’t exist already.

This method is usually unnecessary, as repetition counts are almost always build as soon as they are needed.

Returns

None

add_count_dict(self, circuit, count_dict, record_zero_counts=True, aux=None, update_ol=True)

Add a single circuit’s counts to this DataSet

Parameters
  • circuit (tuple or Circuit) – A tuple of operation labels specifying the circuit or a Circuit object

  • count_dict (dict) – A dictionary with keys = outcome labels and values = counts

  • record_zero_counts (bool, optional) – Whether zero-counts are actually recorded (stored) in this DataSet. If False, then zero counts are ignored, except for potentially registering new outcome labels.

  • aux (dict, optional) – A dictionary of auxiliary meta information to be included with this set of data counts (associated with circuit).

  • update_ol (bool, optional) – This argument is for internal use only and should be left as True.

Returns

None

add_count_list(self, circuit, outcome_labels, counts, record_zero_counts=True, aux=None, update_ol=True, unsafe=False)

Add a single circuit’s counts to this DataSet

Parameters
  • circuit (tuple or Circuit) – A tuple of operation labels specifying the circuit or a Circuit object

  • outcome_labels (list or tuple) – The outcome labels corresponding to counts.

  • counts (list or tuple) – The counts themselves.

  • record_zero_counts (bool, optional) – Whether zero-counts are actually recorded (stored) in this DataSet. If False, then zero counts are ignored, except for potentially registering new outcome labels.

  • aux (dict, optional) – A dictionary of auxiliary meta information to be included with this set of data counts (associated with circuit).

  • update_ol (bool, optional) – This argument is for internal use only and should be left as True.

  • unsafe (bool, optional) – True means that outcome_labels is guaranteed to hold tuple-type outcome labels and never plain strings. Only set this to True if you know what you’re doing.

Returns

None

add_count_arrays(self, circuit, outcome_index_array, count_array, record_zero_counts=True, aux=None)

Add the outcomes for a single circuit, formatted as raw data arrays.

Parameters
  • circuit (Circuit) – The circuit to add data for.

  • outcome_index_array (numpy.ndarray) – An array of outcome indices, which must be values of self.olIndex (which maps outcome labels to indices).

  • count_array (numpy.ndarray) – An array of integer (or sometimes floating point) counts, one corresponding to each outcome index (element of outcome_index_array).

  • record_zero_counts (bool, optional) – Whether zero counts (zeros in count_array should be stored explicitly or not stored and inferred. Setting to False reduces the space taken by data sets containing lots of zero counts, but makes some objective function evaluations less precise.

  • aux (dict or None, optional) – If not None a dictionary of user-defined auxiliary information that should be associated with this circuit.

Returns

None

add_cirq_trial_result(self, circuit, trial_result, key)

Add a single circuit’s counts — stored in a Cirq TrialResult — to this DataSet

Parameters
  • circuit (tuple or Circuit) – A tuple of operation labels specifying the circuit or a Circuit object. Note that this must be a PyGSTi circuit — not a Cirq circuit.

  • trial_result (cirq.TrialResult) – The TrialResult to add

  • key (str) – The string key of the measurement. Set by cirq.measure.

Returns

None

add_raw_series_data(self, circuit, outcome_label_list, time_stamp_list, rep_count_list=None, overwrite_existing=True, record_zero_counts=True, aux=None, update_ol=True, unsafe=False)

Add a single circuit’s counts to this DataSet

Parameters
  • circuit (tuple or Circuit) – A tuple of operation labels specifying the circuit or a Circuit object

  • outcome_label_list (list) – A list of outcome labels (strings or tuples). An element’s index links it to a particular time step (i.e. the i-th element of the list specifies the outcome of the i-th measurement in the series).

  • time_stamp_list (list) – A list of floating point timestamps, each associated with the single corresponding outcome in outcome_label_list. Must be the same length as outcome_label_list.

  • rep_count_list (list, optional) – A list of integer counts specifying how many outcomes of type given by outcome_label_list occurred at the time given by time_stamp_list. If None, then all counts are assumed to be 1. When not None, must be the same length as outcome_label_list.

  • overwrite_existing (bool, optional) – Whether to overwrite the data for circuit (if it exists). If False, then the given lists are appended (added) to existing data.

  • record_zero_counts (bool, optional) – Whether zero-counts (elements of rep_count_list that are zero) are actually recorded (stored) in this DataSet. If False, then zero counts are ignored, except for potentially registering new outcome labels.

  • aux (dict, optional) – A dictionary of auxiliary meta information to be included with this set of data counts (associated with circuit).

  • update_ol (bool, optional) – This argument is for internal use only and should be left as True.

  • unsafe (bool, optional) – When True, don’t bother checking that outcome_label_list contains tuple-type outcome labels and automatically upgrading strings to 1-tuples. Only set this to True if you know what you’re doing and need the marginally faster performance.

Returns

None

_add_raw_arrays(self, circuit, oli_array, time_array, rep_array, overwrite_existing, record_zero_counts, aux)
update_ol(self)

Updates the internal outcome-label list in this dataset.

Call this after calling add_count_dict(…) or add_raw_series_data(…) with update_olIndex=False.

Returns

None

add_series_data(self, circuit, count_dict_list, time_stamp_list, overwrite_existing=True, record_zero_counts=True, aux=None)

Add a single circuit’s counts to this DataSet

Parameters
  • circuit (tuple or Circuit) – A tuple of operation labels specifying the circuit or a Circuit object

  • count_dict_list (list) – A list of dictionaries holding the outcome-label:count pairs for each time step (times given by time_stamp_list.

  • time_stamp_list (list) – A list of floating point timestamps, each associated with an entire dictionary of outcomes specified by count_dict_list.

  • overwrite_existing (bool, optional) – If True, overwrite any existing data for the circuit. If False, add the count data with the next non-negative integer timestamp.

  • record_zero_counts (bool, optional) – Whether zero-counts (elements of the dictionaries in count_dict_list that are zero) are actually recorded (stored) in this DataSet. If False, then zero counts are ignored, except for potentially registering new outcome labels.

  • aux (dict, optional) – A dictionary of auxiliary meta information to be included with this set of data counts (associated with circuit).

Returns

None

aggregate_outcomes(self, label_merge_dict, record_zero_counts=True)

Creates a DataSet which merges certain outcomes in this DataSet.

Used, for example, to aggregate a 2-qubit 4-outcome DataSet into a 1-qubit 2-outcome DataSet.

Parameters
  • label_merge_dict (dictionary) – The dictionary whose keys define the new DataSet outcomes, and whose items are lists of input DataSet outcomes that are to be summed together. For example, if a two-qubit DataSet has outcome labels “00”, “01”, “10”, and “11”, and we want to ‘’aggregate out’’ the second qubit, we could use label_merge_dict = {‘0’:[‘00’,’01’],’1’:[‘10’,’11’]}. When doing this, however, it may be better to use :function:`filter_qubits` which also updates the circuits.

  • record_zero_counts (bool, optional) – Whether zero-counts are actually recorded (stored) in the returned (merged) DataSet. If False, then zero counts are ignored, except for potentially registering new outcome labels.

Returns

merged_dataset (DataSet object) – The DataSet with outcomes merged according to the rules given in label_merge_dict.

aggregate_std_nqubit_outcomes(self, qubit_indices_to_keep, record_zero_counts=True)

Creates a DataSet which merges certain outcomes in this DataSet.

Used, for example, to aggregate a 2-qubit 4-outcome DataSet into a 1-qubit 2-outcome DataSet. This assumes that outcome labels are in the standard format whereby each qubit corresponds to a single ‘0’ or ‘1’ character.

Parameters
  • qubit_indices_to_keep (list) – A list of integers specifying which qubits should be kept, that is, not aggregated.

  • record_zero_counts (bool, optional) – Whether zero-counts are actually recorded (stored) in the returned (merged) DataSet. If False, then zero counts are ignored, except for potentially registering new outcome labels.

Returns

merged_dataset (DataSet object) – The DataSet with outcomes merged.

add_auxiliary_info(self, circuit, aux)

Add auxiliary meta information to circuit.

Parameters
  • circuit (tuple or Circuit) – A tuple of operation labels specifying the circuit or a Circuit object

  • aux (dict, optional) – A dictionary of auxiliary meta information to be included with this set of data counts (associated with circuit).

Returns

None

add_counts_from_dataset(self, other_data_set)

Append another DataSet’s data to this DataSet

Parameters

other_data_set (DataSet) – The dataset to take counts from.

Returns

None

add_series_from_dataset(self, other_data_set)

Append another DataSet’s series data to this DataSet

Parameters

other_data_set (DataSet) – The dataset to take time series data from.

Returns

None

property meantimestep(self)

The mean time-step, averaged over the time-step for each circuit and over circuits.

Returns

float

property has_constant_totalcounts_pertime(self)

True if the data for every circuit has the same number of total counts at every data collection time.

This will return True if there is a different number of total counts per circuit (i.e., after aggregating over time), as long as every circuit has the same total counts per time step (this will happen when the number of time-steps varies between circuit).

Returns

bool

property totalcounts_pertime(self)

Total counts per time, if this is constant over times and circuits.

When that doesn’t hold, an error is raised.

Returns

float or int

property has_constant_totalcounts(self)

True if the data for every circuit has the same number of total counts.

Returns

bool

property has_trivial_timedependence(self)

True if all the data in this DataSet occurs at time 0.

Returns

bool

__str__(self)

Return str(self).

to_str(self, mode='auto')

Render this DataSet as a string.

Parameters

mode ({"auto","time-dependent","time-independent"}) – Whether to display the data as time-series of outcome counts (“time-dependent”) or to report per-outcome counts aggregated over time (“time-independent”). If “auto” is specified, then the time-independent mode is used only if all time stamps in the DataSet are equal to zero (trivial time dependence).

Returns

str

truncate(self, list_of_circuits_to_keep, missing_action='raise')

Create a truncated dataset comprised of a subset of the circuits in this dataset.

Parameters
  • list_of_circuits_to_keep (list of (tuples or Circuits)) – A list of the circuits for the new returned dataset. If a circuit is given in this list that isn’t in the original data set, missing_action determines the behavior.

  • missing_action ({"raise","warn","ignore"}) – What to do when a string in list_of_circuits_to_keep is not in the data set (raise a KeyError, issue a warning, or do nothing).

Returns

DataSet – The truncated data set.

time_slice(self, start_time, end_time, aggregate_to_time=None)

Creates a DataSet by aggregating the counts within the [start_time,`end_time`) interval.

Parameters
  • start_time (float) – The starting time.

  • end_time (float) – The ending time.

  • aggregate_to_time (float, optional) – If not None, a single timestamp to give all the data in the specified range, resulting in time-independent DataSet. If None, then the original timestamps are preserved.

Returns

DataSet

split_by_time(self, aggregate_to_time=None)

Creates a dictionary of DataSets, each of which is a equal-time slice of this DataSet.

The keys of the returned dictionary are the distinct timestamps in this dataset.

Parameters

aggregate_to_time (float, optional) – If not None, a single timestamp to give all the data in each returned data set, resulting in time-independent `DataSet`s. If None, then the original timestamps are preserved.

Returns

OrderedDict – A dictionary of DataSet objects whose keys are the timestamp values of the original (this) data set in sorted order.

drop_zero_counts(self)

Creates a copy of this data set that doesn’t include any zero counts.

Returns

DataSet

process_times(self, process_times_array_fn)

Manipulate this DataSet’s timestamps according to processor_fn.

For example, using, the folloing process_times_array_fn would change the timestamps for each circuit to sequential integers.

``` def process_times_array_fn(times):

return list(range(len(times)))

```

Parameters

process_times_array_fn (function) – A function which takes a single array-of-timestamps argument and returns another similarly-sized array. This function is called, once per circuit, with the circuit’s array of timestamps.

Returns

DataSet – A new data set with altered timestamps.

process_circuits(self, processor_fn, aggregate=False)

Create a new data set by manipulating this DataSet’s circuits (keys) according to processor_fn.

The new DataSet’s circuits result from by running each of this DataSet’s circuits through processor_fn. This can be useful when “tracing out” qubits in a dataset containing multi-qubit data.

Parameters
  • processor_fn (function) – A function which takes a single Circuit argument and returns another (or the same) Circuit. This function may also return None, in which case the data for that string is deleted.

  • aggregate (bool, optional) – When True, aggregate the data for ciruits that processor_fn assigns to the same “new” circuit. When False, use the data from the last original circuit that maps to a given “new” circuit.

Returns

DataSet

process_circuits_inplace(self, processor_fn, aggregate=False)

Manipulate this DataSet’s circuits (keys) in-place according to processor_fn.

All of this DataSet’s circuits are updated by running each one through processor_fn. This can be useful when “tracing out” qubits in a dataset containing multi-qubit data.

Parameters
  • processor_fn (function) – A function which takes a single Circuit argument and returns another (or the same) Circuit. This function may also return None, in which case the data for that string is deleted.

  • aggregate (bool, optional) – When True, aggregate the data for ciruits that processor_fn assigns to the same “new” circuit. When False, use the data from the last original circuit that maps to a given “new” circuit.

Returns

None

remove(self, circuits, missing_action='raise')

Remove (delete) the data for circuits from this DataSet.

Parameters
  • circuits (iterable) – An iterable over Circuit-like objects specifying the keys (circuits) to remove.

  • missing_action ({"raise","warn","ignore"}) – What to do when a string in circuits is not in this data set (raise a KeyError, issue a warning, or do nothing).

Returns

None

_remove(self, gstr_indices)

Removes the data in indices given by gstr_indices

copy(self)

Make a copy of this DataSet.

Returns

DataSet

copy_nonstatic(self)

Make a non-static copy of this DataSet.

Returns

DataSet

done_adding_data(self)

Promotes a non-static DataSet to a static (read-only) DataSet.

This method should be called after all data has been added.

Returns

None

__getstate__(self)
__setstate__(self, state_dict)
save(self, file_or_filename)
write_binary(self, file_or_filename)

Write this data set to a binary-format file.

Parameters

file_or_filename (string or file object) – If a string, interpreted as a filename. If this filename ends in “.gz”, the file will be gzip compressed.

Returns

None

load(self, file_or_filename)
read_binary(self, file_or_filename)

Read a DataSet from a binary file, clearing any data is contained previously.

The file should have been created with :method:`DataSet.write_binary`

Parameters

file_or_filename (str or buffer) – The file or filename to load from.

Returns

None

rename_outcome_labels(self, old_to_new_dict)

Replaces existing output labels with new ones as per old_to_new_dict.

Parameters

old_to_new_dict (dict) – A mapping from old/existing outcome labels to new ones. Strings in keys or values are automatically converted to 1-tuples. Missing outcome labels are left unaltered.

Returns

None

add_std_nqubit_outcome_labels(self, nqubits)

Adds all the “standard” outcome labels (e.g. ‘0010’) on nqubits qubits.

This is useful to ensure that, even if not all outcomes appear in the data, that all are recognized as being potentially valid outcomes (and so attempts to get counts for these outcomes will be 0 rather than raising an error).

Parameters

nqubits (int) – The number of qubits. For example, if equal to 3 the outcome labels ‘000’, ‘001’, … ‘111’ are added.

Returns

None

add_outcome_labels(self, outcome_labels, update_ol=True)

Adds new valid outcome labels.

Ensures that all the elements of outcome_labels are stored as valid outcomes for circuits in this DataSet, adding new outcomes as necessary.

Parameters
  • outcome_labels (list or generator) – A list or generator of string- or tuple-valued outcome labels.

  • update_ol (bool, optional) – Whether to update internal mappings to reflect the new outcome labels. Leave this as True unless you really know what you’re doing.

Returns

None

auxinfo_dataframe(self, pivot_valuename=None, pivot_value=None, drop_columns=False)

Create a Pandas dataframe with aux-data from this dataset.

Parameters
  • pivot_valuename (str, optional) – If not None, the resulting dataframe is pivoted using pivot_valuename as the column whose values name the pivoted table’s column names. If None and pivot_value is not None,`”ValueName”` is used.

  • pivot_value (str, optional) – If not None, the resulting dataframe is pivoted such that values of the pivot_value column are rearranged into new columns whose names are given by the values of the pivot_valuename column. If None and pivot_valuename is not None,`”Value”` is used.

  • drop_columns (bool or list, optional) – A list of column names to drop (prior to performing any pivot). If True appears in this list or is given directly, then all constant-valued columns are dropped as well. No columns are dropped when drop_columns == False.

Returns

pandas.DataFrame

pygsti.drivers.create_bootstrap_dataset(input_data_set, generation_method, input_model=None, seed=None, outcome_labels=None, verbosity=1)

Creates a DataSet used for generating bootstrapped error bars.

Parameters
  • input_data_set (DataSet) – The data set to use for generating the “bootstrapped” data set.

  • generation_method ({ 'nonparametric', 'parametric' }) – The type of dataset to generate. ‘parametric’ generates a DataSet with the same circuits and sample counts as input_data_set but using the probabilities in input_model (which must be provided). ‘nonparametric’ generates a DataSet with the same circuits and sample counts as input_data_set using the count frequencies of input_data_set as probabilities.

  • input_model (Model, optional) – The model used to compute the probabilities for circuits when generation_method is set to ‘parametric’. If ‘nonparametric’ is selected, this argument must be set to None (the default).

  • seed (int, optional) – A seed value for numpy’s random number generator.

  • outcome_labels (list, optional) – The list of outcome labels to include in the output dataset. If None are specified, defaults to the spam labels of input_data_set.

  • verbosity (int, optional) – How verbose the function output is. If 0, then printing is suppressed. If 1 (or greater), then printing is not suppressed.

Returns

DataSet

pygsti.drivers.create_bootstrap_models(num_models, input_data_set, generation_method, fiducial_prep, fiducial_measure, germs, max_lengths, input_model=None, target_model=None, start_seed=0, outcome_labels=None, lsgst_lists=None, return_data=False, verbosity=2)

Creates a series of “bootstrapped” Models.

Models are created from a single DataSet (and possibly Model) and are typically used for generating bootstrapped error bars. The resulting Models are obtained by performing MLGST on data generated by repeatedly calling :function:`create_bootstrap_dataset` with consecutive integer seed values.

Parameters
  • num_models (int) – The number of models to create.

  • input_data_set (DataSet) – The data set to use for generating the “bootstrapped” data set.

  • generation_method ({ 'nonparametric', 'parametric' }) – The type of data to generate. ‘parametric’ generates DataSets with the same circuits and sample counts as input_data_set but using the probabilities in input_model (which must be provided). ‘nonparametric’ generates DataSets with the same circuits and sample counts as input_data_set using the count frequencies of input_data_set as probabilities.

  • fiducial_prep (list of Circuits) – The state preparation fiducial circuits used by MLGST.

  • fiducial_measure (list of Circuits) – The measurement fiducial circuits used by MLGST.

  • germs (list of Circuits) – The germ circuits used by MLGST.

  • max_lengths (list of ints) – List of integers, one per MLGST 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.

  • input_model (Model, optional) – The model used to compute the probabilities for circuits when generation_method is set to ‘parametric’. If ‘nonparametric’ is selected, this argument must be set to None (the default).

  • target_model (Model, optional) – Mandatory model to use for as the target model for MLGST when generation_method is set to ‘nonparametric’. When ‘parametric’ is selected, input_model is used as the target.

  • start_seed (int, optional) – The initial seed value for numpy’s random number generator when generating data sets. For each succesive dataset (and model) that are generated, the seed is incremented by one.

  • outcome_labels (list, optional) – The list of Outcome labels to include in the output dataset. If None are specified, defaults to the effect labels of input_data_set.

  • lsgst_lists (list of circuit lists, optional) – Provides explicit list of circuit lists to be used in analysis; to be given if the dataset uses “incomplete” or “reduced” sets of circuit. Default is None.

  • return_data (bool) – Whether generated data sets should be returned in addition to models.

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

Returns

  • models (list) – The list of generated Model objects.

  • data (list) – The list of generated DataSet objects, only returned when return_data == True.

pygsti.drivers.gauge_optimize_models(gs_list, target_model, gate_metric='frobenius', spam_metric='frobenius', plot=True)

Optimizes the “spam weight” parameter used when gauge optimizing a set of models.

This function gauge optimizes multiple times using a range of spam weights and takes the one the minimizes the average spam error multiplied by the average gate error (with respect to a target model).

Parameters
  • gs_list (list) – The list of Model objects to gauge optimize (simultaneously).

  • target_model (Model) – The model to compare the gauge-optimized gates with, and also to gauge-optimize them to.

  • gate_metric ({ "frobenius", "fidelity", "tracedist" }, optional) – The metric used within the gauge optimization to determing error in the gates.

  • spam_metric ({ "frobenius", "fidelity", "tracedist" }, optional) – The metric used within the gauge optimization to determing error in the state preparation and measurement.

  • plot (bool, optional) – Whether to create a plot of the model-target discrepancy as a function of spam weight (figure displayed interactively).

Returns

list – The list of Models gauge-optimized using the best spamWeight.

pygsti.drivers._model_stdev(gs_func, gs_ensemble, ddof=1, axis=None, **kwargs)

Standard deviation of gs_func over an ensemble of models.

Parameters
  • gs_func (function) – A function that takes a Model as its first argument, and whose additional arguments may be given by keyword arguments.

  • gs_ensemble (list) – A list of Model objects.

  • ddof (int, optional) – As in numpy.std

  • axis (int or None, optional) – As in numpy.std

Returns

numpy.ndarray – The output of numpy.std

pygsti.drivers._model_mean(gs_func, gs_ensemble, axis=None, **kwargs)

Mean of gs_func over an ensemble of models.

Parameters
  • gs_func (function) – A function that takes a Model as its first argument, and whose additional arguments may be given by keyword arguments.

  • gs_ensemble (list) – A list of Model objects.

  • axis (int or None, optional) – As in numpy.mean

Returns

numpy.ndarray – The output of numpy.mean

pygsti.drivers._to_mean_model(gs_list, target_gs)

Take the per-gate-element mean of a set of models.

Return the Model constructed from the mean parameter vector of the models in gs_list, that is, the mean of the parameter vectors of each model in gs_list.

Parameters
  • gs_list (list) – A list of Model objects.

  • target_gs (Model) – A template model used to specify the parameterization of the returned Model.

Returns

Model

pygsti.drivers._to_std_model(gs_list, target_gs, ddof=1)

Take the per-gate-element standard deviation of a list of models.

Return the Model constructed from the standard-deviation parameter vector of the models in gs_list, that is, the standard- devaiation of the parameter vectors of each model in gs_list.

Parameters
  • gs_list (list) – A list of Model objects.

  • target_gs (Model) – A template model used to specify the parameterization of the returned Model.

  • ddof (int, optional) – As in numpy.std

Returns

Model

pygsti.drivers._to_rms_model(gs_list, target_gs)

Take the per-gate-element RMS of a set of models.

Return the Model constructed from the root-mean-squared parameter vector of the models in gs_list, that is, the RMS of the parameter vectors of each model in gs_list.

Parameters
  • gs_list (list) – A list of Model objects.

  • target_gs (Model) – A template model used to specify the parameterization of the returned Model.

Returns

Model

class pygsti.drivers._GSTAdvancedOptions(items=None)

Bases: AdvancedOptions

Advanced options for GST driver functions.

valid_keys

the valid (allowed) keys.

Type

tuple

valid_keys = ['always_perform_mle', 'bad_fit_threshold', 'circuit_weights', 'contract_start_to_cptp',...
class pygsti.drivers._QubitProcessorSpec(num_qubits, gate_names, nonstd_gate_unitaries=None, availability=None, geometry=None, qubit_labels=None, nonstd_gate_symplecticreps=None, aux_info=None)

Bases: ProcessorSpec

The device specification for a one or more qubit quantum computer.

This is objected is geared towards multi-qubit devices; many of the contained structures are superfluous in the case of a single qubit.

Parameters
  • num_qubits (int) – The number of qubits in the device.

  • gate_names (list of strings) –

    The names of gates in the device. This may include standard gate names known by pyGSTi (see below) or names which appear in the nonstd_gate_unitaries argument. The set of standard gate names includes, but is not limited to:

    • ’Gi’ : the 1Q idle operation

    • ’Gx’,’Gy’,’Gz’ : 1-qubit pi/2 rotations

    • ’Gxpi’,’Gypi’,’Gzpi’ : 1-qubit pi rotations

    • ’Gh’ : Hadamard

    • ’Gp’ : phase or S-gate (i.e., ((1,0),(0,i)))

    • ’Gcphase’,’Gcnot’,’Gswap’ : standard 2-qubit gates

    Alternative names can be used for all or any of these gates, but then they must be explicitly defined in the nonstd_gate_unitaries dictionary. Including any standard names in nonstd_gate_unitaries overrides the default (builtin) unitary with the one supplied.

  • nonstd_gate_unitaries (dictionary of numpy arrays) – A dictionary with keys that are gate names (strings) and values that are numpy arrays specifying quantum gates in terms of unitary matrices. This is an additional “lookup” database of unitaries - to add a gate to this QubitProcessorSpec its names still needs to appear in the gate_names list. This dictionary’s values specify additional (target) native gates that can be implemented in the device as unitaries acting on ordinary pure-state-vectors, in the standard computationl basis. These unitaries need not, and often should not, be unitaries acting on all of the qubits. E.g., a CNOT gate is specified by a key that is the desired name for CNOT, and a value that is the standard 4 x 4 complex matrix for CNOT. All gate names must start with ‘G’. As an advanced behavior, a unitary-matrix-returning function which takes a single argument - a tuple of label arguments - may be given instead of a single matrix to create an operation factory which allows continuously-parameterized gates. This function must also return an empty/dummy unitary when None is given as it’s argument.

  • availability (dict, optional) – A dictionary whose keys are some subset of the keys (which are gate names) nonstd_gate_unitaries and the strings (which are gate names) in gate_names and whose values are lists of qubit-label-tuples. Each qubit-label-tuple must have length equal to the number of qubits the corresponding gate acts upon, and causes that gate to be available to act on the specified qubits. Instead of a list of tuples, values of availability may take the special values “all-permutations” and “all-combinations”, which as their names imply, equate to all possible permutations and combinations of the appropriate number of qubit labels (deterined by the gate’s dimension). If a gate name is not present in availability, the default is “all-permutations”. So, the availability of a gate only needs to be specified when it cannot act in every valid way on the qubits (e.g., the device does not have all-to-all connectivity).

  • geometry ({"line","ring","grid","torus"} or QubitGraph, optional) – The type of connectivity among the qubits, specifying a graph used to define neighbor relationships. Alternatively, a QubitGraph object with qubit_labels as the node labels may be passed directly. This argument is only used as a convenient way of specifying gate availability (edge connections are used for gates whose availability is unspecified by availability or whose value there is “all-edges”).

  • qubit_labels (list or tuple, optional) – The labels (integers or strings) of the qubits. If None, then the integers starting with zero are used.

  • nonstd_gate_symplecticreps (dict, optional) – A dictionary similar to nonstd_gate_unitaries that supplies, instead of a unitary matrix, the symplectic representation of a Clifford operations, given as a 2-tuple of numpy arrays.

  • aux_info (dict, optional) – Any additional information that should be attached to this processor spec.

_to_nice_serialization(self)
classmethod _from_nice_serialization(cls, state)
property num_qubits(self)

The number of qubits.

property primitive_op_labels(self)

All the primitive operation labels derived from the gate names and availabilities

gate_num_qubits(self, gate_name)

The number of qubits that a given gate acts upon.

Parameters

gate_name (str) – The name of the gate.

Returns

int

resolved_availability(self, gate_name, tuple_or_function='auto')

The availability of a given gate, resolved as either a tuple of sslbl-tuples or a function.

This function does more than just access the availability attribute, as this may hold special values like “all-edges”. It takes the value of self.availability[gate_name] and resolves and converts it into the desired format: either a tuple of state-space labels or a function with a single state-space-labels-tuple argument.

Parameters
  • gate_name (str) – The gate name to get the availability of.

  • tuple_or_function ({'tuple', 'function', 'auto'}) – The type of object to return. ‘tuple’ means a tuple of state space label tuples, e.g. ((0,1), (1,2)). ‘function’ means a function that takes a single state space label tuple argument and returns True or False to indicate whether the gate is available on the given target labels. If ‘auto’ is given, then either a tuple or function is returned - whichever is more computationally convenient.

Returns

tuple or function

_resolve_availability(self, avail_entry, gate_nqubits, tuple_or_function='auto')
is_available(self, gate_label)

Check whether a gate at a given location is available.

Parameters

gate_label (Label) – The gate name and target labels to check availability of.

Returns

bool

available_gatenames(self, sslbls)

List all the gate names that are available within a set of state space labels.

This function finds all the gate names that are available for at least a subset of sslbls.

Parameters

sslbls (tuple) – The state space labels to find availability within.

Returns

tuple of strings – A tuple of gate names (strings).

available_gatelabels(self, gate_name, sslbls)

List all the gate labels that are available for gate_name on at least a subset of sslbls.

Parameters
  • gate_name (str) – The gate name.

  • sslbls (tuple) – The state space labels to find availability within.

Returns

tuple of Labels – The available gate labels (all with name gate_name).

force_recompute_gate_relationships(self)

Invalidates LRU caches for all compute_* methods of this object, forcing them to recompute their values.

The compute_* methods of this processor spec compute various relationships and properties of its gates. These routines can be computationally intensive, and so their values are cached for performance. If the gates of a processor spec changes and its compute_* methods are used, force_recompute_gate_relationships should be called.

compute_clifford_symplectic_reps(self, gatename_filter=None)

Constructs a dictionary of the symplectic representations for all the Clifford gates in this processor spec.

Parameters

gatename_filter (iterable, optional) – A list, tuple, or set of gate names whose symplectic representations should be returned (if they exist).

Returns

dict – keys are gate names, values are (symplectic_matrix, phase_vector) tuples.

compute_one_qubit_gate_relations(self)

Computes the basic pair-wise relationships relationships between the gates.

1. It multiplies all possible combinations of two 1-qubit gates together, from the full model available to in this device. If the two gates multiple to another 1-qubit gate from this set of gates this is recorded in the dictionary self.oneQgate_relations. If the 1-qubit gate with name name1 followed by the 1-qubit gate with name name2 multiple (up to phase) to the gate with name3, then self.oneQgate_relations[name1,`name2`] = name3.

2. If the inverse of any 1-qubit gate is contained in the model, this is recorded in the dictionary self.gate_inverse.

Returns

  • gate_relations (dict) – Keys are (gatename1, gatename2) and values are either the gate name of the product of the two gates or None, signifying the identity.

  • gate_inverses (dict) – Keys and values are gate names, mapping a gate name to its inverse gate (if one exists).

compute_multiqubit_inversion_relations(self)

Computes the inverses of multi-qubit (>1 qubit) gates.

Finds whether any of the multi-qubit gates in this device also have their inverse in the model. That is, if the unitaries for the multi-qubit gate with name name1 followed by the multi-qubit gate (of the same dimension) with name name2 multiple (up to phase) to the identity, then gate_inverse[name1] = name2 and gate_inverse[name2] = name1

1-qubit gates are not computed by this method, as they are be computed by the method :method:`compute_one_qubit_gate_relations`.

Returns

gate_inverse (dict) – Keys and values are gate names, mapping a gate name to its inverse gate (if one exists).

compute_clifford_ops_on_qubits(self)

Constructs a dictionary mapping tuples of state space labels to the clifford operations available on them.

Returns

dict – A dictionary with keys that are state space label tuples and values that are lists of gate labels, giving the available Clifford gates on those target labels.

compute_ops_on_qubits(self)

Constructs a dictionary mapping tuples of state space labels to the operations available on them.

Returns

dict – A dictionary with keys that are state space label tuples and values that are lists of gate labels, giving the available gates on those target labels.

compute_clifford_2Q_connectivity(self)

Constructs a graph encoding the connectivity between qubits via 2-qubit Clifford gates.

Returns

QubitGraph – A graph with nodes equal to the qubit labels and edges present whenever there is a 2-qubit Clifford gate between the vertex qubits.

compute_2Q_connectivity(self)

Constructs a graph encoding the connectivity between qubits via 2-qubit gates.

Returns

QubitGraph – A graph with nodes equal to the qubit labels and edges present whenever there is a 2-qubit gate between the vertex qubits.

subset(self, gate_names_to_include='all', qubit_labels_to_keep='all')

Construct a smaller processor specification by keeping only a select set of gates from this processor spec.

Parameters

gate_names_to_include (list or tuple or set) – The gate names that should be included in the returned processor spec.

Returns

QubitProcessorSpec

map_qubit_labels(self, mapper)

Creates a new QubitProcessorSpec whose qubit labels are updated according to the mapping function mapper.

Parameters

mapper (dict or function) – A dictionary whose keys are the existing self.qubit_labels values and whose value are the new labels, or a function which takes a single (existing qubit-label) argument and returns a new qubit label.

Returns

QubitProcessorSpec

property idle_gate_names(self)

The gate names that correspond to idle operations.

property global_idle_gate_name(self)

The (first) gate name that corresponds to a global idle operation.

property global_idle_layer_label(self)

Similar to global_idle_gate_name but include the appropriate sslbls (either None or all the qubits)

class pygsti.drivers._Model(state_space)

Bases: pygsti.baseobjs.nicelyserializable.NicelySerializable

A predictive model for a Quantum Information Processor (QIP).

The main function of a Model object is to compute the outcome probabilities of Circuit objects based on the action of the model’s ideal operations plus (potentially) noise which makes the outcome probabilities deviate from the perfect ones.

Parameters

state_space (StateSpace) – The state space of this model.

_to_nice_serialization(self)
property state_space(self)

State space labels

Returns

StateSpaceLabels

property hyperparams(self)

Dictionary of hyperparameters associated with this model

Returns

dict

property num_params(self)

The number of free parameters when vectorizing this model.

Returns

int – the number of model parameters.

property num_modeltest_params(self)

The parameter count to use when testing this model against data.

Often times, this is the same as :method:`num_params`, but there are times when it can convenient or necessary to use a parameter count different than the actual number of parameters in this model.

Returns

int – the number of model parameters.

property parameter_bounds(self)

Upper and lower bounds on the values of each parameter, utilized by optimization routines

set_parameter_bounds(self, index, lower_bound=- _np.inf, upper_bound=_np.inf)

Set the bounds for a single model parameter.

These limit the values the parameter can have during an optimization of the model.

Parameters
  • index (int) – The index of the paramter whose bounds should be set.

  • lower_bound (float, optional) – The lower and upper bounds for the parameter. Can be set to the special numpy.inf (or -numpy.inf) values to effectively have no bound.

  • upper_bound (float, optional) – The lower and upper bounds for the parameter. Can be set to the special numpy.inf (or -numpy.inf) values to effectively have no bound.

Returns

None

property parameter_labels(self)

A list of labels, usually of the form (op_label, string_description) describing this model’s parameters.

property parameter_labels_pretty(self)

The list of parameter labels but formatted in a nice way.

In particular, tuples where the first element is an op label are made into a single string beginning with the string representation of the operation.

set_parameter_label(self, index, label)

Set the label of a single model parameter.

Parameters
  • index (int) – The index of the paramter whose label should be set.

  • label (object) – An object that serves to label this parameter. Often a string.

Returns

None

to_vector(self)

Returns the model vectorized according to the optional parameters.

Returns

numpy array – The vectorized model parameters.

from_vector(self, v, close=False)

Sets this Model’s operations based on parameter values v.

Parameters
  • v (numpy.ndarray) – A vector of parameters, with length equal to self.num_params.

  • close (bool, optional) – Set to True if v is close to the current parameter vector. This can make some operations more efficient.

Returns

None

abstract probabilities(self, circuit, clip_to=None)

Construct a dictionary containing the outcome probabilities of circuit.

Parameters
  • circuit (Circuit or tuple of operation labels) – The sequence of operation labels specifying the circuit.

  • clip_to (2-tuple, optional) – (min,max) to clip probabilities to if not None.

Returns

probs (dictionary) – A dictionary such that probs[SL] = pr(SL,circuit,clip_to) for each spam label (string) SL.

abstract bulk_probabilities(self, circuits, clip_to=None, comm=None, mem_limit=None, smartc=None)

Construct a dictionary containing the probabilities for an entire list of circuits.

Parameters
  • circuits ((list of Circuits) or CircuitOutcomeProbabilityArrayLayout) – When a list, each element specifies a circuit to compute outcome probabilities for. A CircuitOutcomeProbabilityArrayLayout specifies the circuits along with an internal memory layout that reduces the time required by this function and can restrict the computed probabilities to those corresponding to only certain outcomes.

  • clip_to (2-tuple, optional) – (min,max) to clip return value if not None.

  • comm (mpi4py.MPI.Comm, optional) – When not None, an MPI communicator for distributing the computation across multiple processors. Distribution is performed over subtrees of evalTree (if it is split).

  • mem_limit (int, optional) – A rough memory limit in bytes which is used to determine processor allocation.

  • smartc (SmartCache, optional) – A cache object to cache & use previously cached values inside this function.

Returns

probs (dictionary) – A dictionary such that probs[opstr] is an ordered dictionary of (outcome, p) tuples, where outcome is a tuple of labels and p is the corresponding probability.

_init_copy(self, copy_into, memo)

Copies any “tricky” member of this model into copy_into, before deep copying everything else within a .copy() operation.

_post_copy(self, copy_into, memo)

Called after all other copying is done, to perform “linking” between the new model (copy_into) and its members.

copy(self)

Copy this model.

Returns

Model – a (deep) copy of this model.

__str__(self)

Return str(self).

__hash__(self)

Return hash(self).

circuit_outcomes(self, circuit)

Get all the possible outcome labels produced by simulating this circuit.

Parameters

circuit (Circuit) – Circuit to get outcomes of.

Returns

tuple

compute_num_outcomes(self, circuit)

The number of outcomes of circuit, given by it’s existing or implied POVM label.

Parameters

circuit (Circuit) – The circuit to simplify

Returns

int

complete_circuit(self, circuit)

Adds any implied preparation or measurement layers to circuit

Parameters

circuit (Circuit) – Circuit to act on.

Returns

Circuit – Possibly the same object as circuit, if no additions are needed.

pygsti.drivers._create_explicit_model(processor_spec, modelnoise, custom_gates=None, evotype='default', simulator='auto', ideal_gate_type='auto', ideal_prep_type='auto', ideal_povm_type='auto', embed_gates=False, basis='pp')
pygsti.drivers.ROBUST_SUFFIX_LIST = ['.robust', '.Robust', '.robust+', '.Robust+']
pygsti.drivers.DEFAULT_BAD_FIT_THRESHOLD = 2.0
pygsti.drivers.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.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.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.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.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._load_model(model_filename_or_object)
pygsti.drivers._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._update_objfn_builders(builders, advanced_options)
pygsti.drivers._get_badfit_options(advanced_options)
pygsti.drivers._output_to_pickle(obj, output_pkl, comm)
pygsti.drivers._get_gst_initial_model(target_model, advanced_options)
pygsti.drivers._get_gst_builders(advanced_options)
pygsti.drivers._get_optimizer(advanced_options, model_being_optimized)