tensortools: tensor tools

qecsim.tensortools

This module contains sub-modules for tensors, matrix product states/operators (MPS/MPO) and two-dimensional lattices.

qecsim.tensortools.tsr

This module contains functions for tensors

Notes:

  • The functions are for tensors defined as numpy.array objects.

qecsim.tensortools.tsr.as_scalar(tsr)

Return tensor as scalar.

Parameters

tsr (numpy.array (4d)) – Tensor

Returns

Scalar

Return type

numpy.number

Raises

ValueError – if tensor is not a scalar.

qecsim.tensortools.tsr.delta(shape)

Return delta tensor of given shape, i.e. element values of 1 when all non-dummy indices are equal, 0 otherwise.

Parameters

shape (tuple of int) – Shape of tensor.

Returns

Delta tensor

Return type

numpy.array

qecsim.tensortools.mps

This module contains functions for Matrix Product States (MPS) and Matrix Product Operators (MPO)

Notes:

  • An MPS/MPO is represented by a lists of tensors represented by numpy arrays.

  • Most functions support sparse MPS/MPO with None objects in place of tensors but some require a single contiguous list of tensors with None only supported at the start and/or end of the MPS/MPO, see function documentation for details.

  • All tensors must have 4 indices in the following order (N, E, S, W) where N and S are North and South link indices and E and W are East and West physical indices. Irrelevant indices must have dimension 1 to be treated as dummy indices.

  • Equivalently, tensors can be thought of as having 4 indices in the following order (L, U, R, D) where L and R are Left and Right link indices and U and D are Up and Down physical indices.

  • For example, if the tensor network has physical indices of dimension p and link indices of dimension l:

    • A bra MPS is a list of numpy.array with shapes: (1, p, l, 1), (l, p, l, 1), …, (l, p, l, 1), (l, p, 1, 1)

    • An MPO is a list of numpy.array with shapes: (1, p, l, p), (l, p, l, p), …, (l, p, l, p), (l, p, 1, p)

    • A ket MPS is a list of numpy.array with shapes: (1, 1, l, p), (l, 1, l, p), …, (l, 1, l, p), (l, 1, 1, p)

For more details on matrix product states and the functions in this module, see Schollwoeck, U. (2011) “The density-matrix renormalization group in the age of matrix product states” https://arxiv.org/abs/1008.3477

qecsim.tensortools.mps.bond_dimension(mps)

Given an MPS/MPO as a list of tensors with indices (N, E, S, W), return the maximum dimension of the N indices.

(Equivalently, given an MPS/MPO as a list of tensors with indices (L, U, R, D), return the maximum dimension of the L indices.)

Notes:

  • None objects in the MPS/MPO are considered to have dimension 0.

Parameters

mps (list of numpy.array (4d)) – MPS/MPO

Returns

Bond dimension of MPS/MPO.

Return type

int

qecsim.tensortools.mps.contract_ladder(mps)

Given an MPS/MPO as a lists of tensors with indices (N, E, S, W), return the tensor evaluated by contracting the MPS/MPO by summing over the S index of the first tensor and the N index of each subsequent tensor.

(Equivalently, given an MPS/MPO as a lists of tensors with indices (L, U, R, D), return the tensor evaluated by contracting the MPS/MPO by summing over the R index of the first tensor and the L index of each subsequent tensor.)

Notes:

  • Sparse MPS/MPO with None objects are supported provided that they contain a single contiguous list of tensors; None objects at the start and/or end are ignored.

Parameters

mps (list of numpy.array (4d)) – MPS/MPO.

Returns

Contracted tensor.

Return type

numpy.array (4d)

qecsim.tensortools.mps.contract_pairwise(left_mps, right_mps)

Given two MPS/MPO as equal length lists of tensors with indices (N, E, S, W), return a single MPS/MPO evaluated by contracting the tensors of the left MPS/MPO and right MPS/MPO pairwise summing over the E index of each left tensor and the W index of the corresponding right tensor.

