Move MPS/MPO docs from ITensors.jl

Project.toml

@@ -1,7 +1,7 @@
 name = "ITensorMPS"
 uuid = "0d1a4710-d33b-49a5-8f18-73bdf49b47e2"
 authors = ["Matthew Fishman <[email protected]>", "Miles Stoudenmire <[email protected]>"]
-version = "0.3.9"
+version = "0.3.10"
 
 [deps]
 Adapt = "79e6a3ab-5dfb-504d-930d-738a2a938a0e"

README.md

@@ -1,13 +1,13 @@
 # ITensorMPS.jl
 
-[![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://ITensor.github.io/ITensorMPS.jl/stable/)
-[![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://ITensor.github.io/ITensorMPS.jl/dev/)
+[![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://itensor.github.io/ITensorMPS.jl/stable/)
+[![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://itensor.github.io/ITensorMPS.jl/dev/)
 [![Build Status](https://github.com/ITensor/ITensorMPS.jl/actions/workflows/Tests.yml/badge.svg?branch=main)](https://github.com/ITensor/ITensorMPS.jl/actions/workflows/Tests.yml?query=branch%3Amain)
 [![Coverage](https://codecov.io/gh/ITensor/ITensorMPS.jl/branch/main/graph/badge.svg)](https://codecov.io/gh/ITensor/ITensorMPS.jl)
 [![Code Style: Blue](https://img.shields.io/badge/code%20style-blue-4495d1.svg)](https://github.com/invenia/BlueStyle)
 [![Aqua](https://raw.githubusercontent.com/JuliaTesting/Aqua.jl/master/badge.svg)](https://github.com/JuliaTesting/Aqua.jl)
 
-Finite MPS and MPO methods based on the Julia version of [ITensor](https://www.itensor.org) ([ITensors.jl](https://github.com/ITensor/ITensors.jl)). See the [ITensors.jl documentation](https://itensor.github.io/ITensors.jl/dev/) for more details.
+Finite MPS and MPO methods based on the Julia version of [ITensor](https://www.itensor.org) ([ITensors.jl](https://github.com/ITensor/ITensors.jl)). See the [ITensorMPS.jl documentation](https://itensor.github.io/ITensorMPS.jl) for more details.
 
 ## News
 
@@ -31,6 +31,64 @@ This release introduces a new (experimental) function `expand` for performing gl
 
 ITensorMPS.jl v0.2 has been released, which is a breaking release. It updates to using ITensorTDVP.jl v0.4, which has a number of breaking changes to the `tdvp`, `linsolve`, and `dmrg_x` functions. See the [ITensorTDVP.jl v0.4 release notes](https://github.com/ITensor/ITensorTDVP.jl/blob/main/README.md#itensortdvpjl-v04-release-notes) for details.
 
+## Example DMRG Calculation
+
+DMRG is an iterative algorithm for finding the dominant
+eigenvector of an exponentially large, Hermitian matrix.
+It originates in physics with the purpose of finding
+eigenvectors of Hamiltonian (energy) matrices which model
+the behavior of quantum systems.
+
+````julia
+using ITensors, ITensorMPS
+let
+  # Create 100 spin-one indices
+  N = 100
+  sites = siteinds("S=1", N)
+
+  # Input operator terms which define
+  # a Hamiltonian matrix, and convert
+  # these terms to an MPO tensor network
+  # (here we make the 1D Heisenberg model)
+  os = OpSum()
+  for j in 1:(N - 1)
+    os += "Sz", j, "Sz", j + 1
+    os += 0.5, "S+", j, "S-", j + 1
+    os += 0.5, "S-", j, "S+", j + 1
+  end
+  H = MPO(os, sites)
+
+  # Create an initial random matrix product state
+  psi0 = random_mps(sites)
+
+  # Plan to do 5 passes or 'sweeps' of DMRG,
+  # setting maximum MPS internal dimensions
+  # for each sweep and maximum truncation cutoff
+  # used when adapting internal dimensions:
+  nsweeps = 5
+  maxdim = [10, 20, 100, 100, 200]
+  cutoff = 1E-10
+
+  # Run the DMRG algorithm, returning energy
+  # (dominant eigenvalue) and optimized MPS
+  energy, psi = dmrg(H, psi0; nsweeps, maxdim, cutoff)
+  println("Final energy = $energy")
+
+  nothing
+end
+
+# output
+
+# After sweep 1 energy=-137.954199761732 maxlinkdim=9 maxerr=2.43E-16 time=9.356
+# After sweep 2 energy=-138.935058943878 maxlinkdim=20 maxerr=4.97E-06 time=0.671
+# After sweep 3 energy=-138.940080155429 maxlinkdim=92 maxerr=1.00E-10 time=4.522
+# After sweep 4 energy=-138.940086009318 maxlinkdim=100 maxerr=1.05E-10 time=11.644
+# After sweep 5 energy=-138.940086058840 maxlinkdim=96 maxerr=1.00E-10 time=12.771
+# Final energy = -138.94008605883985
+````
+
+You can find more examples of running `dmrg` and related algorithms [here](https://github.com/ITensor/ITensorMPS.jl/tree/main/examples).
+
 ---
 
 *This page was generated using [Literate.jl](https://github.com/fredrikekre/Literate.jl).*

docs/Project.toml

@@ -1,4 +1,11 @@
 [deps]
-ITensorMPS = "0d1a4710-d33b-49a5-8f18-73bdf49b47e2"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+ITensorMPS = "0d1a4710-d33b-49a5-8f18-73bdf49b47e2"
+ITensors = "9136182c-28ba-11e9-034c-db9fb085ebd5"
 Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
+
+[compat]
+Documenter = "1.9.0"
+ITensorMPS = "0.3.9"
+ITensors = "0.8.1"
+Literate = "2.20.1"

docs/make.jl

@@ -1,18 +1,51 @@
-using ITensorMPS: ITensorMPS
+using ITensorMPS
+using ITensors
 using Documenter: Documenter, DocMeta, deploydocs, makedocs
 
 DocMeta.setdocmeta!(ITensorMPS, :DocTestSetup, :(using ITensorMPS); recursive=true)
+DocMeta.setdocmeta!(ITensors, :DocTestSetup, :(using ITensors); recursive=true)
 
 include("make_index.jl")
 
 makedocs(;
-  modules=[ITensorMPS],
+  # Allows using ITensors.jl docstrings in ITensorMPS.jl documentation:
+  # https://github.com/JuliaDocs/Documenter.jl/issues/1734
+  modules=[ITensorMPS, ITensors],
   authors="ITensor developers <[email protected]> and contributors",
   sitename="ITensorMPS.jl",
   format=Documenter.HTML(;
     canonical="https://ITensor.github.io/ITensorMPS.jl", edit_link="main", assets=String[]
   ),
-  pages=["Home" => "index.md"],
+  pages=[
+    "Home" => "index.md",
+    "Tutorials" => [
+      "DMRG" => "tutorials/DMRG.md",
+      "Quantum Number Conserving DMRG" => "tutorials/QN_DMRG.md",
+      "MPS Time Evolution" => "tutorials/MPSTimeEvolution.md",
+    ],
+    "Code Examples" => [
+      "MPS and MPO Examples" => "examples/MPSandMPO.md",
+      "DMRG Examples" => "examples/DMRG.md",
+      "Physics (SiteType) System Examples" => "examples/Physics.md",
+    ],
+    "Documentation" => [
+      "MPS and MPO" => "MPSandMPO.md",
+      "SiteType and op, state, val functions" => "SiteType.md",
+      "SiteTypes Included with ITensor" => "IncludedSiteTypes.md",
+      "DMRG" => [
+        "DMRG.md",
+        "Sweeps.md",
+        "ProjMPO.md",
+        "ProjMPOSum.md",
+        "Observer.md",
+        "DMRGObserver.md",
+      ],
+      "OpSum" => "OpSum.md",
+    ],
+    "Frequently Asked Questions" =>
+      ["DMRG FAQs" => "faq/DMRG.md", "Quantum Number (QN) FAQs" => "faq/QN.md"],
+    "HDF5 File Formats" => "HDF5FileFormats.md",
+  ],
   warnonly=true,
 )
 

docs/src/DMRG.md

@@ -0,0 +1,5 @@
+# DMRG
+
+```@docs
+dmrg
+```

docs/src/DMRGObserver.md

@@ -0,0 +1,43 @@
+# DMRGObserver
+
+A DMRGObserver is a type of [observer](@ref observer) which
+offers certain useful, general purpose capabilities
+for DMRG calculations such as measuring custom
+local observables at each step and stopping DMRG
+early if certain energy convergence conditions are met.
+
+## Sample Usage
+
+In the following example, we have already made a Hamiltonian MPO `H`
+and initial MPS `psi0` for a system of spins whose sites
+have an associated "Sz" operator defined. We construct a
+`DMRGObserver` which measures "Sz" on each site at each
+step of DMRG, and also stops the calculation early if
+the energy no longer changes to a relative precision of 1E-7.
+
+```
+Sz_observer = DMRGObserver(["Sz"],sites,energy_tol=1E-7)
+
+energy, psi = dmrg(H,psi0,sweeps,observer=Sz_observer)
+
+for (sw,Szs) in enumerate(measurements(Sz_observer)["Sz"])
+  println("Total Sz after sweep $sw = ", sum(Szs)/N)
+end
+```
+
+
+## Constructors
+
+```@docs
+DMRGObserver(;energy_tol::Float64,minsweeps::Int)
+DMRGObserver(ops::Vector{String},sites::Vector{<:Index};energy_tol::Float64,minsweeps::Int)
+```
+
+## Methods
+
+```@docs
+measurements(::DMRGObserver)
+DMRGMeasurement
+energies(::DMRGObserver)
+```
+

docs/src/HDF5FileFormats.md

@@ -0,0 +1,30 @@
+## [MPS](@id mps_hdf5)
+
+HDF5 file format for `ITensorMPS.MPS`
+
+Attributes:
+* "version" = 1
+* "type" = "MPS"
+
+Datasets and Subgroups:
+* "length" [integer] = number of tensors of the MPS
+* "rlim" [integer] = right orthogonality limit
+* "llim" [integer] = left orthogonality limit
+* "MPS[n]" [group,ITensor] = each of these groups, where n=1,...,length, stores the nth ITensor of the MPS
+
+
+## [MPO](@id mpo_hdf5)
+
+HDF5 file format for `ITensorMPS.MPO`
+
+Attributes:
+* "version" = 1
+* "type" = "MPO"
+
+Datasets and Subgroups:
+* "length" [integer] = number of tensors of the MPO
+* "rlim" [integer] = right orthogonality limit
+* "llim" [integer] = left orthogonality limit
+* "MPO[n]" [group,ITensor] = each of these groups, where n=1,...,length, stores the nth ITensor of the MPO
+
+