docs: upgrade documentation with docstrings

jack-dunham · jack-dunham · commit 6ff5862bfa7a · 2025-06-24T17:09:12.000+02:00
diff --git a/README.md b/README.md
@@ -1,5 +1,5 @@
 # TensorRenormalizationGroups.jl
 
-*A Julia package implementing various two-dimensional tensor renormalization group-like algorithms in an application agnostic way under a single interface. Based on [TensorKit.jl](https://github.com/Jutho/TensorKit.jl).*
+*A Julia package implementing various two-dimensional tensor renormalization group-like algorithms under a single interface. Designed to be application agnostic. Based on [TensorKit.jl](https://github.com/Jutho/TensorKit.jl).*
 
 [![](https://img.shields.io/badge/docs-dev-blue.svg)](https://jack-dunham.github.io/TensorRenormalizationGroups.jl/dev)
diff --git a/docs/make.jl b/docs/make.jl
@@ -6,7 +6,11 @@ makedocs(
     authors="Jack Dunham",
     pages=[
         "Home" => "index.md",
-        "Library" => "library.md",
+        "Library" => [
+            "Computing and contracting" => "renormalize.md",
+            "Defining tensor networks" => "networks.md",
+            "Algorithms" => "algorithms.md",
+        ],
         "Index" => "_index.md"
     ]
 )
diff --git a/docs/src/algorithms.md b/docs/src/algorithms.md
@@ -0,0 +1,41 @@
+# Algorithms
+
+## Generic
+
+```@docs
+AbstractRenormalizationAlgorithm
+AbstractBoundaryAlgorithm
+AbstractGrainingAlgorithm
+AbstractRenormalizationRuntime
+AbstractBoundaryRuntime
+AbstractGrainingRuntime
+```
+
+## VUMPS
+
+```@docs
+VUMPS
+VUMPSRuntime
+MPS
+FixedPoints
+```
+
+## CTMRG
+
+```@docs
+AbstractCornerMethod
+CTMRG
+CornerMethodTensors
+CornerMethodRuntime 
+Corners
+Edges
+corners
+edges
+```
+
+## TRG
+
+```@docs
+TRG
+TRGRuntime
+```
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -1,3 +1,5 @@
 # TensorRenormalizationGroups.jl
 
-A package for performing contractions of infinite two-dimensional tensor networks.
+```@docs
+TensorRenormalizationGroups
+```
diff --git a/docs/src/library.md b/docs/src/library.md
@@ -1,16 +0,0 @@
-# Library
-
-## Methods
-
-```@docs
-initialize
-calculate!
-contract
-```
-
-## Algorithms
-
-```@docs
-VUMPS
-CTMRG
-```
diff --git a/docs/src/networks.md b/docs/src/networks.md
@@ -0,0 +1,26 @@
+# Defining tensor networks
+
+## Unit cells
+
+```@docs
+AbstractUnitCell
+UnitCell
+```
+
+## Geometry
+
+```@docs
+AbstractUnitCellGeometry
+Square
+SquareSymmetric
+```
+
+## Tensor-specific 
+
+```@docs
+CompositeTensor
+tensortype
+virtualspace
+swapaxes
+invertaxes
+```
diff --git a/docs/src/renormalize.md b/docs/src/renormalize.md
@@ -0,0 +1,11 @@
+# Computing and contracting
+
+```@docs
+Renormalization
+renormalize!
+TRGroups.continue!
+TRGroups.reset!
+TRGroups.recycle!
+TRGroups.restart!
+contract
+```
diff --git a/src/TensorRenormalizationGroups.jl b/src/TensorRenormalizationGroups.jl
@@ -1,3 +1,11 @@
+"""
+*A Julia package implementing various two-dimensional tensor renormalization group-like
+algorithms under a single interface. Designed to be application agnostic. 
+Based on [TensorKit.jl](https://github.com/Jutho/TensorKit.jl).*
+
+!!! note
+    This documentation is a work in progress.
+"""
 module TensorRenormalizationGroups
 const TRGroups = TensorRenormalizationGroups
 
@@ -40,10 +48,14 @@ export AbstractCornerMethod
 export CornerMethodTensors, CornerMethodRuntime, Corners, Edges
 export corners, edges
 
+# GRAINING
+export TRGRuntime
+
 export getboundary
 
 # INTERFACE
-export initialize, renormalize!, contract
+export renormalize!, contract
+public continue!, reset!, recycle!, restart!
 
 # No deps
 include("convergenceinfo.jl")
diff --git a/src/abstractproblem.jl b/src/abstractproblem.jl
@@ -1,4 +1,15 @@
+"""
+$(TYPEDEF)
+
+Abstract supertype of all algorithms available in this package.
+"""
 abstract type AbstractRenormalizationAlgorithm end
+
+"""
+$(TYPEDEF)
+
+Abstract supertype of all algorithm-specific runtime state objects.
+"""
 abstract type AbstractRenormalizationRuntime end
 
 """
@@ -13,22 +24,24 @@ $(TYPEDFIELDS)
 
 # Constructors
 
-    Renormalization(network::AbstractMatrix, alg::AbstractRenormalizationAlgorithm, [initial::AbstractRenormalizationRuntime])
+    $(FUNCTIONNAME)(network::AbstractMatrix, alg::AbstractRenormalizationAlgorithm, [initial::AbstractRenormalizationRuntime])
 
 A new instance of `Renormalization` is constructed by passing `network` and 
 (optionally) an initial runtime object, as well as the chosen `alg`. 
 If `initial` is specified, `convertproblem` will be called to attempt to make
 `initial` compatible with `alg`.
 
-Note, `Renormalization` will *always* be constructed using a `copy` of `network`, but
-*not* a `deepcopy`. That is, one can mutate the `network` struct using `setindex!` with
-out mutating the constructed `Renormalization`, but mutating the tensor elements 
-themselves *will* propagate through to this struct.
-
-    Renormalization(network::AbstractMatrix, problem::Renormalization)
+    $(FUNCTIONNAME)(network::AbstractMatrix, problem::Renormalization)
 
 Constuct a new instance of `Renormalization` using the algorithm and runtime from
 existing `problem`.
+
+!!! warn
+    `Renormalization` will *always* be constructed using a `copy` of `network`, but
+    *not* a `deepcopy`. That is, one can mutate the `network` struct using `setindex!` with
+    out mutating the constructed `Renormalization`, but mutating the tensor elements 
+    themselves *will* propagate through to this struct.
+
 """
 struct Renormalization{
     Alg<:AbstractRenormalizationAlgorithm,
diff --git a/src/abstractunitcell.jl b/src/abstractunitcell.jl
@@ -1,4 +1,16 @@
+"""
+$(TYPEDEF)
+
+Abstract supertype of all unit cell lattice geometries.
+"""
 abstract type AbstractUnitCellGeometry end
+
+"""
+$(TYPEDEF)
+
+Abstract supertype of all unit cells (periodic boundary conditions) defined on a lattice 
+with geometry `G`.
+"""
 abstract type AbstractUnitCell{G<:AbstractUnitCellGeometry,ElType,A} <:
               AbstractMatrix{ElType} end
 
@@ -7,6 +19,12 @@ basedata(arr::AbstractUnitCell) = basedata(getdata(arr))
 
 const AbUnCe{T,G,A} = AbstractUnitCell{G,T,A}
 
+"""
+$(FUNCTIONNAME)(x) -> AbstractTensorMap
+
+Return the type of tensor associated with object `x`, if any. Similar to `eltype` for container
+types but always returns an `AbstractTensorMap`. Defined in both the value and type domains.
+"""
 tensortype(val) = tensortype(typeof(val))
 tensortype(args::Type) = throw(MethodError(tensortype, (args,)))
 tensortype(T::Type{<:AbstractTensorMap}) = T
diff --git a/src/boundaries/abstractboundary.jl b/src/boundaries/abstractboundary.jl
@@ -1,4 +1,15 @@
+"""
+$(TYPEDEF)
+
+Abstract supertype of all boundary algorithms
+"""
 abstract type AbstractBoundaryAlgorithm <: AbstractRenormalizationAlgorithm end
+
+"""
+$(TYPEDEF)
+
+Abstract supertype of all boundary runtime objects.
+"""
 abstract type AbstractBoundaryRuntime <: AbstractRenormalizationRuntime end
 
 function boundaryerror!(S_old::AbstractMatrix, C_new::AbstractMatrix)
diff --git a/src/boundaries/corner/cornermethod.jl b/src/boundaries/corner/cornermethod.jl
@@ -1,3 +1,8 @@
+"""
+$(TYPEDEF)
+
+Abstract supertype of all corner-based boundary methods.
+"""
 abstract type AbstractCornerMethod <: AbstractBoundaryAlgorithm end
 
 struct Projectors{A<:AbstractUnitCell}
@@ -14,10 +19,22 @@ function Base.getindex(p::Projectors, i::Int64)
     return tup[i]
 end
 
+"""
+$(TYPEDEF)
+
+Struct containing the corner tensors C1, C2, C3 and C4 stored in it's only field `:data` as
+a tuple in that order.
+"""
 struct Corners{C<:AbstractUnitCell}
     data::NTuple{4,C}
 end
 
+"""
+$(TYPEDEF)
+
+Struct containing the edge tensors T1, T2, T3 and T4 stored in it's only field `:data` as
+a tuple in that order.
+"""
 struct Edges{E<:AbstractUnitCell}
     data::NTuple{4,E}
 end
@@ -50,6 +67,12 @@ end
 
 TensorKit.scalartype(::Type{<:FourTupleLike{A}}) where {A} = scalartype(A)
 
+"""
+$(TYPEDEF)
+
+Concreate struct containing tensors required for a corner method. Fields are not public. 
+Tensors can be accessed using the field getters [`corners`](@ref) and [`edges`](@ref).
+"""
 struct CornerMethodTensors{C<:Corners,E<:Edges,P<:Projectors,N<:AbstractNetwork}
     corners::C
     edges::E
@@ -58,13 +81,30 @@ struct CornerMethodTensors{C<:Corners,E<:Edges,P<:Projectors,N<:AbstractNetwork}
 end
 geometrytype(::Type{CornerMethodTensors{C,E,P,N}}) where {C,E,P,N} = geometrytype(N)
 
+"""
+    $(FUNCTIONNAME)(x::Union{CornerMethodTensors, CornerMethodRuntime}) -> Corners
+
+Return the corner tensors associated with the object `x`.
+"""
 corners(t::CornerMethodTensors) = t.corners
+
+"""
+    $(FUNCTIONNAME)(x::Union{CornerMethodTensors, CornerMethodRuntime}) -> Edges
+
+Return the edge tensors associated with the object `x`.
+"""
 edges(t::CornerMethodTensors) = t.edges
 
 function TensorKit.scalartype(::Type{<:CornerMethodTensors{C,E}}) where {C,E}
     return promote_type(scalartype(C), scalartype(E))
 end
 
+"""
+$(TYPEDEF)
+
+Runtime state of a corner method renormalization algorithm. Fields are not public. 
+Tensors can be accessed using the field getters [`corners`](@ref) and [`edges`](@ref).
+"""
 struct CornerMethodRuntime{T<:CornerMethodTensors,S<:CornerSingularValues} <:
        AbstractRenormalizationRuntime
     primary::T
diff --git a/src/boundaries/vumps/abstractmps.jl b/src/boundaries/vumps/abstractmps.jl
@@ -8,17 +8,19 @@ Infinite boundary matrix product state (MPS) in mixed canonical form. MPS tensor
 "physical" indices.
 Has fields `AL`, `C`, `AR` and derived field `AC` such that
 ```math
-A_L(x,y) C_(x,y) \\approx C(x - 1, y) A_R(x, y) \\approx AC(x, y) \\forall x,y \\in \\Lambda
+A_L(x,y) C(x,y) \\approx C(x - 1, y) A_R(x, y) \\approx AC(x, y) \\quad \\forall x,y \\in \\Lambda
 ```
 where ``\\Lambda`` defines the unit cell of geometry `G`.
 
 # Examples
 
-```jldoctest
-julia> physbonds = UnitCell(fill(ComplexSpace(2), 3, 3))
-julia> virtbonds = UnitCell(fill(ComplexSpace(3), 3, 3))
-julia> mps = MPS(rand, ComplexF64, physbonds, virtbonds)
-julia> AL, C, AR, AC = mps
+```@repl
+using TensorKit
+physbonds = UnitCell(fill(ComplexSpace(2), 2, 1))
+virtbonds = UnitCell(fill(ComplexSpace(3), 2, 1))
+mps = MPS(rand, ComplexF64, physbonds, virtbonds);
+AL, C, AR, AC = mps;
+C
 ```
 
 """
diff --git a/src/boundaries/vumps/fixedpoints.jl b/src/boundaries/vumps/fixedpoints.jl
@@ -1,7 +1,13 @@
 # DONE (NEEDS RESTRUCTURING)
 abstract type AbstractFixedPoints end
 
-# Fixed points of a transfer matrix
+"""
+$(TYPEDEF)
+
+Left and right fixed points of the transfer matrix formed from each row-to-row transfer
+matrix sandwiched between the a boundary MPS and it's adjoint. This struct has two fields
+`:left` and `:right` which can be accessed directly.
+"""
 struct FixedPoints{A<:AbUnCe{<:TenAbs{2}}} <: AbstractFixedPoints
     left::A
     right::A
@@ -20,6 +26,16 @@ function FixedPoints(f, mps::MPS, network::AbstractNetwork)
     return FixedPoints(left, right)
 end
 
+function Base.iterate(ct::FixedPoints, state=1)
+    if state == 1
+        return ct.left, state + 1
+    elseif state == 1
+        return ct.right, state + 1
+    elseif state > 2
+        return nothing
+    end
+end
+
 Base.similar(fps::FixedPoints) = FixedPoints(similar(fps.left), similar(fps.right))
 
 TensorKit.scalartype(::Type{<:FixedPoints{A}}) where {A} = scalartype(A)
@@ -71,6 +87,13 @@ end
 #     @tensoropt hc[dr dl] = cu[ur ul] * fl[m1 m2; ul dl] * fr[m1 m2; ur dr] * conj(cd[dr dl])
 # end
 
+"""
+    $(FUNCTIONNAME)(mps::MPS, network::AbstractUnitCell [,f0::FixedPoints]) -> FixedPoints
+
+Compute the left and right fixed points of the transfer matrix defined by sandwiching each
+row of `network` between `mps` and it's `adjoint`. If `f0` is provided, use it as an initial
+guess.
+"""
 function fixedpoints(mps::MPS, network, f0=FixedPoints(rand, mps, network))
     return fixedpoints!(f0, mps, network)
 end
diff --git a/src/boundaries/vumps/vumps.jl b/src/boundaries/vumps/vumps.jl
diff --git a/src/compositetensor.jl b/src/compositetensor.jl
diff --git a/src/contract.jl b/src/contract.jl
diff --git a/src/graining/abstractgraining.jl b/src/graining/abstractgraining.jl
diff --git a/src/graining/trg.jl b/src/graining/trg.jl

Original file line number	Diff line number	Diff line change
`@@ -6,7 +6,11 @@ makedocs(`
`6`	`6`	`authors="Jack Dunham",`
`7`	`7`	`pages=[`
`8`	`8`	`"Home" => "index.md",`
`9`		`- "Library" => "library.md",`
	`9`	`+ "Library" => [`
	`10`	`+ "Computing and contracting" => "renormalize.md",`
	`11`	`+ "Defining tensor networks" => "networks.md",`
	`12`	`+ "Algorithms" => "algorithms.md",`
	`13`	`+ ],`
`10`	`14`	`"Index" => "_index.md"`
`11`	`15`	`]`
`12`	`16`	`)`