pygsti.baseobjs.basis

Defines the Basis object and supporting functions

Module Contents

Classes

Basis

An ordered set of labeled matrices/vectors.

LazyBasis

A Basis whose labels and elements that are constructed only when at least one of them is needed.

ExplicitBasis

A Basis whose elements are specified directly.

BuiltinBasis

A basis that is included within and integrated into pyGSTi.

DirectSumBasis

A basis that is the direct sum of one or more "component" bases.

TensorProdBasis

A Basis that is the tensor product of one or more "component" bases.

EmbeddedBasis

A basis that embeds a basis for a smaller state space within a larger state space.

class pygsti.baseobjs.basis.Basis(name, longname, real, sparse)

Bases: pygsti.baseobjs.nicelyserializable.NicelySerializable

An ordered set of labeled matrices/vectors.

The base class for basis objects. A basis in pyGSTi is an abstract notion of a set of labeled elements, or “vectors”. Each basis has a certain size, and has .elements, .labels, and .ellookup members, the latter being a dictionary mapping of labels to elements.

An important point to note that isn’t immediately intuitive is that while Basis object holds elements (in its .elements property) these are not the same as its vectors (given by the object’s vector_elements property). Often times, in what we term a “simple” basis, the you just flatten an element to get the corresponding vector-element. This works for bases where the elements are either vectors (where flattening does nothing) and matrices. By storing elements as distinct from vector_elements, the Basis can capture additional structure of the elements (such as viewing them as matrices) that can be helpful for their display and interpretation. The elements are also sometimes referred to as the “natural elements” because they represent how to display the element in a natrual way. A non-simple basis occurs when vector_elements need to be stored as elements in a larger “embedded” way so that these elements can be displayed and interpeted naturally.

A second important note is that there is assumed to be some underlying “standard” basis underneath all the bases in pyGSTi. The elements in a Basis are always written in this standard basis. In the case of the “std”-named basis in pyGSTi, these elements are just the trivial vector or matrix units, so one can rightly view the “std” pyGSTi basis as the “standard” basis for a that particular dimension.

The arguments below describe the basic properties of all basis objects in pyGSTi. It is important to remember that the vector_elements of a basis are different from its elements (see the Basis docstring), and that dim refers to the vector elements whereas elshape refers to the elements.

For example, consider a 2-element Basis containing the I and X Pauli matrices. The size of this basis is 2, as there are two elements (and two vector elements). Since vector elements are the length-4 flattened Pauli matrices, the dimension (dim) is 4. Since the elements are 2x2 Pauli matrices, the elshape is (2,2).

As another example consider a basis which spans all the diagonal 2x2 matrices. The elements of this basis are the two matrix units with a 1 in the (0,0) or (1,1) location. The vector elements, however, are the length-2 [1,0] and [0,1] vectors obtained by extracting just the diagonal entries from each basis element. Thus, for this basis, size=2, dim=2, and elshape=(2,2) - so the dimension is not just the product of elshape entries (equivalently, elsize).

Parameters

namestring

The name of the basis. This can be anything, but is usually short and abbreviated. There are several types of bases built into pyGSTi that can be constructed by this name.

longnamestring

A more descriptive name for the basis.

realbool

Elements and vector elements are always allowed to have complex entries. This argument indicates whether the coefficients in the expression of an arbitrary vector in this basis must be real. For example, if real=True, then when pyGSTi transforms a vector in some other basis to a vector in this basis, it will demand that the values of that vector (i.e. the coefficients which multiply this basis’s elements to obtain a vector in the “standard” basis) are real.

sparsebool

Whether the elements of .elements for this Basis are stored (when they are stored at all) as sparse matrices or vectors.

Attributes

dimint

The dimension of the vector space this basis fully or partially spans. Equivalently, the length of the vector_elements of the basis.

sizeint

The number of elements (or vector-elements) in the basis.

elshapeint

The shape of each element. Typically either a length-1 or length-2 tuple, corresponding to vector or matrix elements, respectively. Note that vector elements always have shape (dim,) (or (dim,1) in the sparse case).

