`pygsti.baseobjs.basisconstructors`

Functions for creating the standard sets of matrices in the standard, Pauli, Gell-Mann, and qutrit bases

Module Contents

Classes

`MatrixBasisConstructor`	A factory class for constructing builtin basis types whose elements are matrices.
`DiagonalMatrixBasisConstructor`	A factory class for constructing builtin basis types whose elements are diagonal matrices.
`SingleElementMatrixBasisConstructor`	A constructor for a basis containing just a single element (e.g. the identity).
`VectorBasisConstructor`	A factory class for constructing builtin basis types whose elements are vectors.

Functions

`mut`(i, j, n)	A matrix unit.
`std_matrices`(matrix_dim)	Get the elements of the matrix unit, or "standard", basis of matrix-dimension matrix_dim.
`std_labels`(matrix_dim)	Return the standard-matrix-basis labels based on a matrix dimension.
`col_matrices`(matrix_dim)	Get the elements of the matrix unit, or "column-stacked", basis of matrix-dimension matrix_dim.
`col_labels`(matrix_dim)	Return the column-stacked-matrix-basis labels based on a matrix dimension.
`gm_matrices_unnormalized`(matrix_dim)	Get the elements of the generalized Gell-Mann basis spanning the density-matrix space given by matrix_dim.
`gm_matrices`(matrix_dim)	Get the normalized elements of the generalized Gell-Mann basis with matrix dimension matrix_dim.
`gm_labels`(matrix_dim)	Gell-Mann basis labels.
`qsim_matrices`(matrix_dim)	Get the elements of the QuantumSim basis with matrix dimension matrix_dim.
`qsim_labels`(matrix_dim)	QSim basis labels.
`pp_matrices`(matrix_dim[, max_weight, normalize])	Get the elements of the Pauil-product basis with matrix dimension matrix_dim.
`pp_labels`(matrix_dim)	Pauli-product basis labels.
`qt_matrices`(matrix_dim[, selected_pp_indices])	Get the elements of a special basis spanning the density-matrix space of a qutrit.
`qt_labels`(matrix_dim)	The qutrit-basis labels based on a matrix dimension.
`identity_matrices`(matrix_dim)	Matrices for the "identity" basis of matrix dimension matrix_dim.
`identity_labels`(dim)	The identity-basis labels based on a matrix dimension.
`cl_vectors`(dim)	Get the elements (vectors) of the classical basis with dimension dim
`cl_labels`(dim)	Return the classical-basis labels based on a vector dimension.
`clgm_vectors`(dim)	Get the elements (vectors) of the classical Gell-Mann basis with dimension dim
`clgm_labels`(dim)	Return the classical Gell-Mann basis labels based on a vector dimension.
`clpp_vectors`(dim)	Get the elements (vectors) of the classical Pauli-product basis with dimension dim
`clpp_labels`(dim)	Return the classical Pauli-product basis labels based on a vector dimension.
`sv_vectors`(dim)	Get the elements (vectors) of the complex state-vector basis with dimension dim.
`sv_labels`(dim)	Return the state-vector-basis labels based on a vector dimension.
`unknown_els`(dim)	The elements of the "unknown" basis. Just returns an empty list.
`unknown_labels`(dim)	The labels for the "unknown" basis. Just returns an empty list.

Attributes

`sqrt2`
`id2x2`
`sigmax`
`sigmay`
`sigmaz`
`MX_UNIT_VEC`
`MX_UNIT_VEC_2Q`
`MAX_BASIS_MATRIX_DIM`
`PP_matrices`

pygsti.baseobjs.basisconstructors.sqrt2

pygsti.baseobjs.basisconstructors.id2x2

pygsti.baseobjs.basisconstructors.sigmax

pygsti.baseobjs.basisconstructors.sigmay

pygsti.baseobjs.basisconstructors.sigmaz

pygsti.baseobjs.basisconstructors.mut(i, j, n)

A matrix unit.

Parameters

