pygsti.io.readers

Functions for loading GST objects from text files.

Module Contents

Functions

load_dataset(filename[, cache, collision_action, ...])	Deprecated!
read_dataset(filename[, cache, collision_action, ...])	Load a DataSet from a file.
load_multidataset(filename[, cache, collision_action, ...])	Deprecated!
read_multidataset(filename[, cache, collision_action, ...])	Load a MultiDataSet from a file.
load_time_dependent_dataset(filename[, cache, ...])	Deprecated!
read_time_dependent_dataset(filename[, cache, ...])	Load time-dependent (time-stamped) data as a DataSet.
load_model(filename)	Load a Model from a file, formatted using the standard text-format for models.
load_circuit_dict(filename)	Load a circuit dictionary from a file, formatted using the standard text-format.
load_circuit_list(filename[, read_raw_strings, ...])	Deprecated!
read_circuit_list(filename[, read_raw_strings, ...])	Load a circuit list from a file, formatted using the standard text-format.
convert_strings_to_circuits(obj)	Converts an object resulting from convert_circuits_to_strings() back to its original.
read_circuit_strings(filename)	TODO: docstring - load various Circuit-containing standard objects from a file where
load_protocol_from_dir(dirname[, quick_load, comm])	Deprecated!
read_protocol_from_dir(dirname[, quick_load, comm])	Load a Protocol from a directory on disk.
read_protocol_from_mongodb(mongodb, doc_id[, quick_load])	Load a Protocol from a MongoDB database.
remove_protocol_from_mongodb(mongodb, doc_id[, ...])	Remove a Protocol from a MongoDB database.
load_edesign_from_dir(dirname[, quick_load, comm])	Deprecated!
read_edesign_from_dir(dirname[, quick_load, comm])	Load a ExperimentDesign from a directory on disk.
create_edesign_from_dir(dirname)
read_edesign_from_mongodb(mongodb, doc_id[, ...])	Load a ExperimentDesign from a MongoDB database.
remove_edesign_from_mongodb(mongodb, doc_id[, ...])	Remove an ExperimentDesign from a MongoDB database.
load_data_from_dir(dirname[, quick_load, comm])	Deprecated!
read_data_from_dir(dirname[, preloaded_edesign, ...])	Load a ProtocolData from a directory on disk.
read_data_from_mongodb(mongodb, doc_id[, ...])	Load a ProtocolData from a MongoDB database.
remove_data_from_mongodb(mongodb, doc_id[, session, ...])	Remove ProtocolData from a MongoDB database.
load_results_from_dir(dirname[, name, preloaded_data, ...])	Deprecated!
read_results_from_dir(dirname[, name, preloaded_data, ...])	Load a ProtocolResults or ProtocolsResultsDir from a directory on disk.
read_results_from_mongodb(mongodb, doc_id[, ...])	Load a ProtocolResults from a MongoDB database.
read_resultsdir_from_mongodb(mongodb, doc_id[, ...])	Load a ProtocolsResultsDir from a MongoDB database.
remove_results_from_mongodb(mongodb, doc_id[, comm, ...])	Remove ProtocolResults data from a MongoDB database.
remove_resultsdir_from_mongodb(mongodb, doc_id[, ...])	Remove ProtocolsResultsDir data from a MongoDB database.

pygsti.io.readers.load_dataset(filename, cache=False, collision_action='aggregate', record_zero_counts=True, ignore_zero_count_lines=True, with_times='auto', circuit_parse_cache=None, verbosity=1)

Deprecated!

pygsti.io.readers.read_dataset(filename, cache=False, collision_action='aggregate', record_zero_counts=True, ignore_zero_count_lines=True, with_times='auto', circuit_parse_cache=None, verbosity=1)

Load a DataSet from a file.

This function first tries to load file as a saved DataSet object, then as a standard text-formatted DataSet.

Parameters

filenamestring

The name of the file

cachebool, optional

