Renormalizer interface for TRG (attempt 2)

.gitignore

@@ -3,3 +3,4 @@ Manifest.toml
 .vscode
 docs/build/
 .DS_Store
+CLAUDE.md

README.md

@@ -81,7 +81,7 @@ scheme = BTRG(T) # Bond-weighted TRG (excellent choice)
 data = run!(scheme, truncrank(16), maxiter(25)) # max bond-dimension of 16, for 25 iterations
 ```
 
-`data` now contains 26 norms of the tensor, 1 for every time the tensor was normalized. (By default there is a normalization step before the first coarse-graining step wich can be turned off by changing the kwarg `run!(...; finalize_beginning=false)`)
+`data` now contains 25 norms of the tensor, 1 for every time the tensor was normalized.
 
 Using these norms you could, for example, calculate the free energy of the critical classical Ising model:
 ```Julia

docs/src/finalizers.md

@@ -1,5 +1,5 @@
 # Finalizers
-At the end of every TNR step (and before the first step if `finalize_beginning=true` is chose in the `run!` function, which is default behaviour), the state of the scheme is finalized.
+At the end of every TNR step, the state of the scheme is finalized.
 
 By default this finalization process is as follow:
 

docs/src/index.md

@@ -58,7 +58,7 @@ T = classical_ising(ising_βc) # partition function of classical Ising model at
 scheme = BTRG(T) # Bond-weighted TRG (excellent choice)
 data = run!(scheme, truncrank(16), maxiter(25)) # max bond-dimension of 16, for 25 iterations
 ```
-`data` now contains 26 norms of the tensor, 1 for every time the tensor was normalized. (By default there is a normalization step before the first coarse-graining step wich can be turned off by changing the kwarg `run!(...; finalize_beginning=false)`)
+`data` now contains 25 norms of the tensor, 1 for every time the tensor was normalized.
 
 Using these norms you could, for example, calculate the free energy of the critical classical Ising model:
 ```Julia

examples/example.jl

@@ -9,12 +9,8 @@ stopping_criterion = convcrit(1.0e-16, trg_f) & maxiter(20)
 # choose a TensorKit truncation scheme
 trunc = truncrank(16) & trunctol(atol = 1.0e-40)
 
-# initialize the TRG scheme
-scheme = TRG(classical_ising(1.0))
 
-# run the TRG scheme (and normalize and store the norm in the beginning (finalize_beginning=true))
-data = run!(scheme, trunc, stopping_criterion; finalize_beginning = true)
-# or: data = run!(scheme, truncrank(16)), this will default to maxiter(100)
+# ---- old interface (other schemes) ----
 
 # initialize the BTRG scheme
 scheme = BTRG(classical_ising(1.0), -0.5)
@@ -27,3 +23,30 @@ scheme = HOTRG(classical_ising(1.0))
 
 # run the HOTRG scheme
 data = run!(scheme, trunc, stopping_criterion)
+
+# ---- iterable `Renormalizer` interface ----
+
+# create a pure algorithm config (kwargs with sensible defaults)
+alg = TRG(; trunc = trunc, stop = stopping_criterion)
+renorm = Renormalizer(alg, classical_ising(1.0))
+
+# run all steps with logging
+state, data = run!(renorm; verbosity = 1)
+f = free_energy(data, 1.0)
+
+# or, step through manually
+renorm = Renormalizer(alg, classical_ising(1.0))
+for (state, data) in renorm
+    τ0, _ = extract_tau_and_c(state.T; fast = true)
+    # each iteration yields the state after one RG step
+    # renorm.step tracks how many steps have been completed
+end
+# renorm.step is the number of completed steps
+
+# or, advance one step at a time
+renorm = Renormalizer(alg, classical_ising(1.0))
+rgstep!(renorm)  # throws if stop criterion already met
+rgstep!(renorm)
+
+# access the current tensor directly from the state
+T_final = renorm.state.T

src/TNRKit.jl