elndimint

The number of element dimensions, i.e. len(self.elshape)

elsizeint

The total element size, i.e. product(self.elshape)

vector_elementslist

The “vectors” of this basis, always 1D (sparse or dense) arrays.

abstract property dim

The dimension of the vector space this basis fully or partially spans. Equivalently, the length of the vector_elements of the basis.

abstract property size

The number of elements (or vector-elements) in the basis.

abstract property elshape

The shape of each element. Typically either a length-1 or length-2 tuple, corresponding to vector or matrix elements, respectively. Note that vector elements always have shape (dim,) (or (dim,1) in the sparse case).

property elndim

The number of element dimensions, i.e. len(self.elshape)

Returns

int

property elsize

The total element size, i.e. product(self.elshape)

Returns

int

property first_element_is_identity

True if the first element of this basis is proportional to the identity matrix, False otherwise.

property vector_elements

The “vectors” of this basis, always 1D (sparse or dense) arrays.

Returns
list

A list of 1D arrays.

property to_std_transform_matrix

Retrieve the matrix that transforms a vector from this basis to the standard basis of this basis’s dimension.

Returns
numpy array or scipy.sparse.lil_matrix

An array of shape (dim, size) where dim is the dimension of this basis (the length of its vectors) and size is the size of this basis (its number of vectors).

property from_std_transform_matrix

Retrieve the matrix that transforms vectors from the standard basis to this basis.

Returns
numpy array or scipy sparse matrix

An array of shape (size, dim) where dim is the dimension of this basis (the length of its vectors) and size is the size of this basis (its number of vectors).

property to_elementstd_transform_matrix

Get transformation matrix from this basis to the “element space”.

Get the matrix that transforms vectors in this basis (with length equal to the dim of this basis) to vectors in the “element space” - that is, vectors in the same standard basis that the elements of this basis are expressed in.

Returns
numpy array

An array of shape (element_dim, size) where element_dim is the dimension, i.e. size, of the elements of this basis (e.g. 16 if the elements are 4x4 matrices) and size is the size of this basis (its number of vectors).

property from_elementstd_transform_matrix

Get transformation matrix from “element space” to this basis.

Get the matrix that transforms vectors in the “element space” - that is, vectors in the same standard basis that the elements of this basis are expressed in - to vectors in this basis (with length equal to the dim of this basis).

Returns
numpy array

An array of shape (size, element_dim) where element_dim is the dimension, i.e. size, of the elements of this basis (e.g. 16 if the elements are 4x4 matrices) and size is the size of this basis (its number of vectors).

classmethod cast(name_or_basis_or_matrices, dim=None, sparse=None, classical_name='cl')

Convert various things that can describe a basis into a Basis object.

Parameters
name_or_basis_or_matricesvarious

Can take on a variety of values to produce different types of bases:

  • None: an empty ExpicitBasis

  • Basis: checked with dim and sparse and passed through.

  • str: BuiltinBasis or DirectSumBasis with the given name.

  • list: an ExplicitBasis if given matrices/vectors or a

    DirectSumBasis if given a (name, dim) pairs.

dimint or StateSpace, optional

The dimension of the basis to create. Sometimes this can be inferred based on name_or_basis_or_matrices, other times it must be supplied. This is the dimension of the space that this basis fully or partially spans. This is equal to the number of basis elements in a “full” (ordinary) basis. When a StateSpace object is given, a more detailed direct-sum-of-tensor-product-blocks structure for the state space (rather than a single dimension) is described, and a basis is produced for this space. For instance, a DirectSumBasis basis of TensorProdBasis components can result when there are multiple tensor-product blocks and these blocks consist of multiple factors.

sparsebool, optional

Whether the resulting basis should be “sparse”, meaning that its elements will be sparse rather than dense matrices.

classical_namestr, optional

An alternate builtin basis name that should be used when constructing the bases for the classical sectors of dim, when dim is a StateSpace object.

Returns

Basis

is_simple()

