Update documentation

Author: JanReimers

docs/src/index.md

@@ -30,126 +30,30 @@ Where:
 ``\\\hat{\boldsymbol{b}}\quad and\quad\hat{\boldsymbol{c}}`` are operator-valued vectors and
 ``\\\hat{\boldsymbol{A}}`` is an operator-valued matrix which is *not nessecarily triangular*. 
 
-In order to handle all combinations of upper and lower regular forms in conjunction with left and right canonical (orthogonal) forms we must extend ITensors *QR* decomposition capabilities to also include *QL*, *RQ* and *LQ* decomposition.  Below and in the code these will be generically referred to as *QX* decomposition.
-### The V-block
-For lower regular form the V-blocks are:
-```math
-\hat{V}_{L}=\begin{bmatrix}\hat{\boldsymbol{A}}_{L} & 0\\
-\hat{\boldsymbol{c}}_{L} & \hat{\mathbb{I}}
-\end{bmatrix}
-```
-```math
-\hat{V}_{R}=\begin{bmatrix}\hat{\mathbb{I}} & 0\\
-\hat{\boldsymbol{b}}_{L} & \hat{\boldsymbol{A}}_{L}
-\end{bmatrix}
-```
-where the `L` and `R` subscripts refer to `left` and `right` orthogonal forms being targeted.
-### QX decomposition of the V-block
-Block respecting *QL* decomposition is defined as *QL* decomposition of the of corresponding V-block:
-
-`1.` Reshape 
-```math 
-\hat{V}_{ab}\rightarrow V_{ab}^{mn}\rightarrow V_{\left(mna\right)b}
-```
-`2.` *QL* decompose 
-```math
-V_{\left(mna\right)b}=\sum_{k=1}^{\chi+1}Q_{\left(mna\right)k}L_{kb}
-```
-`3.` Reshape 
-```math 
-Q_{\left(mna\right)k}\rightarrow\hat{Q}_{ak}
-```
-`4.` Stuff *Q* back into correct block of *W*.
 
-`5.` Resize and transfer *L* to the next site: 
-```math
-\hat{W}^{\left(i+1\right)}\rightarrow L\hat{W}^{\left(i+1\right)}
-``` 
-Fortunately, under the hood,  ITensor takes care of all the reshaping for us. After this process *W* will now be in left canonical form.  Other cases and some additional details are described in tech notes.
+# Truncation (SVD compression)
+Truncation (or compression) of an MPO starts with 2 orthogonalization sweeps using column pivoting, rank reducing QR decomposoitions.  These sweeps will significantly reduce the bond dimensions of the MPO.  A final sweep using SVD decomposition and compression of the internal degrees of freedom will then yield a bond spectrum at each bond site.  The users can control the rank reduction and SVD compression using parameters described below.
 ```@docs
-block_qx
+ITensorMPOCompression.truncate!
 ```
 # Orthogonalization (Canonical forms)
-This is achieved by simply sweeping through the lattice and carrying out block respecting *QX* steps described above.  For left canoncical form one starts at the left and sweeps right, and the converse applies for right canonical form.
+Most users will not need to deal directly with orthogonalization, as the truncation routine will do this automaticlly.  This is achieved by simply sweeping through the lattice and carrying out block respecting *QX* steps described in the technical notes.  For left canoncical form one starts at the left and sweeps right, and the converse applies for right canonical form.
 ```@docs
 ITensorMPOCompression.orthogonalize!
 ```