@@ -24,6 +24,7 @@ export trivial_convcrit
 
 # schemes
 include("schemes/tnrscheme.jl")
+include("schemes/renormalizer.jl")
 include("schemes/trg.jl")
 include("schemes/btrg.jl")
 include("schemes/hotrg.jl")
@@ -61,9 +62,9 @@ include("schemes/looptnr.jl")
 include("schemes/symmetric_looptnr.jl")
 export classical_ising_inv # Ising model with all legs in codomain
 
-export TNRScheme
+export Renormalizer, TNRScheme, TNRAlgorithm
 
-export TRG
+export TRG, OneSiteState
 export BTRG
 export HOTRG
 export HOTRG_3D
@@ -91,7 +92,7 @@ export CorrelationHOTRG
 export LoopTNR, LoopParameters
 export SLoopTNR
 
-export run!
+export run!, rgstep!
 
 # models
 include("models/ising.jl")

src/schemes/atrg.jl

@@ -7,7 +7,7 @@ Anisotropic Tensor Renormalization Group
     $(FUNCTIONNAME)(T)
 
 # Running the algorithm
-    run!(::ATRG, trunc::TruncationStrategy, stop::Stopcrit[, finalizer=default_Finalizer, finalize_beginning=true, verbosity=1])
+    run!(::ATRG, trunc::TruncationStrategy, stop::Stopcrit[, finalizer=default_Finalizer, verbosity=1])
 
 Each step rescales the lattice by a (linear) factor of √2
 

src/schemes/atrg3d.jl

@@ -7,7 +7,7 @@ $(TYPEDEF)
     $(FUNCTIONNAME)(T)
 
 # Running the algorithm
-    run!(::ATRG_3D, trunc::TruncationStrategy, stop::Stopcrit[, finalizer=defualt_Finalizer, finalize_beginning=true,verbosity=1])
+    run!(::ATRG_3D, trunc::TruncationStrategy, stop::Stopcrit[, finalizer=defualt_Finalizer, verbosity=1])
 
 Each step rescales the lattice by a (linear) factor of 2
 

src/schemes/btrg.jl

@@ -7,7 +7,7 @@ Bond-weighted Tensor Renormalization Group
     $(FUNCTIONNAME)(T [, k=-1/2])
 
 # Running the algorithm
-    run!(::BTRG, trunc::TruncationStrategy, stop::Stopcrit[, finalizer=default_Finalizer, finalize_beginning=true, verbosity=1])
+    run!(::BTRG, trunc::TruncationStrategy, stop::Stopcrit[, finalizer=default_Finalizer, verbosity=1])
 
 Each step rescales the lattice by a (linear) factor of √2
 

src/schemes/ctm/c4vctm.jl

@@ -12,7 +12,7 @@ or with a (0,4) tensor (North, East, South, West) (unflipped arrow convention).
 The keyword argument symmetrize makes the tensor C4v symmetric when set to true. If symmetrize = false, it checks the symmetry explicitly.
 
 # Running the algorithm
-    run!(::c4vCTM, trunc::TruncationStrategy, stop::Stopcrit[, finalize_beginning=true, verbosity=1])
+    run!(::c4vCTM, trunc::TruncationStrategy, stop::Stopcrit[, verbosity=1])
 
 !!! info "verbosity levels"
     - 0: No output

src/schemes/ctm/honeycomb.jl