When set to True, a pickle file with the name filename + “.cache” is searched for and loaded instead of filename if it exists and is newer than filename. If no cache file exists or one exists but it is older than filename, a cache file will be written after loading from filename.

collision_action{“aggregate”, “keepseparate”}

Specifies how duplicate circuits should be handled. “aggregate” adds duplicate-circuit counts, whereas “keepseparate” tags duplicate circuits by setting their .occurrence IDs to sequential positive integers.

record_zero_countsbool, optional

Whether zero-counts are actually recorded (stored) in the returned DataSet. If False, then zero counts are ignored, except for potentially registering new outcome labels. When reading from a cache file (using cache==True) this argument is ignored: the presence of zero- counts is dictated by the value of record_zero_counts when the cache file was created.

ignore_zero_count_linesbool, optional

Whether circuits for which there are no counts should be ignored (i.e. omitted from the DataSet) or not.

with_timesbool or “auto”, optional

Whether to the time-stamped data format should be read in. If “auto”, then the time-stamped format is allowed but not required on a per-circuit basis (so the dataset can contain both formats). Typically you only need to set this to False when reading in a template file.

circuit_parse_cachedict, optional

A dictionary mapping qubit string representations into created Circuit objects, which can improve performance by reducing or eliminating the need to parse circuit strings.

verbosityint, optional

If zero, no output is shown. If greater than zero, loading progress is shown.

Returns

DataSet

pygsti.io.readers.load_multidataset(filename, cache=False, collision_action='aggregate', record_zero_counts=True, verbosity=1)

Deprecated!

pygsti.io.readers.read_multidataset(filename, cache=False, collision_action='aggregate', record_zero_counts=True, verbosity=1)

Load a MultiDataSet from a file.

This function first tries to load file as a saved MultiDataSet object, then as a standard text-formatted MultiDataSet.

Parameters

filenamestring

The name of the file

cachebool, optional

When set to True, a pickle file with the name filename + “.cache” is searched for and loaded instead of filename if it exists and is newer than filename. If no cache file exists or one exists but it is older than filename, a cache file will be written after loading from filename.

collision_action{“aggregate”, “keepseparate”}

Specifies how duplicate circuits should be handled. “aggregate” adds duplicate-circuit counts, whereas “keepseparate” tags duplicate circuits by setting their .occurrence IDs to sequential positive integers.

record_zero_countsbool, optional

Whether zero-counts are actually recorded (stored) in the returned MultiDataSet. If False, then zero counts are ignored, except for potentially registering new outcome labels. When reading from a cache file (using cache==True) this argument is ignored: the presence of zero-counts is dictated by the value of record_zero_counts when the cache file was created.

verbosityint, optional

If zero, no output is shown. If greater than zero, loading progress is shown.

Returns

MultiDataSet

pygsti.io.readers.load_time_dependent_dataset(filename, cache=False, record_zero_counts=True)

Deprecated!

pygsti.io.readers.read_time_dependent_dataset(filename, cache=False, record_zero_counts=True)

Load time-dependent (time-stamped) data as a DataSet.

Parameters

filenamestring

The name of the file

cachebool, optional

Reserved to perform caching similar to read_dataset. Currently this argument doesn’t do anything.

record_zero_countsbool, optional

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

Returns

DataSet

pygsti.io.readers.load_model(filename)

Load a Model from a file, formatted using the standard text-format for models.

Parameters

filenamestring

The name of the file

Returns

Model

pygsti.io.readers.load_circuit_dict(filename)

Load a circuit dictionary from a file, formatted using the standard text-format.

Parameters

filenamestring

The name of the file.

Returns

Dictionary with keys = circuit labels and values = Circuit objects.

pygsti.io.readers.load_circuit_list(filename, read_raw_strings=False, line_labels='auto', num_lines=None)

Deprecated!

pygsti.io.readers.read_circuit_list(filename, read_raw_strings=False, line_labels='auto', num_lines=None)

Load a circuit list from a file, formatted using the standard text-format.

Parameters

filenamestring

The name of the file

read_raw_stringsboolean

If True, circuits are not converted to Circuit objects.

