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 :class:`Protocol`(s) 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.

Functions

run_default_protocols(data, memlimit=None, comm=None)

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

_convert_nameddict_attributes(obj)

A helper function that converts the elements of the "_nameddict_attributes"

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

Bases: object

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

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.

classmethod from_dir(cls, 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
  • 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

abstract run(self, 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

ProtocolResults

write(self, 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

setup_nameddict(self, 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_dict (NamedDict) – the final-level (innermost-nested) NamedDict in the returned nested dictionary.

Returns

NamedDict

_init_unserialized_attributes(self)

Initialize anything that isn’t serialized based on the things that are serialized. Usually this means initializing things with auxfile_type == ‘none’ that aren’t separately serialized.

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

run(self, 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

class pygsti.protocols.protocol.ProtocolRunner

Bases: object

Used to run :class:`Protocol`(s) on an entire tree of data

This class provides a way of combining multiple calls to :method:`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(self, 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

class pygsti.protocols.protocol.TreeRunner(protocol_dict)

Bases: ProtocolRunner

Runs specific protocols on specific data-tree paths.

Parameters

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

run(self, 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

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
  • protocol (Protocol) – The protocol to run.

  • protocol_can_handle_multipass_data (bool, optional) – Whether protocol is able to process multi-pass data, or if 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.)

run(self, 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

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

run(self, 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

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

Bases: pygsti.protocols.treenode.TreeNode

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
  • 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 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 :method:`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.

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

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

classmethod from_edesign(cls, edesign)

Create an ExperimentDesign out of an existing experiment design.

Parameters

edesign (ExperimentDesign) – The experiment design to convert (use as a base).

Returns

ExperimentDesign

_auto_dirname(self, child_key)

A helper function to generate a default directory name base off of a sub-name key

set_actual_circuits_executed(self, 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 Circuit objects that must be the same length as self.all_circuits_needing_data.

Returns

None

add_default_protocol(self, 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_instance (Protocol) – The protocol to add. This protocol’s name is used to index it.

Returns

None

truncate_to_circuits(self, 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

truncate_to_available_data(self, dataset)

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

Parameters

dataset (DataSet) – The dataset to filter based upon.

Returns

ExperimentDesign

truncate_to_design(self, 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.

_truncate_to_circuits_inplace(self, circuits_to_keep)
_truncate_to_design_inplace(self, other_design)
_truncate_to_available_data_inplace(self, dataset)
write(self, 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

setup_nameddict(self, 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_dict (NamedDict) – the final-level (innermost-nested) NamedDict in the returned nested dictionary.

Returns

NamedDict

abstract _create_subdata(self, subdata_name, dataset)

Creates a ProtocolData object for a sub-experiment-design.

Specifically, this creates the object for the sub-experiment-design given by subdata_name starting from dataset as the data for this experiment design. This is used internally by ProtocolData objects, and shouldn’t need to be used by external users.

Parameters
  • subdata_name (immutable) – The child (node) name of the sub-experiment design to create data for.

  • dataset (DataSet) – The data for this experiment design.

Returns

ProtocolData

promote_to_combined(self, 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

name (str, optional) – The sub-design-name of this experiment design within the created combined experiment design.

Returns

CombinedExperimentDesign

promote_to_simultaneous(self)

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

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_lists (list) – A list whose elements are themselves lists of Circuit objects, specifying the data that needs to be taken.

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

classmethod from_edesign(cls, 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

edesign (ExperimentDesign) – The experiment design to convert (use as a base).

Returns

CircuitListsDesign

truncate_to_lists(self, 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.

_truncate_to_circuits_inplace(self, circuits_to_keep)
_truncate_to_design_inplace(self, other_design)
_truncate_to_available_data_inplace(self, dataset)
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_designs (dict 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_circuits (list, 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_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 :method:`write`).

  • interleave (bool, optional) – Whether the circuits of the sub_designs should be interleaved to form the circuit ordering of this experiment design.

classmethod from_edesign(cls, 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
  • 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

_create_subdata(self, sub_name, dataset)

Creates a ProtocolData object for a sub-experiment-design.

Specifically, this creates the object for the sub-experiment-design given by subdata_name starting from dataset as the data for this experiment design. This is used internally by ProtocolData objects, and shouldn’t need to be used by external users.

Parameters
  • sub_name (immutable) – The child (node) name of the sub-experiment design to create data for.

  • dataset (DataSet) – The data for this experiment design.

Returns

ProtocolData

__setitem__(self, key, val)
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
  • edesigns (list) – A list of 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.

classmethod from_edesign(cls, 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

edesign (ExperimentDesign) – The experiment design to convert (use as a base).

Returns

SimultaneousExperimentDesign

_create_subdata(self, qubit_labels, dataset)

Creates a ProtocolData object for a sub-experiment-design.

Specifically, this creates the object for the sub-experiment-design given by subdata_name starting from dataset as the data for this experiment design. This is used internally by ProtocolData objects, and shouldn’t need to be used by external users.

Parameters
  • qubit_labels (tuple) – The child (node) label of the sub-experiment design to create data for.

  • dataset (DataSet) – The data for this experiment design.

Returns

ProtocolData

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

Bases: ExperimentDesign

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.

classmethod from_dataframe(cls, df, qubit_labels=None)

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

classmethod from_edesign(cls, 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

edesign (ExperimentDesign) – The experiment design to convert (use as a base).

Returns

FreeformDesign

_truncate_to_circuits_inplace(self, circuits_to_keep)
to_dataframe(self, pivot_valuename=None, pivot_value='Value', drop_columns=False)
class pygsti.protocols.protocol.ProtocolData(edesign, dataset=None, cache=None)

Bases: pygsti.protocols.treenode.TreeNode

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
  • edesign (ExperimentDesign) – 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.

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

passes

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

Type

dict

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

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

Returns

ProtocolData

__getstate__(self)
__setstate__(self, state_dict)
_create_childval(self, key)

Create the value for key on demand.

copy(self)

Make a copy of this object.

Returns

ProtocolData

property passes(self)

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

Returns

dict

is_multipass(self)

Whether this protocol data contains multiple passes.

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

Returns

bool

prune_tree(self, 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
  • 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

write(self, dirname=None, parent=None)

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.

Returns

None

setup_nameddict(self, 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_dict (NamedDict) – the final-level (innermost-nested) NamedDict in the returned nested dictionary.

Returns

NamedDict

to_dataframe(self, 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

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

Bases: object

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
  • data (ProtocolData) – The input data from which these results are derived.

  • protocol_instance (Protocol) – The protocol that created these results.

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

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

classmethod _from_dir_partial(cls, dirname, quick_load=False, load_protocol=False)

Internal method for loading only the results-specific data, and not the data member. This method may be used independently by derived ProtocolResults objecsts which contain multiple sub-results (e.g. MultiPassResults)

write(self, 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/<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_written (bool, 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

_write_partial(self, results_dir, write_protocol=False)

Internal method used to write the results-specific data to a directory. This method does not write the object’s data member, which must be serialized separately.

to_nameddict(self)

Convert these results into nested NamedDict objects.

Returns

NamedDict

_my_attributes_as_nameddict(self)
to_dataframe(self, 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

__str__(self)

Return str(self).

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
  • data (ProtocolData) – The input data from which these results are derived.

  • protocol_instance (Protocol) – The protocol that created these results.

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

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

to_nameddict(self)

Create a NamedDict of the results within this object.

Returns

NamedDict

copy(self)

Make a copy of this object.

Returns

MultiPassResults

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

Bases: pygsti.protocols.treenode.TreeNode

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: 1. A .for_protocol dictionary of ProtocolResults corresponding

to different protocols (keys are protocol names).

  1. Child ProtocolResultsDir objects, obtained by indexing this object directly using the name of the sub-directory.

Parameters
  • data (ProtocolData) – The data from which all the Results objects in this ProtocolResultsDir are derived.

  • protocol_results (ProtocolResults, 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.

  • children (dict, 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.)

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

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

_create_childval(self, key)

Create the value for key on demand.

write(self, dirname=None, parent=None)

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.

Returns

None

_result_namedicts_on_this_node(self)
_addto_bypath_nameddict(self, dest, path)
to_nameddict(self)

Convert the results in this object into nested NamedDict objects.

Returns

NamedDict

to_dataframe(self, 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

__str__(self)

Return str(self).

pygsti.protocols.protocol.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

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

name (str) – The name of this post-processor.

classmethod from_dir(cls, dirname, quick_load=False)

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

_init_unserialized_attributes(self)
abstract run(self, results, memlimit=None, comm=None)

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

write(self, dirname)

Write this protocol post-processor to a directory.

Parameters

dirname (str) – 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(self, 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

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

run(self, 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

pygsti.protocols.protocol._convert_nameddict_attributes(obj)

A helper function that converts the elements of the “_nameddict_attributes” attribute of several classes to the (key, value, type) array expected by :method:`NamedDict.create_nested`.