@@ -25,7 +25,7 @@ or with a (0,3) tensor (120°, 0°, 240°) where all arrows point inward (unflip
 The keyword argument symmetrize makes the tensor C6v symmetric when set to true. If symmetrize = false, it checks the symmetry explicitly.
 
 # Running the algorithm
-    run!(::CTM, trunc::TruncationStrategy, stop::Stopcrit[, finalize_beginning=true, verbosity=1])
+    run!(::CTM, trunc::TruncationStrategy, stop::Stopcrit[, verbosity=1])
 
 !!! info "verbosity levels"
     - 0: No output
@@ -131,7 +131,7 @@ In the flipped arrow convention, the arrows point from (120°) to (240°, 0°).
 or with a (0,3) tensor (120°, 0°, 240°) where all arrows point inward (unflipped arrow convention).
 
 # Running the algorithm
-    run!(::CTM, trunc::TruncationStrategy, stop::Stopcrit[, finalize_beginning=true, verbosity=1])
+    run!(::CTM, trunc::TruncationStrategy, stop::Stopcrit[, verbosity=1])
 
 !!! info "verbosity levels"
     - 0: No output

src/schemes/ctm/triangular.jl

@@ -25,7 +25,7 @@ or with a (0,6) tensor (120°, 60°, 0°, 300°, 240°, 180°) where all arrows
 The keyword argument symmetrize makes the tensor C6v symmetric when set to true. If symmetrize = false, it checks the symmetry explicitly.
 
 # Running the algorithm
-    run!(::CTM, trunc::TruncationStrategy, stop::Stopcrit[, finalize_beginning=true, verbosity=1])
+    run!(::CTM, trunc::TruncationStrategy, stop::Stopcrit[, verbosity=1])
 
 !!! info "verbosity levels"
     - 0: No output
@@ -100,7 +100,7 @@ or with a (0,6) tensor (120°, 60°, 0°, 300°, 240°, 180°) where all arrows
 The keyword argument symmetrize makes the tensor C6v symmetric when set to true. If symmetrize = false, it checks the symmetry explicitly.
 
 # Running the algorithm
-    run!(::c6vCTM, trunc::MatrixAlgebraKit.TruncationStrategy, stop::Stopcrit[, finalize_beginning=true, projectors=:twothirds, conditioning=true, verbosity=1])
+    run!(::c6vCTM, trunc::MatrixAlgebraKit.TruncationStrategy, stop::Stopcrit[, projectors=:twothirds, conditioning=true, verbosity=1])
 
 `projectors` can either be :twothirds or :full, determining the type of projectors used in the renormalization step. This is based on https://arxiv.org/abs/2510.04907v1.
 `conditioning` determines whether to condition the second projector construction. This is based on https://doi.org/10.1103/PhysRevB.98.235148.

src/schemes/hotrg.jl

@@ -7,7 +7,7 @@ Higher-Order Tensor Renormalization Group
     $(FUNCTIONNAME)(T)
 
 # Running the algorithm
-    run!(::HOTRG, trunc::TruncationStrategy, stop::Stopcrit[, finalizer=default_Finalizer, finalize_beginning=true, verbosity=1])
+    run!(::HOTRG, trunc::TruncationStrategy, stop::Stopcrit[, finalizer=default_Finalizer, verbosity=1])
 
 Each step rescales the lattice by a (linear) factor of 2
 

src/schemes/hotrg3d.jl

@@ -7,7 +7,7 @@ $(TYPEDEF)
     $(FUNCTIONNAME)(T)
 
 # Running the algorithm
-    run!(::HOTRG_3D, trunc::TruncationStrategy, stop::Stopcrit[, finalizer=default_Finalizer, finalize_beginning=true, verbosity=1])
+    run!(::HOTRG_3D, trunc::TruncationStrategy, stop::Stopcrit[, finalizer=default_Finalizer, verbosity=1])
 
 Each step rescales the lattice by a (linear) factor of 2
 

src/schemes/impurityhotrg.jl

@@ -7,7 +7,7 @@ Single impurity method for Higher-Order Tensor Renormalization Group (for 2nd or
     $(FUNCTIONNAME)(T, T_imp_order1_1, T_imp_order1_2, T_imp_order2)
 
 # Running the algorithm
-    run!(::ImpurityHOTRG, trunc::TruncationStrategy, stop::Stopcrit[, finalizer=ImpurityHOTRG_Finalizer, finalize_beginning=true, verbosity=1])
+    run!(::ImpurityHOTRG, trunc::TruncationStrategy, stop::Stopcrit[, finalizer=ImpurityHOTRG_Finalizer, verbosity=1])
 
 Each step rescales the lattice by a (linear) factor of 2
 

src/schemes/impuritytrg.jl

@@ -7,7 +7,7 @@ Impurity method for Tensor Renormalization Group
     $(FUNCTIONNAME)(T, T_imp1, T_imp2, T_imp3, T_imp4)
 
 # Running the algorithm
-    run!(::ImpurityTRG, trunc::TruncationStrategy, stop::Stopcrit[, finalizer=ImpurityTRG_Finalizer, finalize_beginning=true, verbosity=1])
+    run!(::ImpurityTRG, trunc::TruncationStrategy, stop::Stopcrit[, finalizer=ImpurityTRG_Finalizer, verbosity=1])
 
 Each step rescales the lattice by a (linear) factor of √2
 

src/schemes/looptnr.jl

@@ -10,7 +10,7 @@ Loop Optimization for Tensor Network Renormalization
 
 # Running the algorithm
     run!(::LoopTNR, trunc::TruncationStrategy, criterion::stopcrit, [parameters::LoopParameters], [finalizer::Finalizer];
-        [entanglement_criterion::stopcrit, finalize_beginning=true, verbosity=1])
+        [entanglement_criterion::stopcrit, verbosity=1])
 
 # LoopParameters
 See also: [`LoopParameters`](@ref)
@@ -490,17 +490,12 @@ function run!(
         criterion::stopcrit, loop_condition::LoopParameters,
         finalizer::Finalizer{E};
         entanglement_criterion = default_entanglement_criterion,
-        finalize_beginning = true,
         verbosity = 1
     ) where {E}
     data = Vector{E}()
 
     LoggingExtras.withlevel(; verbosity) do
         @infov 1 "Starting simulation\n $(scheme)\n"
-        if finalize_beginning
-            push!(data, finalizer.f!(scheme))
-        end
-
         steps = 0
         crit = true
 

src/schemes/renormalizer.jl

@@ -0,0 +1,77 @@
+abstract type TNRAlgorithm end
+
+"""
+$(TYPEDEF)
+
+Iterator that performs RG coarse-graining steps on network tensors.
+
+# Fields
+$(TYPEDFIELDS)
+
+# Iterator
+In a for-loop, each iteration yields `(state, data)` after each RG step.
+Stops when the algorithm's stopping criterion is met.
+"""
+mutable struct Renormalizer{A <: TNRAlgorithm, S, D}
+    "Algorithm configuration (truncation, maxiter, etc.)"
+    alg::A
+    "Algorithm-specific state holding all involved tensors"
+    state::S
+    "Accumulated per-step data"
+    data::Vector{D}
+    "Number of RG steps performed so far"
+    step::Int
+end
+
+Renormalizer(alg::A, state::S, data::Vector{D}) where {A, S, D} = Renormalizer{A, S, D}(alg, state, data, 0)
+Renormalizer(alg::A, state::S, data::Vector{D}, step::Int) where {A, S, D} = Renormalizer{A, S, D}(alg, state, data, step)
+
+function Base.iterate(r::Renormalizer)
+    return iterate(r, 0)
+end
+
+function Base.iterate(r::Renormalizer, n::Int)
+    r.alg.stop(n, r.data) || return nothing
+    step!(r.state, r.alg)
+    val = finalize!(r.state)
+    push!(r.data, val)
+    r.step = n + 1
+    return ((r.state, r.data), n + 1)
+end
+
+function Base.show(io::IO, r::Renormalizer)
+    println(io, "Renormalizer")
+    println(io, "  * algorithm: $(nameof(typeof(r.alg)))")
+    println(io, "  * state: $(nameof(typeof(r.state)))")
+    println(io, "  * step: $(r.step)")
+    println(io, "  * data: $(length(r.data)) entries")
+    return nothing
+end
+
+"""
+    rgstep!(r::Renormalizer)
+
+Perform one RG coarse-graining step. Wraps `Base.iterate`.
+Throws an error if the stopping criterion has already been met.
+"""
+function rgstep!(r::Renormalizer)
+    r.alg.stop(r.step, r.data) || error("stop criterion reached")
+    iterate(r, r.step)
+    return r.state, r.data
+end
+
+"""
+    run!(r::Renormalizer; verbosity=1)
+
+Run the RG flow to completion. Returns `(final_state, data)`.
+"""
+function run!(r::Renormalizer; verbosity = 1)
+    LoggingExtras.withlevel(; verbosity) do
+        @infov 1 "Starting simulation\n $(r.state)\n"
+        t = @elapsed for (_, data) in r
+            @infov 2 "Step $(r.step), data[end]: $(data[end])"
+        end
+        @infov 1 "Simulation finished\n $(stopping_info(r.alg.stop, r.step, r.data))\n Elapsed time: $(t)s\n Iterations: $(r.step)"
+    end
+    return r.state, r.data
+end

src/schemes/symmetric_looptnr.jl

@@ -9,7 +9,7 @@ c4 & inversion symmetric Loop Optimization for Tensor Network Renormalization
 
 # Running the algorithm
     run!(::SLoopTNR, trscheme::TruncationStrategy,
-              criterion::TNRKit.stopcrit[, finalizer=default_Finalizer, finalize_beginning=true, oneloop=true,
+              criterion::TNRKit.stopcrit[, finalizer=default_Finalizer, oneloop=true,
               verbosity=1])
 
 `oneloop=true` will use disentangled tensors as a starting guess for the optimization.
@@ -194,17 +194,13 @@ end
 
 function run!(
         scheme::SLoopTNR, trscheme::TruncationStrategy,
-        criterion::TNRKit.stopcrit; finalizer = default_Finalizer, finalize_beginning = true, oneloop = true,
+        criterion::TNRKit.stopcrit; finalizer = default_Finalizer, oneloop = true,
         verbosity = 1
     )
     data = output_type(finalizer)[]
 
     LoggingExtras.withlevel(; verbosity) do
         @infov 1 "Starting simulation\n $(scheme)\n"
-
-        if finalize_beginning
-            push!(data, finalizer.f!(scheme))
-        end
         steps = 0
         crit = true
 

src/schemes/tnrscheme.jl

@@ -1,5 +1,4 @@
 # Extra code to make output type available
-function step! end
 function finalize! end
 
 """
@@ -10,7 +9,7 @@ Finalizer for TNR schemes
 # Constructors
     Finalizer(f!::Function, E::Type)
 
-A Finalizer holds a function `f!` that is to be applied to a TNR scheme after each step of the algorithm (and at the beginning if specified by `run!(;finalize_beginning=true)`, which is the default behavior).
+A Finalizer holds a function `f!` that is to be applied to a TNR scheme after each step of the algorithm.
 The type parameter `E` indicates the output type of `f!`, which is used to create an array of the correct type to hold the outputs.
 """
 struct Finalizer{E} # E is the output type of f
@@ -30,16 +29,14 @@ const ImpurityHOTRG_Finalizer = Finalizer(finalize!, Tuple{Float64, Float64, Flo
 # Finalization functions for the various TNR schemes
 abstract type TNRScheme{E, S} end
 
-function run!(scheme::TNRScheme, trscheme::TruncationStrategy, criterion::stopcrit, finalizer::Finalizer{E}; finalize_beginning = true, verbosity = 1) where {E}
+# TODO: This should be eventually replaced by `run!(renorm::Renormalizer; verbosity = 1)`.
+# Finalizers will be dropped at the end.
+function run!(scheme::TNRScheme, trscheme::TruncationStrategy, criterion::stopcrit, finalizer::Finalizer{E}; verbosity = 1) where {E}
     data = Vector{E}()
 
     LoggingExtras.withlevel(; verbosity) do
 
         @infov 1 "Starting simulation\n $(scheme)\n"
-        if finalize_beginning
-            push!(data, finalizer.f!(scheme))
-        end
-
         steps = 0
         crit = true