line_labelsiterable, optional

The (string valued) line labels used to initialize Circuit objects when line label information is absent from the one-line text representation contained in filename. If ‘auto’, then line labels are taken to be the list of all state-space labels present in the circuit’s layers. If there are no such labels then the special value ‘*’ is used as a single line label.

num_linesint, optional

Specify this instead of line_labels to set the latter to the integers between 0 and num_lines-1.

Returns

list of Circuit objects

pygsti.io.readers.convert_strings_to_circuits(obj)

Converts an object resulting from convert_circuits_to_strings() back to its original.

Parameters

objlist or tuple or dict

The object to convert.

Returns

object

pygsti.io.readers.read_circuit_strings(filename)

TODO: docstring - load various Circuit-containing standard objects from a file where they have been replaced by their string representations

pygsti.io.readers.load_protocol_from_dir(dirname, quick_load=False, comm=None)

Deprecated!

pygsti.io.readers.read_protocol_from_dir(dirname, quick_load=False, comm=None)

Load a Protocol from a directory on disk.

Parameters

dirnamestring

Directory name.

quick_loadbool, optional

Setting this to True skips the loading of components that may take a long time to load. This can be useful when this information isn’t needed and loading takes a long time.

commmpi4py.MPI.Comm, optional

When not None, an MPI communicator used to synchronize file access.

Returns

Protocol

pygsti.io.readers.read_protocol_from_mongodb(mongodb, doc_id, quick_load=False)

Load a Protocol from a MongoDB database.

Parameters

mongodbpymongo.database.Database

The MongoDB instance to load data from.

doc_idstr

The user-defined identifier of the protocol object to load.

quick_loadbool, optional

Setting this to True skips the loading of components that may take a long time to load. This can be useful when this information isn’t needed and loading takes a long time.

Returns

Protocol

pygsti.io.readers.remove_protocol_from_mongodb(mongodb, doc_id, session=None, recursive=False)

Remove a Protocol from a MongoDB database.

If no protocol object with doc_id exists, this function returns False, otherwise it returns True.

Parameters

mongodbpymongo.database.Database

The MongoDB instance to remove data from.

doc_idstr

The user-defined identifier of the protocol object to remove.

sessionpymongo.client_session.ClientSession, optional

MongoDB session object to use when interacting with the MongoDB database. This can be used to implement transactions among other things.

recursiveRecursiveRemovalSpecification, optional

An object that filters the type of documents that are removed. Used when working with inter-related experiment designs, data, and results objects to only remove the types of documents you know aren’t being shared with other documents.

Returns

bool

True if the specified protocol object was removed, False if it didn’t exist.

pygsti.io.readers.load_edesign_from_dir(dirname, quick_load=False, comm=None)

Deprecated!

pygsti.io.readers.read_edesign_from_dir(dirname, quick_load=False, comm=None)

Load a ExperimentDesign from a directory on disk.

Parameters

dirnamestring

Directory name.

quick_loadbool, optional

Setting this to True skips the loading of components that may take a long time to load. This can be useful when this information isn’t needed and loading takes a long time.

commmpi4py.MPI.Comm, optional

When not None, an MPI communicator used to synchronize file access.

Returns

ExperimentDesign

pygsti.io.readers.create_edesign_from_dir(dirname)

pygsti.io.readers.read_edesign_from_mongodb(mongodb, doc_id, quick_load=False, comm=None)

Load a ExperimentDesign from a MongoDB database.

Parameters

mongodbpymongo.database.Database

The MongoDB instance to load data from.

doc_idstr

The user-defined identifier of the experiment design to load.

quick_loadbool, optional

Setting this to True skips the loading of components that may take a long time to load. This can be useful when this information isn’t needed and loading takes a long time.

commmpi4py.MPI.Comm, optional

When not None, an MPI communicator used to synchronize file access.

Returns

ExperimentDesign

pygsti.io.readers.remove_edesign_from_mongodb(mongodb, doc_id, session=None, recursive='default')

