doc update and bugfix

Project.toml

@@ -1,7 +1,7 @@
 name = "TeNLib"
 uuid = "1ce00845-9e1b-4798-bd63-033d15ad4ca9"
 authors = ["Titas Chanda"]
-version = "0.0.1-DEV"
+version = "0.1.0"
 
 [deps]
 DataStructures = "864edb3b-99cc-5e75-8d2d-829cb0a9cfe8"

docs/make.jl

@@ -34,7 +34,12 @@ settings = Dict(
                 "Tree Tensor Networks" => "ttn/ttn.md",
                 "The TTN object" => "ttn/ttn_struct.md",
                 "Generating TTN" => "ttn/ttn_gen.md",
-                "StateEnvsTTN" => "ttn/state_envs_ttn.md"
+                "StateEnvsTTN" => "ttn/state_envs_ttn.md",
+                "Perform local updates" => "ttn/update_site_ttn.md",
+                "Sweeping through the TTN" => "ttn/sweep_ttn.md",
+                "Optimizing TTN" => "ttn/optimize_ttn.md",
+                "Example: Optimizing TTN" => "ttn/example_optimize.md",
+                "Measuring the TTN" => "ttn/measure_ttn.md"
             ]
         ],
     :format => Documenter.HTML(

docs/src/base/couplingmodel.md

@@ -1,7 +1,7 @@
 # `CouplingModel`
 
 TeNLib.jl degines as struct, called the `CouplingModel`, to store the Hamiltonian terms. 
-In case of MPS based algorithms, `CouplingModel` can be replaced by `MPO` without modifying
+In case of MPS based algorithms, `CouplingModel` can replace `MPO` without modifying
 rest of the code. For Tree Tensor Network (TTN) codes, only `CouplingModel` can be used.
 Different elements of `CouplingModel` are contracted in parallel.
 

docs/src/index.md

@@ -14,7 +14,7 @@ The documentation for TeNLib.jl can be found [**here**](https://titaschanda.gith
 
 TeNLib.jl features widely-used Tensor Network (TN) codes, designed with a **multi-layered abstraction**
 to cater to diverse user needs. The library provides users with varying levels of control over their computations.
-Presently, TeNLib.jl presents an array of functionalities for:
+Currently, TeNLib.jl presents an array of functionalities for:
 * *(a)* **Finite-size Matrix-Product States (MPS)**: Different variants of Density Matrix Renormalization Group (DMRG) and Time Dependent Variational Principle (TDVP) (including subspace expansion) methods.
 * *(b)* **Tree Tensor Network (TTN)**: Variational search for the ground state and first few excited states.
 
@@ -33,6 +33,17 @@ pkg> add ITensors
 pkg> add https://github.com/titaschanda/TeNLib.jl
 ```
 
+## Found an Issue or Bug?
+
+> "Beware of bugs in the above code; I have only proved it correct, not tried it."
+>    -- Donald Knuth
+
+
+If you find bugs or a mistakes of any kind, please let us know by adding an issue to the
+[GitHub issue tracker](https://github.com/titaschanda/TeNLib.jl/issues).
+You are also welcome to submit a [pull request](https://github.com/titaschanda/TeNLib.jl/pulls).
+
+
 ## Future functionality?
 
 Here is a list for future additions in the decreasing order of priority. Any help / suggestion is welcome.
@@ -41,6 +52,13 @@ Here is a list for future additions in the decreasing order of priority. Any hel
 * **Projected Entangled Pair States (PEPS)** for 2D problems.
 * Real-time evolution method using PEPS and TTN.
 
+Also, please feel free to ask about a new feature by adding a new request to the
+[GitHub issue tracker](https://github.com/titaschanda/TeNLib.jl/issues) labelled
+`feature request`. Note that submitting a pull request, providing the needed changes to
+introduced your requested feature, will speed up the process.
+
+
+
 ## Example: A simple DMRG code
 
 The following code is for a simple DMRG run at **the highest level of abstraction without any additional control**.
@@ -145,7 +163,4 @@ let
 			       
     en, psi = optimize(psi0, H, params, sweeppath)
 end
-```
-!!! info
-    "`OpStrings` and `CouplingModel` can be also used for MPS based codes without modifying other parts of the code."
-
+```    

docs/src/mps/example_dmrg.md

@@ -59,7 +59,7 @@ psi = getpsi(sysenv)
 # psi = sysenv.psi
 ```
 Most often, it is better to do a single-site DMRG (without any noise) after standard two-site update for better
-convergence. Such lowe-level function using `StateEnvs` is useful for that.
+convergence. Such lower-level function using `StateEnvs` is useful for that.
 ```
 sysenv = StateEnvs(psi0, H)
 
@@ -83,8 +83,9 @@ built from a single MPO.
 ```
 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.
+!!! warning
+    Global Subspace Expansion may 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
 

docs/src/mps/sweep.md

@@ -31,14 +31,15 @@ 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`.
+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...)
 ```
 
+!!! info
+    Apart from TDVP, Global Subspace Expansion is also very useful for DMRG to get rid of nasty
+    local minimas.
+

docs/src/ttn/example_optimize.md

@@ -0,0 +1,88 @@
+# Example: Optimizing TTN
+
+## Ground state search
+
+A straight-forward TTN optimization 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)
+
+    psi0 = default_randomTTN(sites, 12, QN("Sz", 0))
+    sweeppath = default_sweeppath(psi0)
+
+    params = OptimizeParamsTTN(; nsweeps = [10, 10], maxdim = [20, 50],
+                               cutoff = 1e-14, noise = 1e-3, noisedecay = 2,
+                               disable_noise_after = 5)
+
+    en, psi = optimize(psi0, H, params, sweeppath)
+end
+```
+
+!!! warning
+    For TTN optimzaion, direct `MPO` input is not supported. One can, however, prepare a
+    `CouplingModel` from `MPO` using
+    [`CouplingModel(mpos::MPO...)`](@ref CouplingModel(mpos::MPO...)). 
+
+
+Instead of using such higher-level code, one can also use lower-level functions for a better
+control.
+```
+sysenv = StateEnvsTTN(psi0, H)
+
+swdata = optimize!(sysenv, params, sweeppath)
+
+# Get energy from `Sweepdata`
+energy = swdata.energy[end]
+
+# take a shallow copy of the TTN
+# if the `StateEnvsTTN` will be updated later again
+psi = getpsi(sysenv)
+
+# Alternatively, take the psi from `StateEnvsTTN` itself.
+# NOTE: This can crash the simulation, if the TTN is modified (e.g., in measurements)
+# and `StateEnvsTTN` is going to be updated later on.
+# psi = sysenv.psi
+```
+
+## Excited state search
+
+Excited state search is also straightforword.
+
+```
+# Given a ground state `psi_gr`, initial TTN `psi0`,
+# and a Hamiltonian `H`
+
+en, psi = optimize(psi0, H, [psi_gr], params, sweeppath; weight = 10.0)
+```
+
+Similarly, using `StateEnvsTTN`:
+```
+sysenv_ex = StateEnvsTTN(psi0, H, [psi_gr]; weight = 10.0)
+swdata_ex = optimize!(sysenv_ex, params, sweeppath)
+
+# Get energy from `Sweepdata`
+energy1 = swdata_ex.energy[end]
+
+# take a shallow copy of the TTN
+# if the `StateEnvsTTN` will be updated later again
+psi1 = getpsi(sysenv_ex)
+
+# Alternatively, take the psi from `StateEnvsTTN` itself.
+# NOTE: This can crash the simulation, if the TTN is modified (e.g., in measurements)
+# and `StateEnvsTTN` is going to be updated later.
+# psi1 = sysenv_ex.psi
+```

docs/src/ttn/measure_ttn.md

@@ -0,0 +1,9 @@
+# Measuring the TTN
+
+```@docs
+measure(::Type{T}, psi::TTN, opten::ITensor) where T <: Union{ComplexF64, Float64}
+measure(::Type{T}, psi::TTN, opstr::String, pos::Int) where T <: Union{ComplexF64, Float64}
+measure(::Type{T}, psi::TTN, opstr::String; kwargs...) where T <: Union{ComplexF64, Float64}
+measure(::Type{T}, psi::TTN, optens::Vector{ITensor}) where T <: Union{ComplexF64, Float64}
+measure(::Type{T}, psi::TTN, oppairs::Vector{Pair{String, Int}}; isfermions::Bool = true) where T <: Union{ComplexF64, Float64}
+```

docs/src/ttn/optimize_ttn.md

@@ -0,0 +1,29 @@
+# Optimizing TTN
+
+Functions to optimize TTN.
+
+## `OptimizeParamsTTN`
+
+TeNLib.jl defines a struct, called  `OptimizeParamsTTN`, to control TTN optimizations.
+
+```@docs
+OptimizeParamsTTN
+OptimizeParamsTTN(;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::OptimizeParamsTTN)
+```
+
+## A lower level optimization function
+
+Following function modifies `StateEnvsTTN` in-place. Skip this function if you want to
+avoid lower-level abstraction.
+
+```@docs
+optimize!(sysenv::StateEnvsTTN, params::OptimizeParamsTTN,sweeppath::Vector{Int2}; kwargs...)
+```
+
+## Higher level optimzation functions
+
+```@docs
+optimize(psi0::TTN, H::CouplingModel, params::OptimizeParamsTTN, sweeppath::Vector{Int2}; kwargs...)
+```
+

docs/src/ttn/sweep_ttn.md

@@ -0,0 +1,26 @@
+# Sweeping through the TTN
+
+At a lower level of abstraction, TeNLib.jl allows to control each fullsweep
+ manually to update `StateEnvsTTN`.
+
+Skip this part if you want to avoid lower-level abstraction.
+
+## `SweepDataTTN`
+
+TeNLib.jl defines a struct, called  `SweepDataTTN`, to store essential data after each fullsweep.
+
+```@docs
+SweepDataTTN
+Base.copy(swdata::SweepDataTTN)
+```
+## `sweeppath`
+
+```@docs
+default_sweeppath
+```
+
+## Perform a fullsweep
+
+```@docs
+fullsweep!(sysenv::StateEnvsTTN, sweeppath::Vector{Int2}, solver, swdata::SweepDataTTN; kwargs...)
+```

docs/src/ttn/ttn.md

@@ -21,11 +21,18 @@ described in [Phys. Rev. B **90**, 125154 (2014)](https://journals.aps.org/prb/a
 ---
 
 Each tensor in the TTN are indexed by a pair (`Tuple`) of `Int`s = `(ll, nn)`.
-```
-const Int2 = Tuple{Int, Int}
+```@docs
+Int2
 ```
 In the default scenario, `ll` denotes the layer index and `nn` denotes the tensor index at each layer (see the image above). The counting for `ll`, in the default case, starts at the bottom (towards to top level), while `nn` counts from left. The structure of the network is defined by a
-[`Graph{Int2}`](@ref "The Graph object") object.
+[`Graph{Int2}`](@ref "The Graph object") object. The link / bond between two neighboring nodes is
+denoted by a `LinkTypeTTN` object, an **unordered** pair of `Int2`s.
+```@docs
+LinkTypeTTN
+```
+!!! info
+    The order of the nodes inside `LinkTypeTTN` is irrelevant, i.e.,
+    `LinkTypeTTN(node1, node2) == LinkTypeTTN(node2, node1)`.
 
 ---
 

docs/src/ttn/update_site_ttn.md

@@ -0,0 +1,16 @@
+# Perform local updates
+
+At the lowest-level of abstraction, TeNLib.jl allows for updating the `StateEnvsTTN` for each sites manually.
+
+Skip this part if you want to avoid lower-level abstraction.
+
+```@docs
+update_position!(sysenv::StateEnvsTTN, solver, node::Int2; time_step::Union{Float64, ComplexF64, Nothing}, normalize::Bool, maxdim::Int, mindim::Int, cutoff::Float64, svd_alg::String, kwargs...)
+```
+
+TeNLib.jl implements the subspace expansion method described in
+[SciPost Phys. Lect. Notes 8 (2019)] (https://scipost.org/10.21468/SciPostPhysLectNotes.8) to increase the bond dimension between two neighboring nodes.
+
+```@docs
+subspace_expand!(psi::TTN, node::Int2, nextnode::Int2, max_expand_dim::Int, noise::Float64)
+```