pygsti.tools.basistools
Utility functions for working with Basis objects
Module Contents
Functions
|
Get the elements of the specifed basis-type which spans the density-matrix space given by dim. |
|
Get the "long name" for a particular basis, which is typically used in reports, etc. |
|
Get a list of short labels corresponding to to the elements of the described basis. |
|
Whether a basis contains sparse matrices. |
|
Convert a operation matrix from one basis of a density matrix space to another. |
|
Constructs bases from transforming mx between two basis names. |
|
Construct a Basis object with type given by basis and dimension approprate for transforming mx. |
|
Change the basis of mx to a potentially larger or smaller 'std'-type basis given by std_basis_2. |
|
Change mx from start_basis to end_basis allowing embedding expansion and contraction if needed. |
|
Wrapper for |
|
Convert a state vector into a density matrix. |
|
Convert a single qubit state vector into a Liouville vector in the Pauli basis. |
|
Convert a vector in this basis to a matrix in the standard basis. |
|
Convert a matrix in the standard basis to a vector in the Pauli basis. |
Attributes
- pygsti.tools.basistools.basis_matrices(name_or_basis, dim, sparse=False)
Get the elements of the specifed basis-type which spans the density-matrix space given by dim.
Parameters
- name_or_basis{‘std’, ‘gm’, ‘pp’, ‘qt’} or Basis
The basis type. Allowed values are Matrix-unit (std), Gell-Mann (gm), Pauli-product (pp), and Qutrit (qt). If a Basis object, then the basis matrices are contained therein, and its dimension is checked to match dim.
- dimint
The dimension of the density-matrix space.
- sparsebool, optional
Whether any built matrices should be SciPy CSR sparse matrices or dense numpy arrays (the default).
Returns
- list
A list of N numpy arrays each of shape (dmDim, dmDim), where dmDim is the matrix-dimension of the overall “embedding” density matrix (the sum of dim_or_block_dims) and N is the dimension of the density-matrix space, equal to sum( block_dim_i^2 ).
- pygsti.tools.basistools.basis_longname(basis)
Get the “long name” for a particular basis, which is typically used in reports, etc.
Parameters
- basisBasis or str
The basis or standard-basis-name.
Returns
string
- pygsti.tools.basistools.basis_element_labels(basis, dim)
Get a list of short labels corresponding to to the elements of the described basis.
These labels are typically used to label the rows/columns of a box-plot of a matrix in the basis.
Parameters
- basis{‘std’, ‘gm’, ‘pp’, ‘qt’}
Which basis the model is represented in. Allowed options are Matrix-unit (std), Gell-Mann (gm), Pauli-product (pp) and Qutrit (qt). If the basis is not known, then an empty list is returned.
- dimint or list
Dimension of basis matrices. If a list of integers, then gives the dimensions of the terms in a direct-sum decomposition of the density matrix space acted on by the basis.
Returns
- list of strings
A list of length dim, whose elements label the basis elements.
- pygsti.tools.basistools.is_sparse_basis(name_or_basis)
Whether a basis contains sparse matrices.
Parameters
- name_or_basisBasis or str
The basis or standard-basis-name.
Returns
bool
- pygsti.tools.basistools.change_basis(mx, from_basis, to_basis, expect_real=True)
Convert a operation matrix from one basis of a density matrix space to another.
Parameters
- mxnumpy array
The operation matrix (a 2D square array or 1D vector) in the from_basis basis.
- from_basis: {‘std’, ‘gm’, ‘pp’, ‘qt’} or Basis object
The source basis. Allowed values are Matrix-unit (std), Gell-Mann (gm), Pauli-product (pp), and Qutrit (qt) (or a custom basis object).
- to_basis{‘std’, ‘gm’, ‘pp’, ‘qt’} or Basis object
The destination basis. Allowed values are Matrix-unit (std), Gell-Mann (gm), Pauli-product (pp), and Qutrit (qt) (or a custom basis object).
- expect_realbool, optional (default True)
Optional flag specifying whether it is expected that the returned array in the new basis is real valued. Default is True.
Returns
- numpy array
The given operation matrix converted to the to_basis basis. Array size is the same as mx.
- pygsti.tools.basistools.create_basis_pair(mx, from_basis, to_basis)
Constructs bases from transforming mx between two basis names.
Construct a pair of Basis objects with types from_basis and to_basis, and dimension appropriate for transforming mx (if they’re not already given by from_basis or to_basis being a Basis rather than a str).
Parameters
- mxnumpy.ndarray
A matrix, assumed to be square and have a dimension that is a perfect square.
- from_basis: {‘std’, ‘gm’, ‘pp’, ‘qt’} or Basis object
The source basis (named because it’s usually the source basis for a basis change). Allowed values are Matrix-unit (std), Gell-Mann (gm), Pauli-product (pp), and Qutrit (qt) (or a custom basis object). If a custom basis object is provided, it’s dimension should be equal to sqrt(mx.shape[0]) == sqrt(mx.shape[1]).
- to_basis: {‘std’, ‘gm’, ‘pp’, ‘qt’} or Basis object
The destination basis (named because it’s usually the destination basis for a basis change). Allowed values are Matrix-unit (std), Gell-Mann (gm), Pauli-product (pp), and Qutrit (qt) (or a custom basis object). If a custom basis object is provided, it’s dimension should be equal to sqrt(mx.shape[0]) == sqrt(mx.shape[1]).
Returns
from_basis, to_basis : Basis
- pygsti.tools.basistools.create_basis_for_matrix(mx, basis)
Construct a Basis object with type given by basis and dimension approprate for transforming mx.
Dimension is taken from mx (if it’s not given by basis) that is sqrt(mx.shape[0]).
Parameters
- mxnumpy.ndarray
A matrix, assumed to be square and have a dimension that is a perfect square.
- basis{‘std’, ‘gm’, ‘pp’, ‘qt’} or Basis object
A basis name or Basis object. Allowed values are Matrix-unit (std), Gell-Mann (gm), Pauli-product (pp), and Qutrit (qt) (or a custom basis object). If a custom basis object is provided, it’s dimension must equal sqrt(mx.shape[0]), as this will be checked.
Returns
Basis
- pygsti.tools.basistools.resize_std_mx(mx, resize, std_basis_1, std_basis_2)
Change the basis of mx to a potentially larger or smaller ‘std’-type basis given by std_basis_2.
(mx is assumed to be in the ‘std’-type basis given by std_basis_1.)
This is possible when the two ‘std’-type bases have the same “embedding dimension”, equal to the sum of their block dimensions. If, for example, std_basis_1 has block dimensions (kite structure) of (4,2,1) then mx, expressed as a sum of 4^2 + 2^2 + 1^2 = 21 basis elements, can be “embedded” within a larger ‘std’ basis having a single block with dimension 7 (7^2 = 49 elements).
When std_basis_2 is smaller than std_basis_1 the reverse happens and mx is irreversibly truncated, or “contracted” to a basis having a particular kite structure.
Parameters
- mxnumpy array
A square matrix in the std_basis_1 basis.
- resize{‘expand’,’contract’}
Whether mx can be expanded or contracted.
- std_basis_1Basis
The ‘std’-type basis that mx is currently in.
- std_basis_2Basis
The ‘std’-type basis that mx should be converted to.
Returns
numpy.ndarray
- pygsti.tools.basistools.flexible_change_basis(mx, start_basis, end_basis)
Change mx from start_basis to end_basis allowing embedding expansion and contraction if needed.
(see
resize_std_mx()for more details).Parameters
- mxnumpy array
The operation matrix (a 2D square array) in the start_basis basis.
- start_basisBasis
The source basis.
- end_basisBasis
The destination basis.
Returns
numpy.ndarray
- pygsti.tools.basistools.resize_mx(mx, dim_or_block_dims=None, resize=None)
Wrapper for
resize_std_mx(), that manipulates mx to be in another basis.This function first constructs two ‘std’-type bases using dim_or_block_dims and sum(dim_or_block_dims). The matrix mx is converted from the former to the latter when resize == “expand”, and from the latter to the former when resize == “contract”.
Parameters
- mxnumpy array
Matrix of size N x N, where N is the dimension of the density matrix space, i.e. sum( dimOrBlockDims_i^2 )
- dim_or_block_dimsint or list of ints
Structure of the density-matrix space. Gives the matrix dimensions of each block.
- resize{‘expand’,’contract’}
Whether mx should be expanded or contracted.
Returns
numpy.ndarray
- pygsti.tools.basistools.state_to_stdmx(state_vec)
Convert a state vector into a density matrix.
Parameters
- state_veclist or tuple
State vector in the standard (sigma-z) basis.
Returns
- numpy.ndarray
A density matrix of shape (d,d), corresponding to the pure state given by the length-d array, state_vec.
- pygsti.tools.basistools.state_to_pauli_density_vec(state_vec)
Convert a single qubit state vector into a Liouville vector in the Pauli basis.
Parameters
- state_veclist or tuple
State vector in the sigma-z basis, len(state_vec) == 2
Returns
- numpy array
The 2x2 density matrix of the pure state given by state_vec, given as a 4x1 column vector in the Pauli basis.
- pygsti.tools.basistools.vec_to_stdmx(v, basis, keep_complex=False)
Convert a vector in this basis to a matrix in the standard basis.
Parameters
- vnumpy array
The vector length 4 or 16 respectively.
- basis{‘std’, ‘gm’, ‘pp’, ‘qt’} or Basis
The basis type. Allowed values are Matrix-unit (std), Gell-Mann (gm), Pauli-product (pp), and Qutrit (qt). If a Basis object, then the basis matrices are contained therein, and its dimension is checked to match v.
- keep_complexbool, optional
If True, leave the final (output) array elements as complex numbers when v is complex. Usually, the final elements are real (even though v is complex) and so when keep_complex=False the elements are forced to be real and the returned array is float (not complex) valued.
Returns
- numpy array
The matrix, 2x2 or 4x4 depending on nqubits
- pygsti.tools.basistools.gmvec_to_stdmx
- pygsti.tools.basistools.ppvec_to_stdmx
- pygsti.tools.basistools.qtvec_to_stdmx
- pygsti.tools.basistools.stdvec_to_stdmx
- pygsti.tools.basistools.stdmx_to_vec(m, basis)
Convert a matrix in the standard basis to a vector in the Pauli basis.
Parameters
- mnumpy array
The matrix, shape 2x2 (1Q) or 4x4 (2Q)
- basis{‘std’, ‘gm’, ‘pp’, ‘qt’} or Basis
The basis type. Allowed values are Matrix-unit (std), Gell-Mann (gm), Pauli-product (pp), and Qutrit (qt). If a Basis object, then the basis matrices are contained therein, and its dimension is checked to match m.
Returns
- numpy array
The vector, length 4 or 16 respectively.
- pygsti.tools.basistools.stdmx_to_ppvec
- pygsti.tools.basistools.stdmx_to_gmvec
- pygsti.tools.basistools.stdmx_to_stdvec