(Equivalently, given two MPS/MPO as equal length lists of tensors with indices (L, U, R, D), return a single MPS/MPO evaluated by contracting the tensors of the left MPS/MPO and right MPS/MPO pairwise summing over the U index of each left tensor and the D index of the corresponding right tensor.)

Notes:

  • Sparse MPS/MPO with None objects are supported by simply copying the corresponding object (tensor or None) from the other MPS/MPO to the resultant contracted MPS/MPO.

Parameters

  • left_mps (list of numpy.array (4d)) – Left MPS/MPO.

  • right_mps (list of numpy.array (4d)) – Right MPS/MPO.

Returns

Pairwise contracted MPS/MPO.

Return type

list of numpy.array (4d)

qecsim.tensortools.mps.inner_product(bra_mps, ket_mps)

Given bra and ket MPS as equal length lists of tensors with indices (N, E, S, W), return the inner product evaluated by pairwise contracting (see contract_pairwise()) the bra and ket MPS, ladder contracting the resultant MPS (see contract_ladder()), and extracting final contracted tensor as a scalar.

(Equivalently, given bra and ket MPS as equal length lists of tensors with indices (L, U, R, D), return the inner product evaluated by pairwise contracting (see contract_pairwise()) the bra and ket MPS and ladder contracting the resultant MPS (see contract_ladder()), and extracting final contracted tensor as a scalar).

Notes:

  • Sparse MPS with None objects are supported, as described in contract_pairwise(), but the pairwise-contracted MPS must contain a single contiguous list of tensors, as described in contract_ladder().

  • The bra MPS must have dummy (dimension 1) indices in the N and W positions of the first tensor, W position of subsequent tensors, and S and W positions of the last tensor.

    (Equivalently, the bra MPS must have dummy (dimension 1) indices in the L and D positions of the first tensor, D position of subsequent tensors, and R and D positions of the last tensor.)

  • The ket MPS must have dummy (dimension 1) indices in the N and E positions of the first tensor, E position of subsequent tensors, and S and E positions of the last tensor.

    (Equivalently, the ket MPS must have dummy (dimension 1) indices in the L and U positions of the first tensor, U position of subsequent tensors, and R and U positions of the last tensor.)

Parameters

  • bra_mps (list of numpy.array (4d)) – Bra MPS.

  • ket_mps (list of numpy.array (4d)) – Ket MPS.

Returns

Inner product.

Return type

numpy.number

Raises

  • ValueError – if pairwise-contracted MPS does not contain a single contiguous list of tensors.

  • ValueError – if final contraction is not a scalar.

qecsim.tensortools.mps.left_canonical_form(mps, chi=None, tol=None, qr=False, normalise=False, mask=None)

Given an MPS/MPO as a list of tensors, return the MPS/MPO in left canonical form evaluated by QR decomposition or SVD of each tensor in turn, retaining the unitary matrix and contracting the other matrices of the decomposition into the next tensor.

Notes:

  • Sparse MPS/MPO with None objects are supported provided that they contain a single contiguous list of tensors; None objects at the start and/or end are ignored.

  • The QR algorithm is faster than the default SVD algorithm but is incompatible with defined chi and tol parameters.

  • If chi is defined, it specifies the number of singular values retained in the SVD of each tensor. This effectively truncates the bond dimension of the MPS/MPO to chi.

  • If tol is defined, only the singular values in the SVD of each tensor that, when normalised, are strictly larger than tol will be retained. This effectively defines a tolerance below which normalised singular values are considered to be zero.

  • If normalise is False, the returned MPS/MPO will not be normalised and the only return value.

  • If normalise is True, the returned MPS/MPO will be normalised and the returned normalisation factor set accordingly. However, if the norm is zero then the returned MPS/MPO will consist of zero tensors like those in the given MPS/MPO but with bond dimension 1, and the normalisation factor will be 0.0.

  • If mask is specified and the element corresponding to a given tensor is falsy, the tensor will be decomposed using the QR algorithm and truncation based on chi or tol will be skipped.