Whether the flattened-element vector space is the same space as the space this basis’s vectors belong to.

Returns

bool

is_complete()

Whether this is a complete basis, i.e. this basis’s vectors span the entire space that they live in.

Returns

bool

is_partial()

The negative of is_complete(), effectively “is_incomplete”.

Returns

bool

copy()

Make a copy of this Basis object.

Returns

Basis

with_sparsity(desired_sparsity)

Returns either this basis or a copy of it with the desired sparsity.

If this basis has the desired sparsity it is simply returned. If not, this basis is copied to one that does.

Parameters
desired_sparsitybool

The sparsity (True for sparse elements, False for dense elements) that is desired.

Returns

Basis

is_equivalent(other, sparseness_must_match=True)

Tests whether this basis is equal to another basis, optionally ignoring sparseness.

Parameters
otherBasis or str

The basis to compare with.

sparseness_must_matchbool, optional

If False then comparison ignores differing sparseness, and this function returns True when the two bases are equal except for their .sparse values.

Returns

bool

create_transform_matrix(to_basis)

Get the matrix that transforms a vector from this basis to to_basis.

Parameters
to_basisBasis or string

The basis to transform to or a built-in basis name. In the latter case, a basis to transform to is built with the same structure as this basis but with all components constructed from the given name.

Returns

numpy.ndarray (even if basis is sparse)

reverse_transform_matrix(from_basis)

Get the matrix that transforms a vector from from_basis to this basis.

The reverse of create_transform_matrix().

Parameters
from_basisBasis or string

The basis to transform from or a built-in basis name. In the latter case, a basis to transform from is built with the same structure as this basis but with all components constructed from the given name.

Returns

numpy.ndarray (even if basis is sparse)

is_normalized()

Check if a basis is normalized, meaning that Tr(Bi Bi) = 1.0.

Available only to bases whose elements are matrices for now.

Returns

bool

create_equivalent(builtin_basis_name)

Create an equivalent basis with components of type builtin_basis_name.

Create a Basis that is equivalent in structure & dimension to this basis but whose simple components (perhaps just this basis itself) is of the builtin basis type given by builtin_basis_name.

Parameters
builtin_basis_namestr

The name of a builtin basis, e.g. “pp”, “gm”, or “std”. Used to construct the simple components of the returned basis.

Returns

Basis

create_simple_equivalent(builtin_basis_name=None)

Create a basis of type builtin_basis_name whose elements are compatible with this basis.

Create a simple basis and one without components (e.g. a TensorProdBasis, is a simple basis w/components) of the builtin type specified whose dimension is compatible with the elements of this basis. This function might also be named “element_equivalent”, as it returns the builtin_basis_name-analogue of the standard basis that this basis’s elements are expressed in.

Parameters
builtin_basis_namestr, optional

The name of the built-in basis to use. If None, then a copy of this basis is returned (if it’s simple) or this basis’s name is used to try to construct a simple and component-free version of the same builtin-basis type.

Returns

Basis

is_compatible_with_state_space(state_space)

Checks whether this basis is compatible with a given state space.

Parameters
state_spaceStateSpace

the state space to check.

Returns

bool

class pygsti.baseobjs.basis.LazyBasis(name, longname, real, sparse)

Bases: Basis

A Basis whose labels and elements that are constructed only when at least one of them is needed.

This class is also used as a base class for higher-level, more specific basis classes.

Parameters

namestring

The name of the basis. This can be anything, but is usually short and abbreviated. There are several types of bases built into pyGSTi that can be constructed by this name.

longnamestring

A more descriptive name for the basis.

realbool

Elements and vector elements are always allowed to have complex entries. This argument indicates whether the coefficients in the expression of an arbitrary vector in this basis must be real. For example, if real=True, then when pyGSTi transforms a vector in some other basis to a vector in this basis, it will demand that the values of that vector (i.e. the coefficients which multiply this basis’s elements to obtain a vector in the “standard” basis) are real.

sparsebool

