Add model docstrings (#83)

* add `classical_ising` docstring

* update docstring

* fix docstring formatting

* update `free_energy` kwarg name and add extra ising docstrings

* update docstrings

* add Potts model docstrings

* remove redundant sentence

* add ref to potts critical temperature

* add sixvertex docstring

* add clock model dosctring

* add gross_neveu_start docstring

* update sixvertex docstring

* format bib file

* update citation names

* fix failing tests

* add references in models on homepage

* fix spelling mistake in `classical_potts_symmetric`

* add documentation comment bot

* make the bot use proper punctuation

Author: VictorVanthilt

.github/workflows/PR_comment.yml

@@ -0,0 +1,17 @@
+name: Docs preview comment
+on:
+  pull_request:
+    types: [labeled]
+
+permissions:
+  pull-requests: write
+jobs:
+  pr_comment:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Create PR comment
+        if: github.event_name == 'pull_request' && github.event.label.name == 'documentation'
+        uses: thollander/actions-comment-pull-request@v3
+        with:
+          message: 'After the build completes, the updated documentation will be available [here](https://victorvanthilt.github.io/TNRKit.jl/previews/PR${{ github.event.number }}/).'
+          comment-tag: 'preview-doc'

docs/src/assets/tnrkit.bib

@@ -1,88 +1,88 @@
+@article{adachiAnisotropicTensorRenormalization2020,
+  title     = {Anisotropic Tensor Renormalization Group},
+  author    = {Adachi, Daiki and Okubo, Tsuyoshi and Todo, Synge},
+  year      = {2020},
+  month     = aug,
+  journal   = {Physical Review B},
+  volume    = {102},
+  number    = {5},
+  publisher = {American Physical Society},
+  doi       = {10.1103/PhysRevB.102.054432}
+}
+
+@article{adachiBondweightedTensorRenormalization2022,
+  title     = {Bond-Weighted Tensor Renormalization Group},
+  author    = {Adachi, Daiki and Okubo, Tsuyoshi and Todo, Synge},
+  year      = {2022},
+  month     = feb,
+  journal   = {Physical Review B},
+  volume    = {105},
+  number    = {6},
+  publisher = {American Physical Society},
+  doi       = {10.1103/PhysRevB.105.L060402},
+  keywords  = {TNR Algorithm}
+}
 
-@article{adachi_bond-weighted_2022,
-	title = {Bond-weighted tensor renormalization group},
-	volume = {105},
-	url = {https://link.aps.org/doi/10.1103/PhysRevB.105.L060402},
-	doi = {10.1103/PhysRevB.105.L060402},
-	abstract = {We propose an improved tensor renormalization-group (TRG) algorithm, the bond-weighted TRG (BTRG). In BTRG, we generalize the conventional TRG by introducing bond weights on the edges of the tensor network. We show that BTRG outperforms the conventional TRG and the higher-order tensor renormalization group with the same bond dimension, whereas its computation time is almost the same as that of TRG. Furthermore, BTRG can have nontrivial fixed-point tensors at an optimal hyperparameter. We demonstrate that the singular value spectrum obtained by BTRG is invariant under the renormalization procedure in the case of the two-dimensional Ising model at the critical point. This property indicates that BTRG performs the tensor contraction with high accuracy whereas keeping the scale-invariant structure of tensors.},
-	number = {6},
-	urldate = {2024-11-18},
-	journal = {Physical Review B},
-	author = {Adachi, Daiki and Okubo, Tsuyoshi and Todo, Synge},
-	month = feb,
-	year = {2022},
-	note = {Publisher: American Physical Society},
-	keywords = {TNR Algorithm},
-	pages = {L060402},
-	file = {APS Snapshot:/home/vvthilt/Zotero/storage/IXUQZVH3/PhysRevB.105.html:text/html;Full Text PDF:/home/vvthilt/Zotero/storage/BA59K9FQ/Adachi et al. - 2022 - Bond-weighted tensor renormalization group.pdf:application/pdf},
+@article{akiyamaTensorRenormalizationGroup2024a,
+  title     = {Tensor Renormalization Group for Fermions},
+  author    = {Akiyama, Shinichiro and Meurice, Yannick and Sakai, Ryo},
+  year      = {2024},
+  month     = may,
+  journal   = {Journal of Physics: Condensed Matter},
+  volume    = {36},
+  number    = {34},
+  publisher = {IOP Publishing},
+  issn      = {0953-8984},
+  doi       = {10.1088/1361-648X/ad4760},
+  langid    = {english}
 }
 
-@article{yang_loop_2017,
-	title = {Loop {Optimization} for {Tensor} {Network} {Renormalization}},
-	volume = {118},
-	url = {https://link.aps.org/doi/10.1103/PhysRevLett.118.110504},
-	doi = {10.1103/PhysRevLett.118.110504},
-	abstract = {We introduce a tensor renormalization group scheme for coarse graining a two-dimensional tensor network that can be successfully applied to both classical and quantum systems on and off criticality. The key innovation in our scheme is to deform a 2D tensor network into small loops and then optimize the tensors on each loop. In this way, we remove short-range entanglement at each iteration step and significantly improve the accuracy and stability of the renormalization flow. We demonstrate our algorithm in the classical Ising model and a frustrated 2D quantum model.},
-	number = {11},
-	urldate = {2024-12-03},
-	journal = {Physical Review Letters},
-	author = {Yang, Shuo and Gu, Zheng-Cheng and Wen, Xiao-Gang},
-	month = mar,
-	year = {2017},
-	note = {Publisher: American Physical Society},
-	keywords = {TNR Algorithm},
-	pages = {110504},
-	file = {APS Snapshot:/home/vvthilt/Zotero/storage/DG7Q5V7F/PhysRevLett.118.html:text/html;Full Text PDF:/home/vvthilt/Zotero/storage/7L5XPMGF/Yang et al. - 2017 - Loop Optimization for Tensor Network Renormalization.pdf:application/pdf;Loop TNR supplementary material:/home/vvthilt/Zotero/storage/IL5NTDBS/Yang et al. - 2017 - Loop Optimization for Tensor Network Renormalization.pdf:application/pdf},
+@article{levinTensorRenormalizationGroup2007,
+  title     = {Tensor {{Renormalization Group Approach}} to {{Two-Dimensional Classical Lattice Models}}},
+  author    = {Levin, Michael and Nave, Cody P.},
+  year      = {2007},
+  month     = sep,
+  journal   = {Physical Review Letters},
+  volume    = {99},
+  number    = {12},
+  publisher = {American Physical Society},
+  doi       = {10.1103/PhysRevLett.99.120601},
+  keywords  = {TNR Algorithm}
 }
 
-@article{levin_tensor_2007,
-	title = {Tensor {Renormalization} {Group} {Approach} to {Two}-{Dimensional} {Classical} {Lattice} {Models}},
-	volume = {99},
-	url = {https://link.aps.org/doi/10.1103/PhysRevLett.99.120601},
-	doi = {10.1103/PhysRevLett.99.120601},
-	abstract = {We describe a simple real space renormalization group technique for two-dimensional classical lattice models. The approach is similar in spirit to block spin methods, but at the same time it is fundamentally based on the theory of quantum entanglement. In this sense, the technique can be thought of as a classical analogue of the density matrix renormalization group method. We demonstrate the method—which we call the tensor renormalization group method—by computing the magnetization of the triangular lattice Ising model.},
-	number = {12},
-	urldate = {2025-02-10},
-	journal = {Physical Review Letters},
-	author = {Levin, Michael and Nave, Cody P.},
-	month = sep,
-	year = {2007},
-	note = {Publisher: American Physical Society},
-	keywords = {TNR Algorithm},
-	pages = {120601},
-	file = {APS Snapshot:/home/vvthilt/Zotero/storage/IZLKUB5B/PhysRevLett.99.html:text/html;Full Text PDF:/home/vvthilt/Zotero/storage/AYJHLV3C/Levin and Nave - 2007 - Tensor Renormalization Group Approach to Two-Dimensional Classical Lattice Models.pdf:application/pdf},
+@article{moritaGlobalOptimizationTensor2021,
+  title     = {Global Optimization of Tensor Renormalization Group Using the Corner Transfer Matrix},
+  author    = {Morita, Satoshi and Kawashima, Naoki},
+  year      = {2021},
+  month     = jan,
+  journal   = {Physical Review B},
+  volume    = {103},
+  number    = {4},
+  publisher = {American Physical Society},
+  doi       = {10.1103/PhysRevB.103.045131}
 }
 
-@article{adachi_anisotropic_2020,
-	title = {Anisotropic tensor renormalization group},
-	volume = {102},
-	url = {https://link.aps.org/doi/10.1103/PhysRevB.102.054432},
-	doi = {10.1103/PhysRevB.102.054432},
-	abstract = {We propose a different tensor renormalization group algorithm, anisotropic tensor renormalization group (ATRG), for lattice models in arbitrary dimensions. The proposed method shares the same versatility with the higher-order tensor renormalization group (HOTRG) algorithm, i.e., it preserves the lattice topology after the renormalization. In comparison with HOTRG, both the computation cost and the memory footprint of our method are drastically reduced, especially in higher dimensions, by renormalizing tensors in an anisotropic way after the singular value decomposition. We demonstrate the ability of ATRG for the square lattice and the simple cubic lattice Ising models. Although the accuracy of the present method degrades when compared with HOTRG of the same bond dimension, the accuracy with fixed computation time is improved greatly due to the drastic reduction of the computation cost.},
-	number = {5},
-	urldate = {2025-03-04},
-	journal = {Physical Review B},
-	author = {Adachi, Daiki and Okubo, Tsuyoshi and Todo, Synge},
-	month = aug,
-	year = {2020},
-	note = {Publisher: American Physical Society},
-	pages = {054432},
-	file = {APS Snapshot:/home/vvthilt/Zotero/storage/E6A7899K/PhysRevB.102.html:text/html;Full Text PDF:/home/vvthilt/Zotero/storage/H4K8SDX8/Adachi et al. - 2020 - Anisotropic tensor renormalization group.pdf:application/pdf},
+@article{xieCoarsegrainingRenormalizationHigherorder2012,
+  title     = {Coarse-Graining Renormalization by Higher-Order Singular Value Decomposition},
+  author    = {Xie, Z. Y. and Chen, J. and Qin, M. P. and Zhu, J. W. and Yang, L. P. and Xiang, T.},
+  year      = {2012},
+  month     = jul,
+  journal   = {Physical Review B},
+  volume    = {86},
+  number    = {4},
+  publisher = {American Physical Society},
+  doi       = {10.1103/PhysRevB.86.045139}
 }
 
-@article{xie_coarse-graining_2012,
-	title = {Coarse-graining renormalization by higher-order singular value decomposition},
-	volume = {86},
-	url = {https://link.aps.org/doi/10.1103/PhysRevB.86.045139},
-	doi = {10.1103/PhysRevB.86.045139},
-	abstract = {We propose a novel coarse-graining tensor renormalization group method based on the higher-order singular value decomposition. This method provides an accurate but low computational cost technique for studying both classical and quantum lattice models in two or three dimensions. We have demonstrated this method using the Ising model on the square and cubic lattices. By keeping up to 16 bond basis states, we obtain by far the most accurate numerical renormalization group results for the three-dimensional Ising model. We have also applied the method to study the ground state as well as finite temperature properties for the two-dimensional quantum transverse Ising model and obtain the results which are consistent with published data.},
-	number = {4},
-	urldate = {2025-05-24},
-	journal = {Physical Review B},
-	author = {Xie, Z. Y. and Chen, J. and Qin, M. P. and Zhu, J. W. and Yang, L. P. and Xiang, T.},
-	month = jul,
-	year = {2012},
-	note = {Publisher: American Physical Society},
-	pages = {045139},
-	file = {APS Snapshot:/home/vvthilt/Zotero/storage/G2NF7VSD/PhysRevB.86.html:text/html;Preprint PDF:/home/vvthilt/Zotero/storage/V3CIZHIS/Xie et al. - 2012 - Coarse-graining renormalization by higher-order singular value decomposition.pdf:application/pdf},
+@article{yangLoopOptimizationTensor2017,
+  title     = {Loop {{Optimization}} for {{Tensor Network Renormalization}}},
+  author    = {Yang, Shuo and Gu, Zheng-Cheng and Wen, Xiao-Gang},
+  year      = {2017},
+  month     = mar,
+  journal   = {Physical Review Letters},
+  volume    = {118},
+  number    = {11},
+  publisher = {American Physical Society},
+  doi       = {10.1103/PhysRevLett.118.110504},
+  keywords  = {TNR Algorithm}
 }

docs/src/index.md

@@ -71,10 +71,10 @@ to choose the verbosity level, simply use `run!(...; verbosity=n)`. The default
 
 ## Included Models
 TNRKit includes several common models out of the box.
-- Ising model: `classical_ising(β; h=0)` and `classical_ising_symmetric(β)`, which has a Z2 grading on each leg.
-- Potts model: `classical_potts(q, β)` and `classical_potts_symetric(q, β)`, which has a Zq grading on each leg.
-- Six Vertex model: `sixvertex(scalartype, spacetype; a=1.0, b=1.0, c=1.0)`
-- Clock model: `classical_clock`
+- Ising model: [`classical_ising`](@ref) and [`classical_ising_symmetric`](@ref), which has a Z2 grading on each leg.
+- Potts model: [`classical_potts`](@ref) and [`classical_potts_symmetric`](@ref), which has a Zq grading on each leg.
+- Six Vertex model: [`sixvertex`](@ref)
+- Clock model: [`classical_clock`](@ref)
 If you want to implement your own model you must respect the leg-convention assumed by all TNRKit schemes.
 
 ## Leg-convention

src/models/clock.jl

@@ -1,3 +1,9 @@
+"""
+$(SIGNATURES)
+
+Constructs the partition function tensor for the classical clock model with `q` states
+and a given inverse temperature `β`.
+"""
 function classical_clock(q::Int64, β::Float64)
     V = ℂ^q
     A_clock = TensorMap(zeros, V ⊗ V ← V ⊗ V)

src/models/gross-neveu.jl

@@ -46,6 +46,15 @@ function gross_neveu_8_leg_tensor(μ::Number, m::Number, g::Number)
     return TensorMap(T, V ⊗ V ⊗ V ⊗ V ← V ⊗ V ⊗ V ⊗ V)
 end
 
+
+"""
+$(SIGNATURES)
+
+Constructs the partition function tensor for the Gross-Neveu model with given parameters `μ`, `m`, and `g`.
+
+### References
+* [Akiyama et. al. J. Phys.: Condens. Matter 36 (2024) 343002](@cite akiyamaTensorRenormalizationGroup2024a)
+"""
 function gross_neveu_start(μ::Number, m::Number, g::Number)
     T_unfused = gross_neveu_8_leg_tensor(μ, m, g)
     V = Vect[FermionParity](0 => 1, 1 => 1)
@@ -55,6 +64,5 @@ function gross_neveu_start(μ::Number, m::Number, g::Number)
     @tensor T_fused[-1 -2; -3 -4] := T_unfused[1 2 3 4; 5 6 7 8] * U[-1; 1 2] * U[-2; 3 4] *
         Udg[5 6; -3] * Udg[7 8; -4]
 
-    # restore the TNRKit.jl convention
     return T_fused
 end

src/models/ising.jl

@@ -4,6 +4,25 @@ const ising_cft_exact = [
     3, 3, 3,
     25 / 8, 25 / 8, 25 / 8, 25 / 8, 25 / 8, 25 / 8,
 ]
+const ising_βc_3D = 1.0 / 4.51152469
+
+"""
+$(SIGNATURES)
+
+Constructs the partition function tensor for a 2D square lattice
+for the classical Ising model with a given inverse temperature `β` and external magnetic field `h`.
+
+### Examples
+```julia
+    classical_ising() # Default inverse temperature is `ising_βc`
+    classical_ising(0.5; h = 1.0) # Custom inverse temperature and magnetic field.
+```
+!!! info
+    When calculating the free energy with `free_energy()`, set the `initial_size` keyword argument to `2.0`.
+    The initial lattice holds 2 spins.
+
+See also: [`classical_ising_symmetric`](@ref), [`classical_ising_symmetric_3D`](@ref), [`classical_ising_3D`](@ref).
+"""
 function classical_ising(β::Number; h = 0)
     function σ(i::Int64)
         return 2i - 3
@@ -23,6 +42,22 @@ function classical_ising(β::Number; h = 0)
 end
 classical_ising() = classical_ising(ising_βc)
 
+"""
+$(SIGNATURES)
+
+Constructs the partition function tensor for a symmetric 2D square lattice
+for the classical Ising model with a given inverse temperature `β`.
+
+This tensor has explicit ℤ₂ symmetry on each of it spaces.
+
+### Examples
+```julia
+    classical_ising_symmetric() # Default inverse temperature is `ising_βc`
+    classical_ising_symmetric(0.5) # Custom inverse temperature.
+```
+
+See also: [`classical_ising`](@ref), [`classical_ising_symmetric_3D`](@ref), [`classical_ising_3D`](@ref).
+"""
 function classical_ising_symmetric(β)
     x = cosh(β)
     y = sinh(β)
@@ -38,6 +73,22 @@ classical_ising_symmetric() = classical_ising_symmetric(ising_βc)
 
 const f_onsager::BigFloat = -2.10965114460820745966777928351108478082549327543540531781696107967700291143188081390114126499095041781
 
+"""
+$(SIGNATURES)
+
+Constructs the partition function tensor for a symmetric 3D cubic lattice
+for the classical Ising model with a given inverse temperature `β`.
+
+This tensor has explicit ℤ₂ symmetry on each of its spaces.
+
+### Examples
+```julia
+    classical_ising_symmetric_3D() # Default inverse temperature is `ising_βc_3D`
+    classical_ising_symmetric_3D(0.5) # Custom inverse temperature.
+```
+
+See also:  [`classical_ising_3D`](@ref), [`classical_ising`](@ref), [`classical_ising_symmetric`](@ref).
+"""
 function classical_ising_symmetric_3D(β)
     x = cosh(β)
     y = sinh(β)
@@ -55,7 +106,22 @@ function classical_ising_symmetric_3D(β)
 
     return permute(T, ((1, 4), (5, 6, 2, 3)))
 end
+classical_ising_symmetric_3D() = classical_ising_symmetric_3D(ising_βc_3D)
+
+"""
+$(SIGNATURES)
 
+Constructs the partition function tensor for a 3D cubic lattice
+for the classical Ising model with a given inverse temperature `β` and coupling constant `J` (by default J = `1.0`).
+    
+### Examples
+```julia
+    classical_ising_3D() # Default inverse temperature is `ising_βc_3D`, coupling constant is `J = 1.0`.
+    classical_ising_3D(0.5; J = 1.0) # Custom inverse temperature and coupling constant.
+```
+
+See also: [`classical_ising_symmetric_3D`](@ref), [`classical_ising`](@ref), [`classical_ising_symmetric`](@ref).
+"""
 function classical_ising_3D(β; J = 1.0)
     K = β * J
 
@@ -75,7 +141,4 @@ function classical_ising_3D(β; J = 1.0)
 
     return TensorMap(o, TMS)
 end
-const ising_βc_3D = 1.0 / 4.51152469
-
-classical_ising_symmetric_3D() = classical_ising_symmetric_3D(ising_βc_3D)
 classical_ising_3D() = classical_ising_3D(ising_βc_3D)

src/models/potts.jl

@@ -1,5 +1,26 @@
+"""
+$(SIGNATURES)
+
+returns the inverse critical temperature for the classical q-state Potts model on a 2D square lattice.
+
+See also: [`classical_potts`](@ref), [`classical_potts_symmetric`](@ref).
+"""
 potts_βc(q) = log(1.0 + sqrt(q))
 
+"""
+$(SIGNATURES)
+
+Constructs the partition function tensor for the classical Potts model with `q` states
+and a given inverse temperature `β`.
+
+### Examples
+```julia
+    classical_potts(3) # Default inverse temperature is `potts_βc(3)`
+    classical_potts(3, 0.5) # Custom inverse temperature.
+```
+
+See also: [`classical_potts_symmetric`](@ref), [`potts_βc`](@ref).
+"""
 function classical_potts(q::Int, β::Float64)
     V = ℂ^q
     A_potts = TensorMap(zeros, V ⊗ V ← V ⊗ V)
@@ -34,6 +55,22 @@ function weyl_heisenberg_matrices(Q::Int, elt = ComplexF64)
     return U, V, W / sqrt(Q)
 end
 
+"""
+$(SIGNATURES)
+
+Constructs the partition function tensor for a symmetric Potts model with `q` states
+and a given inverse temperature `β`.
+
+This tensor has explicit ℤq symmetry on each of its spaces.
+
+### Examples
+```julia
+    classical_potts_symmetric(3) # Default inverse temperature is `potts_βc(3)`
+    classical_potts_symmetric(3, 0.5) # Custom inverse temperature.
+```
+
+See also: [`classical_potts`](@ref), [`potts_βc`](@ref).
+"""
 function classical_potts_symmetric(q::Int64, β::Float64)
     V = ℂ^q
     A_potts = TensorMap(zeros, Float64, V ⊗ V ← V ⊗ V)