Parameters

  • mps (list of numpy.array (4d)) – MPS/MPO

  • chi (int or None) – Truncated bond dimension. (default=None, unrestricted=None)

  • tol (float or None) – Tolerance for treating normalised singular values as zero. (default=None, unrestricted=None)

  • qr (bool) – Use QR decomposition instead of SVD. (Incompatible with chi and tol parameters) (default=False)

  • normalise (bool) – Normalise resultant MPS/MPO. (default=False)

  • mask (list of bool or None) – Mask of same length as mps. True indicates tensor may be truncated. (default=None resolves to all True)

Returns

MPS/MPO in left canonical form (if normalise=True: MPS/MPO in left canonical form, Norm of MPS/MPO)

Return type

list of numpy.array (4d) (if normalise=True: 2-tuple of list of numpy.array (4d), mpmath.mpf)

Raises

ValueError – if MPS/MPO does not contain a single contiguous list of tensors.

qecsim.tensortools.mps.reverse(mps)

Given an MPS/MPO as a list of tensors with indices (N, E, S, W), return the reversed list with N and S indices swapped for each tensor, i.e. (N, E, S, W) -> (S, E, N, W).

(Equivalently, given an MPS/MPO as a list of tensors with indices (L, U, R, D), return the reversed list with L and R indices swapped for each tensor, i.e. (L, U, R, D) -> (R, U, L, D).)

Notes:

  • None objects in the MPS/MPO are copied to the reversed list unchanged.

Parameters

mps (list of numpy.array (4d)) – MPS/MPO

Returns

Reversed MPS/MPO

Return type

list of numpy.array (4d)

qecsim.tensortools.mps.right_canonical_form(mps, chi=None, tol=None, qr=False, normalise=False, mask=None)

Given an MPS/MPO as a list of tensors, return the MPS/MPO in right canonical form evaluated by reversing the MPS/MPO (see reverse()), converting the reversed MPS to left canonical form (see left_canonical_form()), and reversing the resultant MPS.

Notes: see left_canonical_form()

Parameters

  • mps (list of numpy.array (4d)) – MPS/MPO

  • chi (int or None) – Truncated bond dimension. (default=None, unrestricted=None)

  • tol (float or None) – Tolerance for treating normalised singular values as zero. (default=None, unrestricted=None)

  • qr (bool) – Use QR decomposition instead of SVD. (Incompatible with chi and tol parameters) (default=False)

  • normalise (bool) – Normalise resultant MPS/MPO. (default=False)

  • mask (list of bool or None) – Mask of same length as mps. True indicates tensor may be truncated. (default=None resolves to all True)

Returns

MPS/MPO in right canonical form (if normalise=True: MPS/MPO in right canonical form, Norm of MPS/MPO)

Return type

list of numpy.array (4d) (if normalise=True: 2-tuple of list of numpy.array (4d), float)

Raises

ValueError – if MPS/MPO does not contain a single contiguous list of tensors.

qecsim.tensortools.mps.truncate(mps, chi=None, tol=None, mask=None)

Given an MPS/MPO as a list of tensors, return the MPS/MPO with truncated bond dimension.

The evaluation is as follows:

  1. Put the MPS/MPO into left canonical form (see left_canonical_form()) without truncation

  2. Normalise the final tensor of the MPS/MPO and set the norm.

  3. Put the resultant MPS/MPO into right canonical form (see right_canonical_form()) truncating to chi singular values for each tensor.

  4. Return the resultant MPS/MPO in right canonical form with the norm from step 2.

Notes:

  • Sparse MPS/MPO with None objects are supported provided that they contain a single contiguous list of tensors; None objects at the start and/or end are ignored.

  • If tol is unspecified and the current bond dimension (see bond_dimension()) is less than or equal to chi or the mask is all falsy, the MPS/MPO is returned unmodified and the norm is returned as 1.0.

  • If the final tensor of the MPS/MPO cannot be normalised, the norm is returned as 1.0.

Parameters

  • mps (list of numpy.array (4d)) – MPS/MPO

  • chi (int or None) – Truncated bond dimension. (default=None, unrestricted=None)

  • tol (float or None) – Tolerance for treating normalised singular values as zero. (default=None, unrestricted=None)

  • mask (list of bool or None) – Mask of same length as mps. True indicates tensor may be truncated. (default=None resolves to all True)

