docs, still work in progress

Author: Jutho

docs/make.jl

@@ -4,6 +4,7 @@ using TensorKit
 makedocs(modules=[TensorKit],
             sitename="TensorKit.jl",
             authors = "Jutho Haegeman",
+            format = Documenter.HTML(prettyurls = get(ENV, "CI", nothing) == "true"),
             pages = [
                 "Home" => "index.md",
                 "Manual" => ["man/intro.md", "man/spaces.md", "man/sectors.md", "man/tensors.md"],

docs/src/man/intro.md

@@ -1,9 +1,9 @@
-# Introduction
+# [Introduction](@id s_intro)
 
-Before discussing the implementation and how it can be used on the following pages, let us
-discuss some of the rationale behind TensorKit.jl.
+Before providing a typical "user guide" and discussing the implementation of TensorKit.jl
+on the next pages, let us discuss some of the rationale behind this package.
 
-## What is a tensor?
+## [What is a tensor?](@id ss_tensor)
 
 At the very start we should ponder about the most suitable and sufficiently general
 definition of a tensor. A good starting point is the following:
@@ -17,7 +17,7 @@ definition of a tensor. A good starting point is the following:
 
 If you think of a tensor as an object with indices, a rank `N` tensor has `N` indices where
 every index is associated with the corresponding vector space in that it labels a particular
-basis in that space. We will return to index notation below.
+basis in that space. We will return to index notation at the very end of this manual.
 
 As the tensor product of vector spaces is itself a vector space, this implies that a tensor
 behaves as a vector, i.e. tensors from the same tensor product space can be added and
@@ -26,7 +26,7 @@ field, i.e. there is no meaning in ``ℝ^5 ⊗ ℂ^3``. When all the vector spac
 product have an inner product, this also implies an inner product for the tensor product
 space. It is hence clear that the different vector spaces in the tensor product should have
 some form of homogeneity in their structure, yet they do not need to be all equal and can
-e.g. have different dimensions. It goes without saying that defining the vector spaces an
+e.g. have different dimensions. It goes without saying that defining the vector spaces and
 their properties will be an important part of the definition of a tensor. As a consequence,
 this also constitutes a significant part of the implementation, and is discussed in the
 section on [Vector spaces](@ref).
@@ -36,8 +36,8 @@ matrix (or more correctly, a linear map) in order to decompose tensors using lin
 factorisations (e.g. eigenvalue or singular value decomposition). Henceforth, we use the
 term "tensor map" as follows:
 
-*   A tensor map ``t`` is a linear map from a *domain* ``W_1 ⊗ W_2 ⊗ … ⊗ W_{N_2}`` to a
-    *codomain* ``V_1 ⊗ V_2 ⊗ … ⊗ V_{N_1}``, i.e.
+*   A tensor map ``t`` is a linear map from a source or *domain*
+    ``W_1 ⊗ W_2 ⊗ … ⊗ W_{N_2}`` to a target or *codomain* ``V_1 ⊗ V_2 ⊗ … ⊗ V_{N_1}``, i.e.
 
     ``t:W_1 ⊗ W_2 ⊗ … ⊗ W_{N_2} → V_1 ⊗ V_2 ⊗ … ⊗ V_{N_1}.``
 
@@ -47,11 +47,11 @@ matrix multiplication), where the contracted indices correspond to the domain of
 tensor and the codomain of the second tensor.
 
 In order to allow for arbitrary tensor contractions or decompositions, we need to be able to
-reorganise which vector spaces appear in the domain and the codomain of the tensor map. This
-amounts to defining canonical isomorphisms between the different ways to order and partition
-the tensor indices (i.e. the vector spaces). For example, a linear map ``W → V`` is often
-denoted as a rank 2 tensor in ``V ⊗ W^*``, where ``W^*`` corresponds to the dual space of
-`W`. This simple example introduces two new concepts.
+reorganise which vector spaces appear in the domain and the codomain of the tensor map, and
+in which order. This amounts to defining canonical isomorphisms between the different ways
+to order and partition the tensor indices (i.e. the vector spaces). For example, a linear
+map ``W → V`` is often denoted as a rank 2 tensor in ``V ⊗ W^*``, where ``W^*`` corresponds
+to the dual space of `W`. This simple example introduces two new concepts.
 
 1.  Typical vector spaces can appear in the domain and codomain in different variants, e.g.
     as normal space or dual space. In fact, the most generic case is that every vector
@@ -102,7 +102,7 @@ This brings us to our final (yet formal) definition
     category of finite dimensional vector spaces. More generally, our concept of a tensor
     makes sense, in principle, for any ``\mathbf{Vect}``-enriched monoidal category. We refer to the section "[Monoidal categories and their properties (optional)](@ref)".
 
-## Symmetries and block sparsity
+## [Symmetries and block sparsity](@id ss_symmetries)
 
 Physical problems often have some symmetry, i.e. the setup is invariant under the action of
 a group ``\mathsf{G}`` which acts on the vector spaces ``V`` in the problem according to a
@@ -112,7 +112,7 @@ number of times every irreducible representation (irrep) `a` of ``\mathsf{G}`` a
 
 ``V = \bigoplus_{a} ℂ^{n_a} ⊗ R_a``
 
-with `R_a` the space associated with irrep ``a`` of ``\mathsf{G}``, which itself has
+with ``R_a`` the space associated with irrep ``a`` of ``\mathsf{G}``, which itself has
 dimension ``d_a`` (often called the quantum dimension), and ``n_a`` the number of times
 this irrep appears in ``V``. If the unitary irrep ``a`` for ``g ∈ \mathsf{G}`` is given by
 ``u_a(g)``, then the group action of ``\mathsf{G}`` on ``V`` is given by the unitary
@@ -125,34 +125,39 @@ by ``∑_a n_a d_a``.
 
 The reason of implementing symmetries is to exploit the compuation and memory gains
 resulting from restricting to tensor maps ``t:W_1 ⊗ W_2 ⊗ … ⊗ W_{N_2} → V_1 ⊗ V_2 ⊗ … ⊗
-V_{N_1}`` that are invariant under the symmetry (i.e. that act as [intertwiners](https://en.wikipedia.org/wiki/Equivariant_map#Representation_theory)
+V_{N_1}`` that are invariant under the symmetry (i.e. that act as
+[intertwiners](https://en.wikipedia.org/wiki/Equivariant_map#Representation_theory)
 between the symmetry action on the domain and the codomain). Indeed, such tensors should be
 block diagonal because of [Schur's lemma](https://en.wikipedia.org/wiki/Schur%27s_lemma),
-but only after we couple the individual irreps in the spaces `W_i` to a joint irrep. The
-basis change from the tensor product of irreps in the (co)domain to the joint irrep is
-implemented by a sequence of Clebsch-Gordan coefficients, also known as a fusion (or
-splitting) tree. We implement the necessary machinery to manipulate these fusion trees
-under index permutations and repartitions for arbitrary groups ``\mathsf{G}``. In
-particular, this fits with the formalism of monoidal categories discussed below and only
-requires the *topological* data of the group, i.e. the fusion rules of the irreps, their
-quantum dimensions and the F-symbol (6j-symbol or more precisely Racah's W-symbol in the
-case of ``\mathsf{SU}_2``). In particular, we do not need the Clebsch-Gordan coefficients.
+but only after we couple the individual irreps in the spaces ``W_i`` to a joint irrep,
+which is then again split into the individual irreps of the spaces ``V_i``. The basis
+change from the tensor product of irreps in the (co)domain to the joint irrep isimplemented
+by a sequence of Clebsch-Gordan coefficients, also known as a fusion (or splitting) tree.
+We implement the necessary machinery to manipulate these fusion trees under index
+permutations and repartitions for arbitrary groups ``\mathsf{G}``. In particular, this fits
+with the formalism of monoidal categories, and more specifically fusion categoreis,
+discussed below and only requires the *topological* data of the group, i.e. the fusion
+rules of the irreps, their quantum dimensions and the F-symbol (6j-symbol or more precisely
+Racah's W-symbol in the case of ``\mathsf{SU}_2``). In particular, we do not need the
+Clebsch-Gordan coefficients.
 
 Further details are provided in [Sectors, representation spaces and fusion trees](@ref).
 
-## Monoidal categories and their properties (optional)
+## [Monoidal categories and their properties (optional)](@id ss_category)
 
 The purpose of this final introductory section (which can safely be skipped), is to explain
 how certain concepts and terminology from the theory of monoidal categories apply in the
 context of tensors.  In the end, identifying tensor manipulations in TensorKit.jl with
 concepts from category theory is to put the diagrammatic formulation of tensor networks in
 the most general context on a firmer footing. The following definitions are mostly based on
-[^selinger] and [``n``Lab](https://ncatlab.org/), to which we refer for further
+[^selinger], [^kassel] and [``n``Lab](https://ncatlab.org/), to which we refer for further
 information. Furthermore, we recommend the nice introduction of [Beer et al.](^beer)
 
 To start, a category ``C`` consists of
 *   a class ``|C|`` of objects ``V``, ``W``, …
-*   for each pair of objects ``V`` and ``W``, a set ``hom(W,V)`` of morphisms ``f:W→V``
+*   for each pair of objects ``V`` and ``W``, a set ``hom(W,V)`` of morphisms ``f:W→V``;
+    for a given map `f`, `W` is called the *domain* or *source*, and `V` the *codomain* or
+    *target*.
 *   an composition of morphisms ``f:W→V`` and ``g:X→W`` into ``(f ∘ g):X→V`` that is
     associative, such that for ``h:Y→X`` we have ``f ∘ (g ∘ h) = (f ∘ g) ∘ h``
 *   for each object ``V``, an identity morphism ``\mathrm{id}_V:V→V`` such that
@@ -161,8 +166,9 @@ To start, a category ``C`` consists of
 In our case, i.e. the category ``\mathbf{Vect}`` (or some subcategory thereof), the objects
 are vector spaces, and the morphisms are linear maps between these vector spaces with
 "matrix multiplication" as composition. We refer to these morphisms as tensor maps exactly
-because there is an operation `⊗`, the tensor product, that allows to combine objects into
-new objects. This makes ``\mathbf{Vect}`` into a **monoidal category**, which has
+because there is a binary operation `⊗`, the tensor product, that allows to combine objects
+into new objects. This makes ``\mathbf{Vect}`` into a **tensor category**, a.k.a
+a *monoidal category*, which has
 *   a binary operation on objects ``⊗: |C| × |C| → |C|``
 *   a binary operation on morphisms, also denoted as ``⊗``, such that
     ``⊗: hom(W_1,V_1) × hom(W_2,V_2) → hom(W_1 ⊗ W_2, V_1 ⊗ V_2)``
@@ -174,62 +180,60 @@ new objects. This makes ``\mathbf{Vect}`` into a **monoidal category**, which ha
         ``α_{V_1,V_2,V_3}:(V_1 ⊗ V_2) ⊗ V_3 → V_1 ⊗ (V_2 ⊗ V_3)``
     that satisfy certain consistency conditions (coherence axioms), which are known as the
     *triangle equation* and *pentagon equation*.
+In abstract terms, ``⊗`` is a (bi)functor from the product category ``C × C`` to ``C``.
 
 For the category ``\mathbf{Vect}``, the identity object ``I`` is just the scalar field,
 which can be identified with a one-dimensional vector space. Every monoidal category is
-equivalent to a strict monoidal category, where the left and right unitor and associator
+equivalent to a strict tensor category, where the left and right unitor and associator
 act as the identity and their domain and codomain are truly identical. Nonetheless, for
 tensor maps, we do actually discriminate between ``V``, ``I ⊗ V`` and ``V ⊗ I`` because
 this amounts to adding or removing an extra factor `I` to the tensor product structure of
 the (co)domain, i.e. the left and right unitor are analogous to removing extra dimensions
-of size 1 from an array,and an actual operation is required to do so (this has in fact led
+of size 1 from an array, and an actual operation is required to do so (this has in fact led
 to some controversy in several programming languages that provide native support for
 multidimensional arrays). For what concerns the associator, the distinction between
 ``(V_1 ⊗ V_2) ⊗ V_3`` and ``V_1 ⊗ (V_2 ⊗ V_3)`` is typically absent for simple tensors or
 multidimensional arrays. However, this grouping can be taken to indicate how to build the
 fusion tree for coupling irreps to a joint irrep in the case of symmetric tensors. As such,
 going from one to the other requires a recoupling (F-move) which has a non-trivial action
-on the reduced blocks. We return to this in the discussion of symmetric tensors.
+on the reduced blocks. We return to this in
+[the section on fusion trees](@ref s_sectorsrepfusion). However, we can already note that
+we will always represent tensor products using a canonical order
+``(…((V_1 ⊗ V_2) ⊗ V_3) … ⊗ V_N)``. A similar approach can be followed to map any tensor
+category into a strict tensor category (see Section XI.5 of [^kassel]).
 
 With these definitions, we have the minimal requirements for defining tensor maps. In
 principle, we could use a more general definition and define tensor maps as morphism of any
-monoidal category where the hom-sets are themselves vector spaces, such that we can add
+tensor category where the hom-sets are themselves vector spaces, such that we can add
 morphisms and multiply them with scalars. Such categories are called
 ``\mathbf{Vect}``-enriched.
 
 In order to make tensor (maps) useful and to define operations with them, we can now
-introduce additional structure or quantifiers to the monoidal category for which they are
+introduce additional structure or quantifiers to the tensor category for which they are
 the morphisms.
 
-### Braiding
+### [Braiding](@id sss_braiding)
 
 To reorder tensor indices, or, equivalently, to reorder objects in the tensor product
-``V_1 ⊗ V_2 ⁠⊗ … V_N``, we need at the very least a **braided monoidal category** which
-has, ``∀ V, W ∈ |C|``, a braiding ``σ_{V,W}: V⊗W → W⊗V``. There is a consistency condition
-between the braiding and the associator known as the *hexagon equation*. However, for
-general braidings, there is no unique choice to identify a tensor in ``V⊗W`` and ``W⊗V``,
-as any of the maps ``σ_{V,W}``, ``σ_{W,V}^{-1}``, ``σ_{V,W} ∘ σ_{W,V} ∘ σ_{V,W}``, …  and
-are all different. In order for there to be a unique map from ``V_1 ⊗ V_2 ⁠⊗ … V_N`` to any
-permutation of the objects in this tensor product, the braiding needs to be *symmetric*,
-i.e. ``σ_{V,W} = σ_{W,V}^{-1}`` or, equivalently ``σ_{W,V} ∘ σ_{V,W} = \mathrm{id}_{V⊗W}``.
-
-The resulting category is also referred to as a **symmetric monoidal category**. In a
-graphical representation, it means that there is no distinction between over- and under-
+``V_1 ⊗ V_2 ⁠⊗ … V_N``, we need at the very least a **braided tensor category** which has, ``∀ V, W ∈ |C|``, a braiding ``σ_{V,W}: V⊗W → W⊗V``. A valid braiding needs to satisfy consistency condition with the associator ``α`` known as the *hexagon equation*.
+
+However, for general braidings, there is no unique choice to identify a tensor in ``V⊗W``
+and ``W⊗V``, as any of the maps ``σ_{V,W}``, ``σ_{W,V}^{-1}``,
+``σ_{V,W} ∘ σ_{W,V} ∘ σ_{V,W}``, …  mapping from ``V⊗W`` to ``W⊗V`` are all different. In
+order for there to be a unique map from ``V_1 ⊗ V_2 ⁠⊗ … V_N`` to any permutation of the
+objects in this tensor product, the braiding needs to be *symmetric*, i.e.
+``σ_{V,W} = σ_{W,V}^{-1}`` or, equivalently ``σ_{W,V} ∘ σ_{V,W} = \mathrm{id}_{V⊗W}``. The
+resulting category is then referred to as a **symmetric tensor category**. In a graphical
+representation, it means that there is no distinction between over- and under-
 crossings and, as such, lines can just cross.
 
 For a simple cartesian tensor, permuting the tensor indices is equivalent to applying
 Julia's function `permutedims` on the underlying data. Less trivial braiding
-implementations arise in the context of symmetric tensors (where the fusion tree needs to
-be reordered) or in the case of fermions (described using so-called super vector spaces).
+implementations arise in the context of tensors with symmetries (where the fusion tree
+needs to be reordered) or in the case of fermions (described using so-called super vector
+spaces where the braiding is given by the Koszul sign rule).
 
-We can extend a braided category with a **twist** ``θ_V``, i.e. a family of isomorphisms
-``θ_V:V→V`` that satisfy ``θ_{V⊗W} = σ_{W,V} ∘ (θ_W ⊗ θ_V) ∘ σ_{V,W}`` and the resulting
-category is called a **balanced** monoidal category. The corresponding graphical
-representation is that where objects are denoted by ribbons instead of lines, and a twist
-is consistent with the graphical representation of a twisted ribbon and how it combines
-with braidings.
-
-### Duals
+### [Duals](@id sss_dual)
 
 For tensor maps, the braiding structure only allows to reorder the objects within the domain
 or within the codomain separately. An **autonomous** or **rigid** monoidal category is one
@@ -248,10 +252,7 @@ complex vector spaces, using a bra-ket notation and a generic basis ``{|n⟩}``
 dual basis ``{⟨m|}`` for ``V^*`` (such that ``⟨m|n⟩ = δ_{m,n}``), the unit is
 ``η_V:ℂ → V ⊗ V^*:λ → λ ∑_n |n⟩ ⊗ ⟨n|`` and the co-unit is
 ``⁠ϵ_V:V^* ⊗ V → ℂ: ⟨m| ⊗ |n⟩ → δ_{m,n}``. Note that this does not require an inner
-product, i.e. no mapping from ``|n⟩`` to ``⟨n|`` was defined. Furthermore, note that we
-used the physics convention, whereas mathematicians would typically interchange the order
-of ``V`` and ``V^*`` as they appear in the codomain of the unit and in the domain of the co-
-unit.
+product, i.e. no mapping from ``|n⟩`` to ``⟨n|`` was defined.
 
 For a general tensor map ``t:W_1 ⊗ W_2 ⊗ … ⊗ W_{N_2} → V_1 ⊗ V_2 ⊗ … ⊗ V_{N_1}``, by
 successively applying ``η_{W_{N_2}}``, ``η_{W_{N_2-1}}``, …, ``η_{W_{1}}`` (and the left or
@@ -260,6 +261,19 @@ right unitor) but no braiding, we obtain a tensor in
 It does makes sense to define or identify
 ``(W_1 ⊗ W_2 ⊗ … ⊗ W_{N_2})^* = W_{N_2}^* ⊗ … ⊗ W_{1}^*``.
 
+In fact, the above exact pairings are known as the left unit and co-unit, and ``V^*`` is the
+left dual of ``V``. There is also a notion of a right dual ``^*V`` and associated pairings,
+the right unit ``η'_V: I → ^*V ⊗ V`` and the right co-unit ``ϵ'_V: V ⊗ *^V → I``. An
+autonomous category `\mathbf{C}` is one where every object `V` has both a left and right
+dual, and in this case they can be proven to be isomorphic. We will never distinguish
+between the two and refer simply to `dual(V)` for the dual of a vector space.
+
+The braiding of a space and a dual space also follows naturally, it is given by
+``σ_{V^*,W} = λ_{W ⊗ V^*} ∘ (ϵ_V ⊗ \mathrm{id}_{W ⊗ V^*}) ∘ (\mathrm{id}_{V^*} ⊗ σ_{V,W}^{-1} ⊗ \mathrm{id}_{V^*}) ∘ (\mathrm{id}_{V^*⊗ W} ⊗ η_V) ∘ ρ_{V^* ⊗ W}^{-1}``
+
+
+
+
 In general categories, one can distinguish between a left and right dual, but we always
 assume that both objects are naturally isomorphic. Equivalently, ``V^{**} ≂ V`` and the
 category is said to be  **pivotal**. For every morphism ``f:W→V``, there is then a well
@@ -285,7 +299,16 @@ In the case of a symmetric braiding, most of these difficulties go away and the
 structure follows. A symmetric monoidal category with duals is known as a **compact closed
 category**.
 
-### Adjoints
+We can extend a braided category with a **twist** ``θ_V``, i.e. a family of isomorphisms
+``θ_V:V→V`` that satisfy ``θ_{V⊗W} = σ_{W,V} ∘ (θ_W ⊗ θ_V) ∘ σ_{V,W}`` and the resulting
+category is called a **balanced** monoidal category. The corresponding graphical
+representation is that where objects are denoted by ribbons instead of lines, and a twist
+is consistent with the graphical representation of a twisted ribbon and how it combines
+with braidings.
+
+
+
+### [Adjoints](@id sss_adjoints)
 
 
 ## Bibliography