pygsti.io.readers
Functions for loading GST objects from text files.
Module Contents
Functions
|
Deprecated! |
|
Load a DataSet from a file. |
|
Deprecated! |
|
Load a MultiDataSet from a file. |
|
Deprecated! |
|
Load time-dependent (time-stamped) data as a DataSet. |
|
Load a Model from a file, formatted using the standard text-format for models. |
|
Load a circuit dictionary from a file, formatted using the standard text-format. |
|
Deprecated! |
|
Load a circuit list from a file, formatted using the standard text-format. |
Converts an object resulting from |
|
|
TODO: docstring - load various Circuit-containing standard objects from a file where |
|
Deprecated! |
|
Load a |
|
Load a |
|
Remove a |
|
Deprecated! |
|
Load a |
|
|
|
Load a |
|
Remove an |
|
Deprecated! |
|
Load a |
|
Load a |
|
Remove |
|
Deprecated! |
|
Load a |
|
Load a |
|
Load a |
|
Remove |
|
Remove |
- 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
orProtocolsResultsDir
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, aProtocolsResultsDir
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 aProtocolResultsDir
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 aProtocolsResultsDir
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