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