mdopt.mps package

Submodules

mdopt.mps.canonical module

This module contains the CanonicalMPS class. Hereafter, saying the MPS is in a canonical form will mean one of the following.

  1. Right-canonical: all tensors are right isometries, i.e.:

    ---( )---     ---
    |   |       |
    |   |  ==   |
    |   |       |
---(*)---     ---

  2. Left-canonical: all tensors are left isometries, i.e.:

    ---( )---     ---
|   |         |
|   |    ==   |
|   |         |
---(*)---     ---

3) Mixed-canonical: all but one tensors are left or right isometries. This exceptional tensor will be hereafter called the orthogonality centre.

Note that, in the diagrams, a tensor with a star inside means that it is complex-conjugated.

The Matrix Product State is stored as a list of three-dimensional tensors. Essentially, it corresponds to storing each A[i] or B[i] as shown in fig.4c in reference [1].

class mdopt.mps.canonical.CanonicalMPS(tensors: List[ndarray], orth_centre: Optional[int] = None, tolerance: float32 = 1e-12, chi_max: int = 10000)

Class for finite-size canonical matrix product states with open boundary conditions.

tensors

The tensors of the MPS, one per each physical site. Each tensor has legs (virtual left, physical, virtual right), in short (vL, i, vR).

Type:

List[np.ndarray]

orth_centre

Position of the orthogonality centre, does not support negative indexing. As a convention, this attribute is taken 0 for a right-canonical form, len(tensors) - 1 for a left-canonical form, None for a product state.

Type:

Optional[int]

tolerance

Numerical tolerance to zero out the singular values in Singular Value Decomposition.

Type:

np.float32

chi_max

The maximum bond dimension to keep in Singular Value Decompositions.

Type:

int

bond_dimensions

The list of all bond dimensions of the MPS.

Type:

List[int]

phys_dimensions

The list of all physical dimensions of the MPS.

Type:

List[int]

num_sites

Number of sites.

Type:

int

num_bonds

Number of bonds.

Type:

int

Raises:

  • ValueError – If the orthogonality centre position does not correspond to the number of sites.

  • ValueError – If any of the tensors does not have three dimensions.

compress_bond(t_0, t_1)

Compresses the bond between two tensors.

Parameters:

  • t_0 (np.ndarray) – The first tensor.

  • t_1 (np.ndarray) – The second tensor.

Returns:

  • t_0_new (np.ndarray) – The first tensor after compression.

  • t_1_new (np.ndarray) – The second tensor after compression.

Notes

The compression follows a scheme outlined in https://arxiv.org/abs/1708.08932.

conjugate() → CanonicalMPS

Returns a complex-conjugated version of the current MPS.

copy() → CanonicalMPS

Returns a copy of the current MPS.

dense(flatten: bool = True, renormalise: bool = False, norm: Union[None, float, Literal['fro', 'nuc']] = 2) → ndarray

Returns a dense representation of the MPS.

Warning: this method can cause memory overload for number of sites > ~20!

Parameters:

  • flatten (bool) – Whether to merge all the physical indices to form a vector or not.

  • renormalise (bool) – Whether to renormalise the resulting tensor.

  • norm (Any) – The order of the norm to use while renormalising, see numpy.linalg.norm.

density_mpo() → List[ndarray]

Returns the MPO representation (as a list of tensors) of the density matrix defined by the MPS in a canonical form. 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 stand for “left”, “right”, “up”, “down”.

Notes

This operation is depicted in the following diagram:

       i     j
 a     |     |    c                 i     j
...---(*)---(*)---...           ab  |     |  cd
                        -->  ...---[ ]---[ ]---...
...---( )---( )---...               |     |
 b     |     |    d                 k     l
       k     l

In the cartoon, {i,j,k,l} and {a,b,c,d} are indices. Here, the ( )’s represent the MPS tensors, the [ ]’s —the MPO tensors. The MPS with the physical legs up is complex-conjugated element-wise. The empty line between the MPS and its complex-conjugated version stands in fact for the tensor (kronecker) product.

Warning, this object can be memory-intensive for large bond dimensions!

entanglement_entropy(tolerance: float32 = 1e-12) → ndarray

Returns the entanglement entropy for bipartitions at each of the bonds.

