Add docstrings

Author: pbrehmer

src/Defaults.jl

@@ -114,7 +114,7 @@ const eigh_rrule_verbosity = 0
 # Projectors
 const projector_alg = :halfinfinite # ∈ {:halfinfinite, :fullinfinite}
 const projector_verbosity = 0
-const projector_alg_c4v = :c4v_eigh
+const projector_alg_c4v = :c4v_eigh # ∈ {:c4v_eigh, :c4v_qr (TODO)}
 
 # Fixed-point gradient
 const gradient_tol = 1.0e-6

src/algorithms/ctmrg/c4v.jl

@@ -1,3 +1,29 @@
+"""
+$(TYPEDEF)
+
+CTMRG algorithm assuming a C₄ᵥ-symmetric PEPS, i.e. invariance under 90° spatial rotation and
+Hermitian reflection. This requires a single-site unit cell. The projector is obtained from
+`eigh` decomposing the Hermitian enlarged corner.
+
+## Fields
+
+$(TYPEDFIELDS)
+
+## Constructors
+
+    C4vCTMRG(; kwargs...)
+
+Construct a C₄ᵥ CTMRG algorithm struct based on keyword arguments.
+For a full description, see [`leading_boundary`](@ref). The supported keywords are:
+
+* `tol::Real=$(Defaults.ctmrg_tol)`
+* `maxiter::Int=$(Defaults.ctmrg_maxiter)`
+* `miniter::Int=$(Defaults.ctmrg_miniter)`
+* `verbosity::Int=$(Defaults.ctmrg_verbosity)`
+* `trunc::Union{TruncationStrategy,NamedTuple}=(; alg::Symbol=:$(Defaults.trunc))`
+* `decomp_alg::Union{<:EighAdjoint,NamedTuple}`
+* `projector_alg::Symbol=:$(Defaults.projector_alg_c4v)`
+"""
 struct C4vCTMRG{P <: ProjectorAlgorithm} <: CTMRGAlgorithm
     tol::Float64
     maxiter::Int
@@ -10,6 +36,33 @@ function C4vCTMRG(; kwargs...)
 end
 CTMRG_SYMBOLS[:c4v] = C4vCTMRG
 
+"""
+$(TYPEDEF)
+
+Projector algorithm implementing the `eigh` decomposition of a Hermitian enlarged corner.
+
+## Fields
+
+$(TYPEDFIELDS)
+
+## Constructors
+
+    C4vEighProjector(; kwargs...)
+
+Construct the C₄ᵥ `eigh`-based projector algorithm based on the following keyword arguments:
+
+* `decomp_alg::Union{<:EighAdjoint,NamedTuple}=EighAdjoint()` : `eigh` algorithm including the reverse rule. See [`EighAdjoint`](@ref).
+* `trunc::Union{TruncationStrategy,NamedTuple}=(; alg::Symbol=:$(Defaults.trunc))` : Truncation strategy for the projector computation, which controls the resulting virtual spaces. Here, `alg` can be one of the following:
+    - `:fixedspace` : Keep virtual spaces fixed during projection
+    - `:notrunc` : No singular values are truncated and the performed SVDs are exact
+    - `:truncerror` : Additionally supply error threshold `η`; truncate to the maximal virtual dimension of `η`
+    - `:truncrank` : Additionally supply truncation dimension `η`; truncate such that the 2-norm of the truncated values is smaller than `η`
+    - `:truncspace` : Additionally supply truncation space `η`; truncate according to the supplied vector space 
+    - `:trunctol` : Additionally supply singular value cutoff `η`; truncate such that every retained singular value is larger than `η`
+* `verbosity::Int=$(Defaults.projector_verbosity)` : Projector output verbosity which can be:
+    0. Suppress output information
+    1. Print singular value degeneracy warnings
+"""
 struct C4vEighProjector{S <: EighAdjoint, T} <: ProjectorAlgorithm
     decomp_alg::S
     trunc::T
