pygsti.baseobjs.statespace.ExplicitStateSpace

pygsti.baseobjs.statespace.ExplicitStateSpace#

class ExplicitStateSpace(label_list, udims=None, types=None)#

Bases: StateSpace

A customizable definition of a state space.

An ExplicitStateSpace object describes, using string/int labels, how an entire Hilbert state space is decomposed into the direct sum of terms which themselves are tensor products of smaller (typically qubit-sized) Hilbert spaces.

Parameters:

label_list (str or int or iterable) –
Most generally, this can be a list of tuples, where each tuple contains the state-space labels (which can be strings or integers) for a single “tensor product block” formed by taking the tensor product of the spaces associated with the labels. The full state space is the direct sum of all the tensor product blocks. E.g. [(‘Q0’,’Q1’), (‘Q2’,)].

If just an iterable of labels is given, e.g. (‘Q0’,’Q1’), it is assumed to specify the first and only tensor product block.

If a single state space label is given, e.g. ‘Q2’, then it is assumed to completely specify the first and only tensor product block.
udims (int or iterable, optional) –
The dimension of each state space label as an integer, tuple of integers, or list or tuples of integers to match the structure of label_list. e.g., if label_list=(‘Q0’,’Q1’) then udims should be a tuple of 2 integers, or if label_list=’Q0’ then udims should be an integer. Values specify unitary evolution state-space dimensions, i.e. 2 for a qubit, 3 for a qutrit, etc. If None, then the dimensions are inferred, if possible, from the following naming rules:
- if the label starts with ‘L’, udim=1 (a single Level)
- if the label starts with ‘Q’ OR is an int, udim=2 (a Qubit)
- if the label starts with ‘T’, udim=3 (a quTrit)
types (str or iterable, optional) – A list of label types, either ‘Q’ or ‘C’ for “quantum” and “classical” respectively, indicating the type of state-space associated with each label. Like dims, types must match the structure of label_list. A quantum state space of dimension d is a d-by-d density matrix, whereas a classical state space of dimension d is a vector of d probabilities. If None, then all labels are assumed to be quantum.

Methods

`__init__`(label_list[, udims, types])
`add_mongodb_write_ops`(write_ops, mongodb[, ...])	Accumulate write and update operations for writing this object to a MongoDB database.
`cast`(obj)	Casts obj into a `StateSpace` object if possible.
`contains_label`(label)	True if this state space contains a given label.
`contains_labels`(labels)	True if this state space contains all of a given set of labels.
`copy`()	Return a copy of this StateSpace.
`create_stencil_subspace`(labels)	Create a template sub-StateSpace object from a set of potentially stencil-type labels.
`create_subspace`(labels)	Create a sub-StateSpace object from a set of existing labels.
`difference`(other_state_space)	Create a state space whose labels are the difference of the labels of this space and one other.
`dump`(f[, format])	Serializes and writes this object to a given output stream.
`dumps`([format])	Serializes this object and returns it as a string.
`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.
`intersection`(other_state_space)	Create a state space whose labels are the intersection of the labels of this space and one other.
`is_compatible_with`(other_state_space)	Whether another state space is compatible with this one.
`is_entire_space`(labels)	True if this state space is a single tensor product block with (exactly, in order) the given set of labels.
`label_dimension`(label)	The superoperator dimension of the given label (from any tensor product block)
`label_tensor_product_block_index`(label)	The index of the tensor product block containing the given label.
`label_type`(label)	The type (quantum or classical) of the given label (from any tensor product block).
`label_udimension`(label)	The unitary operator dimension of the given label (from any tensor product block)
`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.
`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_product_block_dimensions`(i_tpb)	The superoperator dimensions for the factors in the iTBP-th tensor-product block.
`tensor_product_block_labels`(i_tpb)	The labels for the iTBP-th tensor-product block.
`tensor_product_block_udimensions`(i_tpb)	The unitary-operator dimensions for the factors in the iTBP-th tensor-product block.
`to_nice_serialization`()	Serialize this object in a way that adheres to "niceness" rules of common text file formats.
`union`(other_state_space)	Create a state space whose labels are the union of the labels of this space and one other.
`write`(path, **format_kwargs)	Writes this object to a file.
`write_to_mongodb`(mongodb[, session, ...])	Write this object to a MongoDB database.