explicit(tolerance: float32 = 1e-12, renormalise: bool = True) → ExplicitMPS

Transforms a CanonicalMPS instance into a ExplicitMPS instance. Essentially, retrieves each Γ[i] and Λ[i] from A[i] or B[i]. See fig.4b in [1] for reference.

Parameters:

  • tolerance (np.float32) – Numerical tolerance for the singular values.

  • renormalise (bool) – Whether to renormalise singular values during each SVD.

left_canonical(renormalise: bool = True) → CanonicalMPS

Returns the current MPS in the left-canonical form. See eq.19 in [1] for reference.

marginal(sites_to_marginalise: List[int], canonicalise: bool = False) → CanonicalMPS

Computes a marginal over a subset of sites of an MPS. Attention, this method acts inplace. For the non-inplace version, take a look into the mps.utils module.

Parameters:

  • sites_to_marginalise (List[int]) – The sites to marginalise over.

  • canonicalise (bool) – Whether to put the result in the canonical form, i.e., whether to sweep with SVDs over the left bonds.

Notes

The algorithm proceeds by starting from the bond possessing the maximum dimension and contracting the marginalised tensors into the tensors left untouched. The list of sites to marginalise is then updated by removing the corresponding site from it. This subroutine continues until the list of sites to marginalise is empty. An example of marginalising is shown in the following diagram:

---(0)---(1)---(2)---(3)---    ---(2)---(3)---
    |     |     |     |     ->     |     |
    |     |     |     |            |     |
   (t)   (t)

Here, the (t) (trace) tensor is a tensor consisting af all 1’s.

mixed_canonical(orth_centre: int, renormalise: bool = True) → CanonicalMPS

Returns the current MPS in the mixed-canonical form with the orthogonality centre being located at orth_centre.

Parameters:

orth_centre_index (int) – An integer which can take values 0, 1, ..., num_sites-1. Denotes the position of the orthogonality centre – the only non-isometry in the new canonical MPS.

move_orth_centre(final_pos: int, return_singular_values: bool = False, renormalise: bool = True) → Union[CanonicalMPS, Tuple[CanonicalMPS, List[list]]]

Moves the orthogonality centre from its current position to final_pos.

Returns a new version of the current CanonicalMPS instance with the orthogonality centre moved from self.orth_centre to final_pos, returns also the singular value tensors from every covered bond as well.

Parameters:

  • final_pos (int) – Final position of the orthogonality centre.

  • return_singular_values (bool) – Whether to return the singular values obtained at each involved bond.

  • renormalise (bool) – Whether to renormalise singular values during each SVD.

Raises:

ValueError – If final_pos does not match the MPS length.

move_orth_centre_to_border(renormalise: bool = True) → Tuple[CanonicalMPS, str]

Moves the orthogonality centre from its current position to the closest border.

Parameters:

renormalise (bool) – Whether to renormalise singular values during each SVD.

:param Returns a new version of the current CanonicalMPS instance with: :param the orthogonality centre moved to the closest (from the current position) border.:

norm() → float32

Computes the norm of the current MPS, that is, the modulus squared of its inner product with itself.

one_site_expectation_value(site: int, operator: ndarray) → Union[float32, complex128]

Computes an expectation value of an arbitrary one-site operator (not necessarily unitary) on the given site.

Parameters:

  • site (int) – The site where the operator is applied.

  • operator (np.ndarray) – The one-site operator

Notes

An example of a one-site expectation value is shown in the following diagram:

( )---( )---( )---( )
 |     |     |     |
 |    (o)    |     |
 |     |     |     |
( )---( )---( )---( )
one_site_tensor(site: int) → ndarray

Returs a particular MPS tensor located at the corresponding site.

Parameters:

site (int) – The site index of the tensor.

one_site_tensor_iter() → Iterable

Returns an iterator over the one-site tensors for every site.

reverse() → CanonicalMPS

Returns a reversed version of a given MPS.

right_canonical(renormalise: bool = True) → CanonicalMPS

Returns the current MPS in the right-canonical form. See eq.19 in [1] for reference.

two_site_expectation_value(site: int, operator: ndarray) → Union[float32, complex128]

