`pygsti.protocols.protocol`

Protocol object

Module Contents

Classes

`Protocol`	An analysis routine that is run on experimental data. A generalized notion of a QCVV protocol.
`MultiPassProtocol`	Runs a (contained) `Protocol` on all the passes of a multi-pass `ProtocolData`.
`ProtocolRunner`	Used to run `Protocol` objects on an entire tree of data
`TreeRunner`	Runs specific protocols on specific data-tree paths.
`SimpleRunner`	Runs a single protocol on every data node that has no sub-nodes (possibly separately for each pass).
`DefaultRunner`	Run the default protocol at each data-tree node.
`ExperimentDesign`	An experimental-design specification for one or more QCVV protocols.
`CircuitListsDesign`	Experiment design specification that is comprised of multiple circuit lists.
`CombinedExperimentDesign`	An experiment design that combines the specifications of one or more "sub-designs".
`SimultaneousExperimentDesign`	An experiment design whose circuits are the tensor-products of the circuits from one or more sub-designs.
`FreeformDesign`	Experiment design holding an arbitrary circuit list and meta data.
`ProtocolData`	Represents the experimental data needed to run one or more QCVV protocols.
`ProtocolResults`	Stores the results from running a QCVV protocol on data.
`MultiPassResults`	Holds the results of a single protocol on multiple "passes" (sets of data, typically taken at different times).
`ProtocolResultsDir`	Holds a dictionary of `ProtocolResults` objects.
`ProtocolPostProcessor`	Similar to a protocol, but runs on an existing `ProtocolResults` object.
`DataSimulator`	An analysis routine that is run on an experiment design to produce per-circuit data.
`DataCountsSimulator`	Simulates data counts for each circuit outcome, producing a simulated data set.
`ProtocolCheckpoint`	Class for storing checkpointing intermediate progress during

Functions

run_default_protocols(data[, memlimit, comm])

Run the default protocols for the data-tree rooted at data.

class pygsti.protocols.protocol.Protocol(name=None)

Bases: pygsti.baseobjs.mongoserializable.MongoSerializable

An analysis routine that is run on experimental data. A generalized notion of a QCVV protocol.

A Protocol object represents things like, but not strictly limited to, QCVV protocols. This class is essentially a serializable run function that takes as input a ProtocolData object and returns a ProtocolResults object. This function describes the working of the “protocol”.

Parameters

namestr, optional: The name of this protocol, also used to (by default) name the results produced by this protocol. If None, the class name will be used.

Create a new Protocol object.

Parameters

namestr, optional: The name of this protocol, also used to (by default) name the results produced by this protocol. If None, the class name will be used.

Returns

Protocol

collection_name = 'pygsti_protocols'

classmethod from_dir(dirname, quick_load=False)

Initialize a new Protocol object from dirname.

quick_loadbool, optional: Setting this to True skips the loading of components that may take a long time to load.

Parameters

dirnamestr: The directory name.
quick_loadbool, optional: Setting this to True skips the loading of components that may take a long time to load.

Returns

Protocol

abstract run(data, memlimit=None, comm=None)

Run this protocol on data.

Parameters

dataProtocolData: The input data.
memlimitint, optional: A rough per-processor memory limit in bytes.
commmpi4py.MPI.Comm, optional: When not None, an MPI communicator used to run this protocol in parallel.

Returns

ProtocolResults

write(dirname)

Write this protocol to a directory.

Parameters

dirnamestr: The directory name to write. This directory will be created if needed, and the files in an existing directory will be overwritten.

Returns

None

setup_nameddict(final_dict)

Initializes a set of nested NamedDict dictionaries describing this protocol.

This function is used by ProtocolResults objects when they’re creating nested dictionaries of their contents. This function returns a set of nested, single (key,val)-pair named-dictionaries which describe the particular attributes of this Protocol object named within its self._nameddict_attributes tuple. The final nested dictionary is set to be final_dict, which allows additional result quantities to easily be added.

Parameters

final_dictNamedDict: the final-level (innermost-nested) NamedDict in the returned nested dictionary.

Returns

NamedDict

class pygsti.protocols.protocol.MultiPassProtocol(protocol, name=None)

Bases: Protocol

Runs a (contained) Protocol on all the passes of a multi-pass ProtocolData.

A simple protocol that runs a “sub-protocol” on the passes of a ProtocolData containing a MultiDataSet. The sub-protocol therefore doesn’t need to know how to deal with multiple data passes. Instances of this class essentially act as wrappers around other protocols enabling them to handle multi-pass data.

Parameters

protocolProtocol: The protocol to run on each pass.
namestr, optional: The name of this protocol, also used to (by default) name the results produced by this protocol. If None, the class name will be used.

Create a new MultiPassProtocol object.

Parameters

protocolProtocol: The protocol to run on each pass.
namestr, optional: The name of this protocol, also used to (by default) name the results produced by this protocol. If None, the class name will be used.

Returns

MultiPassProtocol

run(data, memlimit=None, comm=None)

Run this protocol on data.

Parameters

dataProtocolData: The input data.
memlimitint, optional: A rough per-processor memory limit in bytes.
commmpi4py.MPI.Comm, optional: When not None, an MPI communicator used to run this protocol in parallel.

Returns

MultiPassResults

class pygsti.protocols.protocol.ProtocolRunner

Bases: object

Used to run Protocol objects on an entire tree of data

This class provides a way of combining multiple calls to Protocol.run(), potentially running multiple protocols on different data. From the outside, a ProtocolRunner object behaves similarly, and can often be used interchangably, with a Protocol object. It posesses a run method that takes a ProtocolData as input and returns a ProtocolResultsDir that can contain multiple ProtocolResults objects within it.

