pygsti.data.multidataset

Defines the MultiDataSet class and supporting classes and functions

Module Contents

Classes

MultiDataSet

A collection of DataSets that hold data for the same circuits.

class pygsti.data.multidataset.MultiDataSet(oli_dict=None, time_dict=None, rep_dict=None, circuit_indices=None, outcome_labels=None, outcome_label_indices=None, file_to_load_from=None, collision_actions=None, comment=None, comments=None, aux_info=None)

Bases: object

A collection of DataSets that hold data for the same circuits.

The MultiDataSet class allows for the combined access and storage of several static DataSets that contain the same circuits (in the same order) AND the same time-dependence structure (if applicable).

It is designed to behave similarly to a dictionary of DataSets, so that a DataSet is obtained by:

dataset = multiDataset[dataset_name]

where dataset_name may be a string OR a tuple.

Parameters

oli_dictordered dictionary, optional

Keys specify dataset names. Values are 1D numpy arrays which specify outcome label indices. Each value is indexed by the values of circuit_indices.

time_dictordered dictionary, optional

Same format as oli_dict except stores arrays of floating-point time stamp data.

rep_dictordered dictionary, optional

Same format as oli_dict except stores arrays of integer repetition counts (can be None if there are no repetitions)

circuit_indicesordered dictionary, optional

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.

outcome_labelslist of strings

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.

outcome_label_indicesordered 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.

file_to_load_fromstring or file object, optional

Specify this argument and no others to create a MultiDataSet by loading from a file (just like using the load(…) function).

collision_actionsdictionary, optional

Specifies how duplicate circuits should be handled for the data sets. Keys must match those of oli_dict and values are “aggregate” or “keepseparate”. See documentation for DataSet. If None, then “aggregate” is used for all sets by default.

commentstring, 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.

commentsdict, optional

A user-specified dictionary of comments, one per dataset. Keys are dataset names (same as oli_dict keys).

aux_infodict, optional

A user-specified dictionary of per-circuit auxiliary information. Keys should be the circuits in this MultiDataSet and value should be Python dictionaries.

Initialize a MultiDataSet.

Parameters

oli_dictordered dictionary, optional

Keys specify dataset names. Values are 1D numpy arrays which specify outcome label indices. Each value is indexed by the values of circuit_indices.

time_dictordered dictionary, optional

Same format as oli_dict except stores arrays of floating-point time stamp data.

rep_dictordered dictionary, optional

Same format as oli_dict except stores arrays of integer repetition counts (can be None if there are no repetitions)

circuit_indicesordered dictionary, optional

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.

outcome_labelslist of strings

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.

outcome_label_indicesordered 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.

file_to_load_fromstring or file object, optional

Specify this argument and no others to create a MultiDataSet by loading from a file (just like using the load(…) function).

collision_actionsdictionary, optional

Specifies how duplicate circuits should be handled for the data sets. Keys must match those of oli_dict and values are “aggregate” or “keepseparate”. See documentation for DataSet. If None, then “aggregate” is used for all sets by default.

commentstring, 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.

commentsdict, optional

A user-specified dictionary of comments, one per dataset. Keys are dataset names (same as oli_dict keys).

aux_infodict, optional

A user-specified dictionary of per-circuit auxiliary information. Keys should be the circuits in this MultiDataSet and value should be Python dictionaries.

Returns

MultiDataSet

a new multi data set object.

property outcome_labels

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

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).

comment = 'None'

oliType

timeType

repType

keys()

A list of the keys (dataset names) of this MultiDataSet

Returns

list

items()

Iterator over (dataset name, DataSet) pairs.

values()

Iterator over DataSets corresponding to each dataset name.

datasets_aggregate(*dataset_names)

Generate a new DataSet by combining the outcome counts of multiple member Datasets.

Data with the same time-stamp and outcome are merged into a single “bin” in the returned DataSet.

Parameters

dataset_nameslist of strs

one or more dataset names.

Returns

DataSet

a single DataSet containing the summed counts of each of the data named by the parameters.

add_dataset(dataset_name, dataset, update_auxinfo=True)

Add a DataSet to this MultiDataSet.

The dataset must be static and conform with the circuits and time-dependent structure passed upon construction or those inherited from the first dataset added.

Parameters

dataset_namestring

The name to give the added dataset (i.e. the key the new data set will be referenced by).

datasetDataSet

The data set to add.

update_auxinfobool, optional

Whether the auxiliary information (if any exists) in dataset is added to the information already stored in this MultiDataSet.

Returns

None

copy()

Make a copy of this MultiDataSet

Returns

MultiDataSet

save(file_or_filename)

write_binary(file_or_filename)

Write this MultiDataSet to a binary-format file.

Parameters

file_or_filenamefile or string

Either a filename or a file object. In the former case, if the filename ends in “.gz”, the file will be gzip compressed.

Returns

None

load(file_or_filename)

read_binary(file_or_filename)

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

The file should have been created with MultiDataSet.write_binary()

Parameters

file_or_filenamefile or string

Either a filename or a file object. In the former case, if the filename ends in “.gz”, the file will be gzip uncompressed as it is read.

Returns

None

add_auxiliary_info(circuit, aux)

Add auxiliary meta information to circuit.

Parameters

circuittuple or Circuit

A tuple of operation labels specifying the circuit or a Circuit object

auxdict, optional

A dictionary of auxiliary meta information to be included with this set of data counts (associated with circuit).

Returns

None