Computes an expectation value of an arbitrary two-site operator (not necessarily unitary) on the given site and its next neighbour. The operator has legs (UL, DL, UR, DR), where L, R, U, D stand for “left”, “right”, “up”, “down” accordingly.

Parameters:

  • site (int) – The first site where the operator is applied, the second site to be site + 1.

  • operator (np.ndarray) – The two-site operator.

Notes

An example of a two-site expectation value is shown in the following diagram:

( )---( )---( )---( )
 |     |     |     |
 |    (operator)   |
 |     |     |     |
( )---( )---( )---( )
two_site_tensor_next(site: int) → ndarray

Computes a two-site tensor on a given site and the next one.

Parameters:

site (int) – The site index of the tensor.

two_site_tensor_next_iter() → Iterable

Returns an iterator over the two-site tensors for every site and its right neighbour.

two_site_tensor_prev(site: int) → ndarray

Computes a two-site tensor on a given site and the previous one.

Parameters:

site (int) – The site index of the tensor.

two_site_tensor_prev_iter() → Iterable

Returns an iterator over the two-site tensors for every site and its left neighbour.

mdopt.mps.explicit module

This module contains the ExplicitMPS class. Hereafter saying the MPS is in the explicit form will mean that the state is stored in the following format: for each three-dimensional tensor at site i denoted by ( ), there exists a singular values diagonal matrix at bond i denoted by <>:

       i    i    i+1  i+1
...---<>---( )---<>---( )---...
            |          |
            |          |

For “ghost” bonds at indices 0, L-1 (i.e., bonds of dimension 1), where L is the length of the MPS, the corresponding singular value tensors at the boundaries would be the identities of the same dimension. We index sites with i from 0 to L-1, with bond i being left of site i. Essentially, it corresponds to storing each Γ[i] and Λ[i] as shown in fig.4b in reference [1].

class mdopt.mps.explicit.ExplicitMPS(tensors: List[ndarray], singular_values: List[List], tolerance: float32 = 1e-12, chi_max: int = 10000)

Class for finite-size explicit matrix product states (MPS) with open boundary conditions.

tensors

The “physical” tensors of the MPS, one for each physical site. Each tensor has legs (virtual left, physical, virtual right), in short (vL, i, vR).

Type:

List[np.ndarray]

singular_values

The singular values at each of the bonds, singular_values[i] is left of tensors[i]. Each singular values list at each bond is normalised to 1.

Type:

List[List]

tolerance

Absolute tolerance of the normalisation of the singular value spectrum at each bond.

Type:

np.float32

num_sites

Number of sites.

Type:

int

num_bonds

Number of non-trivial bonds, which is equal to num_sites - 1.

Type:

int

Raises:

  • ValueError – If the tensors and the singular_values lists do not have corresponding lengths. The number of singular value matrices should be equal to the number of tensors + 1, because there are two trivial singular value matrices at each of the ghost bonds.

  • ValueError – If any of the MPS tensors is not three-dimensional.

  • ValueError – If any of the singular-values tensors is not normalised within the tolerance attribute.

conjugate() → ExplicitMPS

Returns a complex-conjugated version of the current MPS.

copy() → ExplicitMPS

Returns a copy of the current MPS.

dense(flatten: bool = True, renormalise: bool = False, norm: Union[None, float, Literal['fro', 'nuc']] = 2) → ndarray

Returns a dense representation of the MPS.

Warning: this method can cause memory overload for number of sites > ~20!

Parameters:

  • flatten (bool) – Whether to merge all the physical indices to form a vector or not.

  • renormalise (bool) – Whether to renormalise the resulting tensor.

  • norm (Union[str, int]) – Which norm to use for renormalisation of the final tensor.

density_mpo() → List[ndarray]

Returns the MPO representation (as a list of tensors) of the density matrix defined by a given MPS. This operation is depicted in the following picture:

       i           j
  a    |           |          c              i     j
...---(*)---<>*---(*)---<>*---...        ab  |     |  cd
                                  --> ...---[ ]---[ ]---...
...---( )---<>----( )---<>----...            |     |
  b    |           |          d              k     l
       k           l