iint: Row of the single “1” in the matrix unit.
jint: Column of the single “1” in the matrix unit.
nint: Dimension of matrix

Returns

numpy.ndarray: A (n,n)-shaped array that is all zeros except a single “1” in the i,`j` element.

pygsti.baseobjs.basisconstructors.MX_UNIT_VEC = ()

pygsti.baseobjs.basisconstructors.MX_UNIT_VEC_2Q = ()

pygsti.baseobjs.basisconstructors.MAX_BASIS_MATRIX_DIM

class pygsti.baseobjs.basisconstructors.MatrixBasisConstructor(longname, matrixgen_fn, labelgen_fn, real, first_element_is_identity)

Bases: object

A factory class for constructing builtin basis types whose elements are matrices.

Parameters

longnamestr: The long name for the builtin basis.
matrixgen_fnfunction: A function that generates the matrix elements for this basis given the matrix dimension (i.e. the number of rows or columns in the matrices to produce).
labelgen_fnfunction: A function that generates the element labels for this basis given the matrix dimension (i.e. the number of rows or columns in the matrices to produce).
realbool: Whether vectors expressed in this basis are required to have real components.

Create a new MatrixBasisConstructor:

Parameters

longnamestr: The long name for the builtin basis.
matrixgen_fnfunction: A function that generates the matrix elements for this basis given the matrix dimension (i.e. the number of rows or columns in the matrices to produce).
labelgen_fnfunction: A function that generates the element labels for this basis given the matrix dimension (i.e. the number of rows or columns in the matrices to produce).
realbool: Whether vectors expressed in this basis are required to have real components.

matrix_dim(dim)

Helper function that converts a vector-space dimension dim to matrix-dimension by taking a sqrt.

Parameters

dimint: Dimension

Returns

int

labeler(dim, sparse)

Get the labels of a basis to be constructed.

Parameters

dimint: The vector-space dimension of the basis.
sparsebool: Whether the basis is sparse or not.

Returns

list of labels (strs)

constructor(dim, sparse)

Get the elements of a basis to be constructed.

Parameters

dimint: The vector-space dimension of the basis.
sparsebool: Whether the basis is sparse or not.

Returns

list of basis elements

sizes(dim, sparse)

Get some relevant sizes/dimensions for constructing a basis.

This function is needed for constructing Basis objects because these objects want to know the size & dimension of a basis without having to construct the (potentially large) set of elements.

Parameters

dimint: The vector-space dimension of the basis. e.g. 4 for a basis of 2x2 matrices and 2 for a basis of length=2 vectors.
sparsebool: Whether the basis is sparse or not.

Returns

nElementsint: The number of elements in the basis.
dimint: The vector-space dimension of the basis.
elshapetuple: The shape of the elements that might be constructed (if constructor was called).

class pygsti.baseobjs.basisconstructors.DiagonalMatrixBasisConstructor(longname, matrixgen_fn, labelgen_fn, real, first_element_is_identity)

Bases: MatrixBasisConstructor

A factory class for constructing builtin basis types whose elements are diagonal matrices.

The size of these bases is equal to their matrix dimension (so dim == matrix_dim, similar to a VectorBasisConstructor, but element are diagonal matrices rather than vectors)

Create a new MatrixBasisConstructor:

Parameters

longnamestr: The long name for the builtin basis.
matrixgen_fnfunction: A function that generates the matrix elements for this basis given the matrix dimension (i.e. the number of rows or columns in the matrices to produce).
labelgen_fnfunction: A function that generates the element labels for this basis given the matrix dimension (i.e. the number of rows or columns in the matrices to produce).
realbool: Whether vectors expressed in this basis are required to have real components.

constructor(dim, sparse)

Get the elements of a basis to be constructed.

Parameters

dimint: The vector-space dimension of the basis.
sparsebool: Whether the basis is sparse or not.

Returns

list of basis elements

sizes(dim, sparse)

Get some relevant sizes/dimensions for constructing a basis.

This function is needed for constructing Basis objects because these objects want to know the size & dimension of a basis without having to construct the (potentially large) set of elements.

