:py:mod:`pygsti.protocols.protocol` =================================== .. py:module:: pygsti.protocols.protocol .. autoapi-nested-parse:: Protocol object Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: pygsti.protocols.protocol.Protocol pygsti.protocols.protocol.MultiPassProtocol pygsti.protocols.protocol.ProtocolRunner pygsti.protocols.protocol.TreeRunner pygsti.protocols.protocol.SimpleRunner pygsti.protocols.protocol.DefaultRunner pygsti.protocols.protocol.ExperimentDesign pygsti.protocols.protocol.CanCreateAllCircuitsDesign pygsti.protocols.protocol.CircuitListsDesign pygsti.protocols.protocol.CombinedExperimentDesign pygsti.protocols.protocol.SimultaneousExperimentDesign pygsti.protocols.protocol.FreeformDesign pygsti.protocols.protocol.ProtocolData pygsti.protocols.protocol.ProtocolResults pygsti.protocols.protocol.MultiPassResults pygsti.protocols.protocol.ProtocolResultsDir pygsti.protocols.protocol.ProtocolPostProcessor pygsti.protocols.protocol.DataSimulator pygsti.protocols.protocol.DataCountsSimulator pygsti.protocols.protocol.ProtocolCheckpoint Functions ~~~~~~~~~ .. autoapisummary:: pygsti.protocols.protocol.run_default_protocols .. py:class:: Protocol(name=None) Bases: :py:obj:`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 :class:`ProtocolData` object and returns a :class:`ProtocolResults` object. This function describes the working of the "protocol". Parameters ---------- name : str, 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 ---------- name : str, 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 .. py:attribute:: collection_name :value: "'pygsti_protocols'" .. py:attribute:: name :value: "'Protocol'" .. py:attribute:: tags .. py:attribute:: auxfile_types .. py:method:: from_dir(dirname, quick_load=False) :classmethod: Initialize a new Protocol object from `dirname`. quick_load : bool, optional Setting this to True skips the loading of components that may take a long time to load. Parameters ---------- dirname : str The directory name. quick_load : bool, optional Setting this to True skips the loading of components that may take a long time to load. Returns ------- Protocol .. py:method:: run(data, memlimit=None, comm=None) :abstractmethod: Run this protocol on `data`. Parameters ---------- data : ProtocolData The input data. memlimit : int, optional A rough per-processor memory limit in bytes. comm : mpi4py.MPI.Comm, optional When not ``None``, an MPI communicator used to run this protocol in parallel. Returns ------- ProtocolResults .. py:method:: write(dirname) Write this protocol to a directory. Parameters ---------- dirname : str The directory name to write. This directory will be created if needed, and the files in an existing directory will be overwritten. Returns ------- None .. py:method:: setup_nameddict(final_dict) Initializes a set of nested :class:`NamedDict` dictionaries describing this protocol. This function is used by :class:`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 :class:`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_dict : NamedDict the final-level (innermost-nested) NamedDict in the returned nested dictionary. Returns ------- NamedDict .. py:class:: MultiPassProtocol(protocol, name=None) Bases: :py:obj:`Protocol` Runs a (contained) :class:`Protocol` on all the passes of a multi-pass :class:`ProtocolData`. A simple protocol that runs a "sub-protocol" on the passes of a :class:`ProtocolData` containing a :class:`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 ---------- protocol : Protocol The protocol to run on each pass. name : str, 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 ---------- protocol : Protocol The protocol to run on each pass. name : str, 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 .. py:attribute:: protocol .. py:method:: run(data, memlimit=None, comm=None) Run this protocol on `data`. Parameters ---------- data : ProtocolData The input data. memlimit : int, optional A rough per-processor memory limit in bytes. comm : mpi4py.MPI.Comm, optional When not ``None``, an MPI communicator used to run this protocol in parallel. Returns ------- MultiPassResults .. py:class:: ProtocolRunner Bases: :py:obj:`object` Used to run :class:`Protocol` objects on an entire *tree* of data This class provides a way of combining multiple calls to :meth:`Protocol.run`, potentially running multiple protocols on different data. From the outside, a :class:`ProtocolRunner` object behaves similarly, and can often be used interchangably, with a Protocol object. It posesses a `run` method that takes a :class:`ProtocolData` as input and returns a :class:`ProtocolResultsDir` that can contain multiple :class:`ProtocolResults` objects within it. .. py:method:: run(data, memlimit=None, comm=None) :abstractmethod: Run all the protocols specified by this protocol-runner on `data`. Parameters ---------- data : ProtocolData The input data. memlimit : int, optional A rough per-processor memory limit in bytes. comm : mpi4py.MPI.Comm, optional When not ``None``, an MPI communicator used to run this protocol-runner in parallel. Returns ------- ProtocolResultsDir .. py:class:: TreeRunner(protocol_dict) Bases: :py:obj:`ProtocolRunner` Runs specific protocols on specific data-tree paths. Parameters ---------- protocol_dict : dict A dictionary of :class:`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_dict : dict A dictionary of :class:`Protocol` objects whose keys are paths (tuples of strings) specifying where in the data-tree that protocol should be run. Returns ------- TreeRunner .. py:attribute:: protocols .. py:method:: run(data, memlimit=None, comm=None) Run all the protocols specified by this protocol-runner on `data`. Parameters ---------- data : ProtocolData The input data. memlimit : int, optional A rough per-processor memory limit in bytes. comm : mpi4py.MPI.Comm, optional When not ``None``, an MPI communicator used to run this protocol-runner in parallel. Returns ------- ProtocolResultsDir .. py:class:: SimpleRunner(protocol, protocol_can_handle_multipass_data=False, edesign_type='all') Bases: :py:obj:`ProtocolRunner` Runs a single protocol on every data node that has no sub-nodes (possibly separately for each pass). Parameters ---------- protocol : Protocol The protocol to run. protocol_can_handle_multipass_data : bool, optional Whether `protocol` is able to process multi-pass data, or if :class:`MultiPassProtocol` objects should be created implicitly. edesign_type : type 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 ---------- protocol : Protocol The protocol to run. protocol_can_handle_multipass_data : bool, optional Whether `protocol` is able to process multi-pass data, or if :class:`MultiPassProtocol` objects should be created implicitly. edesign_type : type or 'all' Only run `protocol` on leaves with this type. (If 'all', then no filtering is performed.) Returns ------- SimpleRunner .. py:attribute:: protocol .. py:attribute:: edesign_type :value: "'all'" .. py:attribute:: do_passes_separately :value: 'True' .. py:method:: run(data, memlimit=None, comm=None) Run all the protocols specified by this protocol-runner on `data`. Parameters ---------- data : ProtocolData The input data. memlimit : int, optional A rough per-processor memory limit in bytes. comm : mpi4py.MPI.Comm, optional When not ``None``, an MPI communicator used to run this protocol-runner in parallel. Returns ------- ProtocolResultsDir .. py:class:: DefaultRunner(run_passes_separately=False) Bases: :py:obj:`ProtocolRunner` Run the default protocol at each data-tree node. (Default protocols are given within :class:`ExperimentDesign` objects.) Parameters ---------- run_passes_separately : bool, 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 :class:`ExperimentDesign` objects.) Parameters ---------- run_passes_separately : bool, 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 .. py:attribute:: run_passes_separately :value: 'False' .. py:method:: run(data, memlimit=None, comm=None) Run all the protocols specified by this protocol-runner on `data`. Parameters ---------- data : ProtocolData The input data. memlimit : int, optional A rough per-processor memory limit in bytes. comm : mpi4py.MPI.Comm, optional When not ``None``, an MPI communicator used to run this protocol-runner in parallel. Returns ------- ProtocolResultsDir .. py:class:: ExperimentDesign(circuits=None, qubit_labels=None, children=None, children_dirs=None) Bases: :py:obj:`pygsti.protocols.treenode.TreeNode`, :py:obj:`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 :class:`Protocol`. Minimally, a :class:`ExperimentDesign` object holds a list of :class:`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 :class:`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 :class:`Protocol` object, and it may be the case that the data described by a single :class:`ExperimentDesign` can be used by muliple protocols). Rather, a :class:`ExperimentDesign` specifies what is necessary to acquire and interpret the *data* needed for one or more QCVV protocols. Parameters ---------- circuits : list of Circuits, optional A list of the circuits needing data. If None, then the list is empty. qubit_labels : tuple 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. children : dict, optional A dictionary of whose values are child :class:`ExperimentDesign` objects and whose keys are the names used to identify them in a "path". children_dirs : dict, 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 :meth:`write`). child_category : str, 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 ---------- circuits : list of Circuits, optional A list of the circuits needing data. If None, then the list is empty. qubit_labels : tuple 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. children : dict, optional A dictionary of whose values are child :class:`ExperimentDesign` objects and whose keys are the names used to identify them in a "path". children_dirs : dict, 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 :meth:`write`). Returns ------- ExperimentDesign .. py:attribute:: collection_name :value: "'pygsti_experiment_designs'" .. py:attribute:: all_circuits_needing_data :value: 'None' .. py:attribute:: alt_actual_circuits_executed :value: 'None' .. py:attribute:: default_protocols .. py:attribute:: tags .. py:attribute:: auxfile_types .. py:method:: from_dir(dirname, parent=None, name=None, quick_load=False) :classmethod: Initialize a new ExperimentDesign object from `dirname`. Parameters ---------- dirname : str The *root* directory name (under which there is a 'edesign' subdirectory). parent : ExperimentDesign, optional The parent design object, if there is one. Primarily used internally - if in doubt, leave this as `None`. name : str, 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_load : bool, 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 .. py:method:: from_edesign(edesign) :classmethod: Create an ExperimentDesign out of an existing experiment design. Parameters ---------- edesign : ExperimentDesign The experiment design to convert (use as a base). Returns ------- ExperimentDesign .. py:method:: 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_circuits : list A list of :class:`Circuit` objects that must be the same length as self.all_circuits_needing_data. Returns ------- None .. py:method:: 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 :class:`DefaultRunner` object to run (all) the default protocols of the experiment designs within a :class:`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_instance : Protocol The protocol to add. This protocol's name is used to index it. Returns ------- None .. py:method:: truncate_to_circuits(circuits_to_keep) Builds a new experiment design containing only the specified circuits. Parameters ---------- circuits_to_keep : list A list of the circuits to keep. Returns ------- ExperimentDesign .. py:method:: truncate_to_available_data(dataset) Builds a new experiment design containing only those circuits present in `dataset`. Parameters ---------- dataset : DataSet The dataset to filter based upon. Returns ------- ExperimentDesign .. py:method:: truncate_to_design(other_design) Truncates this experiment design by only keeping the circuits also in `other_design` Parameters ---------- other_design : ExperimentDesign The experiment design to compare with. Returns ------- ExperimentDesign The truncated experiment design. .. py:method:: write(dirname=None, parent=None) Write this experiment design to a directory. Parameters ---------- dirname : str 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). parent : ExperimentDesign, optional The parent experiment design, when a parent is writing this design as a sub-experiment-design. Otherwise leave as None. Returns ------- None .. py:method:: setup_nameddict(final_dict) Initializes a set of nested :class:`NamedDict` dictionaries describing this design. This function is used by :class:`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 :class:`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_dict : NamedDict the final-level (innermost-nested) NamedDict in the returned nested dictionary. Returns ------- NamedDict .. py:method:: promote_to_combined(name='subdesign-0') Promote this experiment design to be a combined experiment design. Wraps this experiment design in a new :class:`CombinedExperimentDesign` whose only sub-design is this one, and returns the combined design. Parameters ---------- name : str, optional The sub-design-name of this experiment design within the created combined experiment design. Returns ------- CombinedExperimentDesign .. py:method:: promote_to_simultaneous() Promote this experiment design to be a simultaneous experiment design. Wraps this experiment design in a new :class:`SimultaneousExperimentDesign` whose only sub-design is this one, and returns the simultaneous design. Returns ------- SimultaneousExperimentDesign .. py:method:: map_qubit_labels(mapper) Creates a new ExperimentDesign whose circuits' qubit labels are updated according to a given mapping. Parameters ---------- mapper : dict or function A dictionary whose keys are the existing self.qubit_labels values and whose value are the new labels, or a function which takes a single (existing qubit-label) argument and returns a new qubit-label. Returns ------- ExperimentDesign .. py:class:: CanCreateAllCircuitsDesign(circuits=None, qubit_labels=None, children=None, children_dirs=None) Bases: :py:obj:`ExperimentDesign` A type of ExperimentDesign that can create all_circuits_needing_data from subdesigns or other information. In cases where all_circuits_needing_data *can* be recreated, i.e. it has not been modified by the user in some unexpected way, this class will ensure that all_circuits_needing_data is skipped during serialization and regenerated during deserialization. Create a new ExperimentDesign object, which holds a set of circuits (needing data). Parameters ---------- circuits : list of Circuits, optional A list of the circuits needing data. If None, then the list is empty. qubit_labels : tuple 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. children : dict, optional A dictionary of whose values are child :class:`ExperimentDesign` objects and whose keys are the names used to identify them in a "path". children_dirs : dict, 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 :meth:`write`). Returns ------- ExperimentDesign .. py:method:: from_dir(dirname, parent=None, name=None, quick_load=False) :classmethod: Initialize a new ExperimentDesign object from `dirname`. This is specialized to regenerate all_circuits_needing_data if it was not serialized. Parameters ---------- dirname : str The *root* directory name (under which there is a 'edesign' subdirectory). parent : ExperimentDesign, optional The parent design object, if there is one. Primarily used internally - if in doubt, leave this as `None`. name : str, 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_load : bool, 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 .. py:method:: write(dirname=None, parent=None) Write this experiment design to a directory. This is specialized to skip writing all_circuits_needing_data if it can be regenerated from other class information. Parameters ---------- dirname : str 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). parent : ExperimentDesign, optional The parent experiment design, when a parent is writing this design as a sub-experiment-design. Otherwise leave as None. Returns ------- None .. py:class:: CircuitListsDesign(circuit_lists, all_circuits_needing_data=None, qubit_labels=None, nested=False, remove_duplicates=True) Bases: :py:obj:`ExperimentDesign` Experiment design specification that is comprised of multiple circuit lists. Parameters ---------- circuit_lists : list or PlaquetteGridCircuitStructure A list whose elements are themselves lists of :class:`Circuit` objects, specifying the data that needs to be taken. Alternatively, a single :class:`PlaquetteGridCircuitStructure` object containing a sequence of circuits lists, each at a different "x" value (usually the maximum circuit depth). all_circuits_needing_data : list, 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_labels : tuple, optional The qubits that this experiment design applies to. If None, the line labels of the first circuit is used. nested : bool, 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_duplicates : bool, 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_lists : list or PlaquetteGridCircuitStructure A list whose elements are themselves lists of :class:`Circuit` objects, specifying the data that needs to be taken. Alternatively, a single :class:`PlaquetteGridCircuitStructure` object containing a sequence of circuits lists, each at a different "x" value (usually the maximum circuit depth). all_circuits_needing_data : list, 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_labels : tuple, optional The qubits that this experiment design applies to. If None, the line labels of the first circuit is used. nested : bool, 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_duplicates : bool, 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 .. py:attribute:: circuit_lists .. py:attribute:: nested :value: 'False' .. py:method:: from_edesign(edesign) :classmethod: 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 ---------- edesign : ExperimentDesign The experiment design to convert (use as a base). Returns ------- CircuitListsDesign .. py:method:: truncate_to_lists(list_indices_to_keep) Truncates this experiment design by only keeping a subset of its circuit lists. Parameters ---------- list_indices_to_keep : iterable A list of the (integer) list indices to keep. Returns ------- CircuitListsDesign The truncated experiment design. .. py:method:: map_qubit_labels(mapper) Creates a new experiment design whose circuits' qubit labels are updated according to a given mapping. Parameters ---------- mapper : dict or function A dictionary whose keys are the existing self.qubit_labels values and whose value are the new labels, or a function which takes a single (existing qubit-label) argument and returns a new qubit-label. Returns ------- CircuitListsDesign .. py:method:: merge_with(other_edesign, remove_duplicates=True) Merge this experiment design with another one and return the result. Parameters ---------- other_edesign: CircuitListsDesign The other experiment design to merge Returns ------- CircuitListsDesign .. py:class:: CombinedExperimentDesign(sub_designs, all_circuits=None, qubit_labels=None, sub_design_dirs=None, interleave=False) Bases: :py:obj:`CanCreateAllCircuitsDesign` An experiment design that combines the specifications of one or more "sub-designs". The sub-designs are preserved as children under the :class:`CombinedExperimentDesign` instance, creating a "data-tree" structure. The :class:`CombinedExperimentDesign` object itself simply merges all of the circuit lists. Parameters ---------- sub_designs : dict or list A dictionary of other :class:`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 " `subdesign-` " are used. all_circuits : list, optional A list of :class:`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_labels : tuple, optional The qubits that this experiment design applies to. If None, the line labels of the first circuit is used. sub_design_dirs : dict, 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 :meth:`write`). interleave : bool, optional Whether the circuits of the `sub_designs` should be interleaved to form the circuit ordering of this experiment design. DEPRECATED Create a new CombinedExperimentDesign object. Parameters ---------- sub_designs : dict or list A dictionary of other :class:`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 " `subdesign-` " are used. all_circuits : list, optional A list of :class:`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_labels : tuple, optional The qubits that this experiment design applies to. If None, the line labels of the first circuit is used. sub_design_dirs : dict, 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 :meth:`write`). interleave : bool, optional Whether the circuits of the `sub_designs` should be interleaved to form the circuit ordering of this experiment design. Returns ------- CombinedExperimentDesign .. py:method:: from_edesign(edesign, name) :classmethod: 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 ---------- edesign : ExperimentDesign The experiment design to convert (use as a base). name : str The sub-name of `edesign` within the returned combined experiment design. Returns ------- CombinedExperimentDesign .. py:method:: map_qubit_labels(mapper) Creates a new experiment design whose circuits' qubit labels are updated according to a given mapping. Parameters ---------- mapper : dict or function A dictionary whose keys are the existing self.qubit_labels values and whose value are the new labels, or a function which takes a single (existing qubit-label) argument and returns a new qubit-label. Returns ------- CombinedExperimentDesign .. py:class:: SimultaneousExperimentDesign(edesigns, tensored_circuits=None, qubit_labels=None) Bases: :py:obj:`ExperimentDesign` An experiment design whose circuits are the tensor-products of the circuits from one or more sub-designs. The sub-:class:`ExperimentDesign` objects must act on disjoint sets of qubits. The sub-designs are preserved as children under the :class:`SimultaneousExperimentDesign` instance, creating a "data-tree" structure. Parameters ---------- edesigns : list A list of :class:`ExperimentDesign` objects whose circuits are to occur simultaneously. tensored_circuits : list, 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_labels : tuple, 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). category : str, optional The category name for the qubit-label-tuples correspoding to the elements of `edesigns`. Create a new SimultaneousExperimentDesign object. Parameters ---------- edesigns : list A list of :class:`ExperimentDesign` objects whose circuits are to occur simultaneously. tensored_circuits : list, 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_labels : tuple, 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 .. py:method:: from_edesign(edesign) :classmethod: 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 ---------- edesign : ExperimentDesign The experiment design to convert (use as a base). Returns ------- SimultaneousExperimentDesign .. py:method:: map_qubit_labels(mapper) Creates a new experiment design whose circuits' qubit labels are updated according to a given mapping. Parameters ---------- mapper : dict or function A dictionary whose keys are the existing self.qubit_labels values and whose value are the new labels, or a function which takes a single (existing qubit-label) argument and returns a new qubit-label. Returns ------- SimultaneousExperimentDesign .. py:class:: FreeformDesign(circuits, qubit_labels=None) Bases: :py:obj:`CanCreateAllCircuitsDesign` Experiment design holding an arbitrary circuit list and meta data. Parameters ---------- circuits : list or dict A list of the circuits needing data. If None, then the list is empty. qubit_labels : tuple, 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 ---------- circuits : list of Circuits, optional A list of the circuits needing data. If None, then the list is empty. qubit_labels : tuple 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. children : dict, optional A dictionary of whose values are child :class:`ExperimentDesign` objects and whose keys are the names used to identify them in a "path". children_dirs : dict, 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 :meth:`write`). Returns ------- ExperimentDesign .. py:attribute:: aux_info .. py:method:: from_dataframe(df, qubit_labels=None) :classmethod: Create a FreeformDesign from a pandas dataframe. Parameters ---------- df : pandas.Dataframe A dataframe containing a `"Circuit"` column and possibly others. qubit_labels : tuple, optional The qubits that this experiment design applies to. If None, the line labels of the first circuit is used. Returns ------- FreeformDesign .. py:method:: from_edesign(edesign) :classmethod: 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 ---------- edesign : ExperimentDesign The experiment design to convert (use as a base). Returns ------- FreeformDesign .. py:method:: to_dataframe(pivot_valuename=None, pivot_value='Value', drop_columns=False) .. py:method:: map_qubit_labels(mapper) Creates a new experiment design whose circuits' qubit labels are updated according to a given mapping. Parameters ---------- mapper : dict or function A dictionary whose keys are the existing self.qubit_labels values and whose value are the new labels, or a function which takes a single (existing qubit-label) argument and returns a new qubit-label. Returns ------- FreeformDesign .. py:class:: ProtocolData(edesign, dataset=None, cache=None) Bases: :py:obj:`pygsti.protocols.treenode.TreeNode`, :py:obj:`pygsti.baseobjs.mongoserializable.MongoSerializable` Represents the experimental data needed to run one or more QCVV protocols. This class contains a :class:`ProtocolIput`, which describes a set of circuits, and a :class:`DataSet` (or :class:`MultiDataSet`) that holds data for these circuits. These members correspond to the `.edesign` and `.dataset` attributes. Parameters ---------- edesign : ExperimentDesign The experiment design describing what circuits this object contains data for. If None, then an unstructured :class:`ExperimentDesign` is created containing the circuits present in `dataset`. dataset : DataSet or MultiDataSet, optional The data counts themselves. cache : dict, optional A cache of values which holds values derived *only* from the experiment design and data in this object. Attributes ---------- passes : dict A dictionary of the data on a per-pass basis (works even it there's just one pass). Create a new ProtocolData object. Parameters ---------- edesign : ExperimentDesign The experiment design describing what circuits this object contains data for. If None, then an unstructured :class:`ExperimentDesign` is created containing the circuits present in `dataset`. dataset : DataSet or MultiDataSet, optional The data counts themselves. cache : dict, optional A cache of values which holds values derived *only* from the experiment design and data in this object. Returns ------- ProtocolData .. py:property:: passes A dictionary of the data on a per-pass basis (works even it there's just one pass). Returns ------- dict .. py:attribute:: collection_name :value: "'pygsti_protocol_data'" .. py:attribute:: CACHE_COLLECTION_NAME :value: "'pygsti_protocol_data_caches'" .. py:attribute:: edesign .. py:attribute:: dataset :value: 'None' .. py:attribute:: cache :value: 'None' .. py:attribute:: tags .. py:method:: from_dir(dirname, parent=None, name=None, preloaded_edesign=None, quick_load=False, record_zero_counts=True) :classmethod: Initialize a new ProtocolData object from `dirname`. Parameters ---------- dirname : str The *root* directory name (under which there are 'edesign' and 'data' subdirectories). parent : ProtocolData, 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`. name : str, 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_edesign : ExperimentDesign, optional In the case that the :class:`ExperimentDesign` object for `dirname` is already loaded, it can be passed in here. Otherwise leave this as None and it will be loaded. quick_load : bool, 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_counts : bool, optional Whether zero-counts are actually recorded (stored) in the datasets held within this ProtocolData object. Returns ------- ProtocolData .. py:method:: copy() Make a copy of this object. Returns ------- ProtocolData .. py:method:: is_multipass() Whether this protocol data contains multiple passes. More accurately, whether the `.dataset` of this object is a :class:`MultiDataSet`. Returns ------- bool .. py:method:: prune_tree(paths, paths_are_sorted=False) Prune the tree rooted here to include only the given paths, discarding all else. Returns a new :class:`ProtocolData` object with a subset of the data-tree paths contained under this one. Parameters ---------- paths : list A list of the paths to keep. Each path is a tuple of keys, delineating a path in the data-tree. paths_are_sorted : bool, optional Whether `paths` has already been sorted lexographically. Returns ------- ProtocolData .. py:method:: write(dirname=None, parent=None, edesign_already_written=False) Write this protocol data to a directory. Parameters ---------- dirname : str 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). parent : ProtocolData, optional The parent protocol data, when a parent is writing this data as a sub-protocol-data object. Otherwise leave as None. edesign_already_written : bool, 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 .. py:method:: setup_nameddict(final_dict) Initializes a set of nested :class:`NamedDict` dictionaries describing this data. This function is used by :class:`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_dict : NamedDict the final-level (innermost-nested) NamedDict in the returned nested dictionary. Returns ------- NamedDict .. py:method:: to_dataframe(pivot_valuename=None, pivot_value=None, drop_columns=False) Create a Pandas dataframe with this data. Parameters ---------- pivot_valuename : str, optional If not None, the resulting dataframe is pivoted using `pivot_valuename` as the column whose values name the pivoted table's column names. If None and `pivot_value` is not None,`"ValueName"` is used. pivot_value : str, optional If not None, the resulting dataframe is pivoted such that values of the `pivot_value` column are rearranged into new columns whose names are given by the values of the `pivot_valuename` column. If None and `pivot_valuename` is not None,`"Value"` is used. drop_columns : bool or list, optional A list of column names to drop (prior to performing any pivot). If `True` appears in this list or is given directly, then all constant-valued columns are dropped as well. No columns are dropped when `drop_columns == False`. Returns ------- pandas.DataFrame .. py:class:: ProtocolResults(data, protocol_instance) Bases: :py:obj:`pygsti.baseobjs.mongoserializable.MongoSerializable` Stores the results from running a QCVV protocol on data. A :class:`ProtocolResults` object Contains a :class:`ProtocolData` object and stores the results of running a :class:`Protcocol` on this data. Parameters ---------- data : ProtocolData The input data from which these results are derived. protocol_instance : Protocol The protocol that created these results. Create a new ProtocolResults object. Parameters ---------- data : ProtocolData The input data from which these results are derived. protocol_instance : Protocol The protocol that created these results. Returns ------- ProtocolResults .. py:attribute:: collection_name :value: "'pygsti_results'" .. py:attribute:: name .. py:attribute:: protocol .. py:attribute:: data .. py:attribute:: auxfile_types .. py:method:: from_dir(dirname, name, preloaded_data=None, quick_load=False) :classmethod: Initialize a new ProtocolResults object from `dirname` / results / `name`. Parameters ---------- dirname : str The *root* directory name (under which there is are 'edesign', 'data', and 'results' subdirectories). name : str 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_data : ProtocolData, optional In the case that the :class:`ProtocolData` object for `dirname` is already loaded, it can be passed in here. Otherwise leave this as None and it will be loaded. quick_load : bool, 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 .. py:method:: write(dirname=None, data_already_written=False) Write these protocol results to a directory. Parameters ---------- dirname : str The *root* directory to write into. This directory will have 'edesign', 'data', and 'results/' 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_written : bool, optional Set this to True if you're sure the `.data` :class:`ProtocolData` object within this results object has already been written to `dirname`. Leaving this as the default is a safe option. Returns ------- None .. py:method:: to_nameddict() Convert these results into nested :class:`NamedDict` objects. Returns ------- NamedDict .. py:method:: to_dataframe(pivot_valuename=None, pivot_value=None, drop_columns=False) Convert these results into Pandas dataframe. Parameters ---------- pivot_valuename : str, optional If not None, the resulting dataframe is pivoted using `pivot_valuename` as the column whose values name the pivoted table's column names. If None and `pivot_value` is not None,`"ValueName"` is used. pivot_value : str, optional If not None, the resulting dataframe is pivoted such that values of the `pivot_value` column are rearranged into new columns whose names are given by the values of the `pivot_valuename` column. If None and `pivot_valuename` is not None,`"Value"` is used. drop_columns : bool or list, optional A list of column names to drop (prior to performing any pivot). If `True` appears in this list or is given directly, then all constant-valued columns are dropped as well. No columns are dropped when `drop_columns == False`. Returns ------- DataFrame .. py:class:: MultiPassResults(data, protocol_instance) Bases: :py:obj:`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 :class:`ProtcolResults` object within the `.passes` attribute. Parameters ---------- data : ProtocolData The input data from which these results are derived. protocol_instance : Protocol 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 ---------- data : ProtocolData The input data from which these results are derived. protocol_instance : Protocol The protocol that created these results. Returns ------- MultiPassResults .. py:attribute:: passes .. py:method:: from_dir(dirname, name, preloaded_data=None, quick_load=False) :classmethod: Initialize a new MultiPassResults object from `dirname` / results / `name`. Parameters ---------- dirname : str The *root* directory name (under which there is are 'edesign', 'data', and 'results' subdirectories). name : str 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_data : ProtocolData, optional In the case that the :class:`ProtocolData` object for `dirname` is already loaded, it can be passed in here. Otherwise leave this as None and it will be loaded. quick_load : bool, 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 .. py:method:: to_nameddict() Create a :class:`NamedDict` of the results within this object. Returns ------- NamedDict .. py:method:: copy() Make a copy of this object. Returns ------- MultiPassResults .. py:class:: ProtocolResultsDir(data, protocol_results=None, children=None) Bases: :py:obj:`pygsti.protocols.treenode.TreeNode`, :py:obj:`pygsti.baseobjs.mongoserializable.MongoSerializable` Holds a dictionary of :class:`ProtocolResults` objects. It contains a :class:`ProtocolData` object and is rooted at the_model corresponding node of the data-tree. It contains links to child-:class:`ProtocolResultsDir` objects representing sub-directories. This container object holds two things: 1. A `.for_protocol` dictionary of :class:`ProtocolResults` corresponding to different protocols (keys are protocol names). 2. Child :class:`ProtocolResultsDir` objects, obtained by indexing this object directly using the name of the sub-directory. Create a new ProtocolResultsDir object. Parameters ---------- data : ProtocolData The data from which *all* the Results objects in this ProtocolResultsDir are derived. protocol_results : ProtocolResults or dict, optional An initial dictionary of :class:`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. children : dict, optional A dictionary of the :class:`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 .. py:attribute:: collection_name :value: "'pygsti_results_directories'" .. py:attribute:: data .. py:method:: from_dir(dirname, parent=None, name=None, preloaded_data=None, quick_load=False) :classmethod: Initialize a new ProtocolResultsDir object from `dirname`. Parameters ---------- dirname : str The *root* directory name (under which there are 'edesign' and 'data', and possibly 'results', subdirectories). parent : ProtocolResultsDir, optional The parent results-directory object that is loading the returned object as a sub-results. This is used internally when loading a :class:`ProtocolResultsDir` that represents a node of the data-tree with children. name : str, optional The name of this result within `parent`. This is only used when `parent` is not None. preloaded_data : ProtocolData, optional In the case that the :class:`ProtocolData` object for `dirname` is already loaded, it can be passed in here. Otherwise leave this as None and it will be loaded. quick_load : bool, 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 .. py:method:: 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_name : str Name of the protocol to be added. results : ProtocolResults The results object to be added Returns ------- None .. py:method:: write(dirname=None, parent=None, data_already_written=False) Write this "protocol results directory" to a directory. Parameters ---------- dirname : str 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). parent : ProtocolResultsDir, 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_written : bool, 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 .. py:method:: to_nameddict() Convert the results in this object into nested :class:`NamedDict` objects. Returns ------- NamedDict .. py:method:: to_dataframe(pivot_valuename=None, pivot_value=None, drop_columns=False) Convert these results into Pandas dataframe. Parameters ---------- pivot_valuename : str, optional If not None, the resulting dataframe is pivoted using `pivot_valuename` as the column whose values name the pivoted table's column names. If None and `pivot_value` is not None,`"ValueName"` is used. pivot_value : str, optional If not None, the resulting dataframe is pivoted such that values of the `pivot_value` column are rearranged into new columns whose names are given by the values of the `pivot_valuename` column. If None and `pivot_valuename` is not None,`"Value"` is used. drop_columns : bool or list, optional A list of column names to drop (prior to performing any pivot). If `True` appears in this list or is given directly, then all constant-valued columns are dropped as well. No columns are dropped when `drop_columns == False`. Returns ------- DataFrame .. py:function:: run_default_protocols(data, memlimit=None, comm=None) Run the default protocols for the data-tree rooted at `data`. Parameters ---------- data : ProtocolData the data to run default protocols on. memlimit : int, optional A rough per-processor memory limit in bytes. comm : mpi4py.MPI.Comm, optional When not ``None``, an MPI communicator used to run the protocols in parallel. Returns ------- ProtocolResultsDir .. py:class:: ProtocolPostProcessor(name) Bases: :py:obj:`object` Similar to a protocol, but runs on an *existing* :class:`ProtocolResults` object. Running a :class:`ProtocolPostProcessor` produces a new (or updated) :class:`ProtocolResults` object. Parameters ---------- name : str The name of this post-processor. Create a new ProtocolPostProcessor object. Parameters ---------- name : str The name of this post-processor. Returns ------- ProtocolPostProcessor .. py:attribute:: name .. py:attribute:: auxfile_types .. py:method:: from_dir(dirname, quick_load=False) :classmethod: Initialize a new ProtocolPostProcessor object from `dirname`. Parameters ---------- dirname : str The directory name. quick_load : bool, optional Setting this to True skips the loading of components that may take a long time to load. Returns ------- ProtocolPostProcessor .. py:method:: run(results, memlimit=None, comm=None) :abstractmethod: Run this post-processor on `results`. Parameters ---------- results : ProtocolResults The input results. memlimit : int, optional A rough per-processor memory limit in bytes. comm : mpi4py.MPI.Comm, optional When not ``None``, an MPI communicator used to run this post-processor in parallel. Returns ------- ProtocolResults .. py:method:: write(dirname) Write this protocol post-processor to a directory. Parameters ---------- dirname : str The directory to write into. Returns ------- None .. py:class:: DataSimulator Bases: :py:obj:`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 :class:`ExperimentDesign` as input and producing a :class:`ProtocolData` object as output. The produced data may consist of data counts for some/all of the circuit outcomes, and thus result in a :class:`ProtocolData` containsing a normal :class:`DataSet`. Alternatively, a data simulator may compute arbitrary quantities to be associated with the circuits, resulting in a :class:`ProtocolData` containsing a normal :class:`FreeformDataSet`. .. py:method:: run(edesign, memlimit=None, comm=None) :abstractmethod: Run this data simulator on an experiment design. Parameters ---------- edesign : ExperimentDesign The input experiment design. memlimit : int, optional A rough per-processor memory limit in bytes. comm : mpi4py.MPI.Comm, optional When not ``None``, an MPI communicator used to run this data simulator in parallel. Returns ------- ProtocolData .. py:class:: 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: :py:obj:`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 ---------- model : Model The model to simulate. num_samples : int 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 :class:`~pygsti.objects.DataSet`, and total counts are taken from it (on a per-circuit basis). sample_error : string, 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. seed : int, optional If not ``None``, a seed for numpy's random number generator, which is used to sample from the binomial or multinomial distribution. rand_state : numpy.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_dict : dict, 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_counts : bool, 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. times : iterable, 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*. .. py:attribute:: model .. py:attribute:: num_samples :value: '1000' .. py:attribute:: sample_error :value: "'multinomial'" .. py:attribute:: seed :value: 'None' .. py:attribute:: rand_state :value: 'None' .. py:attribute:: alias_dict :value: 'None' .. py:attribute:: collision_action :value: "'aggregate'" .. py:attribute:: record_zero_counts :value: 'True' .. py:attribute:: times :value: 'None' .. py:method:: run(edesign, memlimit=None, comm=None) Run this data simulator on an experiment design. Parameters ---------- edesign : ExperimentDesign The input experiment design. memlimit : int, optional A rough per-processor memory limit in bytes. comm : mpi4py.MPI.Comm, optional When not ``None``, an MPI communicator used to run this data simulator in parallel. Returns ------- ProtocolData .. py:class:: ProtocolCheckpoint(name, parent=None) Bases: :py:obj:`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 ---------- name : str Name of the protocol associated with this checkpoint. parent : ProtocolCheckpoint, 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. .. py:attribute:: name .. py:attribute:: parent :value: 'None' .. py:method:: write(path) Writes this object to a file. Parameters ---------- path : str or Path The name of the file that is written. format_kwargs : dict, 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