In the cartoon, {i,j,k,l} and {a,b,c,d} are single indices, while ab and cd denote multi indices. Here, the ( )’s represent the MPS tensors, the <>’s — the singular values tensors, the [ ]’s — the MPO tensors. The MPS with the physical legs up is complex-conjugated element-wise, this is denoted by the star sign. The empty line between the MPS and its complex-conjugated version stands for the tensor (kronecker) product.

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 stand for “left”, “right”, “up”, “down”.

entanglement_entropy() → ndarray

Returns the entanglement entropy for bipartitions at each of the bonds.

left_canonical() → CanonicalMPS

Returns the current MPS in the left-canonical form given the MPS in the explicit form.

(see eq.19 in https://scipost.org/10.21468/SciPostPhysLectNotes.5 for reference),

marginal(sites_to_marginalise: List[int], canonicalise: bool = False) → Union[ExplicitMPS, CanonicalMPS]

Computes a marginal over a subset of sites of an MPS. Attention, this method does not act inplace, but creates a new object.

Parameters:

  • sites_to_marginalise (List[int]) – The sites to marginalise over.

  • canonicalise (bool) – Whether to put the result in the canonical form, i.e., whether to sweep with SVDs over the left bonds.

Notes

The algorithm proceeds by starting from the bond possessing the maximum dimension and contracting the marginalised tensors into the tensors left untouched. The list of sites to marginalise is then updated by removing the corresponding site from it. This subroutine continues until the list of sites to marginalise is empty. An example of marginalising is shown in the following diagram:

-<>-(0)-<>-(1)-<>-(2)-<>-(3)-<>-    ---(2)---(3)---
     |      |      |      |      ->     |     |
     |      |      |      |             |     |
    (t)    (t)

Here, the (t) (trace) tensor is a tensor consisting af all 1’s.

mixed_canonical(orth_centre: int) → CanonicalMPS

Returns the current MPS in the mixed-canonical form with the orthogonality centre being located at orth_centre.

Parameters:

orth_centre_index (int) – An integer which can take values 0, 1, ..., num_sites-1. Denotes the position of the orthogonality centre – the only non-isometry in the new canonical MPS.

norm() → float32

Computes the norm of the current MPS, that is, the modulus squared of its inner product with itself.

one_site_expectation_value(site: int, operator: ndarray) → Union[float32, complex128]

Computes an expectation value of an arbitrary one-site operator (not necessarily unitary) on the given site.

Parameters:

  • site (int) – The site where the operator is applied.

  • operator (np.ndarray) – The one-site operator

Notes

An example of a one-site expectation value is shown in the following diagram:

( )-<>-( )-<>-( )-<>-( )
 |      |      |      |
 |     (o)     |      |
 |      |      |      |
( )-<>-( )-<>-( )-<>-( )
one_site_left_iso(site: int) → ndarray

Computes a one-site left isometry at a given site.

one_site_left_iso_iter() → Iterable

Returns an iterator over the left isometries for every site.

one_site_right_iso(site: int) → ndarray

Computes a one-site right isometry at a given site.

one_site_right_iso_iter() → Iterable

Returns an iterator over the right isometries for every site.

reverse() → ExplicitMPS

Returns a reversed version of a given MPS.

right_canonical() → CanonicalMPS

Returns the current MPS in the right-canonical form given the MPS in the explicit form.

(see eq.19 in https://scipost.org/10.21468/SciPostPhysLectNotes.5 for reference),

two_site_expectation_value(site: int, operator: ndarray) → Union[float32, complex128]

Computes an expectation value of an arbitrary two-site operator (not necessarily unitary) on the given site and its next neighbour. The operator has legs (UL, DL, UR, DR), where L, R, U, D stand for “left”, “right”, “up”, “down” accordingly.

Parameters:

  • site (int) – The first site where the operator is applied, the second site to be site + 1.

  • operator (np.ndarray) – The two-site operator.

Notes

An example of a two-site expectation value is shown in the following diagram:

( )-<>-( )-<>-( )-<>-( )
 |      |      |      |
 |     (operator)     |
 |      |      |      |
( )-<>-( )-<>-( )-<>-( )
two_site_left_iso(site: int) → ndarray

Computes a two-site isometry on a given site and the following one from two one-site left isometries.

two_site_left_iso_iter() → Iterable

Returns an iterator over the two-site left isometries for every site and its right neighbour.

two_site_right_iso(site: int) → ndarray

Computes a two-site isometry on a given site and the following one from two one-site right isometries.

two_site_right_iso_iter() → Iterable

Returns an iterator over the two-site right isometries for every site and its right neighbour.

mdopt.mps.utils module

The mdopt.mps.utils module.

This module contains various MPS utilities.

mdopt.mps.utils.create_custom_product_state(string: str, phys_dim: int = 2, form: str = 'Explicit') → Union[ExplicitMPS, CanonicalMPS]

Creates a custom product-state MPS defined by the string argument.

Parameters:

  • string (str) – The string defining the product-state MPS. Available characters: 0, 1, +.

  • phys_dim (int) – Dimensionality of the local Hilbert space, i.e., the dimension of each physical leg of the MPS.

  • form (str) –

    The form of the MPS. Available options:
    Explicit : The ExplicitMPS form (by default).
    Right-canonical : The CanonicalMPS right-canonical form.
    Left-canonical : The CanonicalMPS left-canonical form.

Returns:

mps – The resulting MPS.

Return type:

Union[ExplicitMPS, CanonicalMPS]

Raises:

  • ValueError – If a symbol inside the string argument does not belong to the available set.

  • ValueError – If the chosen form is mixed-canonical. This form is not available for product states.

Notes

Produces a Matrix Product State consisting of tensors with bond dimenstions equal to 1. The tensors are defined as follows:

\(| 0 \rangle = \underbrace{(1, 0, ..., 0, 0)}_{\text{phys_dim}}\),
\(| 1 \rangle = \underbrace{(0, 0, ..., 0, 1)}_{\text{phys_dim}}\),
\(| + \rangle = \underbrace{(\frac{1}{\sqrt{\text{phys_dim}}}, ..., \frac{1}{\sqrt{\text{phys_dim}}})}_{\text{phys_dim}}\).

The state is renormalized at the end.

mdopt.mps.utils.create_simple_product_state(num_sites: int, which: str = '0', phys_dim: int = 2, form: str = 'Explicit') → Union[ExplicitMPS, CanonicalMPS]

Creates a simple product-state MPS.

Parameters:

  • num_sites (int) – The number of sites.

  • which (str) –

    The form of the MPS, for explanation see the notes. Available options:
    0 : The \(|0...0>\) state.
    1 : The \(|1...1>\) state.
    + : The \(|+...+>\) state.

  • phys_dim (int) – Dimensionality of the local Hilbert space, i.e., the dimension of each physical leg of the MPS.

  • form (str) –

    The form of the MPS. Available options:
    Explicit : The ExplicitMPS form (by default).
    Right-canonical : The CanonicalMPS right-canonical form.
    Left-canonical : The CanonicalMPS left-canonical form.

Returns:

mps – The resulting MPS.

Return type:

Union[ExplicitMPS, CanonicalMPS]

Raises:

ValueError – If the chosen form is mixed-canonical. This form is not available for product states.

Notes

Produces a Matrix Product State consisting of tensors with bond dimenstions equal to 1. The tensors are defined as follows:

\(| 0 \rangle = \underbrace{(1, 0, ..., 0, 0)}_{\text{phys_dim}}\),
\(| 1 \rangle = \underbrace{(0, 0, ..., 0, 1)}_{\text{phys_dim}}\),
\(| + \rangle = \underbrace{(\frac{1}{\sqrt{\text{phys_dim}}}, ..., \frac{1}{\sqrt{\text{phys_dim}}})}_{\text{phys_dim}}\).
mdopt.mps.utils.create_state_vector(num_sites: int, phys_dim: int = 2) → ndarray

Creates a random uniform complex-valued vector of norm 1.

Parameters:

  • num_sites (int) – Number of degrees of freedom.

  • phys_dim (int) – Number of dimensions of each degree of freedom.

Returns:

state_vector – The resulting state vector.

Return type:

np.ndarray

mdopt.mps.utils.find_orth_centre(mps: CanonicalMPS, return_orth_flags: bool = False, tolerance: float = 1e-12)

Returns a list of integers corresponding to positions of orthogonality centres of an MPS.

Parameters:

  • mps (CanonicalMPS) – The MPS to find the orthogonality centre(s) in.

  • return_orth_flags (bool) – Whether to return if each tensor is a right or a left isometry.

  • tolerance (float) – Numerical tolerance for checking the isometry property.

Returns:

  • orth_centres (List[int]) – Indices of sites at which tensors are orthogonality centres.

  • orth_flags_left (Optional[List[bool]]) – Boolean variables for each tensor corresponding to being a left isometry.

  • orth_flags_right (Optional[List[bool]]) – Boolean variables for each tensor corresponding to being a right isometry.

Raises:

ValueError – If an ExplicitMPS instance is passed as an input. They do not have orthogonality centres by definition.

mdopt.mps.utils.inner_product(mps_1: Union[ExplicitMPS, CanonicalMPS], mps_2: Union[ExplicitMPS, CanonicalMPS]) → Union[float32, complex128]

Returns an inner product between 2 Matrix Product States.

Parameters:

  • mps_1 (Union[ExplicitMPS, CanonicalMPS]) – The first MPS in the inner product.

  • mps_1 – The second MPS in the inner product.

Returns:

product – The value of the inner product.

Return type:

Union[np.float32, np.complex128]

Raises:

ValueError – If the Matrix Product States are of different length.

mdopt.mps.utils.is_canonical(mps: CanonicalMPS, tolerance: float = 1e-12)

Checks if the MPS is in any of the canonical forms.

Parameters:

  • mps (CanonicalMPS) – The MPS to check the canonical form of.

  • tolerance (np.float32) – Numerical tolerance for checking the isometry property.

Returns:

if_canonical – True if the MPS is in any of the canonical forms.

Return type:

bool

Raises:

ValueError – If an ExplicitMPS instance is passed as an input. They do not have orthogonality centres by definition.

mdopt.mps.utils.marginalise(mps: Union[ExplicitMPS, CanonicalMPS], sites_to_marginalise: List[int], canonicalise: bool = False) → Union[CanonicalMPS, float32, complex128]

Computes a marginal over a subset of sites of an MPS. This function was created to not act inplace. For the inplace version, take a look into the corresponding methods of available MPS classes.

Parameters:

  • mps (Union[ExplicitMPS, CanonicalMPS]) – The MPS we operate upon.

  • sites_to_marginalise (List[int]) – The sites to marginalise over.

  • canonicalise (bool) – Whether to put the result in the canonical form, i.e., whether to sweep with SVDs over the left bonds.

Notes

The algorithm proceeds by starting from the bond possessing the maximum dimension and contracting the marginalised tensors into the tensors left untouched. This subroutine proceeds until the list of sites to marginalise is empty. An example of marginalising is shown in the following diagram:

---(0)---(1)---(2)---(3)---    ---(2)---(3)---
    |     |     |     |     ->     |     |
    |     |     |     |            |     |
   (t)   (t)

Here, the (t) (trace) tensor is a tensor consisting af all 1’s.

mdopt.mps.utils.mps_from_dense(state_vector: ndarray, phys_dim: int = 2, chi_max: int = 10000, tolerance: float32 = 1e-12, form: str = 'Explicit', orth_centre: Optional[int] = None) → Union[ExplicitMPS, CanonicalMPS]

Builds an MPS from a dense (state-vector) from.

Parameters:

  • state_vector (np.ndarray) – The initial state vector.

  • phys_dim (int) – Dimensionality of the local Hilbert space, i.e., the dimension of each physical leg of the MPS.

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

  • tolerance (np.float32) – Absolute tolerance of the normalisation of the singular value spectrum at each bond.

  • form (str) –

    The form of the MPS. Available options:
    Explicit : The ExplicitMPS form (by default).
    Right-canonical : The CanonicalMPS right-canonical form.
    Left-canonical : The CanonicalMPS left-canonical form.
    Mixed-canonical : The CanonicalMPS mixed-canonical form.

  • orth_centre (Optional[int]) – The orthogonal centre position for the mixed-canonical form.

Returns:

mps – The resulting MPS.

Return type:

Union[ExplicitMPS, CanonicalMPS]

Raises:

ValueError – If the vector’s length does not correspond to the physical dimension.

Module contents