Various docs fixes and improvements (#409)

Author: lkdvos

.gitignore

@@ -5,7 +5,7 @@
 *-old
 __pycache__
 .ipynb*
-Manifest.toml
+*Manifest.toml
 .vscode
 experimental
 refs

Project.toml

@@ -36,7 +36,7 @@ TensorKitFiniteDifferencesExt = "FiniteDifferences"
 TensorKitMooncakeExt = "Mooncake"
 
 [workspace]
-projects = ["test"]
+projects = ["test", "docs"]
 
 [compat]
 Adapt = "4"

docs/Project.toml

@@ -1,3 +1,5 @@
+name = "TensorKitDocs"
+
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterInterLinks = "d12716ef-a0f6-4df4-a9f1-a5a34e75c656"
@@ -8,11 +10,12 @@ TensorKit = "07d1fe3e-3e46-537d-9eac-e9e13d0d4cec"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 WignerSymbols = "9f57e263-0b3d-5e2e-b1be-24f2bb48858b"
 
+[sources]
+TensorKit = {path = ".."}
+
 [compat]
 Documenter = "1"
 DocumenterInterLinks = "1"
-LinearAlgebra = "1"
-Random = "1"
 SUNRepresentations = "0.3"
 Test = "1"
 WignerSymbols = "1,2"

docs/make.jl

@@ -2,15 +2,14 @@
 if Base.active_project() != joinpath(@__DIR__, "Project.toml")
     using Pkg
     Pkg.activate(@__DIR__)
-    Pkg.develop(PackageSpec(; path = joinpath(@__DIR__, "..")))
     Pkg.resolve()
     Pkg.instantiate()
 end
 
 using Documenter
 using Random
 using TensorKit
-using TensorKit: FusionTreePair, Index2Tuple
+using TensorKit: FusionTreePair, FusionTreeBlock, Index2Tuple
 using TensorKit.TensorKitSectors
 using TensorKit.MatrixAlgebraKit
 using DocumenterInterLinks

docs/src/appendix/symmetric_tutorial.md

@@ -2,7 +2,7 @@
 
 In this tutorial, we will demonstrate how to construct specific [`TensorMap`](@ref)s which are relevant to some common physical systems, with an increasing degree of complexity.
 We will assume the reader is somewhat familiar with [the notion of a *tensor map*](@ref ss_whatistensor) and has a rough idea of [what it means for a tensor map to be *symmetric*](@ref ss_symmetries).
-In going through these examples we aim to provide a relatively gentle introduction to the meaning of [symmetry sectors](@ref ss_sectors) and [vector spaces](@ref ss_rep) within the context of TensorKit.jl, [how to initialize a `TensorMap` over a given vector space](@ref ss_tensor_construction) and finally how to manually set the data of a [symmetric `TensorMap`](@ref ss_tutorial_symmetries).
+In going through these examples we aim to provide a relatively gentle introduction to the meaning of [symmetry sectors](@ref ss_sectors) and [vector spaces](@ref ss_representationtheory) within the context of TensorKit.jl, [how to initialize a `TensorMap` over a given vector space](@ref ss_tensor_construction) and finally how to manually set the data of a [symmetric `TensorMap`](@ref ss_tutorial_symmetries).
 We will keep our discussion as intuitive and simple as possible, only adding as many technical details as strictly necessary to understand each example.
 When considering a different physical system of interest, you should then be able to adapt these recipes and the intuition behind them to your specific problem at hand.
 

docs/src/lib/sectors.md

@@ -97,7 +97,7 @@ frobenius_schur_indicator
 twist(::Sector)
 Base.isreal(::Type{<:Sector})
 TensorKitSectors.sectorscalartype
-deligneproduct(::Sector, ::Sector)
+deligneproduct(::Any, ::Any, ::Any, ::Vararg{Any})
 ```
 
 We have also the following methods that are specific to certain types of sectors and serve as accessors to their fields:

docs/src/lib/tensors.md

@@ -55,6 +55,7 @@ Random.randexp(::Type, V::TensorMapSpace)
 as well as a `similar` constructor
 ```@docs
 Base.similar(::AbstractTensorMap, args...)
+similar_diagonal(::AbstractTensorMap, args...)
 ```
 
 ### Specific constructors

docs/src/man/gradedspaces.md

@@ -102,7 +102,7 @@ With [`hassector(V, a)`](@ref) one can check if `V` contains a sector `a` with `
 Finally, `dim(V)` returns the total dimension of the space `V`, i.e. ``∑_a n_a d_a`` or thus `dim(V) = sum(dim(V, a) * dim(a) for a in sectors(V))`.
 Note that a representation space `V` has certain sectors `a` with dimensions `n_a`, then its dual `V'` will report to have sectors `dual(a)`, and `dim(V', dual(a)) == n_a`.
 There is a subtelty regarding the difference between the dual of a representation space ``R_a^*``, on which the conjugate representation acts, and the representation space of the irrep `dual(a) == conj(a)` that is isomorphic to the conjugate representation, i.e. ``R_{\overline{a}} ≂ R_a^*`` but they are not equal.
-We return to this in the section on [fusion trees](@ref ss_fusiontrees).
+We return to this in the section on [fusion trees](@ref sss_fusiontrees).
 This is true also in more general fusion categories beyond the representation categories of groups.
 
 Other methods for `ElementarySpace`, such as [`dual`](@ref), [`fuse`](@ref) and [`flip`](@ref) also work.
@@ -118,7 +118,7 @@ The function [`dims(W, as)`](@ref) returns the corresponding tuple with degenera
 [`hassector(W, as)`](@ref) is equivalent to `dim(W, as) > 0`.
 Finally, there is the function [`blocksectors(W)`](@ref) which returns a list (of type `Vector`) with all possible "block sectors" or total/coupled sectors that can result from fusing the individual uncoupled sectors in `W`.
 Correspondingly, [`blockdim(W, a)`](@ref) counts the total degeneracy dimension of the coupled sector `a` in `W`.
-The machinery for computing this is the topic of the next section on [Fusion trees](@ref ss_fusiontrees), but first, it's time for some examples.
+The machinery for computing this is the topic of the next section on [Fusion trees](@ref sss_fusiontrees), but first, it's time for some examples.
 
 ## Examples
 

docs/src/man/sectors.md

@@ -92,7 +92,7 @@ This means the following methods should be implemented for a new sector type `I
 
 *   `Base.iterate(::Type{SectorValues{I}} [, state])` should implement the iterator interface so as to enable iterating over all values of the sector `I` according to the canonical order defined by `isless`.
 *   `Base.IteratorSize(::Type{SectorValues{I}})` should return `HasLength()` if the number of different values of sector `I` is finite and rather small, and `SizeUnknown()` or `IsInfinite()` otherwise.
-    This is used to encode the degeneracies of the different sectors in a `GradedSpace` object efficiently, as discussed in the next section on [Graded spaces](@ref ss_rep).
+    This is used to encode the degeneracies of the different sectors in a `GradedSpace` object efficiently, as discussed in the next section on [Graded spaces](@ref ss_representationtheory).
 *   If `IteratorSize(::Type{SectorValues{I}}) == HasLength()`, then `Base.length(::Type{SectorValues{I}})` should return the number of different values of sector `I`.
 
 Furthermore, the standard definitions `Base.IteratorEltype(::Type{SectorValues{I}}) = HasEltype()` and `Base.eltype(::Type{SectorValues{I}}) = I` are provided by default in TensorKitSectors.jl.
@@ -330,7 +330,7 @@ The storage benefits for small `N` are not only due to a smaller integer type in
 Base.IteratorSize(::Type{SectorValues{<:ZNIrrep}}) = HasLength()
 Base.IteratorSize(::Type{SectorValues{<:LargeZNIrrep}}) = SizeUnknown()
 ```
-As a result, the `GradedSpace` implementation (see next section on [Graded spaces](@ref ss_rep)) to store general direct sum objects ``V = ⨁_a ℂ^{n_a} ⊗ R_{a}`` will use a very different internal representation for those two cases.
+As a result, the `GradedSpace` implementation (see next section on [Graded spaces](@ref ss_representationtheory)) to store general direct sum objects ``V = ⨁_a ℂ^{n_a} ⊗ R_{a}`` will use a very different internal representation for those two cases.
 
 We furthermore define some aliases for the first (and most commonly used `ℤ{N}` irreps)
 ```julia

docs/src/man/spaces.md

@@ -142,7 +142,7 @@ InnerProductStyle(ℂ^5)
     When creating tensors with indices in `ℝ^n` that have complex data, a one-time warning will be printed, but most operations should continue to work nonetheless.
 
 One more important concrete implementation of `ElementarySpace` with a `EuclideanInnerProduct()` is the [`GradedSpace`](@ref) type, which is used to represent a graded complex vector space, where the grading is provided by the irreducible representations of a group, or more generally, the simple objects of a unitary fusion category.
-We refer to the subsection on [graded spaces](@ref ss_rep) on the [next page](@ref s_sectorsrepfusion) for further information about `GradedSpace`.
+We refer to the subsection on [graded spaces](@ref ss_representationtheory) on the [next page](@ref s_sectorsrepfusion) for further information about `GradedSpace`.
 
 ## Operations with elementary spaces
 
@@ -176,7 +176,7 @@ A second type of operation with elementary spaces is the function [`flip(V::Elem
 `flip(V)` is different from `dual(V)` in the case of [`GradedSpace`](@ref).
 It is useful to flip a tensor index from a ket to a bra (or vice versa), by contracting that index with a unitary map from `V1` to `flip(V1)`.
 
-While we provide some trivial examples here, we refer to the section on [graded spaces](@ref ss_rep) for examples where `flip` acts non-trivially and produces results that are different than `dual`.
+While we provide some trivial examples here, we refer to the section on [graded spaces](@ref ss_representationtheory) for examples where `flip` acts non-trivially and produces results that are different than `dual`.
 
 ```@repl tensorkit
 flip(ℂ^4)