Remove an ExperimentDesign from a MongoDB database.

If no experiment design with doc_id exists, this function returns False, otherwise it returns True.

Parameters

mongodbpymongo.database.Database

The MongoDB instance to remove data from.

doc_idstr

The user-defined identifier of the experiment design to remove.

sessionpymongo.client_session.ClientSession, optional

MongoDB session object to use when interacting with the MongoDB database. This can be used to implement transactions among other things.

recursiveRecursiveRemovalSpecification, optional

An object that filters the type of documents that are removed. Used when working with inter-related experiment designs, data, and results objects to only remove the types of documents you know aren’t being shared with other documents.

Returns

bool

True if the specified experiment design was removed, False if it didn’t exist.

pygsti.io.readers.load_data_from_dir(dirname, quick_load=False, comm=None)

Deprecated!

pygsti.io.readers.read_data_from_dir(dirname, preloaded_edesign=None, quick_load=False, comm=None)

Load a ProtocolData from a directory on disk.

Parameters

dirnamestring

Directory name.

preloaded_edesignExperimentDesign, optional

The experiment deisgn belonging to the to-be-loaded data object, in cases when this has been loaded already (only use this if you know what you’re doing).

quick_loadbool, optional

Setting this to True skips the loading of components that may take a long time to load. This can be useful when this information isn’t needed and loading takes a long time.

commmpi4py.MPI.Comm, optional

When not None, an MPI communicator used to synchronize file access.

Returns

ProtocolData

pygsti.io.readers.read_data_from_mongodb(mongodb, doc_id, preloaded_edesign=None, quick_load=False, comm=None)

Load a ProtocolData from a MongoDB database.

Parameters

mongodbpymongo.database.Database

The MongoDB instance to load data from.

doc_idstr

The user-defined identifier of the data to load.

preloaded_edesignExperimentDesign, optional

The experiment deisgn belonging to the to-be-loaded data object, in cases when this has been loaded already (only use this if you know what you’re doing).

quick_loadbool, optional

Setting this to True skips the loading of components that may take a long time to load. This can be useful when this information isn’t needed and loading takes a long time.

commmpi4py.MPI.Comm, optional

When not None, an MPI communicator used to synchronize database access.

Returns

ProtocolData

pygsti.io.readers.remove_data_from_mongodb(mongodb, doc_id, session=None, recursive='default')

Remove ProtocolData from a MongoDB database.

If no experiment design with doc_id exists, this function returns False, otherwise it returns True.

Parameters

mongodbpymongo.database.Database

The MongoDB instance to remove data from.

doc_idstr

The user-defined identifier of the experiment design to remove.

sessionpymongo.client_session.ClientSession, optional

MongoDB session object to use when interacting with the MongoDB database. This can be used to implement transactions among other things.

recursiveRecursiveRemovalSpecification, optional

An object that filters the type of documents that are removed. Used when working with inter-related experiment designs, data, and results objects to only remove the types of documents you know aren’t being shared with other documents.

Returns

bool

True if the specified experiment design was removed, False if it didn’t exist.

pygsti.io.readers.load_results_from_dir(dirname, name=None, preloaded_data=None, quick_load=False, comm=None)

Deprecated!

pygsti.io.readers.read_results_from_dir(dirname, name=None, preloaded_data=None, quick_load=False, comm=None)

Load a ProtocolResults or ProtocolsResultsDir from a directory on disk.

Which object type is loaded depends on whether name is given: if it is, then a ProtocolResults object is loaded. If not, a ProtocolsResultsDir results.

Parameters

dirnamestring

Directory name. This should be a “base” directory, containing subdirectories like “edesign”, “data”, and “results”

namestring or None

The ‘name’ of a particular ProtocolResults object, which is a sub-directory beneath dirname/results/. If None, then all the results (all names) at the given base-directory are loaded and returned as a ProtocolResultsDir object.

preloaded_dataProtocolData, optional

The data object belonging to the to-be-loaded results, in cases when this has been loaded already (only use this if you know what you’re doing).