abstract run(data, memlimit=None, comm=None)

Run all the protocols specified by this protocol-runner on data.

Parameters

dataProtocolData: The input data.
memlimitint, optional: A rough per-processor memory limit in bytes.
commmpi4py.MPI.Comm, optional: When not None, an MPI communicator used to run this protocol-runner in parallel.

Returns

ProtocolResultsDir

class pygsti.protocols.protocol.TreeRunner(protocol_dict)

Bases: ProtocolRunner

Runs specific protocols on specific data-tree paths.

Parameters

protocol_dictdict: A dictionary of Protocol objects whose keys are paths (tuples of strings) specifying where in the data-tree that protocol should be run.

Create a new TreeRunner object, which runs specific protocols on specific data-tree paths.

Parameters

protocol_dictdict: A dictionary of Protocol objects whose keys are paths (tuples of strings) specifying where in the data-tree that protocol should be run.

Returns

TreeRunner

run(data, memlimit=None, comm=None)

Run all the protocols specified by this protocol-runner on data.

Parameters

dataProtocolData: The input data.
memlimitint, optional: A rough per-processor memory limit in bytes.
commmpi4py.MPI.Comm, optional: When not None, an MPI communicator used to run this protocol-runner in parallel.

Returns

ProtocolResultsDir

class pygsti.protocols.protocol.SimpleRunner(protocol, protocol_can_handle_multipass_data=False, edesign_type='all')

Bases: ProtocolRunner

Runs a single protocol on every data node that has no sub-nodes (possibly separately for each pass).

Parameters

protocolProtocol: The protocol to run.
protocol_can_handle_multipass_databool, optional: Whether protocol is able to process multi-pass data, or if MultiPassProtocol objects should be created implicitly.
edesign_typetype or ‘all’: Only run protocol on leaves with this type. (If ‘all’, then no filtering is performed.)

Create a new SimpleRunner object, which runs a single protocol on every ‘leaf’ of the data-tree.

Parameters

protocolProtocol: The protocol to run.
protocol_can_handle_multipass_databool, optional: Whether protocol is able to process multi-pass data, or if MultiPassProtocol objects should be created implicitly.
edesign_typetype or ‘all’: Only run protocol on leaves with this type. (If ‘all’, then no filtering is performed.)

Returns

SimpleRunner

run(data, memlimit=None, comm=None)

Run all the protocols specified by this protocol-runner on data.

Parameters

dataProtocolData: The input data.
memlimitint, optional: A rough per-processor memory limit in bytes.
commmpi4py.MPI.Comm, optional: When not None, an MPI communicator used to run this protocol-runner in parallel.

Returns

ProtocolResultsDir

class pygsti.protocols.protocol.DefaultRunner(run_passes_separately=False)

Bases: ProtocolRunner

Run the default protocol at each data-tree node.

(Default protocols are given within ExperimentDesign objects.)

Parameters

run_passes_separatelybool, optional: If True, then when multi-pass data is encountered it is split into passes before handing it off to the protocols. Set this to True when the default protocols being run expect single-pass data.

Create a new DefaultRunner object, which runs the default protocol at each data-tree node. (Default protocols are given within ExperimentDesign objects.)

Parameters

run_passes_separatelybool, optional: If True, then when multi-pass data is encountered it is split into passes before handing it off to the protocols. Set this to True when the default protocols being run expect single-pass data.

Returns

DefaultRunner

run(data, memlimit=None, comm=None)

Run all the protocols specified by this protocol-runner on data.

Parameters

dataProtocolData: The input data.
memlimitint, optional: A rough per-processor memory limit in bytes.
commmpi4py.MPI.Comm, optional: When not None, an MPI communicator used to run this protocol-runner in parallel.

Returns

ProtocolResultsDir

class pygsti.protocols.protocol.ExperimentDesign(circuits=None, qubit_labels=None, children=None, children_dirs=None)

Bases: pygsti.protocols.treenode.TreeNode, pygsti.baseobjs.mongoserializable.MongoSerializable

An experimental-design specification for one or more QCVV protocols.

The quantities needed to define the experiments required to run a Protocol. Minimally, a ExperimentDesign object holds a list of Circuit`s that need to be run. Typically, a :class:`ExperimentDesign object also contains information used to interpret these circuits, either by describing how they are constructed from smaller pieces or how they are drawn from a distribution.

It’s important to note that a ExperimentDesign does not contain all the inputs needed to run any particular QCVV protocol (e.g. there may be additional parameters specified when creating a Protocol object, and it may be the case that the data described by a single ExperimentDesign can be used by muliple protocols). Rather, a ExperimentDesign specifies what is necessary to acquire and interpret the data needed for one or more QCVV protocols.

Parameters

circuitslist of Circuits, optional: A list of the circuits needing data. If None, then the list is empty.
qubit_labelstuple or “multiple”, optional: The qubits that this experiment design applies to. These should also be the line labels of circuits. If None, the concatenation of the qubit labels of any child experiment designs is used, or, if there are no child designs, the line labels of the first circuit is used. The special “multiple” value means that different circuits act on different qubit lines.
childrendict, optional: A dictionary of whose values are child ExperimentDesign objects and whose keys are the names used to identify them in a “path”.
children_dirsdict, optional: A dictionary whose values are directory names and keys are child names (the same as the keys of children). If None, then the keys of children must be strings and are used as directory names. Directory names are used when saving the object (via write()).
child_categorystr, optional: The category that describes the children of this object. This is used as a heading for the keys of children.