-# Truncation (SVD compression)
-## Finite lattice
-Prior to truncation the MPO must first be rendered into canoncial form using the orthogonalize! function described above.  If for example the MPO is right-lower canonical form then a truncation sweep starts by doing a block repsecting *QL* decomposition on site 1:
-```math
-\hat{W}^{1}\rightarrow\hat{Q}^{1}L^{1}
-```
-We now must further factor *L* as follows
-```math
-L=\begin{bmatrix}1 & 0 & 0\\
-0 & \mathsf{L} & 0\\
-0 & t & 1
-\end{bmatrix}=ML^{\prime}=\begin{bmatrix}1 & 0 & 0\\
-0 & \mathsf{M} & 0\\
-0 & 0 & 1
-\end{bmatrix}\begin{bmatrix}1 & 0 & 0\\
-0 & \mathsf{\mathbb{I}} & 0\\
-0 & t & 1
-\end{bmatrix}
-```
-where internal sans-M matrix is what gets decomposed with SVD.  Picking out this internal matrix is really the secret sauce for avoiding diverging singular values when the lattice size grows.  After decomposition `M=UsV` the `U` matrix is absorbed to the left such that `W=QU` which is left canoncial. *sV* gets combined with L' and transfered to next site to the right.  There are many details to consider and these are explained in the technical notes.
-
-## Infinite lattice
-Truncation for an infinite lattice operates on the gauge transforms `G` that relate the left and right orthogonal forms:
-```math
-G^{\left(n-1\right)}\hat{W}_{R}^{n}=\hat{W}_{L}^{n}G^{n}\;n=1\cdots N_{cell}
-```
-Where `Ncell` is the number of lattice sites in the repeating unit cell. The gauge transforms are the output from left orthogonalizatio of a right orthogonalized iMPO. As usual we don't decompose `G` directly, but instead do a block respecting `svd` in order to only attack the non-extensive degrees of freedom.  Small singular values can be truncated at this stage.
-```math
-G^{n}=\begin{bmatrix}1 & 0 & 0\\
-0 & \mathsf{G^{n}} & 0\\
-0 & 0 & 1
-\end{bmatrix}=\begin{bmatrix}1 & 0 & 0\\
-0 & \mathsf{U^{n}}\mathsf{s^{n}}\mathsf{V^{n}} & 0\\
-0 & 0 & 1
-\end{bmatrix}\approx\begin{bmatrix}1 & 0 & 0\\
-0 & \mathsf{\tilde{U}^{n}}\mathsf{\tilde{s}^{n}}\mathsf{\tilde{V}^{n}} & 0\\
-0 & 0 & 1
-\end{bmatrix}=\tilde{U}^{n}\tilde{s}^{n}\tilde{V}^{n}
-```
-
-We then use the unitary tensors to transform the MPO tensors:
-```math
-\hat{W}_{R^{\prime}}^{n}=\tilde{V}^{n-1}\hat{W}_{R}^{n}\tilde{V}^{\dagger n},\quad\hat{W}_{L^{\prime}}^{n}=\tilde{U}^{\dagger n-1}\hat{W}_{L}^{n}\tilde{U}^{n}
-```
-which should be reduced in size if there was any truncation. The new gauge transforms, `s`, are now diagonal:
-```math
-\tilde{s}^{n-1}\hat{W}_{R^{\prime}}^{n}=\hat{W}_{L^{\prime}}^{n}\tilde{s}^{n}\;n=1\cdots N_{cell}
-```
-This looks rather elegant compared to the finite lattice case.
-
-## Truncate functions
-```@docs
-truncate!
-```
 
 # Characterizations
 
-The module has a number of functions for characterization of MPOs and operator-valued matrices. Some
-points to keep in mind:
-1. An MPO must be in one of the regular forms in order for orthogonalization to work.
-2. An MPO must be in one ot the orthonormal (canonical) forms prior to SVD truncation (compression). However the truncate! function will detect this and do the orthogonalization if needed.
-3. Lower (upper) regular form does not mean that the MPO is lower (upper) triangular.  As explained in the [Technical Notes](../TechnicalDetails.pdf) the `A`-block does not need to be triangular.
-4. Having said all that, most common hand constructed MPOs are either lower or upper triangular. Lower happens to be the more common convention.
-5. The orthogonalize! operation just happens to preserve lower (upper) trianglur form.  However truncation (SVD) does not preserve triangular form.
-
+The module has a number of functions for viewing and characterization of MPOs and operator-valued matrices. 
 
 ## Regular forms
 
 Regular forms are defined above in section [Regular Forms](@ref)
 
 ```@docs
-reg_form
+ITensorMPOCompression.reg_form
 detect_regular_form
 is_regular_form
-is_lower_regular_form
-is_upper_regular_form
 ```
 
 ## Orthogonal forms
@@ -162,9 +66,9 @@ The definition of orthogonal forms for MPOs or operator-valued matrices are more
 Where the summation limits depend on where the V-block is for `left`/`right` and `lower`/`upper`.  The specifics for all four cases are shown in table 6 in the [Technical Notes](../TechnicalDetails.pdf)
 
 ```@docs
-orth_type
-isortho
-check_ortho
+ITensorMPOCompression.orth_type
+ITensors.isortho
+ITensorMPOCompression.check_ortho
 ```
 
 # Some utility functions
@@ -181,12 +85,3 @@ MPOs for various models.  Right now we have four Hamiltonians available
 4. The 3-body model in eq. 34 of the Parker paper, built with autoMPO.
 The autoMPO MPOs come pre-truncated so they are not as useful for testing truncation. The automated truncation in AutoMPO can **partially** disabled by providing the the keyword argument `cutoff=-1.0` which gets passed down in the svd/truncate call used when building the MPO
 
-```@docs
-transIsing_MPO
-transIsing_AutoMPO
-Heisenberg_AutoMPO
-three_body_MPO
-transIsing_iMPO
-
-
-```

examples/truncate_MPO_demo.jl

@@ -9,6 +9,7 @@ NNN = 7; #Include up to 7th nearest neighbour interactions
 sites = siteinds("S=1/2", N);
 H = transIsing_MPO(sites, NNN);
 is_regular_form(H,lower) == true
+@show get_Dw(H)
 spectrums = truncate!(H,left)
 pprint(H[5])
 @show get_Dw(H)

src/ITensorMPOCompression.jl

@@ -17,7 +17,7 @@ import Base: similar, reverse, transpose
 # reg_form and orth_type values and functions
 export upper, lower, left, right, mirror, flip
 # lots of characterization functions
-export is_regular_form, isortho, check_ortho
+export is_regular_form, isortho, check_ortho, detect_regular_form
 # MPO bond dimensions and bond spectrum
 export get_Dw, min, max
 export bond_spectrums