Parameters

dimint: The vector-space dimension of the basis. e.g. 4 for a basis of 2x2 matrices and 2 for a basis of length=2 vectors.
sparsebool: Whether the basis is sparse or not.

Returns

nElementsint: The number of elements in the basis.
dimint: The vector-space dimension of the basis.
elshapetuple: The shape of the elements that might be constructed (if constructor was called).

class pygsti.baseobjs.basisconstructors.SingleElementMatrixBasisConstructor(longname, matrixgen_fn, labelgen_fn, real, first_element_is_identity)

Bases: MatrixBasisConstructor

A constructor for a basis containing just a single element (e.g. the identity).

Create a new MatrixBasisConstructor:

Parameters

longnamestr: The long name for the builtin basis.
matrixgen_fnfunction: A function that generates the matrix elements for this basis given the matrix dimension (i.e. the number of rows or columns in the matrices to produce).
labelgen_fnfunction: A function that generates the element labels for this basis given the matrix dimension (i.e. the number of rows or columns in the matrices to produce).
realbool: Whether vectors expressed in this basis are required to have real components.

sizes(dim, sparse)

See docstring for MatrixBasisConstructor

Parameters

dimint: The vector-space dimension of the basis. e.g. 4 for a basis of 2x2 matrices and 2 for a basis of length=2 vectors.
sparsebool: Whether the basis is sparse or not.

Returns

nElementsint: The number of elements in the basis.
dimint: The vector-space dimension of the basis.
elshapetuple: The shape of the elements that might be constructed (if constructor was called).

class pygsti.baseobjs.basisconstructors.VectorBasisConstructor(longname, vectorgen_fn, labelgen_fn, real)

Bases: object

A factory class for constructing builtin basis types whose elements are vectors.

Parameters

longnamestr: The long name for the builtin basis.
vectorgen_fnfunction: A function that generates the vector elements for this basis given the vector dimension.
labelgen_fnfunction: A function that generates the element labels for this basis given the vector dimension.
realbool: Whether vectors expressed in this basis are required to have real components.

Create a new VectorBasisConstructor:

Parameters

longnamestr: The long name for the builtin basis.
vectorgen_fnfunction: A function that generates the vector elements for this basis given the vector dimension.
labelgen_fnfunction: A function that generates the element labels for this basis given the vector dimension.
realbool: Whether vectors expressed in this basis are required to have real components.

labeler(dim, sparse)

Get the labels of a basis to be constructed.

Parameters

dimint: The vector-space dimension of the basis.
sparsebool: Whether the basis is sparse or not.

Returns

list of labels (strs)

constructor(dim, sparse)

Get the elements of a basis to be constructed.

Parameters

dimint: The vector-space dimension of the basis.
sparsebool: Whether the basis is sparse or not.

Returns

list of basis elements

sizes(dim, sparse)

Get some relevant sizes/dimensions for constructing a basis.

This function is needed for constructing Basis objects because these objects want to know the size & dimension of a basis without having to construct the (potentially large) set of elements.

Parameters

dimint: The vector-space dimension of the basis. e.g. 4 for a basis of 2x2 matrices and 2 for a basis of length=2 vectors.
sparsebool: Whether the basis is sparse or not.

Returns

nElementsint: The number of elements in the basis.
dimint: The vector-space dimension of the basis.
elshapetuple: The shape of the elements that might be constructed (if constructor was called).

pygsti.baseobjs.basisconstructors.std_matrices(matrix_dim)

Get the elements of the matrix unit, or “standard”, basis of matrix-dimension matrix_dim. The matrices are ordered so that the row index changes the fastest.

Constructs the standard basis spanning the density-matrix space given by matrix_dim x matrix_dim matrices.

The returned matrices are orthonormal basis under the trace inner product, i.e. Tr( dot(Mi,Mj) ) == delta_ij.

Parameters

matrix_dimint: matrix dimension of the density-matrix space, e.g. 2 for a single qubit in a 2x2 density matrix basis.

Returns