Create a new ExperimentDesign object, which holds a set of circuits (needing data).

Parameters

circuitslist of Circuits, optional: A list of the circuits needing data. If None, then the list is empty.
qubit_labelstuple or “multiple”, optional: The qubits that this experiment design applies to. These should also be the line labels of circuits. If None, the concatenation of the qubit labels of any child experiment designs is used, or, if there are no child designs, the line labels of the first circuit is used. The special “multiple” value means that different circuits act on different qubit lines.
childrendict, optional: A dictionary of whose values are child ExperimentDesign objects and whose keys are the names used to identify them in a “path”.
children_dirsdict, optional: A dictionary whose values are directory names and keys are child names (the same as the keys of children). If None, then the keys of children must be strings and are used as directory names. Directory names are used when saving the object (via write()).

Returns

ExperimentDesign

collection_name = 'pygsti_experiment_designs'

classmethod from_dir(dirname, parent=None, name=None, quick_load=False)

Initialize a new ExperimentDesign object from dirname.

Parameters

dirnamestr: The root directory name (under which there is a ‘edesign’ subdirectory).
parentExperimentDesign, optional: The parent design object, if there is one. Primarily used internally - if in doubt, leave this as None.
namestr, optional: The sub-name of the design object being loaded, i.e. the key of this data object beneath parent. Only used when parent is not None.
quick_loadbool, optional: Setting this to True skips the loading of the potentially long circuit lists. This can be useful when loading takes a long time and all the information of interest lies elsewhere, e.g. in an encompassing results object.

Returns

ExperimentDesign

classmethod from_edesign(edesign)

Create an ExperimentDesign out of an existing experiment design.

Parameters

edesignExperimentDesign: The experiment design to convert (use as a base).

Returns

ExperimentDesign

set_actual_circuits_executed(actual_circuits)

Sets a list of circuits that will actually be executed.

This list must be parallel, and corresponding circuits must be logically equivalent, to those in self.all_circuits_needing_data. For example, when the circuits in this design are run simultaneously with other circuits, the circuits in this design may need to be padded with idles.

Parameters

actual_circuitslist: A list of Circuit objects that must be the same length as self.all_circuits_needing_data.

Returns

None

add_default_protocol(default_protocol_instance)

Add a “default” protocol to this experiment design.

Default protocols are a way of designating protocols you mean to run on the the data corresponding to an experiment design before that data has been taken. Use a DefaultRunner object to run (all) the default protocols of the experiment designs within a ProtocolData object.

Note that default protocols are indexed by their names, and so when adding multiple default protocols they need to have distinct names (usually given to the protocol when it is constructed).

Parameters

default_protocol_instanceProtocol: The protocol to add. This protocol’s name is used to index it.

Returns

None

truncate_to_circuits(circuits_to_keep)

Builds a new experiment design containing only the specified circuits.

Parameters

circuits_to_keeplist: A list of the circuits to keep.

Returns

ExperimentDesign

truncate_to_available_data(dataset)

Builds a new experiment design containing only those circuits present in dataset.

Parameters

datasetDataSet: The dataset to filter based upon.

Returns

ExperimentDesign

truncate_to_design(other_design)

Truncates this experiment design by only keeping the circuits also in other_design

Parameters

other_designExperimentDesign: The experiment design to compare with.

Returns

ExperimentDesign: The truncated experiment design.

write(dirname=None, parent=None)

Write this experiment design to a directory.

Parameters

dirnamestr: The root directory to write into. This directory will have an ‘edesign’ subdirectory, which will be created if needed and overwritten if present. If None, then the path this object was loaded from is used (if this object wasn’t loaded from disk, an error is raised).
parentExperimentDesign, optional: The parent experiment design, when a parent is writing this design as a sub-experiment-design. Otherwise leave as None.

Returns

None

setup_nameddict(final_dict)

Initializes a set of nested NamedDict dictionaries describing this design.

This function is used by ProtocolResults objects when they’re creating nested dictionaries of their contents. This function returns a set of nested, single (key,val)-pair named-dictionaries which describe the particular attributes of this ExperimentDesign object named within its self._nameddict_attributes tuple. The final nested dictionary is set to be final_dict, which allows additional result quantities to easily be added.

Parameters

final_dictNamedDict: the final-level (innermost-nested) NamedDict in the returned nested dictionary.

Returns

NamedDict

promote_to_combined(name='**0')

Promote this experiment design to be a combined experiment design.

Wraps this experiment design in a new CombinedExperimentDesign whose only sub-design is this one, and returns the combined design.

Parameters

namestr, optional: The sub-design-name of this experiment design within the created combined experiment design.

Returns

CombinedExperimentDesign

promote_to_simultaneous()

Promote this experiment design to be a simultaneous experiment design.

Wraps this experiment design in a new SimultaneousExperimentDesign whose only sub-design is this one, and returns the simultaneous design.

Returns

SimultaneousExperimentDesign

map_qubit_labels(mapper)

Creates a new ExperimentDesign whose circuits’ qubit labels are updated according to a given mapping.

Parameters

mapperdict 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

ExperimentDesign

class pygsti.protocols.protocol.CircuitListsDesign(circuit_lists, all_circuits_needing_data=None, qubit_labels=None, nested=False, remove_duplicates=True)

Bases: ExperimentDesign

Experiment design specification that is comprised of multiple circuit lists.

Parameters

