:py:mod:`pygsti.baseobjs.basisconstructors` =========================================== .. py:module:: pygsti.baseobjs.basisconstructors .. autoapi-nested-parse:: Functions for creating the standard sets of matrices in the standard, Pauli, Gell-Mann, and qutrit bases Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: pygsti.baseobjs.basisconstructors.MatrixBasisConstructor pygsti.baseobjs.basisconstructors.DiagonalMatrixBasisConstructor pygsti.baseobjs.basisconstructors.SingleElementMatrixBasisConstructor pygsti.baseobjs.basisconstructors.VectorBasisConstructor Functions ~~~~~~~~~ .. autoapisummary:: pygsti.baseobjs.basisconstructors.mut pygsti.baseobjs.basisconstructors.std_matrices pygsti.baseobjs.basisconstructors.std_labels pygsti.baseobjs.basisconstructors.col_matrices pygsti.baseobjs.basisconstructors.col_labels pygsti.baseobjs.basisconstructors.gm_matrices_unnormalized pygsti.baseobjs.basisconstructors.gm_matrices pygsti.baseobjs.basisconstructors.gm_labels pygsti.baseobjs.basisconstructors.lf_labels pygsti.baseobjs.basisconstructors.lf_matrices pygsti.baseobjs.basisconstructors.qsim_matrices pygsti.baseobjs.basisconstructors.qsim_labels pygsti.baseobjs.basisconstructors.pp_matrices pygsti.baseobjs.basisconstructors.pp_labels pygsti.baseobjs.basisconstructors.qt_matrices pygsti.baseobjs.basisconstructors.qt_labels pygsti.baseobjs.basisconstructors.identity_matrices pygsti.baseobjs.basisconstructors.identity_labels pygsti.baseobjs.basisconstructors.cl_vectors pygsti.baseobjs.basisconstructors.cl_labels pygsti.baseobjs.basisconstructors.clgm_vectors pygsti.baseobjs.basisconstructors.clgm_labels pygsti.baseobjs.basisconstructors.clpp_vectors pygsti.baseobjs.basisconstructors.clpp_labels pygsti.baseobjs.basisconstructors.sv_vectors pygsti.baseobjs.basisconstructors.sv_labels pygsti.baseobjs.basisconstructors.unknown_els pygsti.baseobjs.basisconstructors.unknown_labels Attributes ~~~~~~~~~~ .. autoapisummary:: pygsti.baseobjs.basisconstructors.sqrt2 pygsti.baseobjs.basisconstructors.id2x2 pygsti.baseobjs.basisconstructors.sigmax pygsti.baseobjs.basisconstructors.sigmay pygsti.baseobjs.basisconstructors.sigmaz pygsti.baseobjs.basisconstructors.MX_UNIT_VEC pygsti.baseobjs.basisconstructors.MX_UNIT_VEC_2Q pygsti.baseobjs.basisconstructors.MAX_BASIS_MATRIX_DIM pygsti.baseobjs.basisconstructors.PP_matrices .. py:data:: sqrt2 .. py:data:: id2x2 .. py:data:: sigmax .. py:data:: sigmay .. py:data:: sigmaz .. py:function:: 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. .. py:data:: MX_UNIT_VEC .. py:data:: MX_UNIT_VEC_2Q .. py:data:: MAX_BASIS_MATRIX_DIM :value: '64' .. py:class:: MatrixBasisConstructor(longname: str, matrixgen_fn, labelgen_fn, real: bool, first_element_is_identity) Bases: :py:obj:`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. Create a new MatrixBasisConstructor: 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. .. py:attribute:: matrixgen_fn .. py:attribute:: labelgen_fn .. py:attribute:: longname .. py:attribute:: real .. py:attribute:: first_element_is_identity .. py:method:: matrix_dim(dim: int) -> int Helper function that converts a *vector-space* dimension `dim` to matrix-dimension by taking a sqrt. Parameters ---------- dim : int Dimension Returns ------- int .. py:method:: labeler(dim, sparse: bool) -> list[str] 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) .. py:method:: constructor(dim, sparse: bool) 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 .. py:method:: sizes(dim, sparse: bool) -> tuple[int, int, tuple[int, int]] 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). .. py:class:: DiagonalMatrixBasisConstructor(longname: str, matrixgen_fn, labelgen_fn, real: bool, first_element_is_identity) Bases: :py:obj:`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 ---------- 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. .. py:method:: constructor(dim, sparse: bool) 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 .. py:method:: sizes(dim, sparse: bool) 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). .. py:class:: SingleElementMatrixBasisConstructor(longname: str, matrixgen_fn, labelgen_fn, real: bool, first_element_is_identity) Bases: :py:obj:`MatrixBasisConstructor` A constructor for a basis containing just a single element (e.g. the identity). Create a new MatrixBasisConstructor: 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. .. py:method:: sizes(dim, sparse: bool) See docstring for :class:`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). .. py:class:: VectorBasisConstructor(longname, vectorgen_fn, labelgen_fn, real) Bases: :py:obj:`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. Create a new VectorBasisConstructor: 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. .. py:attribute:: vectorgen_fn .. py:attribute:: labelgen_fn .. py:attribute:: longname .. py:attribute:: real .. py:attribute:: first_element_is_identity :value: 'False' .. py:method:: labeler(dim, sparse: bool) 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) .. py:method:: constructor(dim, sparse: bool) 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 .. py:method:: sizes(dim, sparse: bool) 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). .. py:function:: 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 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. .. py:function:: 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 .. py:function:: 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. .. py:function:: 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 .. py:function:: 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 ). .. py:function:: 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 ). .. py:function:: 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 .. py:function:: lf_labels(matrix_dim: int) -> tuple[str, Ellipsis] .. py:function:: lf_matrices(matrix_dim: int) -> list[numpy.ndarray] This basis is used to isolate the parts of Hilbert-Schmidt space that act on the computational subspace induced from a partition of 3-dimensional complex Hilbert space into a 2-dimensional computational subspace and a 1-dimensional leakage space. .. py:function:: 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` .. py:function:: qsim_labels(matrix_dim) QSim basis labels. Parameters ---------- matrix_dim : int The matrix dimension to get labels for. Returns ------- list .. py:function:: 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_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]. normalize : bool, 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` .. py:data:: PP_matrices .. py:function:: pp_labels(matrix_dim) Pauli-product basis labels. Parameters ---------- matrix_dim : int The matrix dimension to get labels for. Returns ------- list .. py:function:: 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). .. py:function:: 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 .. py:function:: 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 .. py:function:: identity_labels(dim) The identity-basis labels based on a matrix dimension. Parameters ---------- dim : int The matrix dimension. .. py:function:: 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,). .. py:function:: 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 .. py:function:: 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,). .. py:function:: 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 .. py:function:: 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,). .. py:function:: 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 .. py:function:: 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,). .. py:function:: 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 .. py:function:: 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 .. py:function:: unknown_labels(dim) The labels for the "unknown" basis. Just returns an empty list. Parameters ---------- dim : int Dimension Returns ------- list