quick_loadbool, optional

Setting this to True skips the loading of data and experiment-design components that may take a long time to load. This can be useful all the information of interest lies only within the results objects.

commmpi4py.MPI.Comm, optional

When not None, an MPI communicator used to synchronize file access.

Returns

ProtocolResults or ProtocolResultsDir

pygsti.io.readers.read_results_from_mongodb(mongodb, doc_id, preloaded_data=None, quick_load=False, comm=None)

Load a ProtocolResults from a MongoDB database.

Parameters

mongodbpymongo.database.Database

The MongoDB instance to load data from.

doc_idstr

The user-defined identifier of the results directory to load.

preloaded_dataProtocolData, optional

The data object belonging to the to-be-loaded results, in cases when this has been loaded already (only use this if you know what you’re doing).

quick_loadbool, optional

Setting this to True skips the loading of data and experiment-design components that may take a long time to load. This can be useful all the information of interest lies only within the results objects.

commmpi4py.MPI.Comm, optional

When not None, an MPI communicator used to synchronize database access.

Returns

ProtocolResults

pygsti.io.readers.read_resultsdir_from_mongodb(mongodb, doc_id, preloaded_data=None, quick_load=False, read_all_results_for_data=False, comm=None)

Load a ProtocolsResultsDir from a MongoDB database.

Parameters

mongodbpymongo.database.Database

The MongoDB instance to load data from.

doc_idstr

The user-defined identifier of the results directory to load.

preloaded_dataProtocolData, optional

The data object belonging to the to-be-loaded results, in cases when this has been loaded already (only use this if you know what you’re doing).

quick_loadbool, optional

Setting this to True skips the loading of data and experiment-design components that may take a long time to load. This can be useful all the information of interest lies only within the results objects.

read_all_results_for_databool, optional

If True, the loaded result directory and sub-directories will read in all the results objects stored in the database associated with their ProtocolData object. Duplicate keys will be renamed to avoid collisions with warning messages are printed. If False (the default), then only the specific results associated with the directory when it was last saved are loaded. This can sometimes be useful for loading old results that have been overwritten but still exist in the database.

commmpi4py.MPI.Comm, optional

When not None, an MPI communicator used to synchronize database access.

Returns

ProtocolResultsDir

pygsti.io.readers.remove_results_from_mongodb(mongodb, doc_id, comm=None, session=None, recursive='default')

Remove ProtocolResults data from a MongoDB database.

Which object type is removed depends on whether name is given: if it is, then data corresponding to a ProtocolResults object is removed. If not, that of a ProtocolsResultsDir is removed.

Parameters

mongodbpymongo.database.Database

The MongoDB instance to remove data from.

doc_idstr

The user-defined identifier of the results directory to remove.

commmpi4py.MPI.Comm, optional

When not None, an MPI communicator used to synchronize database access.

sessionpymongo.client_session.ClientSession, optional

MongoDB session object to use when interacting with the MongoDB database. This can be used to implement transactions among other things.

recursiveRecursiveRemovalSpecification, optional

An object that filters the type of documents that are removed. Used when working with inter-related experiment designs, data, and results objects to only remove the types of documents you know aren’t being shared with other documents.

Returns

None

pygsti.io.readers.remove_resultsdir_from_mongodb(mongodb, doc_id, comm=None, session=None, recursive='default')

Remove ProtocolsResultsDir data from a MongoDB database.

Parameters

mongodbpymongo.database.Database

The MongoDB instance to remove data from.

doc_idstr

The user-defined identifier of the results directory to remove.

commmpi4py.MPI.Comm, optional

When not None, an MPI communicator used to synchronize database access.

sessionpymongo.client_session.ClientSession, optional

MongoDB session object to use when interacting with the MongoDB database. This can be used to implement transactions among other things.

recursiveRecursiveRemovalSpecification, optional

An object that filters the type of documents that are removed. Used when working with inter-related experiment designs, data, and results objects to only remove the types of documents you know aren’t being shared with other documents.

Returns

None