circuit_listslist or PlaquetteGridCircuitStructure: A list whose elements are themselves lists of Circuit objects, specifying the data that needs to be taken. Alternatively, a single PlaquetteGridCircuitStructure object containing a sequence of circuits lists, each at a different “x” value (usually the maximum circuit depth).
all_circuits_needing_datalist, optional: A list of all the circuits needing data. By default, This is just the concatenation of the elements of circuit_lists with duplicates removed. The only reason to specify this separately is if you happen to have this list lying around.
qubit_labelstuple, optional: The qubits that this experiment design applies to. If None, the line labels of the first circuit is used.
nestedbool, optional: Whether the elements of circuit_lists are nested, e.g. whether circuit_lists[i] is a subset of circuit_lists[i+1]. This is useful to know because certain operations can be more efficient when it is known that the lists are nested.
remove_duplicatesbool, optional: Whether to remove duplicates when automatically creating all the circuits that need data (this argument isn’t used when all_circuits_needing_data is given).

Create a new CircuitListsDesign object.

Parameters

circuit_listslist or PlaquetteGridCircuitStructure: A list whose elements are themselves lists of Circuit objects, specifying the data that needs to be taken. Alternatively, a single PlaquetteGridCircuitStructure object containing a sequence of circuits lists, each at a different “x” value (usually the maximum circuit depth).
all_circuits_needing_datalist, optional: A list of all the circuits needing data. By default, This is just the concatenation of the elements of circuit_lists with duplicates removed. The only reason to specify this separately is if you happen to have this list lying around.
qubit_labelstuple, optional: The qubits that this experiment design applies to. If None, the line labels of the first circuit is used.
nestedbool, optional: Whether the elements of circuit_lists are nested, e.g. whether circuit_lists[i] is a subset of circuit_lists[i+1]. This is useful to know because certain operations can be more efficient when it is known that the lists are nested.
remove_duplicatesbool, optional: Whether to remove duplicates when automatically creating all the circuits that need data (this argument isn’t used when all_circuits_needing_data is given).

Returns

CircuitListsDesign

classmethod from_edesign(edesign)

Create a CircuitListsDesign out of an existing experiment design.

If edesign already is a circuit lists experiment design, it will just be returned (not a copy of it).

Parameters

edesignExperimentDesign: The experiment design to convert (use as a base).

Returns

CircuitListsDesign

truncate_to_lists(list_indices_to_keep)

Truncates this experiment design by only keeping a subset of its circuit lists.

Parameters

list_indices_to_keepiterable: A list of the (integer) list indices to keep.

Returns

CircuitListsDesign: The truncated experiment design.

map_qubit_labels(mapper)

Creates a new experiment design whose circuits’ qubit labels are updated according to a given mapping.

Parameters

mapperdict 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

CircuitListsDesign

class pygsti.protocols.protocol.CombinedExperimentDesign(sub_designs, all_circuits=None, qubit_labels=None, sub_design_dirs=None, interleave=False)

Bases: ExperimentDesign

An experiment design that combines the specifications of one or more “sub-designs”.

The sub-designs are preserved as children under the CombinedExperimentDesign instance, creating a “data-tree” structure. The CombinedExperimentDesign object itself simply merges all of the circuit lists.

Parameters

sub_designsdict or list: A dictionary of other ExperimentDesign objects whose keys are names for each sub-edesign (used for directories and to index the sub-edesigns from this experiment design). If a list is given instead, a default names of the form “ **<number> “ are used.
all_circuitslist, optional: A list of Circuit`s, specifying all the circuits needing data. This can include additional circuits that are not in any of `sub_designs. By default, the union of all the circuits in the sub-designs is used.
qubit_labelstuple, optional: The qubits that this experiment design applies to. If None, the line labels of the first circuit is used.
sub_design_dirsdict, optional: A dictionary whose values are directory names and keys are sub-edesign names (the same as the keys of sub_designs). If None, then the keys of sub_designs must be strings and are used as directory names. Directory names are used when saving the object (via write()).
interleavebool, optional: Whether the circuits of the sub_designs should be interleaved to form the circuit ordering of this experiment design.

Create a new CombinedExperimentDesign object.

Parameters

sub_designsdict or list: A dictionary of other ExperimentDesign objects whose keys are names for each sub-edesign (used for directories and to index the sub-edesigns from this experiment design). If a list is given instead, a default names of the form “ **<number> “ are used.
all_circuitslist, optional: A list of Circuit`s, specifying all the circuits needing data. This can include additional circuits that are not in any of `sub_designs. By default, the union of all the circuits in the sub-designs is used.
qubit_labelstuple, optional: The qubits that this experiment design applies to. If None, the line labels of the first circuit is used.
sub_design_dirsdict, optional: A dictionary whose values are directory names and keys are sub-edesign names (the same as the keys of sub_designs). If None, then the keys of sub_designs must be strings and are used as directory names. Directory names are used when saving the object (via write()).
interleavebool, optional: Whether the circuits of the sub_designs should be interleaved to form the circuit ordering of this experiment design.

Returns

CombinedExperimentDesign

classmethod from_edesign(edesign, name)

Create a combined experiment design out of an existing experiment design.

This makes edesign the one and only member of a new combined experiment design, even in edesign is already a CombinedExperimentDesign.

Parameters

edesignExperimentDesign: The experiment design to convert (use as a base).
namestr: The sub-name of edesign within the returned combined experiment design.

Returns

CombinedExperimentDesign

map_qubit_labels(mapper)

Creates a new experiment design whose circuits’ qubit labels are updated according to a given mapping.

Parameters

mapperdict 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

CombinedExperimentDesign

class pygsti.protocols.protocol.SimultaneousExperimentDesign(edesigns, tensored_circuits=None, qubit_labels=None)

Bases: ExperimentDesign

An experiment design whose circuits are the tensor-products of the circuits from one or more sub-designs.

