pygsti.circuits.circuitstructure.PlaquetteGridCircuitStructure

pygsti.circuits.circuitstructure.PlaquetteGridCircuitStructure#

class PlaquetteGridCircuitStructure(plaquettes, x_values, y_values, xlabel, ylabel, additional_circuits=None, op_label_aliases=None, circuit_rules=None, circuit_weights_dict=None, additional_circuits_location='start', name=None)#

Bases: CircuitList

Encapsulates a set of circuits, along with an associated structure.

By “structure”, we mean the ability to index the circuits by a 4-tuple (x, y, minor_x, minor_y) for displaying in nested color box plots, along with any aliases.

Create a CircuitList.

Parameters:

  • circuits (list) – The list of circuits that constitutes the primary data held by this object.

  • op_label_aliases (dict, optional) – Dictionary of circuit meta-data whose keys are operation label “aliases” and whose values are circuits corresponding to what that operation label should be expanded into before querying the dataset. Defaults to the empty dictionary (no aliases defined). e.g. op_label_aliases[‘Gx^3’] = pygsti.baseobjs.Circuit([‘Gx’,’Gx’,’Gx’])

  • circuit_rules (list, optional) – A list of (find,replace) 2-tuples which specify circuit-label replacement rules. Both find and replace are tuples of operation labels (or Circuit objects).

  • circuit_weights (numpy.ndarray, optional) – If not None, an array of per-circuit weights (of length equal to the number of circuits) that are typically used to multiply the counts extracted for each circuit.

  • name (str, optional) – An optional name for this list, used for status messages.

Methods

__init__(plaquettes, x_values, y_values, ...)

Create a CircuitList.

add_mongodb_write_ops(write_ops, mongodb[, ...])

Accumulate write and update operations for writing this object to a MongoDB database.

apply_aliases()

Applies any operation-label aliases to this circuit list.

cast(circuits_or_structure)

Convert (if needed) an object into a circuit structure.

copy()

Returns a copy of this circuit structure.

dump(f[, format])

Serializes and writes this object to a given output stream.

dumps([format])

Serializes this object and returns it as a string.

elementvec_to_array(elementvec, layout[, ...])

Form an array of values corresponding to this CircuitList from an element vector.

from_mongodb(mongodb, doc_id, **kwargs)

Create and initialize an object from a MongoDB instance.

from_mongodb_doc(mongodb, collection_name, ...)

Create and initialize an object from a MongoDB instance and pre-loaded primary document.

from_nice_serialization(state)

Create and initialize an object from a "nice" serialization.

iter_plaquettes()

load(f[, format])

Load an object of this type, or a subclass of this type, from an input stream.

loads(s[, format])

Load an object of this type, or a subclass of this type, from a string.

nested_truncations([axis, keep_rows_cols])

Get the nested truncations of this circuit structure along an axis.

plaquette(x, y[, empty_if_missing])

The plaquette at (x,y).

process_circuits(processor_fn[, updated_aliases])

Create a new plaquette with circuits manipulated according to processor_fn.

read(path[, format])

Read an object of this type, or a subclass of this type, from a file.

remove_from_mongodb(mongodb, doc_id[, ...])

Remove the documents corresponding to an instance of this class from a MongoDB database.

remove_me_from_mongodb(mongodb[, session, ...])

tensor_circuits(other_circuitlist[, new_name])

Given two CircuitList objects, X(=self) and Y(=other_circuitlist), of the same length, combine the two of them so that every Circuit within X is tensored with the corresponding Circuit in Y.

to_nice_serialization()

Serialize this object in a way that adheres to "niceness" rules of common text file formats.

truncate([circuits_to_keep, xs_to_keep, ...])

Truncate this circuit structure to a subset of its current circuits.

truncate_to_dataset(dataset)

Builds a new circuit list containing only those elements in dataset.

write(path, **format_kwargs)

Writes this object to a file.

write_to_mongodb(mongodb[, session, ...])

Write this object to a MongoDB database.

Attributes

collection_name

plaquettes

used_xs

The x-values which have at least one non-empty plaquette

used_ys

The y-values which have at least one non-empty plaquette
add_mongodb_write_ops(write_ops, mongodb, overwrite_existing=False, **kwargs)#

Accumulate write and update operations for writing this object to a MongoDB database.

Similar to write_to_mongodb() but collects write operations instead of actually executing any write operations on the database. This function may be preferred to write_to_mongodb() when this object is being written as a part of a larger entity and executing write operations is saved until the end.

As in write_to_mongodb(), self.collection_name is the collection name and _id is either: 1) the ID used by a previous write or initial read-in, if one exists, OR 2) a new random bson.objectid.ObjectId

Parameters:

  • write_ops (WriteOpsByCollection) – An object that keeps track of pymongo write operations on a per-collection basis. This object accumulates write operations to be performed at some point in the future.

  • mongodb (pymongo.database.Database) – The MongoDB instance to write data to.

  • overwrite_existing (bool, optional) – Whether existing documents should be overwritten. The default of False causes a ValueError to be raised if a document with the given _id already exists and is different from what is being written.

  • **kwargs (dict) – Additional keyword arguments potentially used by subclass implementations. Any arguments allowed by a subclass’s _add_auxiliary_write_ops_and_update_doc method is allowed here.

