Update `MPS` manual in docs #262

jofrevalles · 2024-11-25T12:18:20Z

Summary

This PR updates the MPS manual, accounting with the changes from MPS refactor (PR #232) and thus adding explanation of the different canonical forms we support. I think it makes sense that the manual for the canonical forms is in this MPS manual.

Additionally, I fixed a problem in the Project.toml of the docs.

@starsfordummies Can you take a look at the explanation on each canonical form? Maybe we can explain it better.

starsfordummies · 2024-11-25T14:59:54Z

docs/src/manual/ansatz/mps.md

+An `MPS` representation is not unique: a single `MPS` can be represented in different canonical [`Form`](@ref). The choice of canonical form can affect the efficiency and stability of algorithms used to manipulate the `MPS`. You can check the canonical form of an `MPS` by calling the `form` function:
+
+```@example
+mps = MPS([rand(2, 2), rand(2, 2, 2), rand(2, 2)])


# default ordering is (physical, virtual left, virtual right)

starsfordummies · 2024-11-25T15:02:39Z

docs/src/manual/ansatz/mps.md

+### Canonical Forms
+
+An `MPS` representation is not unique: a single `MPS` can be represented in different canonical [`Form`](@ref). The choice of canonical form can affect the efficiency and stability of algorithms used to manipulate the `MPS`. You can check the canonical form of an `MPS` by calling the `form` function:
+


Depending on the form, Tenet will dispatch under the hood the appropriate algorithm which makes full use of the canonical form, so be careful when making modifications that might alter the form without changing the trait.

starsfordummies · 2024-11-25T15:03:25Z

docs/src/manual/ansatz/mps.md


 fig # hide
 ```

+### Canonical Forms
+
+An `MPS` representation is not unique: a single `MPS` can be represented in different canonical [`Form`](@ref). The choice of canonical form can affect the efficiency and stability of algorithms used to manipulate the `MPS`. You can check the canonical form of an `MPS` by calling the `form` function:


The current form of the MPS is stored as a trait (refs etc) and can be accessed via the form function

docs/src/manual/ansatz/mps.md

… of Yao gates (#258) * try fix reordering of sites * try fix layout of multi-qubit gates in Yao to Tenet conversion * Remove permutedims & add collect for array building * minor fixes on Reactant pkg extension * implement `copy` for some structs * fix column- to row-major layout conversion on `Reactant.promote_to` call * remove dead code --------- Co-authored-by: Todorbsc <[email protected]>

@show

* Add evolve! function for an MPS with an MPO * Add tests for MPS-MPO evolution * Remove unnecessary @show * Add comment * Fix kwarg handling on truncate! function * Fix normalize! for Canonical form and small fixes on evolve! with MPO * Extend evolve!(mps, mpo) tests * Format code * Remove unnecessary kwarg * Refactor code so it is easier to extend for other canonical forms * Fix comment * Enhance tests * Add reset_index kwarg * Update tests * Format code * Remove unnecessary Quantum functions, add docstring for truncate_sweep! * Format code * Remove stale function

mofeing · 2024-12-03T14:13:10Z

docs/src/manual/ansatz/mps.md

 ```
+> :warning: Depending on the form, `Tenet` will dispatch under the hood the appropriate algorithm which assumes full use of the canonical form, so be careful when making modifications that might alter the canonical form without changing the trait.


I don't think this should be a warning.

... which assumes full use of the canonical form ...

what does this mean?

... so be careful when making modifications that might alter the canonical form without changing the trait.

Users must not modify the form field directly; the public API is to call canonize! or mixed_canonize! so they shouldn't care about this.

So I would just put the first part of the paragraph. You can put it in a info box if you want.

I mean, if a user does Tenet.canonize_site! or some other function (replace!, contract!, ...), you lose the sense of form and thus we have that warning.

mofeing · 2024-12-03T14:13:53Z

docs/src/manual/ansatz/mps.md

+> :warning: Depending on the form, `Tenet` will dispatch under the hood the appropriate algorithm which assumes full use of the canonical form, so be careful when making modifications that might alter the canonical form without changing the trait.
+
+`Tenet` has the internal function [`Tenet.check_form`](@ref) to check if the `MPS` is in the correct canonical form. This function can be used to ensure that the `MPS` is in the correct form before performing any operation that requires it.
+Currently, `Tenet` supports the [`NonCanonical`](@ref), [`CanonicalForm`](@ref) and [`MixedCanonical`](@ref) forms.


Suggested change

Currently, `Tenet` supports the [`NonCanonical`](@ref), [`CanonicalForm`](@ref) and [`MixedCanonical`](@ref) forms.

Currently, `Tenet` has the following forms implemented:

mofeing · 2024-12-03T14:15:08Z

docs/src/manual/ansatz/mps.md

+In the `NonCanonical` form, the tensors in the `MPS` do not satisfy any particular orthogonality conditions. This is the default `form` when an `MPS` is initialized without specifying a canonical form. It is useful for general purposes but may not be optimal for certain computations that benefit from orthogonality.
+
+#### `Canonical` Form
+Also known as Vidal's form, the `Canonical` form represents the `MPS` using a sequence of isometric tensors (`Γ`) and diagonal vectors (`λ`) containing the Schmidt coefficients. The `MPS` is expressed as:


Suggested change

Also known as Vidal's form, the `Canonical` form represents the `MPS` using a sequence of isometric tensors (`Γ`) and diagonal vectors (`λ`) containing the Schmidt coefficients. The `MPS` is expressed as:

Also known as Vidal gauge, the `Canonical` form represents the `MPS` using a sequence of isometric tensors (`Γ`) and diagonal vectors (`λ`) containing the Schmidt coefficients. Mathematically, the `MPS` is expressed as:

mofeing · 2024-12-03T14:16:53Z

docs/src/manual/ansatz/mps.md

+
+form(mps)


maybe better remove this? or maybe better use @repl instead of @example

https://documenter.juliadocs.org/stable/man/syntax/#@repl-block

mofeing · 2024-12-03T14:17:23Z

docs/src/manual/ansatz/mps.md

+```
+
+#### `MixedCanonical` Form
+In the `MixedCanonical` form, tensors to the left of the orthogonality center are left-canonical, tensors to the right are right-canonical, and the tensors at the orthogonality center (which can be `Site` or `Vector{<:Site}`) contains the entanglement information between the left and right parts of the chain. The position of the orthogonality center is stored in the `orthog_center` field.


You need to explain what is left-/right-canonical

... contains the entanglement information between the left and right parts of the chain. ...

I'm not convinced by this phrase but I don't know how to rephrase it jajajaj

any idea @arturgs @starsfordummies?

I'd just remove the sentence "and the tensors... "

mofeing · 2024-12-03T14:19:42Z

docs/src/manual/ansatz/mps.md

+
+##### Additional Resources
+For more in-depth information on Matrix Product States and their canonical forms, you may refer to:
+- Schollwöck, U. (2011). The density-matrix renormalization group in the age of matrix product states. Annals of physics, 326(1), 96-192.


ahh for this kind of citations we had a Documenter plugin that I've disabled. we can reenable it.

look for DocumenterCitations.jl

mofeing · 2024-12-03T14:21:14Z

docs/src/manual/ansatz/mps.md

+Depending on the boundary conditions, the chains can be open or closed (i.e. periodic boundary conditions), currently
+only `Open` boundary conditions are supported in `Tenet`.


....currently
only Open boundary conditions are supported in Tenet.

There is a weird newline there. But also, this is the kind of information that can better be in a warning box.

jofrevalles added 4 commits November 25, 2024 12:54

Fix Tenet path in docs' Project.toml by changing it to a relative path

f3b2c4f

Update MPS manual

a9623a6

Update mps manual

20c4ef2

Remove physical indices of lambda in eq1

e18b5f7

jofrevalles requested a review from starsfordummies November 25, 2024 14:16

jofrevalles added 2 commits November 25, 2024 15:37

Remove physical indices of lambda in eq1

f8c3470

Fix exampple code on mps manual

c2a63bc

starsfordummies reviewed Nov 25, 2024

View reviewed changes

Update MPS docs with Stefano's suggestions

1372e1a

starsfordummies self-requested a review November 26, 2024 08:32

starsfordummies approved these changes Nov 26, 2024

View reviewed changes

jofrevalles and others added 3 commits December 2, 2024 12:15

Update mps tutorial docs

8d53a34

mofeing reviewed Dec 3, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update `MPS` manual in docs #262

Update `MPS` manual in docs #262

jofrevalles commented Nov 25, 2024

starsfordummies Nov 25, 2024

starsfordummies Nov 25, 2024

starsfordummies Nov 25, 2024

mofeing Dec 3, 2024 •

edited

Loading

jofrevalles Dec 3, 2024

mofeing Dec 3, 2024

mofeing Dec 3, 2024

mofeing Dec 3, 2024

mofeing Dec 3, 2024

mofeing Dec 3, 2024

starsfordummies Dec 3, 2024

mofeing Dec 3, 2024

mofeing Dec 3, 2024

		### Canonical Forms

		An `MPS` representation is not unique: a single `MPS` can be represented in different canonical [`Form`](@ref). The choice of canonical form can affect the efficiency and stability of algorithms used to manipulate the `MPS`. You can check the canonical form of an `MPS` by calling the `form` function:

		```
		> :warning: Depending on the form, `Tenet` will dispatch under the hood the appropriate algorithm which assumes full use of the canonical form, so be careful when making modifications that might alter the canonical form without changing the trait.

	Currently, `Tenet` supports the [`NonCanonical`](@ref), [`CanonicalForm`](@ref) and [`MixedCanonical`](@ref) forms.

	Currently, `Tenet` has the following forms implemented:

	Also known as Vidal's form, the `Canonical` form represents the `MPS` using a sequence of isometric tensors (`Γ`) and diagonal vectors (`λ`) containing the Schmidt coefficients. The `MPS` is expressed as:
	Also known as Vidal gauge, the `Canonical` form represents the `MPS` using a sequence of isometric tensors (`Γ`) and diagonal vectors (`λ`) containing the Schmidt coefficients. Mathematically, the `MPS` is expressed as:

		Depending on the boundary conditions, the chains can be open or closed (i.e. periodic boundary conditions), currently
		only `Open` boundary conditions are supported in `Tenet`.


		form(mps)

Update MPS manual in docs #262

Are you sure you want to change the base?

Update MPS manual in docs #262

Conversation

jofrevalles commented Nov 25, 2024

Summary

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mofeing Dec 3, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Update `MPS` manual in docs #262

Update `MPS` manual in docs #262

mofeing Dec 3, 2024 •

edited

Loading