The sub-ExperimentDesign objects must act on disjoint sets of qubits. The sub-designs are preserved as children under the SimultaneousExperimentDesign instance, creating a “data-tree” structure.

Parameters

edesignslist: A list of ExperimentDesign objects whose circuits are to occur simultaneously.
tensored_circuitslist, optional: A list of all the circuits for this experiment design. By default, these are the circuits of those in edesigns tensored together. Typically this is left as the default.
qubit_labelstuple, optional: The qubits that this experiment design applies to. If None, the concatenated qubit labels of edesigns are used (this is usually what you want).
categorystr, optional: The category name for the qubit-label-tuples correspoding to the elements of edesigns.

Create a new SimultaneousExperimentDesign object.

Parameters

edesignslist: A list of ExperimentDesign objects whose circuits are to occur simultaneously.
tensored_circuitslist, optional: A list of all the circuits for this experiment design. By default, these are the circuits of those in edesigns tensored together. Typically this is left as the default.
qubit_labelstuple, optional: The qubits that this experiment design applies to. If None, the concatenated qubit labels of edesigns are used (this is usually what you want).

Returns

SimultaneousExperimentDesign

classmethod from_edesign(edesign)

Create a simultaneous experiment design out of an existing experiment design.

This makes edesign the one and only member of a new simultanieous experiment design, even in edesign is already a SimultaneousExperimentDesign.

Parameters

edesignExperimentDesign: The experiment design to convert (use as a base).

Returns

SimultaneousExperimentDesign

map_qubit_labels(mapper)

Creates a new experiment design whose circuits’ qubit labels are updated according to a given mapping.

Parameters

mapperdict 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

SimultaneousExperimentDesign

class pygsti.protocols.protocol.FreeformDesign(circuits, qubit_labels=None)

Bases: ExperimentDesign

Experiment design holding an arbitrary circuit list and meta data.

Parameters

circuitslist or dict: A list of the circuits needing data. If None, then the list is empty.
qubit_labelstuple, optional: The qubits that this experiment design applies to. If None, the line labels of the first circuit is used.

Create a new ExperimentDesign object, which holds a set of circuits (needing data).

Parameters

circuitslist of Circuits, optional: A list of the circuits needing data. If None, then the list is empty.
qubit_labelstuple or “multiple”, optional: The qubits that this experiment design applies to. These should also be the line labels of circuits. If None, the concatenation of the qubit labels of any child experiment designs is used, or, if there are no child designs, the line labels of the first circuit is used. The special “multiple” value means that different circuits act on different qubit lines.
childrendict, optional: A dictionary of whose values are child ExperimentDesign objects and whose keys are the names used to identify them in a “path”.
children_dirsdict, optional: A dictionary whose values are directory names and keys are child names (the same as the keys of children). If None, then the keys of children must be strings and are used as directory names. Directory names are used when saving the object (via write()).

Returns

ExperimentDesign

classmethod from_dataframe(df, qubit_labels=None)

Create a FreeformDesign from a pandas dataframe.

Parameters

dfpandas.Dataframe: A dataframe containing a “Circuit” column and possibly others.
qubit_labelstuple, optional: The qubits that this experiment design applies to. If None, the line labels of the first circuit is used.

Returns

FreeformDesign

classmethod from_edesign(edesign)

Create a FreeformDesign out of an existing experiment design.

If edesign already is a free-form experiment design, it will just be returned (not a copy of it).

Parameters

edesignExperimentDesign: The experiment design to convert (use as a base).

Returns

FreeformDesign

to_dataframe(pivot_valuename=None, pivot_value='Value', drop_columns=False)

map_qubit_labels(mapper)

Creates a new experiment design whose circuits’ qubit labels are updated according to a given mapping.

Parameters

mapperdict 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

FreeformDesign

class pygsti.protocols.protocol.ProtocolData(edesign, dataset=None, cache=None)

Bases: pygsti.protocols.treenode.TreeNode, pygsti.baseobjs.mongoserializable.MongoSerializable

Represents the experimental data needed to run one or more QCVV protocols.

This class contains a ProtocolIput, which describes a set of circuits, and a DataSet (or MultiDataSet) that holds data for these circuits. These members correspond to the .edesign and .dataset attributes.

Parameters

edesignExperimentDesign: The experiment design describing what circuits this object contains data for. If None, then an unstructured ExperimentDesign is created containing the circuits present in dataset.
datasetDataSet or MultiDataSet, optional: The data counts themselves.
cachedict, optional: A cache of values which holds values derived only from the experiment design and data in this object.

Attributes

passesdict: A dictionary of the data on a per-pass basis (works even it there’s just one pass).

Create a new ProtocolData object.

Parameters

edesignExperimentDesign: The experiment design describing what circuits this object contains data for. If None, then an unstructured ExperimentDesign is created containing the circuits present in dataset.
datasetDataSet or MultiDataSet, optional: The data counts themselves.
cachedict, optional: A cache of values which holds values derived only from the experiment design and data in this object.

Returns

ProtocolData

property passes: A dictionary of the data on a per-pass basis (works even it there’s just one pass).

Returns

dict

collection_name = 'pygsti_protocol_data'

CACHE_COLLECTION_NAME = 'pygsti_protocol_data_caches'

classmethod from_dir(dirname, parent=None, name=None, preloaded_edesign=None, quick_load=False, record_zero_counts=True)

Initialize a new ProtocolData object from dirname.

Parameters

