docs(examples): regroup the gallery by computational task

docs/make.jl

@@ -12,13 +12,19 @@ using DocumenterVitepress
 using DocumenterCitations
 using DocumenterInterLinks
 
-# examples
+# examples — grouped by computational task; each group is a subdirectory of src/examples/
 example_dir = joinpath(@__DIR__, "src", "examples")
-classic_pages = map(readdir(joinpath(example_dir, "classic2d"))) do dir
-    return joinpath("examples", "classic2d", dir, "index.md")
-end
-quantum_pages = map(readdir(joinpath(example_dir, "quantum1d"))) do dir
-    return joinpath("examples", "quantum1d", dir, "index.md")
+example_groups = [
+    "Ground states" => "groundstates",
+    "Excitations & dispersions" => "excitations",
+    "Dynamics & finite temperature" => "dynamics",
+    "Statistical mechanics" => "statmech",
+]
+example_pages = map(example_groups) do (title, group)
+    pages = map(readdir(joinpath(example_dir, group))) do dir
+        return joinpath("examples", group, dir, "index.md")
+    end
+    return title => pages
 end
 
 # contributing guide: `CONTRIBUTING.md` in the repository root is canonical, since that is the
@@ -70,7 +76,10 @@ makedocs(;
             "man/parallelism.md",
             "man/lattices.md",
         ],
-        "Examples" => "examples/index.md",
+        "Examples" => [
+            "Overview" => "examples/index.md",
+            example_pages...,
+        ],
         "Library" => "lib/lib.md",
         "References" => "references.md",
         "Changelog" => "changelog.md",

docs/src/examples/quantum1d/3.ising-dqpt/index.md → docs/src/examples/dynamics/ising-dqpt/index.md

@@ -1,32 +1,33 @@
 ```@meta
-EditURL = "../../../../../examples/quantum1d/3.ising-dqpt/main.jl"
+EditURL = "../../../../../examples/dynamics/ising-dqpt/main.jl"
 ```
 
