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.

_check_dim(dim)

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.

_get_gell_mann_non_identity_diag_mxs(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=None)

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=(0, 5, 10, 11, 1, 2, 3, 6, 7))

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

_basis_constructor_dict

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
  • i (int) – Row of the single “1” in the matrix unit.

  • j (int) – Column of the single “1” in the matrix unit.

  • n (int) – 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
pygsti.baseobjs.basisconstructors._check_dim(dim)
class pygsti.baseobjs.basisconstructors.MatrixBasisConstructor(longname, matrixgen_fn, labelgen_fn, real)

Bases: object

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

Parameters
  • longname (str) – The long name for the builtin basis.

  • matrixgen_fn (function) – 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_fn (function) – 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).

  • real (bool) – Whether vectors expressed in this basis are required to have real components.

matrix_dim(self, dim)

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

Parameters

dim (int) – Dimension

Returns

int

labeler(self, dim, sparse)

Get the labels of a basis to be constructed.

Parameters
  • dim (int) – The vector-space dimension of the basis.

  • sparse (bool) – Whether the basis is sparse or not.

Returns

list of labels (strs)

constructor(self, dim, sparse)

Get the elements of a basis to be constructed.

Parameters
  • dim (int) – The vector-space dimension of the basis.

  • sparse (bool) – Whether the basis is sparse or not.

Returns

list of basis elements

sizes(self, 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
  • dim (int) – 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.

  • sparse (bool) – Whether the basis is sparse or not.

Returns

  • nElements (int) – The number of elements in the basis.

  • dim (int) – The vector-space dimension of the basis.

  • elshape (tuple) – The shape of the elements that might be constructed (if constructor was called).

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

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)

constructor(self, dim, sparse)

Get the elements of a basis to be constructed.

Parameters
  • dim (int) – The vector-space dimension of the basis.

  • sparse (bool) – Whether the basis is sparse or not.

Returns

list of basis elements

sizes(self, 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
  • dim (int) – 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.

  • sparse (bool) – Whether the basis is sparse or not.

Returns

  • nElements (int) – The number of elements in the basis.

  • dim (int) – The vector-space dimension of the basis.

  • elshape (tuple) – The shape of the elements that might be constructed (if constructor was called).

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

Bases: MatrixBasisConstructor

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

sizes(self, dim, sparse)

See docstring for MatrixBasisConstructor

Parameters
  • dim (int) – 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.

  • sparse (bool) – Whether the basis is sparse or not.

Returns

  • nElements (int) – The number of elements in the basis.

  • dim (int) – The vector-space dimension of the basis.

  • elshape (tuple) – 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
  • longname (str) – The long name for the builtin basis.

  • vectorgen_fn (function) – A function that generates the vector elements for this basis given the vector dimension.

  • labelgen_fn (function) – A function that generates the element labels for this basis given the vector dimension.

  • real (bool) – Whether vectors expressed in this basis are required to have real components.

labeler(self, dim, sparse)

Get the labels of a basis to be constructed.

Parameters
  • dim (int) – The vector-space dimension of the basis.

  • sparse (bool) – Whether the basis is sparse or not.

Returns

list of labels (strs)

constructor(self, dim, sparse)

Get the elements of a basis to be constructed.

Parameters
  • dim (int) – The vector-space dimension of the basis.

  • sparse (bool) – Whether the basis is sparse or not.

Returns

list of basis elements

sizes(self, 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
  • dim (int) – 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.

  • sparse (bool) – Whether the basis is sparse or not.

Returns

  • nElements (int) – The number of elements in the basis.

  • dim (int) – The vector-space dimension of the basis.

  • elshape (tuple) – 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_dim (int) – 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_dim (int) – 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_dim (int) – 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_dim (int) – 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._get_gell_mann_non_identity_diag_mxs(dimension)
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_dim (int) – 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_dim (int) – 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_dim (int) – 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_dim (int) – 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_dim (int) – The matrix dimension to get labels for.

Returns

list

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

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 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_dim (int) – Matrix-dimension of the density-matrix space. Must be a power of 2.

  • max_weight (int, 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].

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_labels(matrix_dim)

Pauli-product basis labels.

Parameters

matrix_dim (int) – 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_dim (int) – Matrix-dimension of the density-matrix space. Must equal 3 (present just to maintain consistency which other routines)

  • selected_pp_indices (tuple, 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_dim (int) – 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_dim (int) – The matrix dimension.

Returns

list

pygsti.baseobjs.basisconstructors.identity_labels(dim)

The identity-basis labels based on a matrix dimension.

Parameters

dim (int) – 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

dim (int) – 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

dim (int) – 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

dim (int) – 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

dim (int) – 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

dim (int) – 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

dim (int) – 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

dim (int) – 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

dim (int) – 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

dim (int) – 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

dim (int) – Dimension

Returns

list

pygsti.baseobjs.basisconstructors._basis_constructor_dict