Whether the elements of .elements for this Basis are stored (when they are stored at all) as sparse matrices or vectors.

Attributes

ellookupdict

A dictionary mapping basis element labels to the elements themselves, for fast element lookup.

elementsnumpy.ndarray

The basis elements (sometimes different from the vectors)

labelslist

The basis labels

Creates a new LazyBasis. Parameters are the same as those to Basis.__init__().

property ellookup

A dictionary mapping basis element labels to the elements themselves

Returns

dict

property elements

The basis elements (sometimes different from the vectors)

Returns

numpy.ndarray

property labels

The basis labels

Returns

list

class pygsti.baseobjs.basis.ExplicitBasis(elements, labels=None, name=None, longname=None, real=False, sparse=None, vector_elements=None)

Bases: Basis

A Basis whose elements are specified directly.

All explicit bases are simple: their vector space is taken to be that of the the flattened elements unless separate vector_elements are given.

Parameters

elementsnumpy.ndarray

The basis elements (sometimes different from the vectors)

labelslist

The basis labels

namestr, optional

The name of this basis. If None, then a name will be automatically generated.

longnamestr, optional

A more descriptive name for this basis. If None, then the short name will be used.

realbool, optional

Whether the coefficients in the expression of an arbitrary vector as a linear combination of this basis’s elements must be real.

sparsebool, optional

Whether the elements of this Basis are stored as sparse matrices or vectors. If None, then this is automatically determined by the type of the initial object: elements[0] (sparse=False is used when len(elements) == 0).

vector_elementsnumpy.ndarray, optional

A list or array of the 1D vectors corresponding to each element. If None, then the flattened elements are used as vectors. The size of these vectors sets the dimension of the basis.

Attributes

Countint

The number of custom bases, used for serialized naming

Create a new ExplicitBasis.

Parameters

elementsiterable

A list of the elements of this basis.

labelsiterable, optional

A list of the labels corresponding to the elements of elements. If given, len(labels) must equal len(elements).

namestr, optional

The name of this basis. If None, then a name will be automatically generated.

longnamestr, optional

A more descriptive name for this basis. If None, then the short name will be used.

realbool, optional

Whether the coefficients in the expression of an arbitrary vector as a linear combination of this basis’s elements must be real.

sparsebool, optional

Whether the elements of this Basis are stored as sparse matrices or vectors. If None, then this is automatically determined by the type of the initial object: elements[0] (sparse=False is used when len(elements) == 0).

vector_elementsnumpy.ndarray, optional

A list or array of the 1D vectors corresponding to each element. If None, then the flattened elements are used as vectors. The size of these vectors sets the dimension of the basis.

property dim

The dimension of the vector space this basis fully or partially spans. Equivalently, the length of the vector_elements of the basis.

property size

The number of elements (or vector-elements) in the basis.

property elshape

The shape of each element. Typically either a length-1 or length-2 tuple, corresponding to vector or matrix elements, respectively. Note that vector elements always have shape (dim,) (or (dim,1) in the sparse case).

property vector_elements

The “vectors” of this basis, always 1D (sparse or dense) arrays.

Returns
list

A list of 1D arrays.

Count = '0'
class pygsti.baseobjs.basis.BuiltinBasis(name, dim_or_statespace, sparse=False)

Bases: LazyBasis

A basis that is included within and integrated into pyGSTi.

Such bases may, in most cases be represented merely by its name. (In actuality, a dimension is also required, but this is often able to be inferred from context.)

Parameters

name{“pp”, “gm”, “std”, “qt”, “id”, “cl”, “sv”}

Name of the basis to be created.

dim_or_statespaceint or StateSpace

The dimension of the basis to be created or the state space for which a basis should be created. Note that when this is an integer it is the dimension of the vectors, which correspond to flattened elements in simple cases. Thus, a 1-qubit basis would have dimension 2 in the state-vector (name=”sv”) case and dimension 4 when constructing a density-matrix basis (e.g. name=”pp”).

sparsebool, optional

Whether basis elements should be stored as SciPy CSR sparse matrices or dense numpy arrays (the default).