list: A list of N numpy arrays each of shape (matrix_dim, matrix_dim).

Notes

Each element is a matrix containing a single “1” entry amidst a background of zeros.

pygsti.baseobjs.basisconstructors.std_labels(matrix_dim)

Return the standard-matrix-basis labels based on a matrix dimension.

Parameters

matrix_dimint: The matrix dimension of the basis to generate labels for (the number of rows or columns in a matrix).

Returns

list of strs

pygsti.baseobjs.basisconstructors.col_matrices(matrix_dim)

Get the elements of the matrix unit, or “column-stacked”, basis of matrix-dimension matrix_dim. The matrices are ordered so that the column index changes the fastest.

Constructs the standard basis spanning the density-matrix space given by matrix_dim x matrix_dim matrices.

The returned matrices are orthonormal basis under the trace inner product, i.e. Tr( dot(Mi,Mj) ) == delta_ij.

Parameters

matrix_dimint: matrix dimension of the density-matrix space, e.g. 2 for a single qubit in a 2x2 density matrix basis.

Returns

list: A list of N numpy arrays each of shape (matrix_dim, matrix_dim).

Notes

Each element is a matrix containing a single “1” entry amidst a background of zeros.

pygsti.baseobjs.basisconstructors.col_labels(matrix_dim)

Return the column-stacked-matrix-basis labels based on a matrix dimension.

Parameters

matrix_dimint: The matrix dimension of the basis to generate labels for (the number of rows or columns in a matrix).

Returns

list of strs

pygsti.baseobjs.basisconstructors.gm_matrices_unnormalized(matrix_dim)

Get the elements of the generalized Gell-Mann basis spanning the density-matrix space given by matrix_dim.

The returned matrices are given in the standard basis of the “embedding” density matrix space, that is, the space which embeds the block-diagonal matrix structure stipulated in dim. These matrices form an orthogonal but not orthonormal basis under the trace inner product.

Parameters

matrix_dimint: Dimension of the density-matrix space.

Returns

list: A list of N numpy arrays each of shape (matrix_dim, matrix_dim), where matrix_dim is the matrix-dimension of the overall “embedding” density matrix (the sum of matrix_dim) and N is the dimension of the density-matrix space, equal to sum( block_dim_i^2 ).

pygsti.baseobjs.basisconstructors.gm_matrices(matrix_dim)

Get the normalized elements of the generalized Gell-Mann basis with matrix dimension matrix_dim.

That is, construct the basis spanning the density-matrix space given by matrix_dim.

The returned matrices are given in the standard basis of the “embedding” density matrix space, that is, the space which embeds the block-diagonal matrix structure stipulated in matrix_dim. These matrices form an orthonormal basis under the trace inner product, i.e. Tr( dot(Mi,Mj) ) == delta_ij.

Parameters

matrix_dimint: Dimension of the density-matrix space.

Returns

list: A list of N numpy arrays each of shape (matrix_dim, matrix_dim), where matrix_dim is the matrix-dimension of the overall “embedding” density matrix (the sum of matrix_dim) and N is the dimension of the density-matrix space, equal to sum( block_dim_i^2 ).

pygsti.baseobjs.basisconstructors.gm_labels(matrix_dim)

Gell-Mann basis labels.

Parameters

matrix_dimint: The labels (names) of the Gell-Mann basis elements with a given matrix dimension.

Returns

list

pygsti.baseobjs.basisconstructors.qsim_matrices(matrix_dim)

Get the elements of the QuantumSim basis with matrix dimension matrix_dim.

These matrices span the space of matrix_dim x matrix_dim density matrices (matrix-dimension matrix_dim, space dimension matrix_dim^2).

The returned matrices are given in the QuantumSim representation of the density matrix space, and are thus kronecker products of the standard representation of the QuantumSim matrices:

‘0’ == [[1, 0],[0,0]]
‘X’ == [[0, 1],[1,0]]
‘Y’ == [[0,-1.j],[1.j,0]]
‘1’ == [[0, 0],[0,1]]