Returns:

The identifier (_id value) of the main document that was written.

Return type:

bson.objectid.ObjectId

apply_aliases()#

Applies any operation-label aliases to this circuit list.

Returns:

A list of Circuit objects.

Return type:

list

classmethod cast(circuits_or_structure)#

Convert (if needed) an object into a circuit structure.

Parameters:

circuits_or_structure (list or CircuitList) – The object to convert. If a PlaquetteGridCircuitStructure, then the object is simply returned. Lists of circuits (including CircuitList objects are converted to structures having no plaquettes.

Return type:

PlaquetteGridCircuitStructure

copy()#

Returns a copy of this circuit structure.

Return type:

PlaquetteGridCircuitStructure

dump(f, format='json', **format_kwargs)#

Serializes and writes this object to a given output stream.

Parameters:

  • f (file-like) – A writable output stream.

  • format ({'json', 'repr'}) – The format to write.

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

Return type:

None

dumps(format='json', **format_kwargs)#

Serializes this object and returns it as a string.

Parameters:

  • format ({'json', 'repr'}) – The format to write.

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

Return type:

str

elementvec_to_array(elementvec, layout, mergeop='sum')#

Form an array of values corresponding to this CircuitList from an element vector.

An element vector holds individual-outcome elements (e.g. the bulk probabilities computed by a model).

Parameters:

  • elementvec (numpy array) – An array containing the values to use when constructing a matrix of values for this CircuitList. This array may contain more values than are needed by this CircuitList. Indices into this array are given by elindices_lookup.

  • layout (CircuitOutcomeProbabilityArrayLayout) – The layout of elementvec, giving the mapping between its elements and circuit outcomes.

  • mergeop ("sum" or format string, optional) – Dictates how to combine the elementvec components corresponding to a single plaquette entry (circuit). If “sum”, the returned array contains summed values. If a format string, e.g. “%.2f”, then the so-formatted components are joined together, and the resulting array contains string (object-type) entries.

Return type:

numpy array

classmethod from_mongodb(mongodb, doc_id, **kwargs)#

Create and initialize an object from a MongoDB instance.

Parameters:

  • mongodb (pymongo.database.Database) – The MongoDB instance to load from.

  • doc_id (bson.objecctid.ObjectId or dict) – The object ID or filter used to find a single object ID within the database. This document is loaded from the collection given by the collection_name attribute of this class.

  • **kwargs (dict) – Additional keyword arguments potentially used by subclass implementations. Any arguments allowed by a subclass’s _create_obj_from_doc_and_mongodb method is allowed here.

Return type:

object

classmethod from_mongodb_doc(mongodb, collection_name, doc, **kwargs)#

Create and initialize an object from a MongoDB instance and pre-loaded primary document.

Parameters:

  • mongodb (pymongo.database.Database) – The MongoDB instance to load from.

  • collection_name (str) – The collection name within mongodb that doc was loaded from. This is needed for the sole purpose of setting the created (returned) object’s database “coordinates”.

  • doc (dict) – The already-retrieved main document for the object being loaded. This takes the place of giving an identifier for this object.

  • **kwargs (dict) – Additional keyword arguments potentially used by subclass implementations. Any arguments allowed by a subclass’s _create_obj_from_doc_and_mongodb method is allowed here.

Return type:

object

classmethod from_nice_serialization(state)#

Create and initialize an object from a “nice” serialization.

A “nice” serialization here means one created by a prior call to to_nice_serialization using this class or a subclass of it. Nice serializations adhere to additional rules (e.g. that dictionary keys must be strings) that make them amenable to common file formats (e.g. JSON).

The state argument is typically a dictionary containing ‘module’ and ‘state’ keys specifying the type of object that should be created. This type must be this class or a subclass of it.

Parameters:

state (object) – An object, usually a dictionary, representing the object to de-serialize.

Return type:

object

classmethod load(f, format='json')#

Load an object of this type, or a subclass of this type, from an input stream.

Parameters:

  • f (file-like) – An open input stream to read from.

  • format ({'json'}) – The format of the input stream data.

Return type:

NicelySerializable

classmethod loads(s, format='json')#

Load an object of this type, or a subclass of this type, from a string.

Parameters:

  • s (str) – The serialized object.

  • format ({'json'}) – The format of the string data.

Return type:

NicelySerializable

nested_truncations(axis='x', keep_rows_cols=False)#

Get the nested truncations of this circuit structure along an axis.

When axis == ‘x’, a list of truncations (of this structure) that keep an incrementally larger set of all the x-values. E.g., if the x-values are [1,2,4], truncations to [1], [1,2], and [1,2,4] (no truncation) would be returned.

Setting axis ==’y’ gives the same behavior except using the y-values.

Parameters:

  • axis ({'x', 'y'}) – Which axis to truncate along (see above).

  • keep_rows_cols (bool) – Whether to retain the same number of rows as columns (even if entire rows and/or columns are empty).

Returns:

A list of PlaquetteGridCircuitStructure objects (truncations of this object).

Return type:

list

plaquette(x, y, empty_if_missing=False)#

The plaquette at (x,y).

Parameters:

  • x (various) – x-value (not index)

  • y (various) – y-value (not index)

  • empty_if_missing (bool, optional) – Whether an empty (0-element) plaquette should be returned when the requested (x,y) is missing.

Return type:

CircuitPlaquette

process_circuits(processor_fn, updated_aliases=None)#

Create a new plaquette with circuits manipulated according to processor_fn.

Parameters:

  • processor_fn (function) – A function which takes a single Circuit argument and returns another (or the same) Circuit.

  • updated_aliases (dict, optional) – Because the Label keys of an alias dictionary (maps Label -> Circuit) cannot be processed as a Circuit, one must supply a manually processed alias dictionary. If you don’t use alias dictionaries just leave this set to None.

Return type:

PlaquetteGridCircuitStructure

classmethod read(path, format=None)#

Read an object of this type, or a subclass of this type, from a file.

Parameters:

  • path (str or Path or file-like) – The filename to open or an already open input stream.

  • format ({'json', None}) – The format of the file. If None this is determined automatically by the filename extension of a given path.

Return type:

NicelySerializable

classmethod remove_from_mongodb(mongodb, doc_id, collection_name=None, session=None, recursive='default')#

Remove the documents corresponding to an instance of this class from a MongoDB database.

Parameters:

  • mongodb (pymongo.database.Database) – The MongoDB instance to remove documents from.

  • doc_id (bson.objectid.ObjectId) – The identifier of the root document stored in the database.

  • collection_name (str, optional) – the MongoDB collection within mongodb where the main document resides. If None, then <this_class>.collection_name is used (which is usually what you want).

  • session (pymongo.client_session.ClientSession, optional) – MongoDB session object to use when interacting with the MongoDB database. This can be used to implement transactions among other things.

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

Return type:

None

tensor_circuits(other_circuitlist, new_name=None)#

Given two CircuitList objects, X(=self) and Y(=other_circuitlist), of the same length, combine the two of them so that every Circuit within X is tensored with the corresponding Circuit in Y.

Returns:

CircuitList with the subcircuits tensored together.

Parameters:

  • other_circuitlist (CircuitList)

  • new_name (str | None)

Notes

TODO: Remove this function or change its behavior to something more useful.

to_nice_serialization()#

Serialize this object in a way that adheres to “niceness” rules of common text file formats.

Returns:

Usually a dictionary representing the serialized object, but may also be another native Python type, e.g. a string or list.

Return type:

object

truncate(circuits_to_keep=None, xs_to_keep=None, ys_to_keep=None, keep_rows_cols=True)#

Truncate this circuit structure to a subset of its current circuits.

Parameters:

  • circuits_to_keep (list) – Keep only the circuits present in this list (of Circuit objects).

  • xs_to_keep (list, optional) – The x-values to keep. If None, then all are kept.

  • ys_to_keep (list, optional) – The y-values to keep. If None, then all are kept.

  • keep_rows_cols (bool) – Whether to retain the same number of rows as columns (even if entire rows and/or columns are empty). By default, this is True because we usually want all the plaquettes of a PlaquetteGridCircuitStructure to have the same number of rows and columns.

Return type:

PlaquetteGridCircuitStructure

truncate_to_dataset(dataset)#

Builds a new circuit list containing only those elements in dataset.

Parameters:

dataset (DataSet) – The dataset to check. Aliases are applied to the circuits in this circuit list before they are tested.

Return type:

CircuitList

write(path, **format_kwargs)#

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.

Return type:

None

write_to_mongodb(mongodb, session=None, overwrite_existing=False, **kwargs)#

Write this object to a MongoDB database.

The collection name used is self.collection_name, and the _id is either: 1) the ID used by a previous write or initial read-in, if one exists, OR 2) a new random bson.objectid.ObjectId

Parameters:

  • mongodb (pymongo.database.Database) – The MongoDB instance to write data to.

  • session (pymongo.client_session.ClientSession, optional) – MongoDB session object to use when interacting with the MongoDB database. This can be used to implement transactions among other things.

  • overwrite_existing (bool, optional) – Whether existing documents should be overwritten. The default of False causes a ValueError to be raised if a document with the given _id already exists and is different from what is being written.

  • **kwargs (dict) – Additional keyword arguments potentially used by subclass implementations. Any arguments allowed by a subclass’s _add_auxiliary_write_ops_and_update_doc method is allowed here.

Returns:

The identifier (_id value) of the main document that was written.

Return type:

bson.objectid.ObjectId

property used_xs#

The x-values which have at least one non-empty plaquette

Return type:

list

property used_ys#

The y-values which have at least one non-empty plaquette

Return type:

list