docstrings updated

docs/Project.toml

@@ -1,6 +1,7 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterTools = "35a29f4d-8980-5a13-9543-d66fff28ecb8"
+ITensors = "9136182c-28ba-11e9-034c-db9fb085ebd5"
 
 [compat]
 Documenter = "1.2"

docs/build/.documenter-siteinfo.json

@@ -1 +1 @@
-{"documenter":{"julia_version":"1.9.4","generation_timestamp":"2023-12-20T23:47:47","documenter_version":"1.2.1"}}
+{"documenter":{"julia_version":"1.9.4","generation_timestamp":"2023-12-21T04:54:01","documenter_version":"1.2.1"}}

docs/make.jl

@@ -1,5 +1,6 @@
 push!(LOAD_PATH,"../src/")
 
+using ITensors, DataStructures
 using Documenter, TeNLib
 
 ############################################################################
@@ -11,9 +12,13 @@ settings = Dict(
         [
             "Introduction" => "index.md"
             "MPS based methods" => [
-                "StateEnvs" => "mps/state_envs.md"
+                "StateEnvs" => "mps/state_envs.md",
+                "Perform local updates" => "mps/update_site.md",
+                "Sweeping through the MPS" => "mps/sweep.md",
+                "Performing DMRG" => "mps/dmrg.md",
+                "Example: DMRG" => "mps/example_dmrg.md",
+                "Performing TDVP" => "mps/tdvp.md"
                 ]
-            "DMRG" => "dmrg.md"
         ],
     :format => Documenter.HTML(; assets=["assets/favicon.ico"], prettyurls=false),
     :doctest => true,

docs/src/mps/dmrg.md

@@ -0,0 +1,31 @@
+# Performing DMRG
+
+Functions to perfom (and control) DMRG runs.
+
+## `DMRGParams`
+
+TeNLib defines a struct, called  `DMRGParams`, to control DMRG simulations.
+
+```@docs
+DMRGParams
+DMRGParams(;maxdim::Vector{Int}, nsweeps::Vector{Int}, cutoff::Union{Vector{Float64}, Float64} = _Float64_Threshold, noise::Union{Vector{Float64}, Float64, Int} = 0.0, noisedecay::Union{Vector{Float64}, Float64, Int} = 1.0, disable_noise_after::Union{Vector{Int}, Int} = typemax(Int))
+Base.copy(params::DMRGParams)
+```
+
+## A lower level DMRG function
+
+Following function modifies `StateEnvs` in-place. Skip this function if you want to avoid lower-level abstraction.
+
+```@docs
+dmrg!(sysenv::StateEnvs, params::DMRGParams, nsite::Int; kwargs...)
+```
+
+## Higher level DMRG functions
+
+Standard two- and single-site DMRG functions. Single-site DMRG can increasing the bond-dimension
+if `noise > Float64_threshold()`.
+```@docs
+dmrg2(psi0::MPS, H::T, params::DMRGParams; kwargs...) where T <: Union{MPO, Vector{MPO}, CouplingModel}
+dmrg1(psi0::MPS, H::T, params::DMRGParams; kwargs...) where T <: Union{MPO, Vector{MPO}, CouplingModel}
+```
+

docs/src/mps/example_dmrg.md

@@ -0,0 +1,106 @@
+# Example: DMRG
+
+## Ground state search
+
+A straight-forward DMRG can be performed as follows.
+
+```
+using ITensors
+using TeNLib
+
+let
+    N = 32
+    sites = siteinds("S=1/2",N)
+    os = OpStrings()
+    
+    for j=1:N-1
+        os += 1, "Sz" => j, "Sz" => j+1
+        os += 0.5, "S+" => j, "S-" => j+1
+        os += 0.5, "S-" => j, "S+" => j+1
+    end
+    
+    H = CouplingModel(os,sites)
+    states = [isodd(n) ? "Up" : "Dn" for n in 1:N]
+    psi0 = MPS(sites, states)
+
+    params = DMRGParams(;nsweeps = [10, 10], maxdim = [20, 50],
+                        cutoff = 1e-14, noise = 1e-3, noisedecay = 2,
+                        disable_noise_after = 5)
+
+    # dmrg2 for two-site DMRG
+    en, psi = dmrg2(psi0, H, params)
+
+    # or dmrg1 for single-site DMRG
+    # en, psi = dmrg1(psi0, H, params)
+end
+```
+
+Here, we have used `OpStrings` and `CouplingModel`. Alternatively, standard `OpSum` and `MPO` can
+be used.
+
+Instead of using such higher-level code, one can also use lower-level functions for a better
+control.
+```
+sysenv = StateEnvs(psi0, H)
+nsite = 2 # two-site update
+swdata = dmrg!(sysenv, params, nsite)
+
+# Get energy from `Sweepdata`
+energy = swdata.energy[end]
+
+# take a shallow copy of the MPS
+# if the `StateEnvs` will be updated later again
+psi = getpsi(sysenv)
+
+# Alternatively, take the psi from `StateEnvs` itself.
+# NOTE: This can crash the simulation, if the MPS is modified (e.g., in measurements)
+# and `StateEnvs` is going to be updated later.
+# psi = sysenv.psi
+```
+Using such lower-level function, one can restart the simulation at later times
+(e.g., by saving the `StateEnvs` using `Serialization.jl`), or one can perform
+[`updateH!`](@ref updateH!(sysenv::StateEnvs{ProjMPO}, H::MPO; recalcEnv::Bool = true)) to slowly
+change the Hamiltonian during DMRG simulations.
+
+
+Global Subspace Expansion can also be used to get rid of nasty local minimas (if needed).
+```
+krylov_extend!(sysenv; extension_applyH_maxdim = 40)
+```
+**Note**: Global Subspace Expansion can result into huge MPS bond dimension. That is why
+the named input parameters of [`krylov_extend!`](@ref krylov_extend!(sysenv::StateEnvs{ProjMPO}; kwargs...)) should be chosen carefully.
+
+## Excited state DMRG
+
+Excited state DMRG is also straightforword.
+
+```
+# Given a ground state `psi_gr`, initial MPS `psi0`,
+# and a Hamiltonian `H`
+
+# dmrg2 for two-site DMRG
+en, psi = dmrg2(psi0, H, [psi_gr], params; weight = 10.0)
+
+# or dmrg1 for single-site DMRG
+# en, psi = dmrg1(psi0, H, [psi_gr], params; weight = 10.0)
+```
+
+Similarly, using `StateEnvs`:
+```
+sysenv_ex = StateEnvs(psi0, H, [psi_gr]; weight = 10.0)
+nsite = 2 # two-site update
+
+swdata_ex = dmrg!(sysenv_ex, params, nsite)
+
+# Get energy from `Sweepdata`
+energy1 = swdata_ex.energy[end]
+
+# take a shallow copy of the MPS
+# if the `StateEnvs` will be updated later again
+psi1 = getpsi(sysenv_ex)
+
+# Alternatively, take the psi from `StateEnvs` itself.
+# NOTE: This can crash the simulation, if the MPS is modified (e.g., in measurements)
+# and `StateEnvs` is going to be updated later.
+# psi1 = sysenv_ex.psi
+```

docs/src/mps/state_envs.md

@@ -1,9 +1,28 @@
-# `StateEnvs`: A container to store the MPS and its environment
+# `StateEnvs`: A container to store the MPS and its environments
+
+At the lowest-level of abstraction, TeNLib defines `StateEnvs` to hold an MPS and its
+environments to be modified in place.
 
-At the lowest-level of abstraction, TeNLib defines `StateEnvs` to hold an MPS and its environment to be modified in place.
 Skip this part if you want to avoid lower-level abstraction.
 
-```@autodocs
-Modules = [TeNLib]
-Pages   = ["mps/state_envs.jl"]
+```@docs
+StateEnvs
+getpsi(sysenv::StateEnvs)
+getenv(sysenv::StateEnvs)
+StateEnvs(psi::MPS, H::MPO)
+StateEnvs(psi::MPS, Hs::Vector{MPO})
+StateEnvs(psi::MPS, H::MPO, Ms::Vector{MPS}; weight::Float64)
+StateEnvs(psi::MPS, Hs::Vector{MPO}, Ms::Vector{MPS}; weight::Float64)
+StateEnvs(psi::MPS, H::CouplingModel)
+StateEnvs(psi::MPS, H::CouplingModel, Ms::Vector{MPS}; weight::Float64)
+updateH!(sysenv::StateEnvs{ProjMPO}, H::MPO; recalcEnv::Bool = true)
+updateH!(sysenv::StateEnvs{ProjMPOSum2}, Hs::Vector{MPO}; recalcEnv::Bool = true)
+updateH!(sysenv::StateEnvs{ProjMPO_MPS2}, H::MPO, Ms::Vector{MPS};  weight::Float64, recalcEnv::Bool = true)
+updateH!(sysenv::StateEnvs{ProjMPOSum_MPS}, H::Vector{MPO}, Ms::Vector{MPS}; weight::Float64, recalcEnv::Bool = true)
+updateH!(sysenv::StateEnvs{ProjCouplingModel_MPS}, H::CouplingModel, Ms::Vector{MPS}; weight::Float64, recalcEnv::Bool = true)
+nsite(sysenv::StateEnvs)
+set_nsite!(sysenv::StateEnvs, nsite::Int)
+position!(sysenv::StateEnvs, pos::Int)
+Base.copy(sysenv::StateEnvs)
+Base.length(sysenv::StateEnvs)
 ```

docs/src/mps/sweep.md

@@ -0,0 +1,44 @@
+# Sweeping through the MPS
+
+At a lower level of abstraction, TeNLib allows to control each fullsweep
+(left-to-right and right-to-left) manually to update `StateEnvs`.
+
+Skip this part if you want to avoid lower-level abstraction.
+
+## `SweepData`
+
+TeNLib defines a struct, called  `SweepData`, to store essential data after each fullsweep.
+
+```@docs
+SweepData
+Base.copy(swdata::SweepData)
+```
+
+## Perform a fullsweep
+
+```@docs
+fullsweep!(sysenv::StateEnvs, solver, nsite::Int, swdata::SweepData; kwargs...)
+```
+
+## Perform a dynamical fullsweep
+
+TeNLib defines the following function to dynamically decide whether to perform single- or
+two-site update at each bond, depending on the entropy growth at the previous halfsweep.
+
+```@docs
+dynamic_fullsweep!(sysenv::StateEnvs, solver, swdata::SweepData; kwargs...)
+```
+
+## Global Subspace Expansion
+
+Following [Phys. Rev. B **102**, 094315 (2020)](https://journals.aps.org/prb/abstract/10.1103/PhysRevB.102.094315), a Global Subspace Expansion can be performed using Krylov subspace if the
+environments are created by a single `MPO`.
+
+Apart from TDVP, Global Subspace Expansion is also very useful for DMRG to get rid of nasty
+local minimas.
+
+```@docs
+krylov_extend!(psi::MPS, H::MPO; kwargs...)
+krylov_extend!(sysenv::StateEnvs{ProjMPO}; kwargs...)
+```
+

docs/src/mps/tdvp.md

@@ -0,0 +1,30 @@
+# Performing TDVP
+
+## `TDVPEngine`
+
+TeNLib defines a struct, called `TDVPEngine`, to store essential data during TDVP sweeps.
+
+```@docs
+TDVPEngine
+TDVPEngine(psi::MPS, H::T) where T <: Union{MPO, Vector{MPO}, CouplingModel}
+TDVPEngine(psi::MPS, H::T, Ms::Vector{MPS}; weight::Float64) where T <: Union{MPO, Vector{MPO}, CouplingModel}
+getpsi(engine::TDVPEngine)
+sweepcount(engine::TDVPEngine)
+getenergy(engine::TDVPEngine)
+getentropy(engine::TDVPEngine)
+maxchi(engine::TDVPEngine)
+totalerror(engine::TDVPEngine)
+sweeperror(engine::TDVPEngine)
+krylov_extend!(engine::TDVPEngine{ProjMPO}; kwargs...)
+sweepdata(engine::TDVPEngine)
+abstime(engine::TDVPEngine)
+updateH!(engine::TDVPEngine, H::T; recalcEnv::Bool = true) where T <: Union{MPO, Vector{MPO}, CouplingModel}
+updateH!(engine::TDVPEngine, H::T, Ms::Vector{MPS}; weight::Float64, recalcEnv::Bool = true) where T <: Union{MPO, Vector{MPO}, CouplingModel}
+Base.copy(engine::TDVPEngine)
+```
+
+## `tdvpsweep!`
+
+```@docs
+tdvpsweep!
+```

docs/src/mps/update_site.md

@@ -0,0 +1,9 @@
+# Perform local updates
+
+At the lowest-level of abstraction, TeNLib allows for updating the `StateEnvs` for each sites/bonds manually.
+
+Skip this part if you want to avoid lower-level abstraction.
+
+```@docs
+update_position!(sysenv::StateEnvs, solver, pos::Int, nsite::Int, ortho::String; kwargs...)
+```