mdopt.utils package#

Submodules#

mdopt.utils.utils module#

This module contains miscellaneous utilities.

mdopt.utils.utils.create_random_mpo(num_sites: int, bond_dimensions: List[int], phys_dim: int, which: str = 'uniform') → List[ndarray]#

Creates a random complex-valued Matrix Product Operator.

Parameters:

  • num_sites (int) – The number of sites for the MPO. This will be equal to the number of tensors.

  • bond_dimensions (List[int]) – A list of bond dimensions.

  • phys_dim (int) – Physical dimension of the tensors.

  • which (str) – Specifies the distribution from which the matrix elements are being taken. Options: “uniform”, “normal”, “randint”.

Returns:

mpo – The resulting MPO.

Return type:

List[np.ndarray]

Notes

The bond_dimensions argument should be given as a list of right virtual dimensions without the last trivial virtual dimension. Thus, the length of the list is num_sites - 1.

The distributions available: uniform(0,1), normal, random integer {0,1}.

Each tensor in the MPO list has legs (vL, vR, pU, pD), where v stands for “virtual”, p – for “physical”, and L, R, U, D – for “left”, “right”, “up”, “down” accordingly.

mdopt.utils.utils.kron_tensors(tensor_1: ndarray, tensor_2: ndarray, conjugate_second: bool = False, merge_physicals: bool = True) → ndarray#

Computes a Kronecker product of 2 MPS tensors.

Parameters:

  • tensor_1 (np.ndarray) – The first tensor of the product.

  • tensor_2 (np.ndarray) – The second tensor of the product.

  • conjugate_second (bool) – Whether to complex-conjugate the second tensor.

  • merge_physicals (bool) – Whether to merge physical indices.

Returns:

The resulting Kronecker product.

Return type:

product

Raises:

  • ValueError – If the first MPS tensor is not three-dimensional.

  • ValueError – If the second MPS tensor is not three-dimensional.

Notes

This function acts according to the following diagram:

   tensor_2
      i
      |                      i
j ---( )--- k                |
                -->    jl---( )---kn
l ---( )--- n                |
      |                      m
      m
   tensor_1

The legs of the resulting tensor are indexed as (jl, m, i, kn). Indices i and m can be merged if merge_physicals=True.

mdopt.utils.utils.mpo_from_matrix(matrix: ndarray, num_sites: int, interlaced: bool = True, orthogonalise: bool = False, phys_dim: int = 2, chi_max: int = 10000) → List[ndarray]#

Creates an MPO from a matrix (either grouped 2D or ungrouped 2N-D).

If orthogonalise=True, carry singular values to the orthogonality centre (isometric tensors except centre). Otherwise split sqrt singular values to both sides (non-isometric, no single centre).

mdopt.utils.utils.mpo_to_matrix(mpo: List[ndarray], interlace: bool = False, group: bool = False) → ndarray#

Creates a matrix from an MPO.

Parameters:

  • mpo (List[np.ndarray]) – The MPO to convert to a matrix.

  • interlace (bool) – Whether to interlace the matrix’ legs or not.

  • group (bool) – Whether to group the matrix’ legs or not, see the notes. Grouping means merging all the up legs into one leg and the same for the down legs.

Returns:

matrix – The resulting matrix.

Return type:

np.ndarray

Raises:

ValueError – If any of the MPO tensors is not four-dimensional.

Notes

If interlace==True, the matrix’ legs will go as (p0U, p0D, p1U, p1D, ...), which means physical legs sticking up and down with the site number. If interlace==False, the matrix’ legs will go as (p0D, p1D, ..., p0U, p1U, ...), which means listing first all physical legs sticking down with the site number, and then all physical legs sticking up. This is done to adjust the matrix to the @ numpy-native matrix-vector multiplication. Note, grouping (if wanted) is being done after the interlacing.

An example of a matrix with ungrouped legs on three sites:

  p0U p1U p2U
 __|___|___|__