Creates a new LazyBasis. Parameters are the same as those to Basis.__init__().

property dim

The dimension of the vector space this basis fully or partially spans. Equivalently, the length of the vector_elements of the basis.

property size

The number of elements (or vector-elements) in the basis.

property elshape

The shape of each element. Typically either a length-1 or length-2 tuple, corresponding to vector or matrix elements, respectively. Note that vector elements always have shape (dim,) (or (dim,1) in the sparse case).

property first_element_is_identity

True if the first element of this basis is proportional to the identity matrix, False otherwise.

is_equivalent(other, sparseness_must_match=True)

Tests whether this basis is equal to another basis, optionally ignoring sparseness.

Parameters
otherBasis or str

The basis to compare with.

sparseness_must_matchbool, optional

If False then comparison ignores differing sparseness, and this function returns True when the two bases are equal except for their .sparse values.

Returns

bool

class pygsti.baseobjs.basis.DirectSumBasis(component_bases, name=None, longname=None)

Bases: LazyBasis

A basis that is the direct sum of one or more “component” bases.

Elements of this basis are the union of the basis elements on each component, each embedded into a common block-diagonal structure where each component occupies its own block. Thus, when there is more than one component, a DirectSumBasis is not a simple basis because the size of its elements is larger than the size of its vector space (which corresponds to just the diagonal blocks of its elements).

Parameters

component_basesiterable

A list of the component bases. Each list elements may be either a Basis object or a tuple of arguments to Basis.cast(), e.g. (‘pp’,4).

namestr, optional

The name of this basis. If None, the names of the component bases joined with “+” is used.

longnamestr, optional

A longer description of this basis. If None, then a long name is automatically generated.

Attributes

vector_elementslist

The “vectors” of this basis, always 1D (sparse or dense) arrays.

Create a new DirectSumBasis - a basis for a space that is the direct-sum of the spaces spanned by other “component” bases.

Parameters

component_basesiterable

A list of the component bases. Each list elements may be either a Basis object or a tuple of arguments to Basis.cast(), e.g. (‘pp’,4).

namestr, optional

The name of this basis. If None, the names of the component bases joined with “+” is used.

longnamestr, optional

A longer description of this basis. If None, then a long name is automatically generated.

property dim

The dimension of the vector space this basis fully or partially spans. Equivalently, the length of the vector_elements of the basis.

property size

The number of elements (or vector-elements) in the basis.

property elshape

The shape of each element. Typically either a length-1 or length-2 tuple, corresponding to vector or matrix elements, respectively. Note that vector elements always have shape (dim,) (or (dim,1) in the sparse case).

property vector_elements

The “vectors” of this basis, always 1D (sparse or dense) arrays.

Returns

list

property to_std_transform_matrix

Retrieve the matrix that transforms a vector from this basis to the standard basis of this basis’s dimension.

Returns
numpy array or scipy.sparse.lil_matrix

An array of shape (dim, size) where dim is the dimension of this basis (the length of its vectors) and size is the size of this basis (its number of vectors).

property to_elementstd_transform_matrix

Get transformation matrix from this basis to the “element space”.

Get the matrix that transforms vectors in this basis (with length equal to the dim of this basis) to vectors in the “element space” - that is, vectors in the same standard basis that the elements of this basis are expressed in.

Returns
numpy array

An array of shape (element_dim, size) where element_dim is the dimension, i.e. size, of the elements of this basis (e.g. 16 if the elements are 4x4 matrices) and size is the size of this basis (its number of vectors).

is_equivalent(other, sparseness_must_match=True)

Tests whether this basis is equal to another basis, optionally ignoring sparseness.

Parameters
otherBasis or str

The basis to compare with.

sparseness_must_matchbool, optional

If False then comparison ignores differing sparseness, and this function returns True when the two bases are equal except for their .sparse values.

Returns

bool

create_equivalent(builtin_basis_name)

Create an equivalent basis with components of type builtin_basis_name.