@@ -45,7 +45,7 @@ end
 
 default_eps = 1e-14 #for characterization routines, floats abs()<default_eps are considered to be zero.
 
-"""
+@doc """
     @enum reg_form  upper lower
     
 Indicates that an MPO or operator-valued matrix has either an `upper` or `lower` regular form.
@@ -54,7 +54,7 @@ See also [`detect_regular_form`](@ref) and related functions
 """
 @enum reg_form upper lower
 
-"""
+@doc """
     @enum orth_type left right
 
 Indicates that an MPO matrix satisfies the conditions for `left` or `right` canonical form     

src/characterization.jl

@@ -143,21 +143,6 @@ end
 #
 #  Detection of canonical (orthogonal) forms
 #
-
-@doc """
-check_ortho(H,lr[,eps])::Bool
-
-Test if all sites in an MPO statisfty the condition for `lr` orthogonal (canonical) form.
-
-# Arguments
-- `H:MPO` : MPO to be characterized.
-- `lr::orth_type` : choose `left` or `right` orthogonality condition to test for.
-- `eps::Float64 = 1e-14` : operators inside H with norm(W[i,j])<eps are assumed to be zero.
-
-Returns `true` if the MPO is in `lr` orthogonal (canonical) form.  This is an expensive operation which scales as N*Dw^3 which should mostly be used only for unit testing code or in debug mode.  In production code use isortho which looks at the cached ortho state.
-
-"""
-
 @doc """
 isortho(H,lr)::Bool
 
@@ -200,38 +185,42 @@ end
 #      We must therefore test for both and return true if either one is true. 
 #
 
+
 @doc """
-    detect_regular_form(W[,eps])::Tuple{Bool,Bool}
+    detect_regular_form(H)::Tuple{Bool,Bool}
     
-Inspect the structure of an operator-valued matrix W to see if it satisfies the regular form 
-conditions as specified in Section III, definition 3 of
-> *Daniel E. Parker, Xiangyu Cao, and Michael P. Zaletel Phys. Rev. B 102, 035147*
+Inspect the structure of an MPO `H` to see if it satisfies the regular form conditions.
 
 # Arguments
-- `W::ITensor` : operator-valued matrix to be characterized. W is expected to have 2 "Site" indices and 1 or 2 "Link" indices
-- `eps::Float64 = 1e-14` : operators inside W with norm(W[i,j])<eps are assumed to be zero.
+- `H::MPO` : MPO to be characterized.
+
+# Keywords
+- `eps::Float64 = 1e-14` : operators inside `W` with norm(W[i,j])<eps are assumed to be zero.
 
 # Returns a Tuple containing
-- `reg_lower::Bool` Indicates W is in lower regular form.
-- `reg_upper::Bool` Indicates W is in upper regular form.
-The function returns two Bools in order to handle cases where W is not in regular form, returning 
-(false,false) and W is in a special pseudo diagonal regular form, returning (true,true).
+- `reg_lower::Bool` Indicates all sites in `H` are in lower regular form.
+- `reg_upper::Bool` Indicates all sites in `H` are in upper regular form.
+The function returns two Bools in order to handle cases where `H` is not regular form, returning (`false`,`false`) and `H` is in a special pseudo-diagonal regular form, returning (`true`,`true`).
     
 """
+function detect_regular_form(H::AbstractMPS;kwargs...)::Tuple{Bool,Bool}
+  return is_regular_form(H, lower;kwargs...), is_regular_form(H, upper;kwargs...)
+end
 
 @doc """
-    detect_regular_form(H[,eps])::Tuple{Bool,Bool}
+is_regular_form(H::MPO,ul::reg_form)::Bool
     
-Inspect the structure of an MPO `H` to see if it satisfies the regular form conditions.
+Inspect the structure of an MPO `H` to see if it satisfies the `lower/upper` regular form conditions.
 
 # Arguments
 - `H::MPO` : MPO to be characterized.
+- `ul::reg_form` : Select whether to test for `lower` or `upper` regular form.
+
+# Keywords
 - `eps::Float64 = 1e-14` : operators inside `W` with norm(W[i,j])<eps are assumed to be zero.
 
-# Returns a Tuple containing
-- `reg_lower::Bool` Indicates all sites in `H` are in lower regular form.
-- `reg_upper::Bool` Indicates all sites in `H` are in upper regular form.
-The function returns two Bools in order to handle cases where `H` is not regular form, returning (`false`,`false`) and `H` is in a special pseudo-diagonal regular form, returning (`true`,`true`).
+# Returns
+- `regular::Bool` Indicates all sites in `H` are in `ul` regular form.
     
 """
 function is_regular_form(H::AbstractMPS, ul::reg_form;kwargs...)::Bool
@@ -247,9 +236,6 @@ function is_regular_form(H::AbstractMPS, ul::reg_form;kwargs...)::Bool
 end
 
 
-function detect_regular_form(H::AbstractMPS;kwargs...)::Tuple{Bool,Bool}
-  return is_regular_form(H, lower;kwargs...), is_regular_form(H, upper;kwargs...)
-end
 
 function get_Dw(H::MPO)::Vector{Int64}
   N = length(H)