|            |
|____________|
   |   |   |
  p0D p1D p2D

Each tensor in the MPO list has legs (vL, vR, pU, pD), where v stands for “virtual”, p – for “physical”, and L, R, U, D – for “left”, “right”, “up”, “down” accordingly. Warning: will cause memory overflow for number of sites > ~20.

mdopt.utils.utils.qr(mat: ndarray, cut: float = 1e-12, chi_max: int = 10000, renormalise: bool = False, return_truncation_error: bool = False) → Tuple[ndarray, ndarray, float | None]#

Performs QR Decomposition with a possibility for truncation.

Parameters:

  • mat (np.ndarray) – Matrix provided as a np.ndarray with 2 dimensions.

  • cut (float) – Threshold below which the diagonal values of R are discarded.

  • chi_max (int) – Maximum number of columns/rows to keep after truncation.

  • renormalise (bool) – Whether to renormalise the matrix after truncation.

  • return_truncation_error (bool) – Whether to return the truncation error.

Returns:

  • Q (np.ndarray) – The orthogonal matrix after truncation.

  • R (np.ndarray) – The upper triangular matrix after truncation.

  • truncation_error (Optional[float]) – The truncation error. Returned only if return_truncation_error is True.

Raises:

ValueError – If the input matrix does not have 2 dimensions.

Notes

The truncation is based on the magnitudes of the absolute values of the diagonal elements of R.

mdopt.utils.utils.split_two_site_tensor(tensor: ndarray, chi_max: int = 10000, cut: float = 1e-12, renormalise: bool = False, strategy: str = 'svd', return_truncation_error: bool = False) → Tuple#

Split and truncate a two-site MPS tensor according to the following diagram (in case of the SVD strategy, similarly but without the singular vals for the others):

                                      m         n
i ---(tensor)--- l     ->    i ---(A)---diag(S)---(B)--- l
      |   |                        |               |
      j   k                        j               k
Parameters:

  • tensor (np.ndarray) – Two-site tensor (i, j, k, l).

  • chi_max (int) – Maximum number of singular/diagonal values to keep.

  • cut (float) – Discard any singular/diagonal values smaller than this.

  • renormalise (bool) – Whether to renormalise the singular value spectrum or the R diagonal after the cut.

  • strategy (str) – Which strategy to use for the splitting. Available options: svd and qr.

  • return_truncation_error (bool) – Whether to return the truncation error.

Returns:

  • a_l (np.ndarray) – Left isometry (i, j, m).

  • singular_values (np.ndarray) – List of singular values. Only returned if the decomposition strategy is set to svd.

  • b_r (np.ndarray) – Right isometry (n, k, l).

  • truncation_error (Optional[float]) – The truncation error.

Raises:

  • ValueError – If the tensor is not four-dimensional.

  • ValueError – If the strategy is not one of the available ones.

mdopt.utils.utils.svd(mat: ndarray, cut: float = 1e-12, chi_max: int = 10000, renormalise: bool = False, return_truncation_error: bool = False) → Tuple[ndarray, List[float], ndarray, float | None]#

Performs Singular Value Decomposition with different features.

Parameters:

  • mat (np.ndarray) – Matrix provided as a np.ndarray with 2 dimensions.

  • cut (float) – Singular values smaller than this will be discarded.

  • chi_max (int) – Maximum number of singular values to keep.

  • renormalise (bool) – Whether to renormalise the singular value spectrum after the cut.

  • return_truncation_error (bool) – Whether to return the truncation error.

Returns:

  • u_l (np.ndarray) – Unitary matrix having left singular vectors as columns.

  • singular_values (list) – The singular values, sorted in non-increasing order.

  • v_r (np.ndarray) – Unitary matrix having right singular vectors as rows.

  • truncation_error (Optional[float]) – The truncation error. Only returned if return_truncation_error is True.

Raises:

ValueError – If the input matrix does not have 2 dimensions.

Module contents#