dirnamestr: The root directory name (under which there are ‘edesign’ and ‘data’ subdirectories).
parentProtocolData, optional: The parent data object, if there is one. This is needed for sub-data objects which reference/inherit their parent’s dataset. Primarily used internally - if in doubt, leave this as None.
namestr, optional: The sub-name of the object being loaded, i.e. the key of this data object beneath parent. Only used when parent is not None.
preloaded_edesignExperimentDesign, optional: In the case that the ExperimentDesign object for dirname is already loaded, it can be passed in here. Otherwise leave this as None and it will be loaded.
quick_loadbool, optional: Setting this to True skips the loading of components that may take a long time, e.g. the actual raw data set(s). This can be useful when loading takes a long time and all the information of interest lies elsewhere, e.g. in an encompassing results object.
record_zero_countsbool, optional: Whether zero-counts are actually recorded (stored) in the datasets held within this ProtocolData object.

Returns

ProtocolData

copy(): Make a copy of this object.

Returns

ProtocolData

is_multipass()

Whether this protocol data contains multiple passes.

More accurately, whether the .dataset of this object is a MultiDataSet.

Returns

bool

prune_tree(paths, paths_are_sorted=False)

Prune the tree rooted here to include only the given paths, discarding all else.

Returns a new ProtocolData object with a subset of the data-tree paths contained under this one.

Parameters

pathslist: A list of the paths to keep. Each path is a tuple of keys, delineating a path in the data-tree.
paths_are_sortedbool, optional: Whether paths has already been sorted lexographically.

Returns

ProtocolData

write(dirname=None, parent=None, edesign_already_written=False)

Write this protocol data to a directory.

Parameters

dirnamestr: The root directory to write into. This directory will have ‘edesign’ and ‘data’ subdirectories, which will be created if needed and overwritten if present. If None, then the path this object was loaded from is used (if this object wasn’t loaded from disk, an error is raised).
parentProtocolData, optional: The parent protocol data, when a parent is writing this data as a sub-protocol-data object. Otherwise leave as None.
edesign_already_writtenbool, optional: If True, the experiment design within this data object is not written to disk, and it is left to the caller to ensure the experiment design is saved.

Returns

None

setup_nameddict(final_dict)

Initializes a set of nested NamedDict dictionaries describing this data.

This function is used by ProtocolResults objects when they’re creating nested dictionaries of their contents. The final nested dictionary is set to be final_dict, which allows additional result quantities to easily be added.

Parameters

final_dictNamedDict: the final-level (innermost-nested) NamedDict in the returned nested dictionary.

Returns

NamedDict

to_dataframe(pivot_valuename=None, pivot_value=None, drop_columns=False)

Create a Pandas dataframe with this data.

Parameters

pivot_valuenamestr, 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_valuestr, 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_columnsbool 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

class pygsti.protocols.protocol.ProtocolResults(data, protocol_instance)

Bases: pygsti.baseobjs.mongoserializable.MongoSerializable

Stores the results from running a QCVV protocol on data.

A ProtocolResults object Contains a ProtocolData object and stores the results of running a Protcocol on this data.

Parameters

dataProtocolData: The input data from which these results are derived.
protocol_instanceProtocol: The protocol that created these results.

Create a new ProtocolResults object.

Parameters

dataProtocolData: The input data from which these results are derived.
protocol_instanceProtocol: The protocol that created these results.

Returns

ProtocolResults

collection_name = 'pygsti_results'

classmethod from_dir(dirname, name, preloaded_data=None, quick_load=False)

Initialize a new ProtocolResults object from dirname / results / name.

Parameters

dirnamestr: The root directory name (under which there is are ‘edesign’, ‘data’, and ‘results’ subdirectories).
namestr: The sub-directory name of the particular results object to load (there can be multiple under a given root dirname). This is the name of a subdirectory of dirname / results.
preloaded_dataProtocolData, optional: In the case that the ProtocolData object for dirname is already loaded, it can be passed in here. Otherwise leave this as None and it will be loaded.
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 object.

Returns

ProtocolResults

write(dirname=None, data_already_written=False)

Write these protocol results to a directory.

Parameters

dirnamestr: The root directory to write into. This directory will have ‘edesign’, ‘data’, and ‘results/<myname>’ subdirectories, which will path be created if needed and overwritten if present. If None, then the this object was loaded from is used (if this object wasn’t loaded from disk, an error is raised).
data_already_writtenbool, optional: Set this to True if you’re sure the .data ProtocolData object within this results object has already been written to dirname. Leaving this as the default is a safe option.

Returns

None

to_nameddict(): Convert these results into nested NamedDict objects.

Returns

NamedDict

to_dataframe(pivot_valuename=None, pivot_value=None, drop_columns=False)

Convert these results into Pandas dataframe.

Parameters

pivot_valuenamestr, 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_valuestr, 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_columnsbool 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

DataFrame

class pygsti.protocols.protocol.MultiPassResults(data, protocol_instance)

Bases: ProtocolResults

Holds the results of a single protocol on multiple “passes” (sets of data, typically taken at different times).

The results of each pass are held as a separate ProtcolResults object within the .passes attribute.

Parameters

dataProtocolData: The input data from which these results are derived.
protocol_instanceProtocol: The protocol that created these results.

Initialize an empty MultiPassResults object, which contain a dictionary of sub-results one per “pass”. Usually these sub-results are obtained by running protocol_instance on each data set within data.

Parameters

dataProtocolData: The input data from which these results are derived.
protocol_instanceProtocol: The protocol that created these results.

Returns

MultiPassResults

classmethod from_dir(dirname, name, preloaded_data=None, quick_load=False)

Initialize a new MultiPassResults object from dirname / results / name.

Parameters

