pygsti.baseobjs.basis
Defines the Basis object and supporting functions
Module Contents
Classes
An ordered set of labeled matrices/vectors. |
|
A |
|
A Basis whose elements are specified directly. |
|
A basis that is included within and integrated into pyGSTi. |
|
A basis that is the direct sum of one or more "component" bases. |
|
A Basis that is the tensor product of one or more "component" bases. |
- 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 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).
- name
- longname
- real
- sparse
- classmethod cast_from_name_and_statespace(name: str, state_space: pygsti.baseobjs.statespace.StateSpace, sparse=None)
- classmethod cast_from_name_and_dims(name: str, dim: int | list | tuple, sparse=None)
- classmethod cast_from_basis(basis, dim=None, sparse=None)
- classmethod cast_from_arrays(arrays, dim=None, sparse=None)
- classmethod cast(arg, dim=None, sparse=None)
- 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
- 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
- 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__()
.
- 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'
- labels
- elements = '[]'
- ellookup
- 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).
- component_bases = '[]'
- 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).
- component_bases = '[]'
- 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