-[![](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/QuantumKitHub/MPSKit.jl/gh-pages?filepath=dev/examples/quantum1d/3.ising-dqpt/main.ipynb)
-[![](https://img.shields.io/badge/show-nbviewer-579ACA.svg)](https://nbviewer.jupyter.org/github/QuantumKitHub/MPSKit.jl/blob/gh-pages/dev/examples/quantum1d/3.ising-dqpt/main.ipynb)
-[![](https://img.shields.io/badge/download-project-orange)](https://minhaskamal.github.io/DownGit/#/home?url=https://github.com/QuantumKitHub/MPSKit.jl/examples/tree/gh-pages/dev/examples/quantum1d/3.ising-dqpt)
+[![](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/QuantumKitHub/MPSKit.jl/gh-pages?filepath=dev/examples/dynamics/ising-dqpt/main.ipynb)
+[![](https://img.shields.io/badge/show-nbviewer-579ACA.svg)](https://nbviewer.jupyter.org/github/QuantumKitHub/MPSKit.jl/blob/gh-pages/dev/examples/dynamics/ising-dqpt/main.ipynb)
+[![](https://img.shields.io/badge/download-project-orange)](https://minhaskamal.github.io/DownGit/#/home?url=https://github.com/QuantumKitHub/MPSKit.jl/examples/tree/gh-pages/dev/examples/dynamics/ising-dqpt)
 
 # DQPT in the Ising model
 
-In this tutorial we will try to reproduce the results from
-[this paper](https://arxiv.org/pdf/1206.2505.pdf). The needed packages are
+In this tutorial we will try to reproduce the results from [this paper](https://arxiv.org/pdf/1206.2505.pdf).
+The needed packages are
 
 ````julia
 using MPSKit, MPSKitModels, TensorKit
 ````
 
 Dynamical quantum phase transitions (DQPT in short) are signatures of equilibrium phase transitions in a dynamical quantity - the Loschmidt echo.
-This quantity is given by ``L(t) = \frac{-2}{N} ln(| < \psi(t) | \psi(0) > |) `` where ``N`` is the system size.
+This quantity is given by ``L(t) = \frac{-2}{N} \ln |⟨ψ(t)|ψ(0)⟩|`` where ``N`` is the system size.
 One typically starts from a ground state and then quenches the Hamiltonian to a different point.
-Non analycities in the Loschmidt echo are called 'dynamical quantum phase transitions'.
+Non-analyticities in the Loschmidt echo are called 'dynamical quantum phase transitions'.
 
 In the mentioned paper they work with
 
-``H(g) = - \sum^{N-1}_{i=1} \sigma^z_i \sigma^z_{i+1} + g \sum_{i=1}^N \sigma^x_i``
+``H(g) = - \sum^{N-1}_{i=1} σ^z_i σ^z_{i+1} + g \sum_{i=1}^N σ^x_i``
 
-and show that divergences occur when quenching across the critical point (g₀ → g₁) for ``t^*_n = t^*(n+\frac{1}{2})`` with ``t^* = \pi/e(g_1,k^*)``, ``cos(k^*) = (1+g_0 g_1) / (g_0 + g_1)``, `` e(g,k) = \sqrt{(g-cos k)^2 + sin^2 k}``.
+and show that divergences occur when quenching across the critical point (g₀ → g₁) for ``t^*_n = t^*(n+\frac{1}{2})`` with ``t^* = π/e(g_1,k^*)``, ``cos(k^*) = (1+g_0 g_1) / (g_0 + g_1)``, `` e(g,k) = \sqrt{(g-cos k)^2 + sin^2 k}``.
 
-The outline of the tutorial is as follows. We will pick ``g₀ = 0.5``, ``g₁ = 2.0``, and perform the time evolution at different system sizes and compare with the thermodynamic limit.
+The outline of the tutorial is as follows.
+We will pick ``g₀ = 0.5``, ``g₁ = 2.0``, and perform the time evolution at different system sizes and compare with the thermodynamic limit.
 For those ``g`` we expect non-analyticities to occur at ``t_n ≈ 2.35 (n + 1/2)``.
 
 First we construct the Hamiltonian in MPO form, and obtain the pre-quenched ground state:
@@ -35,30 +36,20 @@ First we construct the Hamiltonian in MPO form, and obtain the pre-quenched grou
 L = 20
 H₀ = transverse_field_ising(FiniteChain(L); g = -0.5)
 ψ₀ = FiniteMPS(L, ℂ^2, ℂ^10)
-ψ₀, _ = find_groundstate(ψ₀, H₀, DMRG());
-````
-
-````
-[ Info: DMRG init:	obj = +9.979013604153e+00	err = 1.4988e-01
-[ Info: DMRG   1:	obj = -2.040021714911e+01	err = 6.6274818897e-04	time = 4.21 sec
-[ Info: DMRG   2:	obj = -2.040021715179e+01	err = 4.7025708686e-07	time = 0.30 sec
-[ Info: DMRG   3:	obj = -2.040021786572e+01	err = 3.1050733385e-05	time = 0.09 sec
-[ Info: DMRG   4:	obj = -2.040021786702e+01	err = 1.7208246127e-06	time = 0.04 sec
-[ Info: DMRG   5:	obj = -2.040021786703e+01	err = 3.5080300899e-08	time = 0.04 sec
-[ Info: DMRG conv 6:	obj = -2.040021786703e+01	err = 3.6868374475e-11	time = 4.71 sec
-
+ψ₀, _ = find_groundstate(ψ₀, H₀, DMRG(; verbosity = 0));
 ````
 
 ## Finite MPS quenching
 
-We can define a helper function that measures the loschmith echo
+We can define a helper function that measures the Loschmidt echo
 
 ````julia
 echo(ψ₀::FiniteMPS, ψₜ::FiniteMPS) = -2 * log(abs(dot(ψ₀, ψₜ))) / length(ψ₀)
 @assert isapprox(echo(ψ₀, ψ₀), 0, atol = 1.0e-10)
 ````
 
-We will initially use a two-site TDVP scheme to dynamically increase the bond dimension while time evolving, and later on switch to a faster one-site scheme. A single timestep can be done using
+We will initially use a two-site TDVP scheme to dynamically increase the bond dimension while time evolving, and later on switch to a faster one-site scheme.
+A single timestep can be done using
 
 ````julia
 H₁ = transverse_field_ising(FiniteChain(L); g = -2.0)
@@ -67,15 +58,16 @@ dt = 0.01
 ψₜ, envs = timestep(ψₜ, H₁, 0, dt, TDVP2(; trunc = truncrank(20)));
 ````
 
-"envs" is a kind of cache object that keeps track of all environments in `ψ`. It is often advantageous to re-use the environment, so that MPSKit doesn't need to recalculate everything.
+"envs" is a kind of cache object that keeps track of all environments in `ψ`.
+It is often advantageous to re-use the environment, so that MPSKit doesn't need to recalculate everything.
 
 Putting it all together, we get
 
 ````julia
 function finite_sim(L; dt = 0.05, finaltime = 5.0)
     ψ₀ = FiniteMPS(L, ℂ^2, ℂ^10)
     H₀ = transverse_field_ising(FiniteChain(L); g = -0.5)
-    ψ₀, _ = find_groundstate(ψ₀, H₀, DMRG())
+    ψ₀, _ = find_groundstate(ψ₀, H₀, DMRG(; verbosity = 0))
 
     H₁ = transverse_field_ising(FiniteChain(L); g = -2.0)
     ψₜ = deepcopy(ψ₀)
@@ -107,30 +99,18 @@ Similarly we could start with an initial infinite state and find the pre-quench
 ````julia
 ψ₀ = InfiniteMPS([ℂ^2], [ℂ^10])
 H₀ = transverse_field_ising(; g = -0.5)
-ψ₀, _ = find_groundstate(ψ₀, H₀, VUMPS());
-````
-
-````
-[ Info: VUMPS init:	obj = +4.970192050239e-01	err = 3.8858e-01
-[ Info: VUMPS   1:	obj = -1.049521519045e+00	err = 9.6762771022e-02	time = 1.62 sec
-[ Info: VUMPS   2:	obj = -1.063544398670e+00	err = 1.0462983506e-04	time = 0.02 sec
-[ Info: VUMPS   3:	obj = -1.063544409966e+00	err = 3.0128180222e-06	time = 0.01 sec
-[ Info: VUMPS   4:	obj = -1.063544409973e+00	err = 5.4785900416e-08	time = 0.01 sec
-[ Info: VUMPS   5:	obj = -1.063544409973e+00	err = 3.5329191510e-09	time = 0.01 sec
-[ Info: VUMPS   6:	obj = -1.063544409973e+00	err = 3.7796484550e-10	time = 0.01 sec
-[ Info: VUMPS conv 7:	obj = -1.063544409973e+00	err = 2.9001138645e-11	time = 1.69 sec
-
+ψ₀, _ = find_groundstate(ψ₀, H₀, VUMPS(; verbosity = 0));
 ````
 
-The dot product of two infinite matrix product states scales as  ``\alpha ^N`` where ``α`` is the dominant eigenvalue of the transfer matrix.
+The dot product of two infinite matrix product states scales as  ``α ^N`` where ``α`` is the dominant eigenvalue of the transfer matrix.
 It is this ``α`` that is returned when calling
 
 ````julia
 dot(ψ₀, ψ₀)
 ````
 
 ````
-0.9999999999999996 + 3.8955006105253705e-16im
+1.0000000000000047 + 1.040736567930811e-16im
 ````
 
 so the Loschmidt echo takes on the pleasant form
@@ -140,7 +120,8 @@ echo(ψ₀::InfiniteMPS, ψₜ::InfiniteMPS) = -2 * log(abs(dot(ψ₀, ψₜ)))
 @assert isapprox(echo(ψ₀, ψ₀), 0, atol = 1.0e-10)
 ````
 
-We make use of the `changebonds` machinery to grow the bond dimension. This can also be achieved through a two-site scheme.
+We make use of the `changebonds` machinery to grow the bond dimension.
+This can also be achieved through a two-site scheme.
 Multiple algorithms are available, but we will only focus on `OptimalExpand()`.
 Growing the bond dimension by ``5`` can be done by calling:
 
@@ -163,7 +144,7 @@ The final code is
 ````julia
 function infinite_sim(dt = 0.05, finaltime = 5.0)
     ψ₀ = InfiniteMPS([ℂ^2], [ℂ^10])
-    ψ₀, _ = find_groundstate(ψ₀, H₀, VUMPS())
+    ψ₀, _ = find_groundstate(ψ₀, H₀, VUMPS(; verbosity = 0))
 
     ψₜ = deepcopy(ψ₀)
     envs = environments(ψₜ, H₁, ψₜ)

docs/src/examples/quantum1d/3.ising-dqpt/main.ipynb → docs/src/examples/dynamics/ising-dqpt/main.ipynb

@@ -6,8 +6,8 @@
    "source": [
     "# DQPT in the Ising model\n",
     "\n",
-    "In this tutorial we will try to reproduce the results from\n",
-    "[this paper](https://arxiv.org/pdf/1206.2505.pdf). The needed packages are"
+    "In this tutorial we will try to reproduce the results from [this paper](https://arxiv.org/pdf/1206.2505.pdf).\n",
+    "The needed packages are"
    ]
   },
   {
@@ -24,17 +24,18 @@
    "metadata": {},
    "source": [
     "Dynamical quantum phase transitions (DQPT in short) are signatures of equilibrium phase transitions in a dynamical quantity - the Loschmidt echo.\n",
-    "This quantity is given by $L(t) = \\frac{-2}{N} ln(| < \\psi(t) | \\psi(0) > |) $ where $N$ is the system size.\n",
+    "This quantity is given by $L(t) = \\frac{-2}{N} \\ln |⟨ψ(t)|ψ(0)⟩|$ where $N$ is the system size.\n",
     "One typically starts from a ground state and then quenches the Hamiltonian to a different point.\n",
-    "Non analycities in the Loschmidt echo are called 'dynamical quantum phase transitions'.\n",
+    "Non-analyticities in the Loschmidt echo are called 'dynamical quantum phase transitions'.\n",
     "\n",
     "In the mentioned paper they work with\n",
     "\n",
-    "$H(g) = - \\sum^{N-1}_{i=1} \\sigma^z_i \\sigma^z_{i+1} + g \\sum_{i=1}^N \\sigma^x_i$\n",
+    "$H(g) = - \\sum^{N-1}_{i=1} σ^z_i σ^z_{i+1} + g \\sum_{i=1}^N σ^x_i$\n",
     "\n",
-    "and show that divergences occur when quenching across the critical point (g₀ → g₁) for $t^*_n = t^*(n+\\frac{1}{2})$ with $t^* = \\pi/e(g_1,k^*)$, $cos(k^*) = (1+g_0 g_1) / (g_0 + g_1)$, $ e(g,k) = \\sqrt{(g-cos k)^2 + sin^2 k}$.\n",
+    "and show that divergences occur when quenching across the critical point (g₀ → g₁) for $t^*_n = t^*(n+\\frac{1}{2})$ with $t^* = π/e(g_1,k^*)$, $cos(k^*) = (1+g_0 g_1) / (g_0 + g_1)$, $ e(g,k) = \\sqrt{(g-cos k)^2 + sin^2 k}$.\n",
     "\n",
-    "The outline of the tutorial is as follows. We will pick $g₀ = 0.5$, $g₁ = 2.0$, and perform the time evolution at different system sizes and compare with the thermodynamic limit.\n",
+    "The outline of the tutorial is as follows.\n",
+    "We will pick $g₀ = 0.5$, $g₁ = 2.0$, and perform the time evolution at different system sizes and compare with the thermodynamic limit.\n",
     "For those $g$ we expect non-analyticities to occur at $t_n ≈ 2.35 (n + 1/2)$.\n",
     "\n",
     "First we construct the Hamiltonian in MPO form, and obtain the pre-quenched ground state:"
@@ -49,7 +50,7 @@
     "L = 20\n",
     "H₀ = transverse_field_ising(FiniteChain(L); g = -0.5)\n",
     "ψ₀ = FiniteMPS(L, ℂ^2, ℂ^10)\n",
-    "ψ₀, _ = find_groundstate(ψ₀, H₀, DMRG());"
+    "ψ₀, _ = find_groundstate(ψ₀, H₀, DMRG(; verbosity = 0));"
    ]
   },
   {
@@ -58,7 +59,7 @@
    "source": [
     "## Finite MPS quenching\n",
     "\n",
-    "We can define a helper function that measures the loschmith echo"
+    "We can define a helper function that measures the Loschmidt echo"
    ]
   },
   {
@@ -75,7 +76,8 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "We will initially use a two-site TDVP scheme to dynamically increase the bond dimension while time evolving, and later on switch to a faster one-site scheme. A single timestep can be done using"
+    "We will initially use a two-site TDVP scheme to dynamically increase the bond dimension while time evolving, and later on switch to a faster one-site scheme.\n",
+    "A single timestep can be done using"
    ]
   },
   {
@@ -94,7 +96,8 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "\"envs\" is a kind of cache object that keeps track of all environments in `ψ`. It is often advantageous to re-use the environment, so that MPSKit doesn't need to recalculate everything.\n",
+    "\"envs\" is a kind of cache object that keeps track of all environments in `ψ`.\n",
+    "It is often advantageous to re-use the environment, so that MPSKit doesn't need to recalculate everything.\n",
     "\n",
     "Putting it all together, we get"
    ]
@@ -108,7 +111,7 @@
     "function finite_sim(L; dt = 0.05, finaltime = 5.0)\n",
     "    ψ₀ = FiniteMPS(L, ℂ^2, ℂ^10)\n",
     "    H₀ = transverse_field_ising(FiniteChain(L); g = -0.5)\n",
-    "    ψ₀, _ = find_groundstate(ψ₀, H₀, DMRG())\n",
+    "    ψ₀, _ = find_groundstate(ψ₀, H₀, DMRG(; verbosity = 0))\n",
     "\n",
     "    H₁ = transverse_field_ising(FiniteChain(L); g = -2.0)\n",
     "    ψₜ = deepcopy(ψ₀)\n",
@@ -151,14 +154,14 @@
    "source": [
     "ψ₀ = InfiniteMPS([ℂ^2], [ℂ^10])\n",
     "H₀ = transverse_field_ising(; g = -0.5)\n",
-    "ψ₀, _ = find_groundstate(ψ₀, H₀, VUMPS());"
+    "ψ₀, _ = find_groundstate(ψ₀, H₀, VUMPS(; verbosity = 0));"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The dot product of two infinite matrix product states scales as  $\\alpha ^N$ where $α$ is the dominant eigenvalue of the transfer matrix.\n",
+    "The dot product of two infinite matrix product states scales as  $α ^N$ where $α$ is the dominant eigenvalue of the transfer matrix.\n",
     "It is this $α$ that is returned when calling"
    ]
   },
@@ -192,7 +195,8 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "We make use of the `changebonds` machinery to grow the bond dimension. This can also be achieved through a two-site scheme.\n",
+    "We make use of the `changebonds` machinery to grow the bond dimension.\n",
+    "This can also be achieved through a two-site scheme.\n",
     "Multiple algorithms are available, but we will only focus on `OptimalExpand()`.\n",
     "Growing the bond dimension by $5$ can be done by calling:"
    ]
@@ -241,7 +245,7 @@
    "source": [
     "function infinite_sim(dt = 0.05, finaltime = 5.0)\n",
     "    ψ₀ = InfiniteMPS([ℂ^2], [ℂ^10])\n",
-    "    ψ₀, _ = find_groundstate(ψ₀, H₀, VUMPS())\n",
+    "    ψ₀, _ = find_groundstate(ψ₀, H₀, VUMPS(; verbosity = 0))\n",
     "\n",
     "    ψₜ = deepcopy(ψ₀)\n",
     "    envs = environments(ψₜ, H₁, ψₜ)\n",