dirnamestr: The root directory name (under which there is are ‘edesign’, ‘data’, and ‘results’ subdirectories).
namestr: The sub-directory name of the particular results object to load (there can be multiple under a given root dirname). This is the name of a subdirectory of dirname / results.
preloaded_dataProtocolData, optional: In the case that the ProtocolData object for dirname is already loaded, it can be passed in here. Otherwise leave this as None and it will be loaded.
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 object.

Returns

ProtocolResults

to_nameddict(): Create a NamedDict of the results within this object.

Returns

NamedDict

copy(): Make a copy of this object.

Returns

MultiPassResults

class pygsti.protocols.protocol.ProtocolResultsDir(data, protocol_results=None, children=None)

Bases: pygsti.protocols.treenode.TreeNode, pygsti.baseobjs.mongoserializable.MongoSerializable

Holds a dictionary of ProtocolResults objects.

It contains a ProtocolData object and is rooted at the_model corresponding node of the data-tree. It contains links to child-ProtocolResultsDir objects representing sub-directories.

This container object holds two things:

A .for_protocol dictionary of ProtocolResults corresponding to different protocols (keys are protocol names).
Child ProtocolResultsDir objects, obtained by indexing this object directly using the name of the sub-directory.

Parameters

dataProtocolData: The data from which all the Results objects in this ProtocolResultsDir are derived.
protocol_resultsProtocolResults, optional: An initial (single) results object to add. The name of the results object is used as its key within the .for_protocol dictionary. If None, then an empty results directory is created.
childrendict, optional: A dictionary of the ProtocolResultsDir objects that are sub-directories beneath this one. If None, then children are automatically created based upon the tree given by data. (To avoid creating any children, you can pass an empty dict here.)

Create a new ProtocolResultsDir object.

This container object holds two things:

A .for_protocol dictionary of ProtocolResults corresponding to different protocols (keys are protocol names).
Child ProtocolResultsDir objects, obtained by indexing this object directly using the name of the sub-directory.

Parameters

dataProtocolData: The data from which all the Results objects in this ProtocolResultsDir are derived.
protocol_resultsProtocolResults or dict, optional: An initial dictionary of ProtocolResults objects to add, or a single results object. The name(s) of the results object(s) must be used as keys (and will used as its key for a single results object). This beccomes the created object’s .for_protocol dictionary. If None, then an empty results directory is created.
childrendict, optional: A dictionary of the ProtocolResultsDir objects that are sub-directories beneath this one. If None, then children are automatically created based upon the tree given by data. (To avoid creating any children, you can pass an empty dict here.)

Returns

ProtocolResultsDir

collection_name = 'pygsti_results_directories'

classmethod from_dir(dirname, parent=None, name=None, preloaded_data=None, quick_load=False)

Initialize a new ProtocolResultsDir object from dirname.

Parameters

dirnamestr: The root directory name (under which there are ‘edesign’ and ‘data’, and possibly ‘results’, subdirectories).
parentProtocolResultsDir, optional: The parent results-directory object that is loading the returned object as a sub-results. This is used internally when loading a ProtocolResultsDir that represents a node of the data-tree with children.
namestr, optional: The name of this result within parent. This is only used when parent is not None.
preloaded_dataProtocolData, optional: In the case that the ProtocolData object for dirname is already loaded, it can be passed in here. Otherwise leave this as None and it will be loaded.
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 contained results objects.

Returns

ProtcolResultsDir

add_results(for_protocol_name, results)

Add a new results object to this results directory node.

The added results object must share this result directory’s data, i.e., its .data attribute must match the .data of this directory. This requirement is usually met because the results have been created by running a protocol on this directory’s .data. The results object is stored in the .for_protocol[for_protocol_name] attribute of this directory.

Parameters

for_protocol_namestr: Name of the protocol to be added.
resultsProtocolResults: The results object to be added

Returns

None

write(dirname=None, parent=None, data_already_written=False)

Write this “protocol results directory” to a directory.

Parameters

dirnamestr: The root directory to write into. This directory will have ‘edesign’, ‘data’, and ‘results’ subdirectories, which will be created if needed and overwritten if present. If None, then the path this object was loaded from is used (if this object wasn’t loaded from disk, an error is raised).
parentProtocolResultsDir, optional: The parent protocol results directory, when a parent is writing this results dir as a sub-results-dir. Otherwise leave as None.
data_already_writtenbool, optional: If True, the data object within this results directory is not written to disk, and it is left to the caller to ensure the data object is saved.

Returns

None

to_nameddict(): Convert the results in this object into nested NamedDict objects.

Returns

NamedDict

to_dataframe(pivot_valuename=None, pivot_value=None, drop_columns=False)

Convert these results into Pandas dataframe.

Parameters

pivot_valuenamestr, 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_valuestr, 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_columnsbool 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

DataFrame

pygsti.protocols.protocol.run_default_protocols(data, memlimit=None, comm=None)

Run the default protocols for the data-tree rooted at data.

Parameters

dataProtocolData: the data to run default protocols on.
memlimitint, optional: A rough per-processor memory limit in bytes.
commmpi4py.MPI.Comm, optional: When not None, an MPI communicator used to run the protocols in parallel.

Returns

ProtocolResultsDir

class pygsti.protocols.protocol.ProtocolPostProcessor(name)

Bases: object

Similar to a protocol, but runs on an existing ProtocolResults object.

Running a ProtocolPostProcessor produces a new (or updated) ProtocolResults object.

Parameters

namestr: The name of this post-processor.

Create a new ProtocolPostProcessor object.

Parameters

namestr: The name of this post-processor.

Returns

ProtocolPostProcessor

