pygsti.tools.basistools

Utility functions for working with Basis objects

Module Contents

Functions

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.

basis_longname(basis)

Get the "long name" for a particular basis, which is typically used in reports, etc.

basis_element_labels(basis, dim)

Get a list of short labels corresponding to to the elements of the described basis.

is_sparse_basis(name_or_basis)

Whether a basis contains sparse matrices.

change_basis(mx, from_basis, to_basis)

Convert a operation matrix from one basis of a density matrix space to another.

create_basis_pair(mx, from_basis, to_basis)

Constructs bases from transforming mx between two basis names.

create_basis_for_matrix(mx, basis)

Construct a Basis object with type given by basis and dimension approprate for transforming mx.

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.

flexible_change_basis(mx, start_basis, end_basis)

Change mx from start_basis to end_basis allowing embedding expansion and contraction if needed.

resize_mx(mx, dim_or_block_dims=None, resize=None)

Wrapper for resize_std_mx(), that manipulates mx to be in another basis.

state_to_stdmx(state_vec)

Convert a state vector into a density matrix.

state_to_pauli_density_vec(state_vec)

Convert a single qubit state vector into a Liouville vector in the Pauli basis.

vec_to_stdmx(v, basis, keep_complex=False)

Convert a vector in this basis to a matrix in the standard basis.

stdmx_to_vec(m, basis)

Convert a matrix in the standard basis to a vector in the Pauli basis.

Attributes

gmvec_to_stdmx

ppvec_to_stdmx

qtvec_to_stdmx

stdvec_to_stdmx

stdmx_to_ppvec

stdmx_to_gmvec

stdmx_to_stdvec

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.

  • dim (int) – The dimension of the density-matrix space.

  • sparse (bool, 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

basis (Basis 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.

  • dim (int 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_basis (Basis or str) – The basis or standard-basis-name.

Returns

bool

pygsti.tools.basistools.change_basis(mx, from_basis, to_basis)

Convert a operation matrix from one basis of a density matrix space to another.

Parameters
  • mx (numpy array) – The operation matrix (a 2D square array) 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).

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
  • mx (numpy.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
  • mx (numpy.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
  • mx (numpy array) – A square matrix in the std_basis_1 basis.

  • resize ({'expand','contract'}) – Whether mx can be expanded or contracted.

  • std_basis_1 (Basis) – The ‘std’-type basis that mx is currently in.

  • std_basis_2 (Basis) – 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
  • mx (numpy array) – The operation matrix (a 2D square array) in the start_basis basis.

  • start_basis (Basis) – The source basis.

  • end_basis (Basis) – 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
  • mx (numpy 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_dims (int 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_vec (list 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_vec (list 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
  • v (numpy 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_complex (bool, 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
  • m (numpy 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