The normalization is such that the resulting basis is orthonormal under the trace inner product:

Tr( dot(Mi,Mj) ) == delta_ij.

In the returned list, the right-most factor of the kronecker product varies the fastest, so, for example, when matrix_dim == 4 the returned list is:

[ 00,0X,0Y,01,X0,XX,XY,X1,Y0,Y0,YX,YY,Y1,10,1X,1Y,11 ].

Parameters

matrix_dimint: Matrix-dimension of the density-matrix space. Must be a power of 2.

Returns

list: A list of N numpy arrays each of shape (matrix_dim, matrix_dim), where N == matrix_dim^2, the dimension of the density-matrix space.

Notes

Matrices are ordered with first qubit being most significant, e.g., for 2 qubits: 00, 0X, 0Y, 01, X0, XX, XY, X1, Y0, … 11

pygsti.baseobjs.basisconstructors.qsim_labels(matrix_dim)

QSim basis labels.

Parameters

matrix_dimint: The matrix dimension to get labels for.

Returns

list

pygsti.baseobjs.basisconstructors.pp_matrices(matrix_dim, max_weight=None, normalize=True)

Get the elements of the Pauil-product basis with matrix dimension matrix_dim.

These matrices span the space of matrix_dim x matrix_dim density matrices (matrix-dimension matrix_dim, space dimension matrix_dim^2).

