more on extension + references within package

Author: borisdevos

docs/src/man/extension.md

@@ -1,4 +1,4 @@
-# MultiTensorKit as an extension to TensorKit
+# [MultiTensorKit as an extension to TensorKit](@id extension)
 
 This section will explain the internal changes to TensorKit which are required to extend the compatibility with fusion categories to multifusion ones.
 Users who are unfamiliar with TensorKit are kindly guided towards the [TensorKit tutorial](https://jutho.github.io/TensorKit.jl/stable/man/tutorial/).
@@ -30,9 +30,16 @@ These data are cached in a hash table for later use.
 
 A consequence of the multifusion structure is the colorings used in the graphical calculus of fusions.
 A natural introduction is the notion of a *left* and *right* unit of some (simple) object in the multifusion category.
+These are called with the functions `TensorKitSectors.leftunit` and `TensorKitSectors.rightunit`.
 Clearly, for the usual case of just one fusion category, these both coincide with the unique unit object.
+For this reason, the `TensorKitSectors.UnitStyle` trait is introduced to differentiate between fusion categories and multifusion categories, returning `SimpleUnit()` and `GenericUnit()`, respectively.
+This trait is used to specialise certain functions within TensorKit (see below).
+`TensorKitSectors.allunits` is also introduced to return all the simple unit objects of the (multi)fusion category.
+This function must be defined for every multifusion category to be compatible with TensorKit.
 Via the fusion rules, the left and right units of all `BimoduleSector`s along with their duals are also extracted and cached.
-Since the most general fusion rule possible is one with multiplicities involved, the entire `BimoduleSector` is set to have `TensorKitSectors.FusionStyle(::Type{<:BimoduleSector}) = GenericFusion()`.
+The fusion behavior that must be imposed for the entire `BimoduleSector` is the most general one that appears in the fusion between any two `BimoduleSector`s.
+In particular, if one of the diagonal fusion categories has fusion rules with multiplicities, then the entire `BimoduleSector` must be set to have `TensorKitSectors.FusionStyle(::Type{<:BimoduleSector}) = GenericFusion()`.
+This is the case for the $A_4$ `BimoduleSector`, since $\mathsf{Rep(A_4)}$ is one of the diagonal fusion categories and has fusion rules with multiplicities.
 
 Going beyond the ring structure, the F-symbols are also read in from the artifact, and are stored in a hash table for later use.
 The F-symbols are then used to perform F-moves on `BimoduleSector`s, which is required to perform recouplings of fusion trees when doing e.g. contractions of tensors with these categories grading the vector spaces.
@@ -48,15 +55,23 @@ This allows for more general tensor network simulations of quantum many-body sys
 
 Certain changes within TensorKit were required to make it compatible with the multifusion categorical structure.
 In particular, the presence of a simple unit object for every fusion category on the diagonal of the multifusion category, along with the off-diagonal nature of the simple objects of the bimodule categories, required some internal changes to the way unit objects were treated in TensorKit.
-Most notably, the unit object is no longer unique, and thus it is of utmost importance that the correct unit object is considered when performing tensor contractions at the level of the fusion trees.
+Most notably, the unit object is no longer unique, and thus it is of utmost importance that the correct one is considered when performing tensor contractions at the level of the fusion trees.
 This is achieved precisely through colorings and the use of `leftunit` and `rightunit`.
 For this reason, every fusion tree manipulation which previously involved "the" unit object, now involves the `leftunit` and `rightunit` of some neighboring sector in the manipulation to identify the correct color.
-An important example of this is explained in the previous section [#TODO: add opposite module categories reference], namely the mapping of a splitting vertex to a fusion vertex through the B-move.
+An important example of this is explained in the previous section on [Opposite module categories](@ref opposite_module_categories), namely the mapping of a splitting vertex to a fusion vertex via a B-move.
+
+When manipulating spaces graded by `BimoduleSector`s, one needs to also be careful of which unit spaces can compose with other graded spaces on which side.
+This introduces the functions `TensorKit.leftunitspace` and `TensorKit.rightunitspace`, which check whether the coloring of the (in general) composite object grading the space is uniform, then return the one-dimensional space with the unique left/right unit object consistent with that coloring.
+Clearly, `leftunitspace` and `rightunitspace` coincide for fusion categories; this defaults to `TensorKit.unitspace`.
+For multifusion categories, the latter function returns the space with the semisimple unit object grading it.
+`leftunitspace` and `rightunitspace` are used with the functions `TensorKit.insertleftunit` and `TensorKit.insertrightunit`.
+There, based on the index where a unit space is wished to be inserted, a `leftunitspace` or `rightunitspace` is added such that the resulting space remains consistent with the fusion rules of the multifusion category.
+Similarly, `TensorKit.removeunit` is used to remove unit spaces, and will explicitly check whether the space contains only unit objects of any color with `TensorKit.isunitspace`.
 
 # MultiTensorKit compatibility with MPSKit
 
 This section will briefly explain the changes within MPSKit which are required to make it compatible with MultiTensorKit.
-For a more practical explanation, users are kindly guided towards the next section [#TODO: add implementation reference].
+For a more practical explanation, users are kindly guided towards the [Example section](@ref implementation).
 
 The main change within MPSKit is very similar to the fusion tree manipulations in TensorKit, namely the use of `leftunit` and `rightunit` to identify the correct unit object.
 In the case of MPSKit, trivial spaces are used everywhere, from the boundary of a finite MPS to the virtual spaces of a Hamiltonian written in MPO form.

docs/src/man/fusioncats.md

@@ -1,4 +1,4 @@
-# Introduction 
+# [Introduction](@id intro)
 
 The manual has been divided into different sections in an attempt to break down the information the user requires to use MultiTensorKit.jl.
 We start off with a short summary of fusion category theory.
@@ -7,7 +7,7 @@ Be aware that notation may differ from the literature.
 
 Afterwards, the extension to multifusion categories is explained, and its relation to (bi)module categories over fusion categories is shown.
 
-# Fusion category theory
+# [Fusion category theory](@id fusion_cat_theory)
 
 The aim of this section is to explain the bare minimum required to proceed to the next section on multifusion category theory and bimodule categories.
 More details can be found in the [TensorKit](https://jutho.github.io/TensorKit.jl/stable/man/categories/) documentation or the book Tensor Categories [etingof2016tensor](@cite).

docs/src/man/implementation.md

@@ -1,4 +1,4 @@
-# Symmetric tensor networks: $\mathsf{Rep(A_4)}$ as a guiding example
+# [Symmetric tensor networks: $\mathsf{Rep(A_4)}$ as a guiding example](@id implementation)
 This tutorial is dedicated to explaining how MultiTensorKit was implemented to be compatible with with TensorKit and MPSKit for matrix product state simulations.
 In particular, we will be making a generalised anyonic spin chain.
 We will demonstrate how to reproduce the entanglement spectra found in [Lootens_2024](@cite).
@@ -36,8 +36,6 @@ Thus, the 7 module categories $\mathcal{M}$ one can choose over $\mathsf{Rep(A_4
 
 When referring to specific fusion and module categories, we will use this non-multifusion notation.
 
-The easiest way to identify which elements of the multifusion category correspond to the subcategories we wish to use is ... #TODO
-
 Now that we have identified the fusion and module categories, we want to select the relevant objects we wish to place in our graded spaces.
 Unfortunately, due to the nature of how the N-symbol and F-symbol data are generated, the objects of the fusion subcategories are not ordered such that `label=1` corresponds to the unit object.
 Hence, the simplest way to find the unit object of a fusion subcategory is

docs/src/man/multifusioncats.md

@@ -1,4 +1,4 @@
-# Extending to multifusion category theory
+# [Extending to multifusion category theory](@id multifusion_cat_theory)
 
 This section will explain how to go from a fusion category to a multifusion category, as well as why one would want to consider the latter.
 Multifusion categories naturally embed the structure of **bimodule categories**.
@@ -65,7 +65,7 @@ An F-move with ${}^{\bowtie}\!F$ is given by:
 ```@raw html
 <img src="../img/Fmove_CMD.svg" alt="" width="70%" class="color-invertible"/>
 ``` 
-## Opposite module categories
+## [Opposite module categories](@id opposite_module_categories)
 Consider a fusion category $\mathcal{D}$ and a *right* module category $\mathcal{M}$ over $\mathcal{D}$.
 We can define $\mathcal{M}^{\text{op}}$ to be the opposite category of $\mathcal{M}$ [etingof2009](@cite).
 Then, $\mathcal{M}^{\text{op}}$ is a *left* module category over $\mathcal{D}$.
@@ -256,7 +256,7 @@ Sectors provided by MultiTensorKit do *not* support braiding.
 We do this for two reasons.
 On the one hand, there is no natural 1-categorical way of defining braidings between the components of the multifusion category.
 It is possible that the diagonal fusion categories themselves are braided, but a "componentwise" braiding is unwise to support.
-On the other hand, it is entirely possible to write matrix product state manipulations in a planar manner (which has been done in [MPSKit](https://github.com/QuantumKitHub/MPSKit.jl)), thus avoiding the need of a braiding tensor. More information on this can be found in the next section [#TODO: add reference to extension page]
+On the other hand, it is entirely possible to write matrix product state manipulations in a planar manner (which has been done in [MPSKit](https://github.com/QuantumKitHub/MPSKit.jl)), thus avoiding the need of a braiding tensor. More information on this can be found in [MultiTensorKit as an extension to TensorKit](@ref extension).
 
 ## Examples of multifusion categories
 Without specifying any of the categories, the simplest non-trivial multifusion category is a $2\times 2$ one, and the categories can be organised in a matrix as
@@ -275,4 +275,4 @@ This particular example can be found in [TensorKitSectors](https://github.com/Qu
 This construction can be generalised to $\mathcal{C}_1 = \mathcal{C}_2 = \mathsf{Rep(G)}$ with $\mathsf{G}$ a finite abelian group, such that the entire multifusion category is Morita equivalent to $\mathsf{Rep(G)}$ and can be evaluated as the Tambara-Yamagami category $\mathsf{TY}(\mathsf{G})$ (with positive Frobenius-Schur indicator for our purposes), and $\mathsf{Vec}$ will represent the duality object which squares to all invertible objects of the original group.
 To be exact, one of the diagonal fusion categories should be $\mathsf{Vec_G}$ for the correct Morita dual relation, but it is known for abelian groups that this is isomorphic to $\mathsf{Rep(G)}$.
 
-The example $\mathcal{C}_1 = \mathsf{Rep(A_4)}$ is worked out more in detail on the [#TODO add reference to implementation page].
+The example $\mathcal{C}_1 = \mathsf{Rep(A_4)}$ is worked out more in detail in the [guiding example](@ref implementation).