@@ -44,15 +97,26 @@ function ctmrg_iteration(
     return CTMRGEnv(corner′, edge′), info
 end
 
+"""
+    c4v_enlarge(network, env, ::C4vEighProjector)
+
+Compute the normalized and Hermitian-symmetrized C₄ᵥ enlarged corner.
+"""
 function c4v_enlarge(network, env, ::C4vEighProjector)
-    return TensorMap(EnlargedCorner(network, env, (NORTHWEST, 1, 1)))
+    enlarged_corner = TensorMap(EnlargedCorner(network, env, (NORTHWEST, 1, 1)))
+    return 0.5 * (enlarged_corner + enlarged_corner') / norm(enlarged_corner)
 end
 # function c4v_enlarge(enlarged_corner, alg::C4vQRProjector)
 #     # TODO
 # end
 
+"""
+    c4v_projector(enlarged_corner, alg::C4vEighProjector)
+
+Compute the C₄ᵥ projector from `eigh` decomposing the Hermitian `enlarged_corner`.
+Also return the normalized eigenvalues as the new corner tensor.
+"""
 function c4v_projector(enlarged_corner, alg::C4vEighProjector)
-    hermitian_corner = 0.5 * (enlarged_corner + enlarged_corner') / norm(enlarged_corner)
     trunc = truncation_strategy(alg, enlarged_corner)
     D, U, info = eigh_trunc!(hermitian_corner, decomposition_algorithm(alg); trunc)
 
@@ -70,11 +134,17 @@ end
 #     # TODO
 # end
 
+"""
+    c4v_renormalize(network, env, projector)
+
+Renormalize the single edge tensor.
+"""
 function c4v_renormalize(network, env, projector)
     new_edge = renormalize_north_edge(env.edges[1], projector, projector', network[1, 1])
     return new_edge / norm(new_edge)
 end
 
+# TODO: this should eventually be the constructor for a new C4vCTMRGEnv type
 function CTMRGEnv(
         corner::AbstractTensorMap{T, S, 1, 1}, edge::AbstractTensorMap{T′, S, N, 1}
     ) where {T, T′, S, N}

src/algorithms/ctmrg/ctmrg.jl

@@ -66,8 +66,9 @@ supplied via the keyword arguments or directly as an [`CTMRGAlgorithm`](@ref) st
     3. Iteration info
     4. Debug info
 * `alg::Symbol=:$(Defaults.ctmrg_alg)` : Variant of the CTMRG algorithm. See also [`CTMRGAlgorithm`](@ref).
-    - `:simultaneous`: Simultaneous expansion and renormalization of all sides.
-    - `:sequential`: Sequential application of left moves and rotations.
+    - `:simultaneous` : Simultaneous expansion and renormalization of all sides.
+    - `:sequential` : Sequential application of left moves and rotations.
+    - `:c4v` : CTMRG assuming C₄ᵥ-symmetric PEPS and environment.
 
 ### Projector algorithm
 
@@ -82,6 +83,7 @@ supplied via the keyword arguments or directly as an [`CTMRGAlgorithm`](@ref) st
 * `projector_alg::Symbol=:$(Defaults.projector_alg)` : Variant of the projector algorithm. See also [`ProjectorAlgorithm`](@ref).
     - `:halfinfinite` : Projection via SVDs of half-infinite (two enlarged corners) CTMRG environments.
     - `:fullinfinite` : Projection via SVDs of full-infinite (all four enlarged corners) CTMRG environments.
+    - `:c4v_eigh` : Projection via `eigh` of the Hermitian enlarged corner.
 
 ## Return values
 
@@ -103,6 +105,8 @@ set of vectors and values will be returned as well:
 * `U_full` : Last unit cell of all left singular vectors.
 * `S_full` : Last unit cell of all singular values.
 * `V_full` : Last unit cell of all right singular vectors.
+
+For `C4vCTMRG` instead the last eigendecomposition `U` and `D` (and `U_full`, `D_full`) will be returned.
 """
 function leading_boundary(env₀::CTMRGEnv, network::InfiniteSquareNetwork; kwargs...)
     alg = select_algorithm(leading_boundary, env₀; kwargs...)

src/algorithms/ctmrg/projectors.jl

@@ -45,6 +45,14 @@ function ProjectorAlgorithm(;
     return alg_type(decomp_algorithm, truncation_strategy, verbosity)
 end
 
+"""
+    decomposition_algorithm(alg::ProjectorAlgorithm)
+    decomposition_algorithm(alg::ProjectorAlgorithm, (dir, r, c))
+
+Return the tensor decomposition algorithm of the `alg` projector algorithm.
+Additionally, the multi-index `(dir, r, c)` can be supplied which will return the
+decomposition performed at that index, e.g. when using `FixedEigh` or `FixedSVD`.
+"""
 decomposition_algorithm(alg::ProjectorAlgorithm) = alg.decomp_alg
 function decomposition_algorithm(alg::ProjectorAlgorithm, (dir, r, c))
     decomp_alg = decomposition_algorithm(alg)

src/utility/eigh.jl

@@ -23,7 +23,7 @@ Construct a `FullEighPullback` algorithm struct from the following keyword argum
 * `verbosity::Int=0` : Suppresses all output if `≤0`, prints gauge dependency warnings if `1`, and always prints gauge dependency if `≥2`.
 """
 @kwdef struct FullEighPullback
-    verbosity::Int = 1
+    verbosity::Int = 0
 end
 
 """
@@ -44,10 +44,9 @@ Construct a `TruncEighPullback` algorithm struct from the following keyword argu
 * `verbosity::Int=0` : Suppresses all output if `≤0`, prints gauge dependency warnings if `1`, and always prints gauge dependency if `≥2`.
 """
 @kwdef struct TruncEighPullback
-    verbosity::Int = 1
+    verbosity::Int = 0
 end
 
-# TODO: should this be same struct as SVDAdjoint?
 """
 $(TYPEDEF)
 
@@ -142,7 +141,9 @@ function MatrixAlgebraKit.eigh_trunc!(
     return adjoint(D), adjoint(U), info
 end
 
+#
 ## Forward algorithms
+#
 
 # Truncated eigh but also return full D and U to make it compatible with :fixed mode
 function _eigh_trunc!(
@@ -331,7 +332,10 @@ function _create_eightensors(t::TensorMap, eighdata, dims)
     return D, U
 end
 
+#
 ## Reverse-rule algorithms
+#
+
 function _get_pullback_gauge_tol(verbosity::Int)
     if verbosity ≤ 0 # never print gauge sensitivity
         return (_) -> Inf