The returned matrices are given in the standard basis of the density matrix space, and are thus kronecker products of the standard representation of the Pauli matrices, (i.e. where sigma_y == [[ 0, -i ], [i, 0]] ) normalized (when normalize=True so that the resulting basis is orthonormal under the trace inner product, i.e. Tr( dot(Mi,Mj) ) == delta_ij. In the returned list, the right-most factor of the kronecker product varies the fastest, so, for example, when matrix_dim == 4 the returned list is [ II,IX,IY,IZ,XI,XX,XY,XY,YI,YX,YY,YZ,ZI,ZX,ZY,ZZ ].

Parameters

matrix_dimint: Matrix-dimension of the density-matrix space. Must be a power of 2.
max_weightint, optional: Restrict the elements returned to those having weight <= max_weight. An element’s “weight” is defined as the number of non-identity single-qubit factors of which it is comprised. For example, if matrix_dim == 4 and max_weight == 1 then the returned list is [II, IX, IY, IZ, XI, YI, ZI].
normalizebool, optional: Whether the Pauli matrices are normalized (see above) or not.

Returns

list: A list of N numpy arrays each of shape (matrix_dim, matrix_dim), where N == matrix_dim^2, the dimension of the density-matrix space. (Exception: when max_weight is not None, the returned list may have fewer than N elements.)

Notes

Matrices are ordered with first qubit being most significant, e.g., for 2 qubits: II, IX, IY, IZ, XI, XX, XY, XZ, YI, … ZZ

pygsti.baseobjs.basisconstructors.PP_matrices

pygsti.baseobjs.basisconstructors.pp_labels(matrix_dim)

Pauli-product basis labels.

Parameters

matrix_dimint: The matrix dimension to get labels for.

Returns

list

pygsti.baseobjs.basisconstructors.qt_matrices(matrix_dim, selected_pp_indices=(0, 5, 10, 11, 1, 2, 3, 6, 7))

Get the elements of a special basis spanning the density-matrix space of a qutrit.

The returned matrices are given in the standard basis of the density matrix space. These matrices form an orthonormal basis under the trace inner product, i.e. Tr( dot(Mi,Mj) ) == delta_ij.

Parameters

matrix_dimint: Matrix-dimension of the density-matrix space. Must equal 3 (present just to maintain consistency which other routines)
selected_pp_indicestuple, optional: The indices of the 2-qubit Pauli-product matrices that should be projected onto the qutrit space to arrive at a qutrit basis. Don’t alter this value unless you know what you’re doing.

Returns

list: A list of 9 numpy arrays each of shape (3, 3).

pygsti.baseobjs.basisconstructors.qt_labels(matrix_dim)

The qutrit-basis labels based on a matrix dimension.

Parameters

matrix_dimint: The matrix dimension of the basis to generate labels for (the number of rows or columns in a matrix).

Returns

list of strs

pygsti.baseobjs.basisconstructors.identity_matrices(matrix_dim)

Matrices for the “identity” basis of matrix dimension matrix_dim.

The “identity basis” consists of only the identity matrix, so this function returns a list of a single matrix_dim x matrix_dim identity matrix.

Parameters

matrix_dimint: The matrix dimension.

Returns

list

pygsti.baseobjs.basisconstructors.identity_labels(dim)

The identity-basis labels based on a matrix dimension.

Parameters

dimint: The matrix dimension.

pygsti.baseobjs.basisconstructors.cl_vectors(dim)

Get the elements (vectors) of the classical basis with dimension dim

That is, the dim standard unit vectors of length dim.

Parameters

dimint: dimension of the vector space.

Returns

list: A list of dim numpy arrays each of shape (dim,).

pygsti.baseobjs.basisconstructors.cl_labels(dim)

Return the classical-basis labels based on a vector dimension.

Parameters

dimint: The dimension of the basis to generate labels for (e.g. 2 for a single classical bit).

Returns

list of strs

pygsti.baseobjs.basisconstructors.clgm_vectors(dim)

Get the elements (vectors) of the classical Gell-Mann basis with dimension dim

The elements of this basis are the diagonals of the un-normalized Gell-Mann basis (of the matching dimension) elements with non-zero diagonal.

Parameters

dimint: dimension of the vector space.

Returns

list: A list of dim numpy arrays each of shape (dim,).

pygsti.baseobjs.basisconstructors.clgm_labels(dim)

Return the classical Gell-Mann basis labels based on a vector dimension.

Parameters

dimint: The dimension of the basis to generate labels for (e.g. 2 for a single classical bit).

Returns

list of strs

pygsti.baseobjs.basisconstructors.clpp_vectors(dim)

Get the elements (vectors) of the classical Pauli-product basis with dimension dim

The elements of this basis are the diagonals of the un-normalized Pauli-product basis (of the matching dimension) elements with non-zero diagonal (those using I and Z).

Parameters

dimint: dimension of the vector space.

Returns

list: A list of dim numpy arrays each of shape (dim,).

pygsti.baseobjs.basisconstructors.clpp_labels(dim)

Return the classical Pauli-product basis labels based on a vector dimension.

Parameters

dimint: The dimension of the basis to generate labels for (e.g. 2 for a single classical bit).

Returns

list of strs

pygsti.baseobjs.basisconstructors.sv_vectors(dim)

Get the elements (vectors) of the complex state-vector basis with dimension dim.

That is, the dim standard complex unit vectors of length dim.

Parameters

dimint: dimension of the vector space.

Returns

list: A list of dim numpy arrays each of shape (dim,).

pygsti.baseobjs.basisconstructors.sv_labels(dim)

Return the state-vector-basis labels based on a vector dimension.

Parameters

dimint: The dimension of the basis to generate labels for (e.g. 2 for a single qubit represented as a state vector).

Returns

list of strs

pygsti.baseobjs.basisconstructors.unknown_els(dim)

The elements of the “unknown” basis. Just returns an empty list.

Parameters

dimint: The dimension of the basis (doesn’t really matter).

Returns

list

pygsti.baseobjs.basisconstructors.unknown_labels(dim)

The labels for the “unknown” basis. Just returns an empty list.

Parameters

dimint: Dimension

Returns

list

pygsti.baseobjs.basisconstructors

Module Contents

Classes

Functions

Attributes

Parameters

Returns

Parameters

Parameters

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Parameters

Returns

Parameters

Returns

Parameters

Parameters

Returns

Parameters

Parameters

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Notes

Parameters

Returns

Parameters

Returns

Notes

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Notes

Parameters

Returns

Parameters

Returns

Notes

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

`pygsti.baseobjs.basisconstructors`