Attributes

`Castable`	alias of `StateSpace` \| `int` \| `list`[`int`] \| `list`[`str`]
`collection_name`
`common_dimension`	Returns the common super-op dimension of all the labels in this space.
`common_udimension`	Returns the common unitary-op dimension of all the labels in this space.
`dim`	Integer Hilbert-Schmidt (super-operator) or classical dimension of this state space.
`is_entirely_qubits`	Whether this state space is just the tensor product of qubit subspaces.
`labels`	The labels for all the tensor-product blocks.
`num_qubits`	The number of qubits in this quantum state space.
`num_qudits`	The number of qudits in this quantum state space.
`num_tensor_product_blocks`	The number of tensor-product blocks which are direct-summed to get the final state space.
`sole_tensor_product_block_labels`	The labels of the first and only tensor product block within this state space.
`state_space_labels`	Return a tuple corresponding to the concatenation of the constituent state space labels within each tensor product block of this StateSpace object.
`tensor_product_blocks_dimensions`	The superoperator dimensions for all the tensor-product blocks.
`tensor_product_blocks_labels`	The labels for all the tensor-product blocks.
`tensor_product_blocks_types`	The type (quantum vs classical) of all the tensor-product blocks.
`tensor_product_blocks_udimensions`	The unitary operator dimensions for all the tensor-product blocks.
`udim`	Integer Hilbert (unitary operator) space dimension of this quantum state space.

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

classmethod cast(obj)#

Casts obj into a StateSpace object if possible.

If obj is already of this type, it is simply returned without modification.

Parameters:: obj (StateSpace or int or list) – Either an already-built state space object or an integer specifying the number of qubits, or a list of labels as would be provided to the first argument of ExplicitStateSpace.__init__().
Return type:: StateSpace

contains_label(label)#

True if this state space contains a given label.

Parameters:: label (str or int) – the label to test for.
Return type:: bool

contains_labels(labels)#

True if this state space contains all of a given set of labels.

Parameters:: labels (iterable) – the labels to test.
Return type:: bool

copy()#

Return a copy of this StateSpace.

Return type:: StateSpace

create_stencil_subspace(labels)#

Create a template sub-StateSpace object from a set of potentially stencil-type labels.

That is, the elements of labels don’t need to actually exist within this state space – they may be stencil labels that will resolve to a label in this state space later on.

Parameters:: labels (iterable) – The labels to include in the returned state space.
Return type:: StateSpace

create_subspace(labels)#

Create a sub-StateSpace object from a set of existing labels.

Parameters:: labels (iterable) – The labels to include in the returned state space.
Return type:: StateSpace

difference(other_state_space)#

Create a state space whose labels are the difference of the labels of this space and one other. I.e. a state space containing the labels of this space which don’t appear in the other.

Dimensions associated with the labels are preserved, as is the tensor product block index. If the two spaces have the same label, but their dimensions or indices do not agree, an error is raised.

Parameters:: other_state_space (StateSpace) – The other state space.
Return type:: StateSpace

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

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

intersection(other_state_space)#

Create a state space whose labels are the intersection of the labels of this space and one other.

Dimensions associated with the labels are preserved, as is the ordering of tensor product blocks. If the two spaces have the same label, but their dimensions or indices do not agree, an error is raised.

Parameters:: other_state_space (StateSpace) – The other state space.
Return type:: StateSpace

is_compatible_with(other_state_space)#

Whether another state space is compatible with this one.

Two state spaces are considered “compatible” when their overall dimensions agree (even if their tensor product block structure and labels do not). (This checks whether the Hilbert spaces are isomorphic.)

Parameters:: other_state_space (StateSpace) – The state space to check compatibility with.
Return type:: bool

is_entire_space(labels)#

True if this state space is a single tensor product block with (exactly, in order) the given set of labels.

Parameters:: labels (iterable) – the labels to test.
Return type:: bool

