pygsti.baseobjs.statespace

Defines OrderedDict-derived classes used to store specific pyGSTi objects

Module Contents

Classes

StateSpace

Base class for defining a state space (Hilbert or Hilbert-Schmidt space).

QuditSpace

A state space consisting of N qudits.

QubitSpace

A state space consisting of N qubits.

ExplicitStateSpace

A customizable definition of a state space.

Functions

default_space_for_dim(dim)

Create a state space for a given superoperator dimension.

default_space_for_udim(udim)

Create a state space for a given unitary operator dimension.

default_space_for_num_qubits(num_qubits)

Create a state space for a given number of qubits.

class pygsti.baseobjs.statespace.StateSpace

Bases: pygsti.baseobjs.nicelyserializable.NicelySerializable

Base class for defining a state space (Hilbert or Hilbert-Schmidt space).

This base class just sets the API for a “state space” in pyGSTi, accessed as the direct sum of one or more tensor products of Hilbert spaces.

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

abstract property dim

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

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

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

abstract property num_tensor_product_blocks

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

Returns

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.

abstract property tensor_product_blocks_labels

The labels for all the tensor-product blocks.

Returns

tuple of tuples

abstract property tensor_product_blocks_dimensions

The superoperator dimensions for all the tensor-product blocks.

Returns

tuple of tuples

abstract property tensor_product_blocks_udimensions

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

Returns

tuple of tuples

abstract property tensor_product_blocks_types

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

Returns

tuple of tuples

property is_entirely_qubits

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

Returns

bool

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.

Returns

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.

Returns

int or None

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_listtuple

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.

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

objStateSpace 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__().

Returns

StateSpace

abstract label_dimension(label)

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

Parameters

labelstr or int

The label whose dimension should be retrieved.

Returns

int

abstract label_udimension(label)

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

Parameters

labelstr or int

The label whose dimension should be retrieved.

Returns

int

abstract label_tensor_product_block_index(label)

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

Parameters

labelstr or int

The label whose index should be retrieved.

Returns

int

abstract label_type(label)

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

Parameters

labelstr or int

The label whose type should be retrieved.

Returns

str

tensor_product_block_labels(i_tpb)

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

Parameters

i_tpbint

Tensor-product block index.

Returns

tuple

tensor_product_block_dimensions(i_tpb)

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

Parameters

i_tpbint

Tensor-product block index.

Returns

tuple

tensor_product_block_udimensions(i_tpb)

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

Parameters

i_tpbint

Tensor-product block index.

Returns

tuple

copy()

Return a copy of this StateSpace.

Returns

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_spaceStateSpace

The state space to check compatibility with.

Returns

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

labelsiterable

the labels to test.

Returns

bool

contains_labels(labels)

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

Parameters

labelsiterable

the labels to test.

Returns

bool

contains_label(label)

True if this state space contains a given label.

Parameters

labelstr or int

the label to test for.

Returns

bool

create_subspace(labels)

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

Parameters

labelsiterable

The labels to include in the returned state space.

Returns

StateSpace

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_spaceStateSpace

The other state space.

Returns

StateSpace

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_spaceStateSpace

The other state space.

Returns

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

labelsiterable

The labels to include in the returned state space.

Returns

StateSpace

class pygsti.baseobjs.statespace.QuditSpace(nqudits_or_labels, udim_or_udims)

Bases: StateSpace

A state space consisting of N qudits.

property udim

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

property dim

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

property num_qudits

The number of qubits in this quantum state space.

property num_tensor_product_blocks

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

Returns

int

property tensor_product_blocks_labels

Get the labels for all the tensor-product blocks.

Returns

tuple of tuples

property tensor_product_blocks_dimensions

Get the superoperator dimensions for all the tensor-product blocks.

Returns

tuple of tuples

property tensor_product_blocks_udimensions

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

Returns

tuple of tuples

property tensor_product_blocks_types

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

Returns

tuple of tuples

label_dimension(label)

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

Parameters

labelstr or int

The label whose dimension should be retrieved.

Returns

int

label_udimension(label)

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

Parameters

labelstr or int

The label whose dimension should be retrieved.

Returns

int

label_tensor_product_block_index(label)

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

Parameters

labelstr or int

The label whose index should be retrieved.

Returns

int

label_type(label)

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

Parameters

labelstr or int

The label whose type should be retrieved.

Returns

str

class pygsti.baseobjs.statespace.QubitSpace(nqubits_or_labels)

Bases: QuditSpace

A state space consisting of N qubits.

property udim

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

property dim

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

property qubit_labels

The labels of the qubits

property num_qubits

The number of qubits in this quantum state space.

property num_tensor_product_blocks

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

Returns

int

property tensor_product_blocks_labels

Get the labels for all the tensor-product blocks.

Returns

tuple of tuples

property tensor_product_blocks_dimensions

Get the superoperator dimensions for all the tensor-product blocks.

Returns

tuple of tuples

property tensor_product_blocks_udimensions

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

Returns

tuple of tuples

property tensor_product_blocks_types

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

Returns

tuple of tuples

label_dimension(label)

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

Parameters

labelstr or int

The label whose dimension should be retrieved.

Returns

int

label_udimension(label)

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

Parameters

labelstr or int

The label whose dimension should be retrieved.

Returns

int

label_tensor_product_block_index(label)

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

Parameters

labelstr or int

The label whose index should be retrieved.

Returns

int

label_type(label)

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

Parameters

labelstr or int

The label whose type should be retrieved.

Returns

str

class pygsti.baseobjs.statespace.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_liststr 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 asociated 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.

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

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

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.

property dim

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

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.

Returns

int

property tensor_product_blocks_labels

The labels for all the tensor-product blocks.

Returns

tuple of tuples

property tensor_product_blocks_dimensions

The superoperator dimensions for all the tensor-product blocks.

Returns

tuple of tuples

property tensor_product_blocks_udimensions

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

Returns

tuple of tuples

property tensor_product_blocks_types

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

Returns

tuple of tuples

label_dimension(label)

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

Parameters
labelstr or int

The label whose dimension should be retrieved.

Returns

int

label_udimension(label)

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

Parameters
labelstr or int

The label whose dimension should be retrieved.

Returns

int

label_tensor_product_block_index(label)

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

Parameters
labelstr or int

The label whose index should be retrieved.

Returns

int

label_type(label)

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

Parameters
labelstr or int

The label whose type should be retrieved.

Returns

str

pygsti.baseobjs.statespace.default_space_for_dim(dim)

Create a state space for a given superoperator dimension.

Parameters

dimint

The dimension.

Returns

StateSpace

pygsti.baseobjs.statespace.default_space_for_udim(udim)

Create a state space for a given unitary operator dimension.

Parameters

dimint

The dimension.

Returns

StateSpace

pygsti.baseobjs.statespace.default_space_for_num_qubits(num_qubits)

Create a state space for a given number of qubits.

Parameters

num_qubitsint

The number of qubits.

Returns

QubitStateSpace