Create a Basis that is equivalent in structure & dimension to this basis but whose simple components (perhaps just this basis itself) is of the builtin basis type given by builtin_basis_name.

Parameters
builtin_basis_namestr

The name of a builtin basis, e.g. “pp”, “gm”, or “std”. Used to construct the simple components of the returned basis.

Returns

DirectSumBasis

create_simple_equivalent(builtin_basis_name=None)

Create a basis of type builtin_basis_name whose elements are compatible with this basis.

Create a simple basis and one without components (e.g. a TensorProdBasis, is a simple basis w/components) of the builtin type specified whose dimension is compatible with the elements of this basis. This function might also be named “element_equivalent”, as it returns the builtin_basis_name-analogue of the standard basis that this basis’s elements are expressed in.

Parameters
builtin_basis_namestr, optional

The name of the built-in basis to use. If None, then a copy of this basis is returned (if it’s simple) or this basis’s name is used to try to construct a simple and component-free version of the same builtin-basis type.

Returns

Basis

class pygsti.baseobjs.basis.TensorProdBasis(component_bases, name=None, longname=None)

Bases: LazyBasis

A Basis that is the tensor product of one or more “component” bases.

The elements of a TensorProdBasis consist of all tensor products of component basis elements (respecting the order given). The components of a TensorProdBasis must be simple bases so that kronecker products can be used to produce the parent basis’s elements.

A TensorProdBasis is a “simple” basis in that its flattened elements do correspond to its vectors.

Parameters

component_basesiterable

A list of the component bases. Each list elements may be either a Basis object or a tuple of arguments to Basis.cast(), e.g. (‘pp’,4).

namestr, optional

The name of this basis. If None, the names of the component bases joined with “*” is used.

longnamestr, optional

A longer description of this basis. If None, then a long name is automatically generated.

Create a new TensorProdBasis whose elements are the tensor products of the elements of a set of “component” bases.

Parameters

component_basesiterable

A list of the component bases. Each list elements may be either a Basis object or a tuple of arguments to Basis.cast(), e.g. (‘pp’,4).

namestr, optional

The name of this basis. If None, the names of the component bases joined with “*” is used.

longnamestr, optional

A longer description of this basis. If None, then a long name is automatically generated.

property dim

The dimension of the vector space this basis fully or partially spans. Equivalently, the length of the vector_elements of the basis.

property size

The number of elements (or vector-elements) in the basis.

property elshape

The shape of each element. Typically either a length-1 or length-2 tuple, corresponding to vector or matrix elements, respectively. Note that vector elements always have shape (dim,) (or (dim,1) in the sparse case).

is_equivalent(other, sparseness_must_match=True)

Tests whether this basis is equal to another basis, optionally ignoring sparseness.

Parameters
otherBasis or str

The basis to compare with.

sparseness_must_matchbool, optional

If False then comparison ignores differing sparseness, and this function returns True when the two bases are equal except for their .sparse values.

Returns

bool

create_equivalent(builtin_basis_name)

Create an equivalent basis with components of type builtin_basis_name.

Create a Basis that is equivalent in structure & dimension to this basis but whose simple components (perhaps just this basis itself) is of the builtin basis type given by builtin_basis_name.

Parameters
builtin_basis_namestr

The name of a builtin basis, e.g. “pp”, “gm”, or “std”. Used to construct the simple components of the returned basis.

Returns

TensorProdBasis

create_simple_equivalent(builtin_basis_name=None)

Create a basis of type builtin_basis_name whose elements are compatible with this basis.

Create a simple basis and one without components (e.g. a TensorProdBasis, is a simple basis w/components) of the builtin type specified whose dimension is compatible with the elements of this basis. This function might also be named “element_equivalent”, as it returns the builtin_basis_name-analogue of the standard basis that this basis’s elements are expressed in.

Parameters
builtin_basis_namestr, optional

The name of the built-in basis to use. If None, then a copy of this basis is returned (if it’s simple) or this basis’s name is used to try to construct a simple and component-free version of the same builtin-basis type.