label_dimension(label)#

The superoperator dimension of the given label (from any tensor product block)

Parameters:: label (str or int) – The label whose dimension should be retrieved.
Return type:: int

label_tensor_product_block_index(label)#

The index of the tensor product block containing the given label.

Parameters:: label (str or int) – The label whose index should be retrieved.
Return type:: int

label_type(label)#

The type (quantum or classical) of the given label (from any tensor product block).

Parameters:: label (str or int) – The label whose type should be retrieved.
Return type:: str

label_udimension(label)#

The unitary operator dimension of the given label (from any tensor product block)

Parameters:: label (str or int) – The label whose dimension should be retrieved.
Return type:: int

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

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_product_block_dimensions(i_tpb)#

The superoperator dimensions for the factors in the iTBP-th tensor-product block.

Parameters:: i_tpb (int) – Tensor-product block index.
Return type:: tuple

tensor_product_block_labels(i_tpb)#

The labels for the iTBP-th tensor-product block.

Parameters:: i_tpb (int) – Tensor-product block index.
Return type:: tuple

tensor_product_block_udimensions(i_tpb)#

The unitary-operator dimensions for the factors in the iTBP-th tensor-product block.

Parameters:: i_tpb (int) – Tensor-product block index.
Return type:: tuple

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

union(other_state_space)#

Create a state space whose labels are the union of the labels of this space and one other.

Dimensions associated with the labels are preserved, as is the tensor product block index. If the two spaces have the same label, but their dimensions or indices do not agree, an error is raised.

Parameters:: other_state_space (StateSpace) – The other state space.
Return type:: StateSpace

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

Returns the common super-op dimension of all the labels in this space.

If not all the labels in this space have the same dimension, then None is returned to indicate this.

This property is useful when working with stencils, where operations are created for a “stencil space” that is not exactly a subspace of a StateSpace space but will be mapped to one in the future.

Return type:: int or None

property common_udimension#

Returns the common unitary-op dimension of all the labels in this space.

If not all the labels in this space have the same dimension, then None is returned to indicate this.

This property is useful when working with stencils, where operations are created for a “stencil space” that is not exactly a subspace of a StateSpace space but will be mapped to one in the future.

Return type:: int or None

property dim#: Integer Hilbert-Schmidt (super-operator) or classical dimension of this state space.

property is_entirely_qubits#

Whether this state space is just the tensor product of qubit subspaces.

Return type:: bool

property labels#

The labels for all the tensor-product blocks.

Return type:: tuple of tuples

property num_qubits#

The number of qubits in this quantum state space.

Raises a ValueError if this state space doesn’t consist entirely of qubits.

property num_qudits#

The number of qudits in this quantum state space.

Raises a ValueError if this state space doesn’t consist entirely of qudits.

property num_tensor_product_blocks#

The number of tensor-product blocks which are direct-summed to get the final state space.

Return type:: int

property sole_tensor_product_block_labels#

The labels of the first and only tensor product block within this state space.

If there are multiple blocks, a ValueError is raised.

property state_space_labels#

Return a tuple corresponding to the concatenation of the constituent state space labels within each tensor product block of this StateSpace object.

Returns:: flattened_state_space_label_list – A tuple containing a flattened list of all of the state space labels appearing within the tensor product blocks of this StateSpace objects label list.
Return type:: tuple

property tensor_product_blocks_dimensions#

The superoperator dimensions for all the tensor-product blocks.

Return type:: tuple of tuples

property tensor_product_blocks_labels#

The labels for all the tensor-product blocks.

Return type:: tuple of tuples

property tensor_product_blocks_types#

The type (quantum vs classical) of all the tensor-product blocks.

Return type:: tuple of tuples

property tensor_product_blocks_udimensions#

The unitary operator dimensions for all the tensor-product blocks.

Return type:: tuple of tuples

property udim#

Integer Hilbert (unitary operator) space dimension of this quantum state space.

Raises an error if this space is not a quantum state space.

pygsti.baseobjs.statespace.ExplicitStateSpace

Contents

pygsti.baseobjs.statespace.ExplicitStateSpace#