WIP: Documentation update/overhaul

docs/make.jl

@@ -13,11 +13,15 @@ links = InterLinks(
 pages = [
     "Home" => "index.md",
     "Manual" => [
-        "man/intro.md", "man/tutorial.md", "man/categories.md",
+        "man/intro.md", "man/tutorial.md",
         "man/spaces.md", "man/sectors.md", "man/tensors.md",
     ],
-    "Library" => ["lib/sectors.md", "lib/spaces.md", "lib/tensors.md"],
+    "Library" => [
+        "lib/sectors.md", "lib/fusiontrees.md",
+        "lib/spaces.md", "lib/tensors.md",
+    ],
     "Index" => ["index/index.md"],
+    "Appendix" => ["appendix/categories.md"],
 ]
 
 makedocs(;

docs/src/index.md

@@ -17,29 +17,38 @@ factorizations). Finally, tensor contractions can be performed using the `@tenso
 from [TensorOperations.jl](https://github.com/QuantumKitHub/TensorOperations.jl).
 
 Currently, most effort is oriented towards tensors as they appear in the context of quantum
-many body physics and in particular the field of tensor networks. Such tensors often have
-large dimensions and take on a specific structure when symmetries are present. To deal with
-generic symmetries, we employ notations and concepts from category theory all the way down
-to the definition of a tensor.
+many-body physics and in particular the field of tensor networks. Such tensors often have
+large dimensions and take on a specific structure when symmetries are present. By employing
+concepts from category theory, we can represent and manipulate tensors with a large
+variety of symmetries, including abelian and non-abelian symmetries, fermionic statistics,
+as well as generalized (a.k.a. non-invertible or anyonic) symmetries.
 
 At the same time, TensorKit.jl focusses on computational efficiency and performance. The
-underlying storage of a tensor's data can be any `DenseArray`. Currently, certain operations
-are already multithreaded, either by distributing the different blocks in case of a
-structured tensor (i.e. with symmetries) or by using multithreading provided by the package
-[Strided.jl](https://github.com/Jutho/Strided.jl). In the future, we also plan to
-investigate using `CuArray`s as underlying storage for the tensors data, so as to leverage
-GPUs for the different operations defined on tensors.
+underlying storage of a tensor's data can be any `DenseArray`. When the data is stored
+in main memory (corresponding to `Array`), multiple CPUs can be leveraged as many
+operations come with multithreaded implementations, either by distributing the different
+blocks in case of a structured tensor (i.e. with symmetries) or by using multithreading
+provided by the package [Strided.jl](https://github.com/Jutho/Strided.jl). Support for 
+storing and manipulating tensors on NVidia and AMD GPUs is currently being developed,
+whereas support for distributed arrays is planned for the future.
 
 ## Contents of the manual
 
 ```@contents
-Pages = ["man/intro.md", "man/categories.md", "man/spaces.md", "man/sectors.md", "man/tensors.md"]
+Pages = ["man/intro.md", "man/spaces.md", "man/sectors.md", "man/tensors.md"]
 Depth = 3
 ```
 
 ## Library outline
 
 ```@contents
-Pages = ["lib/sectors.md","lib/spaces.md","lib/tensors.md"]
+Pages = ["lib/sectors.md","lib/fusiontrees.md","lib/spaces.md","lib/tensors.md"]
 Depth = 2
 ```
+
+## Appendix
+
+```@contents
+Pages = ["appendix/categories.md"]
+Depth = 3
+```

docs/src/lib/fusiontrees.md

@@ -0,0 +1,55 @@
+# Fusion trees
+
+```@meta
+CurrentModule = TensorKit
+```
+
+# Type hierarchy
+
+```@docs
+FusionTree
+```
+
+## Methods for defining and generating fusion trees
+
+```@docs
+fusiontrees(uncoupled::NTuple{N,I}, coupled::I,
+                     isdual::NTuple{N,Bool}) where {N,I<:Sector}
+```
+
+## Methods for manipulating fusion trees
+
+For manipulating single fusion trees, the following internal methods are defined:
+```@docs
+insertat
+split
+merge
+elementary_trace
+planar_trace(f::FusionTree{I,N}, q1::IndexTuple{N₃}, q2::IndexTuple{N₃}) where {I<:Sector,N,N₃}
+artin_braid
+braid(f::FusionTree{I,N}, levels::NTuple{N,Int}, p::NTuple{N,Int}) where {I<:Sector,N}
+permute(f::FusionTree{I,N}, p::NTuple{N,Int}) where {I<:Sector,N}
+```
+
+These can be composed to implement elementary manipulations of fusion-splitting tree pairs,
+according to the following methods
+
+```julia
+# TODO: add documentation for the following methods
+TensorKit.bendright
+TensorKit.bendleft
+TensorKit.foldright
+TensorKit.foldleft
+TensorKit.cycleclockwise
+TensorKit.cycleanticlockwise
+```
+
+Finally, these are used to define large manipulations of fusion-splitting tree pairs, which
+are then used in the index manipulation of `AbstractTensorMap` objects. The following methods
+defined on fusion splitting tree pairs have an associated definition for tensors.
+```@docs
+repartition(::FusionTree{I,N₁}, ::FusionTree{I,N₂}, ::Int) where {I<:Sector,N₁,N₂}
+transpose(::FusionTree{I}, ::FusionTree{I}, ::IndexTuple{N₁}, ::IndexTuple{N₂}) where {I<:Sector,N₁,N₂}
+braid(::FusionTree{I}, ::FusionTree{I}, ::IndexTuple, ::IndexTuple, ::IndexTuple{N₁}, ::IndexTuple{N₂}) where {I<:Sector,N₁,N₂}
+permute(::FusionTree{I}, ::FusionTree{I}, ::IndexTuple{N₁}, ::IndexTuple{N₂}) where {I<:Sector,N₁,N₂}
+```

docs/src/lib/sectors.md

@@ -1,120 +1,136 @@
-# Symmetry sectors and fusion trees
+# Symmetry sectors
 
 ```@meta
 CurrentModule = TensorKit
 ```
 
 ## Type hierarchy
+
+The fundamental abstract supertype for symmetry sectors is `Sector`:
+
 ```@docs
 Sector
-SectorValues
-FusionStyle
-BraidingStyle
-AbstractIrrep
+```
+
+Various concrete subtypes of `Sector` are provided within the TensorKitSectors library:
+
+```@docs
 Trivial
+AbstractIrrep
 ZNIrrep
+DNIrrep
 U1Irrep
 SU2Irrep
 CU1Irrep
-ProductSector
+AbstractGroupElement
+ZNElement
 FermionParity
 FermionNumber
 FermionSpin
 FibonacciAnyon
 IsingAnyon
+PlanarTrivial
+IsingBimodule
+TimeReversed
+ProductSector
+```
+
+Several more concrete sector types can be found in other packages such as
+[SUNRepresentations.jl](https://github.com/QuantumKitHub/SUNRepresentations.jl),
+[CategoryData.jl](https://github.com/QuantumKitHub/CategoryData.jl),
+[QWignerSymbols.jl](https://github.com/lkdvos/QWignerSymbols.jl), ...:
+
+Some of these types are parameterized by a type parameter that represents a group.
+We therefore also provide a number of types to represent groups:
+
+```@docs
+TensorKitSectors.Group
+TensorKitSectors.AbelianGroup
+TensorKitSectors.Cyclic
+TensorKitSectors.U₁
+TensorKitSectors.CU₁
+TensorKitSectors.SU
+TensorKitSectors.Dihedral
+TensorKitSectors.ProductGroup
+```
+
+The following types are used to characterise different properties of the different types
+of sectors:
+
+```@docs
+FusionStyle
+BraidingStyle
+UnitStyle
+```
+
+Finally, the following auxiliary types are defined to facilitate the implementation
+of some of the methods on sectors:
+
+```@docs
+TensorKitSectors.SectorValues
+TensorKitSectors.SectorProductIterator
 ```
 
 ## Useful constants
+
+The following constants are defined to facilitate obtaining the type associated
+with the group elements or the irreducible representations of a given group:
+
 ```@docs
 Irrep
+GroupElement
 ```
 
-## Methods for defining and characterizing `Sector` subtypes
+## Methods for characterizing and manipulating `Sector` objects
+
+The following methods can be used to obtain properties such as topological data
+of sector objects, or to manipulate them or create related sectors:
+
 ```@docs
-unit(::Sector)
-dual
+unit
+isunit
+leftunit
+rightunit
+allunits
+dual(::Sector)
 Nsymbol
 ⊗
 Fsymbol
 Rsymbol
 Bsymbol
 dim(::Sector)
 frobenius_schur_phase
+frobenius_schur_indicator
 twist(::Sector)
 Base.isreal(::Type{<:Sector})
 TensorKitSectors.sectorscalartype
 deligneproduct(::Sector, ::Sector)
 ```
 
-Compile all revelant methods for a sector:
+We have also the following methods that are specific to certain types of sectors
+and serve as accessors to their fields:
 
 ```@docs
-TensorKitSectors.precompile_sector
+charge
+modulus
 ```
 
-
-## Types and methods for groups
-
-Types and constants:
-
-```julia
-# TODO: add documentation for the following types
-Group
-TensorKitSectors.AbelianGroup
-U₁
-ℤ{N} where N
-SU{N} where N
-const SU₂ = SU{2}
-ProductGroup
-```
-
-Specific methods:
+Furthermore, we also have one specific method acting on groups, represented as types
 
 ```@docs
 ×
 ```
 
+Because we sometimes want to customize the string representation of our sector types,
+we also have the following method:
 
-## Methods for defining and generating fusion trees
 ```@docs
-FusionTree
-fusiontrees(uncoupled::NTuple{N,I}, coupled::I,
-                     isdual::NTuple{N,Bool}) where {N,I<:Sector}
+TensorKitSectors.type_repr
 ```
 
-## Methods for manipulating fusion trees
+Finally, we provide functionality to compile all revelant methods for a sector:
 
-For manipulating single fusion trees, the following internal methods are defined:
 ```@docs
-insertat
-split
-merge
-elementary_trace
-planar_trace(f::FusionTree{I,N}, q1::IndexTuple{N₃}, q2::IndexTuple{N₃}) where {I<:Sector,N,N₃}
-artin_braid
-braid(f::FusionTree{I,N}, levels::NTuple{N,Int}, p::NTuple{N,Int}) where {I<:Sector,N}
-permute(f::FusionTree{I,N}, p::NTuple{N,Int}) where {I<:Sector,N}
-```
-
-These can be composed to implement elementary manipulations of fusion-splitting tree pairs,
-according to the following methods
-
-```julia
-# TODO: add documentation for the following methods
-TensorKit.bendright
-TensorKit.bendleft
-TensorKit.foldright
-TensorKit.foldleft
-TensorKit.cycleclockwise
-TensorKit.cycleanticlockwise
+TensorKitSectors.precompile_sector
 ```
 
-Finally, these are used to define large manipulations of fusion-splitting tree pairs, which
-are then used in the index manipulation of `AbstractTensorMap` objects. The following methods
-defined on fusion splitting tree pairs have an associated definition for tensors.
-```@docs
-repartition(::FusionTree{I,N₁}, ::FusionTree{I,N₂}, ::Int) where {I<:Sector,N₁,N₂}
-transpose(::FusionTree{I}, ::FusionTree{I}, ::IndexTuple{N₁}, ::IndexTuple{N₂}) where {I<:Sector,N₁,N₂}
-braid(::FusionTree{I}, ::FusionTree{I}, ::IndexTuple, ::IndexTuple, ::IndexTuple{N₁}, ::IndexTuple{N₂}) where {I<:Sector,N₁,N₂}
-permute(::FusionTree{I}, ::FusionTree{I}, ::IndexTuple{N₁}, ::IndexTuple{N₂}) where {I<:Sector,N₁,N₂}
-```

docs/src/lib/spaces.md

@@ -1,4 +1,4 @@
-# Vector spaces
+# [Vector spaces](@id s_libvectorspaces)
 
 ```@meta
 CurrentModule = TensorKit
@@ -21,7 +21,7 @@ ProductSpace
 HomSpace
 ```
 
-together with the following specific types for encoding the inner product structure of
+together with the following specific type for encoding the inner product structure of
 a space:
 
 ```@docs
@@ -85,23 +85,24 @@ space
 The following methods act specifically on `ElementarySpace` spaces:
 
 ```@docs
-isdual
 dual(::VectorSpace)
 conj
+isconj
+isdual
 flip
-⊕
-⊖
 zerospace
 unitspace
+⊕
+⊖
 supremum
 infimum
 ```
 
 while the following also work on both `ElementarySpace` and `ProductSpace`
 
 ```@docs
-one(::VectorSpace)
 fuse
+one(::VectorSpace)
 ⊗(::VectorSpace, ::VectorSpace)
 ⊠(::VectorSpace, ::VectorSpace)
 ismonomorphic

docs/src/man/intro.md

@@ -93,17 +93,18 @@ to the dual space of ``W``. This simple example introduces two new concepts.
     ``V ⊗ W^*`` is not an equivalence but an isomorphism, which needs to be defined.
     Similarly, there is an isomorphism between between ``V ⊗ W`` and ``W ⊗ V`` that can be
     non-trivial (e.g. in the case of fermions / super vector spaces). The correct formalism
-    here is provided by theory of monoidal categories, which is introduced on the next
-    page. Nonetheless, we try to hide these canonical isomorphisms from the user wherever
-    possible, and one does not need to know category theory to be able to use this package.
+    here is provided by theory of monoidal categories, the details of which are explained
+    in the appendix. Nonetheless, we try to hide these canonical isomorphisms from the user
+    wherever possible, and one does not need to know category theory to be able to use this
+    package.
 
 This brings us to our final (yet formal) definition
 
 *   A tensor (map) is a homomorphism between two objects from the category ``\mathbf{Vect}``
     (or some subcategory thereof). In practice, this will be ``\mathbf{FinVect}``, the
     category of finite dimensional vector spaces. More generally even, our concept of a
     tensor makes sense, in principle, for any linear (a.k.a. ``\mathbf{Vect}``-enriched)
-    monoidal category. We refer to the next page on
+    monoidal category. For more details, we refer the curious reader to the appendix on
     "[Monoidal categories and their properties](@ref s_categories)".
 
 ## [Symmetries and block sparsity](@id ss_symmetries)