Returns

Basis

class pygsti.baseobjs.basis.EmbeddedBasis(basis_to_embed, state_space, target_labels, name=None, longname=None)

Bases: LazyBasis

A basis that embeds a basis for a smaller state space within a larger state space.

The elements of an EmbeddedBasis are therefore just embedded versions of the elements of the basis that is embedded.

Parameters

basis_to_embedBasis

The basis being embedded.

state_space_labelsStateSpaceLabels

An object describing the struture of the entire state space.

target_labelslist or tuple

The labels contained in stateSpaceLabels which demarcate the portions of the state space acted on by basis_to_embed.

namestr, optional

The name of this basis. If None, the names of basis_to_embed is joined with ‘:’ characters to the elements of target_labels.

longnamestr, optional

A longer description of this basis. If None, then a long name is automatically generated.

Create a new EmbeddedBasis.

Parameters

basis_to_embedBasis

The basis being embedded.

state_spaceStateSpace

An object describing the struture of the entire state space.

target_labelslist or tuple

The labels contained in stateSpaceLabels which demarcate the portions of the state space acted on by basis_to_embed.

namestr, optional

The name of this basis. If None, the names of basis_to_embed is joined with ‘:’ characters to the elements of target_labels.

longnamestr, optional

A longer description of this basis. If None, then a long name is automatically generated.

property dim

The dimension of the vector space this basis fully or partially spans. Equivalently, the length of the vector_elements of the basis.

property size

The number of elements (or vector-elements) in the basis.

property elshape

The shape of each element. Typically either a length-1 or length-2 tuple, corresponding to vector or matrix elements, respectively. Note that vector elements always have shape (dim,) (or (dim,1) in the sparse case).

classmethod embed_label(lbl, target_labels)

Gets the EmbeddedBasis label for lbl.

Convenience method that gives the EmbeddedBasis label for lbl without needing to construct the EmbeddedBasis. E.g. “XX:1,2”.

Parameters
lblstr

Un-embedded basis element label, e.g. “XX”.

target_labelstuple

The target state space labels upon which this basis element will be embedded, e.g. (1,2)

Returns
str

The embedded-basis-element label as an EmbeddedBasis would assign it. E.g. “XX:1,2”.

classmethod unembed_label(lbl, target_labels)

Convenience method that performs the reverse of embed_label()

Parameters
lblstr

Embedded basis element label, e.g. “XX:1,2”.

target_labelstuple

The target state space labels upon which this basis element will be embedded, e.g. (1,2)

Returns
str

The un-embedded label, e.g. “XX”.

is_equivalent(other, sparseness_must_match=True)

Tests whether this basis is equal to another basis, optionally ignoring sparseness.

Parameters
otherBasis or str

The basis to compare with.

sparseness_must_matchbool, optional

If False then comparison ignores differing sparseness, and this function returns True when the two bases are equal except for their .sparse values.

Returns

bool

create_equivalent(builtin_basis_name)

Create an equivalent basis with components of type builtin_basis_name.

Create a Basis that is equivalent in structure & dimension to this basis but whose simple components (perhaps just this basis itself) is of the builtin basis type given by builtin_basis_name.

Parameters
builtin_basis_namestr

The name of a builtin basis, e.g. “pp”, “gm”, or “std”. Used to construct the simple components of the returned basis.

Returns

EmbeddedBasis

create_simple_equivalent(builtin_basis_name=None)

Create a basis of type builtin_basis_name whose elements are compatible with this basis.

Create a simple basis and one without components (e.g. a TensorProdBasis, is a simple basis w/components) of the builtin type specified whose dimension is compatible with the elements of this basis. This function might also be named “element_equivalent”, as it returns the builtin_basis_name-analogue of the standard basis that this basis’s elements are expressed in.

Parameters
builtin_basis_namestr, optional

The name of the built-in basis to use. If None, then a copy of this basis is returned (if it’s simple) or this basis’s name is used to try to construct a simple and component-free version of the same builtin-basis type.

Returns

Basis