classmethod from_dir(dirname, quick_load=False)

Initialize a new ProtocolPostProcessor object from dirname.

Parameters

dirnamestr: The directory name.
quick_loadbool, optional: Setting this to True skips the loading of components that may take a long time to load.

Returns

ProtocolPostProcessor

abstract run(results, memlimit=None, comm=None)

Run this post-processor on results.

Parameters

resultsProtocolResults: The input results.
memlimitint, optional: A rough per-processor memory limit in bytes.
commmpi4py.MPI.Comm, optional: When not None, an MPI communicator used to run this post-processor in parallel.

Returns

ProtocolResults

write(dirname)

Write this protocol post-processor to a directory.

Parameters

dirnamestr: The directory to write into.

Returns

None

class pygsti.protocols.protocol.DataSimulator

Bases: object

An analysis routine that is run on an experiment design to produce per-circuit data.

A DataSimulator fundamentally simulates a model to create data, taking an ExperimentDesign as input and producing a ProtocolData object as output.

The produced data may consist of data counts for some/all of the circuit outcomes, and thus result in a ProtocolData containsing a normal DataSet. Alternatively, a data simulator may compute arbitrary quantities to be associated with the circuits, resulting in a ProtocolData containsing a normal FreeformDataSet.

abstract run(edesign, memlimit=None, comm=None)

Run this data simulator on an experiment design.

Parameters

edesignExperimentDesign: The input experiment design.
memlimitint, optional: A rough per-processor memory limit in bytes.
commmpi4py.MPI.Comm, optional: When not None, an MPI communicator used to run this data simulator in parallel.

Returns

ProtocolData

class pygsti.protocols.protocol.DataCountsSimulator(model, num_samples=1000, sample_error='multinomial', seed=None, rand_state=None, alias_dict=None, collision_action='aggregate', record_zero_counts=True, times=None)

Bases: DataSimulator

Simulates data counts for each circuit outcome, producing a simulated data set.

This object can also be used to compute the outcome probabilities for each circuit outcome instead of sampled counts by setting sample_error=”none”.

Parameters

modelModel

The model to simulate.

num_samplesint or list of ints or None, optional

The simulated number of samples for each circuit. This only has effect when sample_error == "binomial" or "multinomial". If an integer, all circuits have this number of total samples. If a list, integer elements specify the number of samples for the corresponding circuit. If None, then model_or_dataset must be a DataSet, and total counts are taken from it (on a per-circuit basis).

sample_errorstring, optional

What type of sample error is included in the counts. Can be:

“none” - no sample error: counts are floating point numbers such that the exact probabilty can be found by the ratio of count / total.
“clip” - no sample error, but clip probabilities to [0,1] so, e.g., counts are always positive.
“round” - same as “clip”, except counts are rounded to the nearest integer.
“binomial” - the number of counts is taken from a binomial distribution. Distribution has parameters p = (clipped) probability of the circuit and n = number of samples. This can only be used when there are exactly two SPAM labels in model_or_dataset.
“multinomial” - counts are taken from a multinomial distribution. Distribution has parameters p_k = (clipped) probability of the gate string using the k-th SPAM label and n = number of samples.

seedint, optional

If not None, a seed for numpy’s random number generator, which is used to sample from the binomial or multinomial distribution.

rand_statenumpy.random.RandomState

A RandomState object to generate samples from. Can be useful to set instead of seed if you want reproducible distribution samples across multiple random function calls but you don’t want to bother with manually incrementing seeds between those calls.

alias_dictdict, optional

A dictionary mapping single operation labels into tuples of one or more other operation labels which translate the given circuits before values are computed using model_or_dataset. The resulting Dataset, however, contains the un-translated circuits as keys.

collision_action{“aggregate”, “keepseparate”}

Determines how duplicate circuits are handled by the resulting DataSet. Please see the constructor documentation for DataSet.

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.

timesiterable, optional

When not None, a list of time-stamps at which data should be sampled. num_samples samples will be simulated at each time value, meaning that each circuit in circuit_list will be evaluated with the given time value as its start time.

run(edesign, memlimit=None, comm=None)

Run this data simulator on an experiment design.

Parameters

edesignExperimentDesign: The input experiment design.
memlimitint, optional: A rough per-processor memory limit in bytes.
commmpi4py.MPI.Comm, optional: When not None, an MPI communicator used to run this data simulator in parallel.

Returns

ProtocolData

class pygsti.protocols.protocol.ProtocolCheckpoint(name, parent=None)

Bases: pygsti.baseobjs.nicelyserializable.NicelySerializable

Class for storing checkpointing intermediate progress during the running of a protocol in order to enable restarting subsequent runs of the protocol from that point.

Parameters

namestr: Name of the protocol associated with this checkpoint.
parentProtocolCheckpoint, optional (default None): When specified this checkpoint object is treated as the child of another ProtocolCheckpoint object that acts as the parent. When present, the parent’s write method supersedes the child objects and is called when calling write on the child. Currently only used in the implementation of StandardGSTCheckpoint.

write(path)

Writes this object to a file.

Parameters

pathstr or Path: The name of the file that is written.
format_kwargsdict, optional: Additional arguments specific to the format being used. For example, the JSON format accepts indent as an argument because json.dump does.

Returns

None

pygsti.protocols.protocol

Module Contents

Classes

Functions

Parameters

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Parameters

Returns

Parameters

Returns

Parameters

Parameters

Returns

Parameters

Returns

Parameters

Parameters

Returns

Parameters

Returns

Parameters

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Returns

Parameters

Returns

Parameters

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

`pygsti.protocols.protocol`