Merge pull request #3 from BrieucLD/master

Update Readme.md and documentation

README.md

@@ -63,7 +63,7 @@ A = productstatemps(physdims(H), state=[ψ, fill(unitcol(1,d), N)...]) # MPS
 ```
 
 This will generate a product state MPS with local Hilbert space dimensions corresponding to the MPO `H`, representing the
-spin in the up state and the bath in the vacuum state.
+spin in the up state (`ψ`) and the bath in the vacuum state.
 
 We may then wish to construct some observables to measure along the trajectory. For example
 
@@ -122,15 +122,15 @@ at every time step for every bond-dimension, while the observables supplied to `
 The final MPS is returned to `A` and the measurement data is returned to `dat`. If the option `save=true` is used the
 data will also be saved to a file. The directory in which data should be saved may be passed to the keyword argument
 `savedir`; by default the save directory is ~/MPSDynamics, which will be created if it doesn't exist (if using Windows
-the slashes will need to be reversed).
+the slashes will need to be reversed). The data directory name can be changed with the keyword argument `unid`.
 
 If the option `plot=true` is used, plots for 1D observables will be automatically generated and saved along with the data.
 
 Otherwise plots can be produced from `dat`, e.g.
 ```Julia
 using Plots
-plot(dat["data/times"], dat["convdata/sz"],label=["Dmax=2" "Dmax=4" "Dmax=6"], xlabel="t",ylabel="sz")
-heatmap(dat["data/times"], collect(1:N), abs.(dat["data/SXdisp"][1,:,:]), xlabel="t",ylabel="i")
+plot(dat["data/times"], dat["convdata/sz"],label=["Dmax=2" "Dmax=4" "Dmax=6"], xlabel="t",ylabel="sz", title="")
+heatmap(dat["data/times"], collect(1:N), abs.(dat["data/SXdisp"][1,:,:]), xlabel="t",ylabel="i", title="")
 ```
 ![Convergence plot of <sz> with increasing bond dimension Dmax](https://raw.githubusercontent.com/angusdunnett/MPSDynamics/master/images/plot.png "Convergence plot of <sz> with increasing bond dimension Dmax")
 

src/MPSDynamics.jl

@@ -29,6 +29,41 @@ include("run_A1TDVP.jl")
 include("chainA1TDVP.jl")
 include("switchmpo.jl")
 
+"""
+    runsim(dt, tmax, A, H; 
+		method=:TDVP1, 
+		machine=LocalMachine(), 
+		params=[], 
+		obs=[], 
+		convobs=[],
+                convparams=error("Must specify convergence parameters"),
+                save=false,
+                plot=save,
+                savedir=string(homedir(),"/MPSDynamics/"),
+                unid=randstring(5),
+                name=nothing,
+		kwargs...
+		)
+
+Propagate the MPS `A` with the MPO `H` up to time `tmax` in time steps of `dt`. The final MPS is returned to `A` and the measurement data is returned to `dat` 
+
+# Arguments
+
+* `method`: Several methods are implemented in MPSDynamics. `:TDVP1` refers to 1-site TDVP on tree and chain MPS, `:TDVP2` refers to 2-site TDVP on chain MPS, `:DTDVP` refers to a variant of 1-site TDVP with dynamics bond-dimensions on chain MPS
+* `machine`: `LocalMachine()` points local ressources, `RemoteMachine()` points distant ressources
+* `params`: list of parameters written in the log.txt file to describe the dynamics. Can be listed with @LogParams(). 
+* `obs`: list of observables that will be measured at every time step for the most accurate convergence parameter supplied to `convparams` 
+* `convobs`: list of observables that will be measure at every time step for every convergence parameter supplied to `convparams` 
+* `convparams`: list of convergence parameter with which the propagation will be calculated for every parameter. At each parameter, `convobs` are measured while `obs` are measured only for the most accurate dynamics
+* `save`: Used to choose whether the data will also be saved to a file  
+* `plot`: Used to choose whether plots for 1D observables will be automatically generated and saved along with the data
+* `savedir`: Used to specify the path where resulting files are stored
+* `unid`: Used to specify the name of the directory containing the resulting files
+* `name`: Used to describe the calculation. This name will appear in the log.txt file
+ 
+"""
+
+
 function runsim(dt, tmax, A, H;
                 method=:TDVP1,
                 machine=LocalMachine(),

src/measure.jl

@@ -95,7 +95,7 @@ end
 """
     measure(A, O; kwargs...)
 
-measure observable `O` on mps state `A`
+Measure observable `O` on mps state `A`
 
 """
 measure(A, O::OneSiteObservable; acs=nothing, ρ=nothing, kwargs...) = measure(A, O, acs, ρ)

src/models.jl

@@ -129,7 +129,7 @@ Create an MPO representing a tight-binding chain of `N` oscillators with `d` Foc
 # Arguments
 
 * `reverse`: If `reverse=true` create a chain were the last (i.e. Nth) site is the site which couples to the system
-* `coupletox`: Used to choose the form of the system coupling. `coupletox=true` gives a non-number conserving coupling of the form ``H_{\\text{I}}=A_{\\text{S}}(b_{0}^\\dagger + b_0)`` where ``A_{\\text{S}}`` is a system operator, while `coupletox=false` gives the number-converving coupling ``H_{\\text{I}}=(A_{\\text{S}} b_{0}^\\dagger + A_{\\text{S}}^\\dagger b_0)``
+* `coupletox`: Used to choose the form of the system coupling. `coupletox=true` gives a non-number conserving coupling of the form ``H_{\\text{I}}= A_{\\text{S}}(b_{0}^\\dagger + b_0)`` where ``A_{\\text{S}}`` is a system operator, while `coupletox=false` gives the number-converving coupling ``H_{\\text{I}}=(A_{\\text{S}} b_{0}^\\dagger + A_{\\text{S}}^\\dagger b_0)``
 * `tree`: If `true` the resulting chain will be of type `TreeNetwork`; useful for construcing tree-MPOs 
 
 # Example
@@ -345,15 +345,15 @@ end
 Generate MPO for a spin-1/2 coupled to a chain of harmonic oscillators, defined by the Hamiltonian
 
 ``
-H = \\frac{ω_0}{2}σ_z + Δσ_x + c_0σ_x(b_0^\\dagger+b_0) + \\sum_{i=0}^{N-1} t_i (b_{i+1}^\\dagger b_i +h.c.) + \\sum_{i=0}^{N-1} ϵ_ib_i^\\dagger b_i
+H = \\frac{ω_0}{2}σ_z + Δσ_x + c_0σ_x(b_0^\\dagger+b_0) + \\sum_{i=0}^{N-1} t_i (b_{i+1}^\\dagger b_i +h.c.) + \\sum_{i=0}^{N} ϵ_ib_i^\\dagger b_i
 ``.
 
 The spin is on site 1 of the MPS and the bath modes are to the right.
 
 This Hamiltonain is unitarily equivalent (before the truncation to `N` sites) to the spin-boson Hamiltonian defined by
 
 ``
-H =  \\frac{ω_0}{2}σ_z + Δσ_x + σ_x\\int_0^∞ dω\\sqrt{J(ω)}(b_ω^\\dagger+b_ω) + \\int_0^∞ωb_ω^\\dagger b_ω
+H =  \\frac{ω_0}{2}σ_z + Δσ_x + σ_x\\int_0^∞ dω\\sqrt{\\frac{J(ω)}{π}}(b_ω^\\dagger+b_ω) + \\int_0^∞ dω ωb_ω^\\dagger b_ω
 ``.
 
 The chain parameters, supplied by `chainparams`=``[[ϵ_0,ϵ_1,...],[t_0,t_1,...],c_0]``, can be chosen to represent any arbitrary spectral density ``J(ω)`` at any temperature.
@@ -416,7 +416,7 @@ hard cutoff: ``J(ω) = 2παω_c (\\frac{ω}{ω_c})^s θ(ω-ω_c)``
 The coefficients parameterise the chain Hamiltonian
 
 ``
-H = H_S + c_0 A_S⊗B_0+\\sum_{i=0}^{N-1}t_i (b_{i+1}^\\dagger b_i +h.c.) + \\sum_{i=0}^{N-1} ϵ_ib_i^\\dagger b_i
+H = H_S + c_0 A_S⊗B_0+\\sum_{i=0}^{N-1}t_i (b_{i+1}^\\dagger b_i +h.c.) + \\sum_{i=0}^{N} ϵ_ib_i^\\dagger b_i
 ``
 
 which is unitarily equivalent (before the truncation to `N` sites) to

src/mpsBasics.jl

@@ -139,14 +139,25 @@ Return an MPS representing a product state with local Hilbert space dimensions g
 By default all bond-dimensions will be 1 since the state is a product state. However, to
 embed the product state in a manifold of greater bond-dimension, `Dmax` can be set accordingly.
 
-The indvidual states of the MPS sites can be provdided by setting `state` to a list of
+The indvidual states of the MPS sites can be provided by setting `state` to a list of
 column vectors. Setting `state=:Vacuum` will produce an MPS in the vacuum state (where the
 state of each site is represented by a column vector with a 1 in the first row and zeros
 elsewhere). Setting `state=:FullOccupy` will produce an MPS in which each site is fully
 occupied (ie. a column vector with a 1 in the last row and zeros elsewhere).
 
 The argument `mpsorthog` can be used to set the gauge of the resulting MPS.
 
+# Example
+
+```julia-repl
+julia> ψ = unitcol(1,2); d = 6; N = 30; α = 0.1; Δ = 0.0; ω0 = 0.2; s = 1
+
+julia> cpars = chaincoeffs_ohmic(N, α, s)
+
+julia> H = spinbosonmpo(ω0, Δ, d, N, cpars)
+
+julia> A = productstatemps(physdims(H), state=[ψ, fill(unitcol(1,d), N)...]) # MPS representation of |ψ>|Vacuum>
+```
 """
 function productstatemps(physdims::Dims, Dmax=1; state=:Vacuum, mpsorthog=:Right)
 
@@ -239,6 +250,8 @@ end
 
 Generate an MPS with `numex` excitations of an equal super-position over `sites`
 
+The returned MPS will have bond-dimensions and physical dimensions `numex+1`
+
 """
 function chainmps(N::Int, sites::Vector{Int}, numex::Int)
     all(x-> 1<=x<=N, sites) || throw(ErrorException("tried to excite non-existant site of $N-site chain"))

src/treeTDVP.jl

@@ -521,6 +521,33 @@ function tdvp1sweep_lc!(dt, A::TreeNetwork, M::TreeNetwork, lc::TreeLightCone, F
     return A, F
 end
 
+"""
+    productstatemps(tree_::Tree, physdims::Dims, Dmax::Int=1; state=:Vacuum)
+
+Return a tree-MPS representing a product state with local Hilbert space dimensions given by `physdims`.
+
+By default all bond-dimensions will be 1 since the state is a product state. However, to
+embed the product state in a manifold of greater bond-dimension, `Dmax` can be set accordingly.
+
+The indvidual states of the MPS sites can be provided by setting `state` to a list of
+column vectors. Setting `state=:Vacuum` will produce an MPS in the vacuum state (where the
+state of each site is represented by a column vector with a 1 in the first row and zeros
+elsewhere). Setting `state=:FullOccupy` will produce an MPS in which each site is fully
+occupied (ie. a column vector with a 1 in the last row and zeros elsewhere).
+
+# Example
+
+```julia-repl
+julia> ψ = unitcol(1,2); d = 6; N = 30; α = 0.1; Δ = 0.0; ω0 = 0.2; s = 1
+
+julia> cpars = chaincoeffs_ohmic(N, α, s)
+
+julia> H = spinbosonmpo(ω0, Δ, d, N, cpars, tree=true)
+
+julia> A = productstatemps(H.tree, physdims(H), state=[ψ, fill(unitcol(1,d), N)...]) # tree-MPS representation of |ψ>|Vacuum>
+```
+"""
+
 function productstatemps(tree_::Tree, physdims::Dims, Dmax::Int=1; state=:Vacuum)
     tree = deepcopy(tree_)
     hn = findheadnode(tree)