Returns

MPS/MPO with truncated bond dimension, norm from putting into left canonical form.

Return type

list of numpy.array (4d), float

Raises

ValueError – if MPS/MPO does not contain a single contiguous list of tensors.

qecsim.tensortools.mps.zeros_like(mps)

Given an MPS/MPO as a lists of tensors with indices (N, E, S, W), return an MPS/MPO consisting of zero tensors with virtual indices (N, S) of dimension 1 and physical indices (E, W) of the same dimensions as those of the corresponding tensor in the given MPS/MPO.

(Equivalently, given an MPS/MPO as a lists of tensors with indices (L, U, R, D), return an MPS/MPO consisting of zero tensors with virtual indices (L, R) of dimension 1 and physical indices (U, D) of the same dimensions as those of the corresponding tensor in the given MPS/MPO.)

Notes:

  • Sparse MPS/MPO with None objects are supported by simply inserting None objects in the zeros MPS/MPO in the corresponding position in the list.

Parameters

mps (list of numpy.array (4d)) – MPS/MPO.

Returns

Zeros MPS/MPO.

Return type

list of numpy.array (4d)

qecsim.tensortools.mps2d

This module contains functions for two-dimensional lattice tensor networks

Notes:

  • The functions are for 2-D tensor networks where each row or column is an MPS/MPO.

qecsim.tensortools.mps2d.contract(tn, chi=None, tol=None, start=None, stop=None, step=None, mask=None)

Return column-by-column contraction of tensor network where each column as an MPS/MPO.

Notes:

  • Sparse MPS/MPO with None objects are supported provided that they contain a single contiguous list of tensors; None objects at the start and/or end are ignored.

  • The contraction is performed as a series of qecsim.tensortools.mps.contract_pairwise() / qecsim.tensortools.mps.truncate() operations followed by a qecsim.tensortools.mps.inner_product() operation on the final pair of columns without truncation.

  • In case of a full contraction, the network is assumed to contract to a scalar.

  • In case of a partial contraction, the final column is truncated but not contracted to a scalar.

  • In case of a partial contraction, to avoid underflow, a multiplier is returned that is only the cumulative norm from the truncation operations. Therefore, it should not be assumed that the returned value is fully normalised; rather the true value is given by the product of the returned value and multiplier.

  • In case of a partial contraction where the range of columns is empty, None is returned with multiplier 1.

Parameters

  • tn (numpy.array (2d) of numpy.array (4d)) – Tensor network whose columns are MPS/MPO.

  • chi (int or None) – Truncated bond dimension. (default=None, unrestricted=None)

  • tol (float or None) – Tolerance for treating normalised singular values as zero. (default=None, unrestricted=None)

  • start (int or None) – Start column index (default=None resolves to 0)

  • stop (int or None) – Stop column index (exclusive) (default=None resolves to number of columns)

  • step (int or None) – Step (default=None resolves to 1)

  • mask (numpy.array (2d) of bool or None) – Mask of same shape as tn. True indicates tensor may be truncated. (default=None resolves to all True)

Returns

Contraction value (if partial contraction: Partially contracted tensor network as MPS/MPO, Multiplier)

Return type

mpmath.mpf (if partial contraction: numpy.array (1d) of numpy.array (4d), mpmath.mpf)

Raises

  • ValueError – if pairwise-contracted MPS/MPOs do not contain a single contiguous list of tensors.

  • ValueError – if full contraction and final contraction value is not a scalar.

qecsim.tensortools.mps2d.transpose(tn)

Return transposed network of tensors.

Notes:

  • Both the network and each tensor is transposed, so that contracting the transposed network column-by-column is equivalent to contracting the original network row-by-row.

  • Sparse tensor networks with None objects are supported; None objects are unchanged.

Parameters

tn (numpy.array (2d) of numpy.array (4d)) – Tensor network whose columns are MPS/MPO.

Returns

Transposed tensor network.

Return type

numpy.array (2d) of numpy.array (4d)