Skip to content

Commit 226d2ee

Browse files
mtfishmanmtfishman
authored
Move MPS/MPO docs from ITensors.jl (#119)
1 parent 16241c9 commit 226d2ee

39 files changed

+3524
-14
lines changed

‎Project.toml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
name = "ITensorMPS"
22
uuid = "0d1a4710-d33b-49a5-8f18-73bdf49b47e2"
33
authors = ["Matthew Fishman <mfishman@flatironinstitute.org>", "Miles Stoudenmire <mstoudenmire@flatironinstitute.org>"]
4-
version = "0.3.9"
4+
version = "0.3.10"
55

66
[deps]
77
Adapt = "79e6a3ab-5dfb-504d-930d-738a2a938a0e"

‎README.md

Lines changed: 61 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
11
# ITensorMPS.jl
22

3-
[![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://ITensor.github.io/ITensorMPS.jl/stable/)
4-
[![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://ITensor.github.io/ITensorMPS.jl/dev/)
3+
[![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://itensor.github.io/ITensorMPS.jl/stable/)
4+
[![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://itensor.github.io/ITensorMPS.jl/dev/)
55
[![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)
66
[![Coverage](https://codecov.io/gh/ITensor/ITensorMPS.jl/branch/main/graph/badge.svg)](https://codecov.io/gh/ITensor/ITensorMPS.jl)
77
[![Code Style: Blue](https://img.shields.io/badge/code%20style-blue-4495d1.svg)](https://github.com/invenia/BlueStyle)
88
[![Aqua](https://raw.githubusercontent.com/JuliaTesting/Aqua.jl/master/badge.svg)](https://github.com/JuliaTesting/Aqua.jl)
99

10-
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.
10+
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.
1111

1212
## News
1313

@@ -31,6 +31,64 @@ This release introduces a new (experimental) function `expand` for performing gl
3131

3232
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.
3333

34+
## Example DMRG Calculation
35+
36+
DMRG is an iterative algorithm for finding the dominant
37+
eigenvector of an exponentially large, Hermitian matrix.
38+
It originates in physics with the purpose of finding
39+
eigenvectors of Hamiltonian (energy) matrices which model
40+
the behavior of quantum systems.
41+
42+
````julia
43+
using ITensors, ITensorMPS
44+
let
45+
# Create 100 spin-one indices
46+
N = 100
47+
sites = siteinds("S=1", N)
48+
49+
# Input operator terms which define
50+
# a Hamiltonian matrix, and convert
51+
# these terms to an MPO tensor network
52+
# (here we make the 1D Heisenberg model)
53+
os = OpSum()
54+
for j in 1:(N - 1)
55+
os += "Sz", j, "Sz", j + 1
56+
os += 0.5, "S+", j, "S-", j + 1
57+
os += 0.5, "S-", j, "S+", j + 1
58+
end
59+
H = MPO(os, sites)
60+
61+
# Create an initial random matrix product state
62+
psi0 = random_mps(sites)
63+
64+
# Plan to do 5 passes or 'sweeps' of DMRG,
65+
# setting maximum MPS internal dimensions
66+
# for each sweep and maximum truncation cutoff
67+
# used when adapting internal dimensions:
68+
nsweeps = 5
69+
maxdim = [10, 20, 100, 100, 200]
70+
cutoff = 1E-10
71+
72+
# Run the DMRG algorithm, returning energy
73+
# (dominant eigenvalue) and optimized MPS
74+
energy, psi = dmrg(H, psi0; nsweeps, maxdim, cutoff)
75+
println("Final energy = $energy")
76+
77+
nothing
78+
end
79+
80+
# output
81+
82+
# After sweep 1 energy=-137.954199761732 maxlinkdim=9 maxerr=2.43E-16 time=9.356
83+
# After sweep 2 energy=-138.935058943878 maxlinkdim=20 maxerr=4.97E-06 time=0.671
84+
# After sweep 3 energy=-138.940080155429 maxlinkdim=92 maxerr=1.00E-10 time=4.522
85+
# After sweep 4 energy=-138.940086009318 maxlinkdim=100 maxerr=1.05E-10 time=11.644
86+
# After sweep 5 energy=-138.940086058840 maxlinkdim=96 maxerr=1.00E-10 time=12.771
87+
# Final energy = -138.94008605883985
88+
````
89+
90+
You can find more examples of running `dmrg` and related algorithms [here](https://github.com/ITensor/ITensorMPS.jl/tree/main/examples).
91+
3492
---
3593

3694
*This page was generated using [Literate.jl](https://github.com/fredrikekre/Literate.jl).*

‎docs/Project.toml

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,11 @@
11
[deps]
2-
ITensorMPS = "0d1a4710-d33b-49a5-8f18-73bdf49b47e2"
32
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
3+
ITensorMPS = "0d1a4710-d33b-49a5-8f18-73bdf49b47e2"
4+
ITensors = "9136182c-28ba-11e9-034c-db9fb085ebd5"
45
Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
6+
7+
[compat]
8+
Documenter = "1.9.0"
9+
ITensorMPS = "0.3.9"
10+
ITensors = "0.8.1"
11+
Literate = "2.20.1"

‎docs/make.jl

Lines changed: 36 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,51 @@
1-
using ITensorMPS: ITensorMPS
1+
using ITensorMPS
2+
using ITensors
23
using Documenter: Documenter, DocMeta, deploydocs, makedocs
34

45
DocMeta.setdocmeta!(ITensorMPS, :DocTestSetup, :(using ITensorMPS); recursive=true)
6+
DocMeta.setdocmeta!(ITensors, :DocTestSetup, :(using ITensors); recursive=true)
57

68
include("make_index.jl")
79

810
makedocs(;
9-
modules=[ITensorMPS],
11+
# Allows using ITensors.jl docstrings in ITensorMPS.jl documentation:
12+
# https://github.com/JuliaDocs/Documenter.jl/issues/1734
13+
modules=[ITensorMPS, ITensors],
1014
authors="ITensor developers <support@itensor.org> and contributors",
1115
sitename="ITensorMPS.jl",
1216
format=Documenter.HTML(;
1317
canonical="https://ITensor.github.io/ITensorMPS.jl", edit_link="main", assets=String[]
1418
),
15-
pages=["Home" => "index.md"],
19+
pages=[
20+
"Home" => "index.md",
21+
"Tutorials" => [
22+
"DMRG" => "tutorials/DMRG.md",
23+
"Quantum Number Conserving DMRG" => "tutorials/QN_DMRG.md",
24+
"MPS Time Evolution" => "tutorials/MPSTimeEvolution.md",
25+
],
26+
"Code Examples" => [
27+
"MPS and MPO Examples" => "examples/MPSandMPO.md",
28+
"DMRG Examples" => "examples/DMRG.md",
29+
"Physics (SiteType) System Examples" => "examples/Physics.md",
30+
],
31+
"Documentation" => [
32+
"MPS and MPO" => "MPSandMPO.md",
33+
"SiteType and op, state, val functions" => "SiteType.md",
34+
"SiteTypes Included with ITensor" => "IncludedSiteTypes.md",
35+
"DMRG" => [
36+
"DMRG.md",
37+
"Sweeps.md",
38+
"ProjMPO.md",
39+
"ProjMPOSum.md",
40+
"Observer.md",
41+
"DMRGObserver.md",
42+
],
43+
"OpSum" => "OpSum.md",
44+
],
45+
"Frequently Asked Questions" =>
46+
["DMRG FAQs" => "faq/DMRG.md", "Quantum Number (QN) FAQs" => "faq/QN.md"],
47+
"HDF5 File Formats" => "HDF5FileFormats.md",
48+
],
1649
warnonly=true,
1750
)
1851

‎docs/src/DMRG.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# DMRG
2+
3+
```@docs
4+
dmrg
5+
```

‎docs/src/DMRGObserver.md

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# DMRGObserver
2+
3+
A DMRGObserver is a type of [observer](@ref observer) which
4+
offers certain useful, general purpose capabilities
5+
for DMRG calculations such as measuring custom
6+
local observables at each step and stopping DMRG
7+
early if certain energy convergence conditions are met.
8+
9+
## Sample Usage
10+
11+
In the following example, we have already made a Hamiltonian MPO `H`
12+
and initial MPS `psi0` for a system of spins whose sites
13+
have an associated "Sz" operator defined. We construct a
14+
`DMRGObserver` which measures "Sz" on each site at each
15+
step of DMRG, and also stops the calculation early if
16+
the energy no longer changes to a relative precision of 1E-7.
17+
18+
```
19+
Sz_observer = DMRGObserver(["Sz"],sites,energy_tol=1E-7)
20+
21+
energy, psi = dmrg(H,psi0,sweeps,observer=Sz_observer)
22+
23+
for (sw,Szs) in enumerate(measurements(Sz_observer)["Sz"])
24+
println("Total Sz after sweep $sw = ", sum(Szs)/N)
25+
end
26+
```
27+
28+
29+
## Constructors
30+
31+
```@docs
32+
DMRGObserver(;energy_tol::Float64,minsweeps::Int)
33+
DMRGObserver(ops::Vector{String},sites::Vector{<:Index};energy_tol::Float64,minsweeps::Int)
34+
```
35+
36+
## Methods
37+
38+
```@docs
39+
measurements(::DMRGObserver)
40+
DMRGMeasurement
41+
energies(::DMRGObserver)
42+
```
43+

‎docs/src/HDF5FileFormats.md

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
## [MPS](@id mps_hdf5)
2+
3+
HDF5 file format for `ITensorMPS.MPS`
4+
5+
Attributes:
6+
* "version" = 1
7+
* "type" = "MPS"
8+
9+
Datasets and Subgroups:
10+
* "length" [integer] = number of tensors of the MPS
11+
* "rlim" [integer] = right orthogonality limit
12+
* "llim" [integer] = left orthogonality limit
13+
* "MPS[n]" [group,ITensor] = each of these groups, where n=1,...,length, stores the nth ITensor of the MPS
14+
15+
16+
## [MPO](@id mpo_hdf5)
17+
18+
HDF5 file format for `ITensorMPS.MPO`
19+
20+
Attributes:
21+
* "version" = 1
22+
* "type" = "MPO"
23+
24+
Datasets and Subgroups:
25+
* "length" [integer] = number of tensors of the MPO
26+
* "rlim" [integer] = right orthogonality limit
27+
* "llim" [integer] = left orthogonality limit
28+
* "MPO[n]" [group,ITensor] = each of these groups, where n=1,...,length, stores the nth ITensor of the MPO
29+
30+

0 commit comments

Comments
 (0)