Documentation

.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.repository == github.event.pull_request.head.repo.full_name && 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://quantumkithub.github.io/MultiTensorKit.jl/previews/PR${{ github.event.number }}/)'
+          comment-tag: 'preview-doc'

.gitignore

@@ -11,4 +11,3 @@ Manifest.toml
 benchmark/*.json
 docs/Manifest.toml
 docs/build/
-docs/src/index.md

Project.toml

@@ -5,15 +5,22 @@ version = "0.1.0"
 
 [deps]
 Artifacts = "56f22d72-fd6d-98f1-02f0-08ddc0907c33"
+BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
+BlockTensorKit = "5f87ffc2-9cf1-4a46-8172-465d160bd8cd"
+DelimitedFiles = "8bb1440f-4735-579b-a4ab-409b98df4dab"
 JSON3 = "0f8b85d8-7281-11e9-16c2-39a750bddbf1"
+MPSKit = "bb1c41ca-d63c-52ed-829e-0820dda26502"
+MPSKitModels = "ca635005-6f8c-4cd1-b51d-8491250ef2ab"
+TensorKit = "07d1fe3e-3e46-537d-9eac-e9e13d0d4cec"
 TensorKitSectors = "13a9c161-d5da-41f0-bcbd-e1a08ae0647f"
+TestExtras = "5ed8adda-3752-4e41-b88a-e8b09835ee3a"
+TupleTools = "9d95972d-f1c8-5527-a6e0-b4b365fa01f6"
 
 [compat]
 Aqua = "0.8.9"
 Artifacts = "1.10, 1"
 JSON3 = "1.14.1"
 SafeTestsets = "0.1"
-TensorKitSectors = "0.1.2"
 Test = "1.10"
 TestExtras = "0.3"
 julia = "1.10"

docs/Project.toml

@@ -0,0 +1,4 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
+MultiTensorKit = "f0555a46-f681-4ef1-bed5-d64870568636"

docs/make.jl

@@ -0,0 +1,26 @@
+using Documenter
+using DocumenterCitations
+using MultiTensorKit
+
+pages = ["Home" => "index.md",
+         "Manual" => ["man/fusioncats.md", "man/multifusioncats.md", "man/implementation.md"],
+         "Library" => "lib/library.md",
+         "References" => "references.md"]
+
+# bibliography
+bibpath = joinpath(@__DIR__, "src", "assets", "MTKrefs.bib")
+bib = CitationBibliography(bibpath; style=:authoryear)
+
+mathengine = MathJax3(Dict(:loader => Dict("load" => ["[tex]/physics"]),
+                           :tex => Dict("inlineMath" => [["\$", "\$"], ["\\(", "\\)"]],
+                                        "tags" => "ams",
+                                        "packages" => ["base", "ams", "autoload", "physics",
+                                                       "mathtools"])))
+
+makedocs(; sitename="MultiTensorKit.jl", modules=[MultiTensorKit],
+         authors="Boris De Vos, Laurens Lootens and Lukas Devos",
+         pages=pages, pagesonly=true, plugins=[bib],
+         format=Documenter.HTML(; prettyurls=true, mathengine=mathengine, 
+         assets=["assets/custom.css"]))
+
+deploydocs(; repo="https://github.com/QuantumKitHub/MultiTensorKit.jl", push_preview = true)

docs/src/assets/MTKrefs.bib

@@ -0,0 +1,53 @@
+@book{etingof2016tensor,
+  title={Tensor Categories},
+  author={Etingof, P. and Gelaki, S. and Nikshych, D. and Ostrik, V.},
+  isbn={9781470434410},
+  lccn={2015006773},
+  series={Mathematical Surveys and Monographs},
+  url={https://books.google.be/books?id=Z6XLDAAAQBAJ},
+  year={2016},
+  publisher={American Mathematical Society}
+}
+
+@article{Lootens_2023,
+   title={Dualities in One-Dimensional Quantum Lattice Models: Symmetric Hamiltonians and Matrix Product Operator Intertwiners},
+   volume={4},
+   ISSN={2691-3399},
+   url={http://dx.doi.org/10.1103/PRXQuantum.4.020357},
+   DOI={10.1103/prxquantum.4.020357},
+   number={2},
+   journal={PRX Quantum},
+   publisher={American Physical Society (APS)},
+   author={Lootens, Laurens and Delcamp, Clement and Ortiz, Gerardo and Verstraete, Frank},
+   year={2023},
+   month=jun }
+
+@misc{etingof2009,
+      title={Fusion categories and homotopy theory}, 
+      author={Pavel Etingof and Dmitri Nikshych and Victor Ostrik and with an appendix by Ehud Meir},
+      year={2009},
+      eprint={0909.3140},
+      archivePrefix={arXiv},
+      primaryClass={math.QA},
+      url={https://arxiv.org/abs/0909.3140}, 
+}
+
+@misc{henriques2020,
+      title={Representations of fusion categories and their commutants}, 
+      author={André Henriques and David Penneys},
+      year={2020},
+      eprint={2004.08271},
+      archivePrefix={arXiv},
+      primaryClass={math.OA},
+      url={https://arxiv.org/abs/2004.08271}, 
+}
+
+@misc{Lootens_2024,
+      title={Entanglement and the density matrix renormalisation group in the generalised Landau paradigm}, 
+      author={Laurens Lootens and Clement Delcamp and Frank Verstraete},
+      year={2024},
+      eprint={2408.06334},
+      archivePrefix={arXiv},
+      primaryClass={quant-ph},
+      url={https://arxiv.org/abs/2408.06334}, 
+}

docs/src/assets/custom.css

@@ -0,0 +1,47 @@
+.center {
+  display: block;
+  margin-left: auto;
+  margin-right: auto;
+}
+
+/* set fixed non-trivial inversion and hue rotation */
+:root {
+    --inversionFraction: 100%;
+    --hueRotation: -180deg;
+}
+
+/* color-invert images */
+.color-invertible {
+    filter: invert(var(--inversionFraction)) hue-rotate(var(--hueRotation)) !important;
+    -ms-filter: invert(var(--inversionFraction)) !important;
+    -webkit-filter: invert(var(--inversionFraction)) hue-rotate(var(--hueRotation)) !important;
+}
+/* including the logo when we make one
+.docs-logo {
+    filter: invert(var(--inversionFraction)) hue-rotate(var(--hueRotation)) !important;
+    -ms-filter: invert(var(--inversionFraction)) !important;
+    -webkit-filter: invert(var(--inversionFraction)) hue-rotate(var(--hueRotation)) !important;
+} */
+
+/* but disable for the two light themes */
+.theme--documenter-light .color-invertible {
+    filter: invert(0%) hue-rotate(0deg) !important;
+    -ms-filter: invert(var(0%)) !important;
+    -webkit-filter: invert(var(0%)) hue-rotate(0deg) !important;
+}
+.theme--catppuccin-latte .color-invertible {
+    filter: invert(0%) hue-rotate(0deg) !important;
+    -ms-filter: invert(var(0%)) !important;
+    -webkit-filter: invert(var(0%)) hue-rotate(0deg) !important;
+}
+/* for the logo as well */
+/* .theme--documenter-light .docs-logo {
+    filter: invert(0%) hue-rotate(0deg) !important;
+    -ms-filter: invert(var(0%)) !important;
+    -webkit-filter: invert(var(0%)) hue-rotate(0deg) !important;
+}
+.theme--catppuccin-latte .docs-logo {
+    filter: invert(0%) hue-rotate(0deg) !important;
+    -ms-filter: invert(var(0%)) !important;
+    -webkit-filter: invert(var(0%)) hue-rotate(0deg) !important;
+} */

docs/src/index.md

@@ -0,0 +1,34 @@
+# MultiTensorKit
+
+**TensorKit extension to multifusion categories**
+
+## Package summary
+MultiTensorKit.jl provides the user a package to work with multifusion categories, the extension of regular fusion categories where the unit is no longer simple and unique.
+Multifusion categories naturally embed the structure of module categories over fusion categories. Hence, MultiTensorKit.jl allows not only the fusion of objects within the same
+fusion category (as TensorKit.jl), but also the fusion with and between module categories over these fusion categories. 
+
+MultiTensorKit.jl is built to be compatible with TensorKit, thus allowing the construction of symmetric tensors with new symmetries due to the module structure. Through this,
+tensor network simulations of quantum many-body systems with aid of [MPSKit.jl](https://github.com/QuantumKitHub/MPSKit.jl) can be performed.
+
+## Table of contents
+
+```@contents
+Pages = ["man/fusioncats.md","man/multifusioncats.md","lib/library.md", "references.md"]
+Depth = 2
+```
+
+## Installation
+
+MultiTensorKit.jl is currently not registered to the Julia General Registry. You can install the package as
+```
+pkg> add https://github.com/QuantumKitHub/MultiTensorKit.jl.git
+```
+
+## Usage
+
+As the name suggests, MultiTensorKit is an extension of [TensorKit.jl](https://github.com/Jutho/TensorKit.jl) and
+[TensorKitSectors.jl](https://github.com/QuantumKitHub/TensorKitSectors.jl). Therefore, we recommend including TensorKit 
+to your project. Additionally, MultiTensorKit was made to be functional with [MPSKit.jl](https://github.com/QuantumKitHub/MPSKit.jl)
+and [MPSKitModels.jl](https://github.com/QuantumKitHub/MPSKitModels.jl) for Matrix Product State (MPS) calculations, supporting symmetries
+which go beyond TensorKit. All these packages are registered in JuliaRegistries and can be added through the package manager.
+

docs/src/lib/library.md

@@ -0,0 +1,5 @@
+# Library 
+
+```@autodocs
+Modules = [MultiTensorKit]
+```

docs/src/man/fusioncats.md

@@ -0,0 +1,59 @@
+# Introduction 
+
+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. Users familiar with TensorKit.jl may have read the [Optional introduction to category theory](https://jutho.github.io/TensorKit.jl/stable/man/categories/) in the documentation of TensorKit; this section can then largely be skipped. 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
+
+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).
+
+Let us start simple and introduce the **fusion ring** $\mathcal{C}$ in a black-box manner. This ring 
+*   consists of finitely many simple objects $\{ X_1, X_2, ..., X_R \}$, with $R$ the rank of the fusion ring,
+*   which can be fused with one another: $X_i \otimes X_j \cong \sum_k N_{ij}^k X_k,$ introducing the **N-symbol** $N_{ij}^k \in \mathbb{N}$ in the fusion rules,
+*   contains a *unique* unit object $1_\mathcal{C}$ which satisfies $1_\mathcal{C} \otimes X_i \cong X_i \otimes 1_\mathcal{C} \cong X_i$ for all objects $X_i \in \mathcal{C}$,
+*   has a dual object $\overline{X}$ for every object $X$ such that $X \otimes \overline{X} \cong \overline{X} \otimes X \cong 1_\mathcal{C} \oplus ...$, generalising the notion of the inverse element.
+
+To extend the fusion ring to the **fusion category**, we need to add the following structure:
+*   Consider only the representatives of isomorphism classes of simple objects $\mathcal{I}_\mathcal{C}$,
+*   The associator $F^{X_iX_jX_k}: (X_i \otimes X_j) \otimes X_k \xrightarrow{\sim} X_i \otimes (X_j \otimes X_k)$
+   which fulfills the famous pentagon equation,
+*   Morphisms between (simple) objects $\text{Hom}_\mathcal{C}(X_i, X_j)$, which are empty vector spaces unless the objects are isomorphic, the latter then giving $\mathbb{C}$,
+*   More general morphisms $\text{Hom}_\mathcal{C}(X_i \otimes X_j, X_k) \cong \mathbb{C}^{N_{ij}^k}$.
+
+This way, we can describe fusion categories by a triple $(\otimes, 1_\mathcal{C}, F)$ of $\mathcal{C}$ defining its monoidal product, unit object and monoidal associator, the latter also commonly called the **F-symbol**. In particular, the simple objects have their respective quantum dimensions $d_i = \dim(X_i)$ which form their own one-dimensional representation of the fusion algebra: $d_i d_j = \sum_k N_{ij}^k d_k$. In particular, the unit object always has quantum dimension 1, and all other quantum dimensions are larger or equal to one. These quantum dimensions are encoded in the F-symbol. The isomorphisms instead of the equalities are a technical detail, so we drop that notation. 
+
+Vectors in these hom-spaces are graphically denoted as living in the trivalent junction
+```@raw html
+<img src="../img/homvector.svg" alt="" width="30%" class="center color-invertible"/>
+``` 
+
+
+With the F-symbol, we can perform F-moves:
+
+```@raw html
+<img src="../img/Fmove.svg" alt="" width="80%" class="color-invertible"/>
+``` 
+
+TensorKit requires the F-symbols to be unitary. This way, we can interpret the F-symbol $F^{ijk}_l$ as a unitary matrix, and the F-move as a unitary basis transformation. Unitarity is also useful from a diagrammatic point of view because the category is then equipped with a pivotal and spherical structure. This essentially means that morphisms can be drawn and moved around freely on a 2-sphere, such that vector spaces can be moved freely from domain (codomain) to codomain (domain). 
+
+## Examples
+
+### $\mathsf{Vec_G}$ and $\mathsf{Rep(G)}$
+Colloquially speaking, category theory attempts to generalise mathematical structures and their relations in a way that different structures can be treated in an equal manner. This is noted in particular as fusion category theory encompasses not only finite and compact groups, but also their representations. We show a table sketching how these are put on equal footing categorically.
+
+|$\mathsf{Vec_G}$|$\mathsf{Rep(G)}$|Categorical generalisation|
+|:---:|:---:|:---:|
+|$G$-graded vector spaces $V_1, V_2, ...$|Representations of $G$ $(V_1, \pi_1), (V_2, \pi_2), ...$|Objects|
+|$G$-graded preserving linear maps $\phi: V \rightarrow W$|Intertwiners $f: V_1 \rightarrow V_2$, $f \circ \pi_1 = \pi_2 \circ f$|Morphisms $\text{Hom}_\mathcal{C}$|
+1d subspaces $\mathbb{C}_{g_1}, \mathbb{C}_{g_2}$:  $\text{Hom}_{\mathsf{Vec_G}}(\mathbb{C}_{g_1},\mathbb{C}_{g_2}) = \delta_{g_1g_2}$|Irreps: $\text{Hom}_{\mathsf{Rep(G)}}(\rho_i,\rho_j) = \delta_{ij} \mathbb{C}$ (Schur)|Simple objects: $\text{Hom}_{\mathcal{C}}(a,b) = \delta_{ab}\mathbb{C}$|
+$G$-graded tensor product $(V \otimes W)_g = \oplus_{hk=g} V_h \otimes W_k$| $\pi_i \otimes \pi_j \simeq \oplus_i N_{ij}^k\rho_k$ | Direct sum, monoidal product, fusion rules, multiplicity|
+$\mathbb{C}_1 \otimes W \simeq W \simeq W \otimes \mathbb{C}_1$ | Trivial rep 1: $1 \otimes \rho = \rho = \rho \otimes 1$ | Monoidal unit $1_\mathcal{C}$
+$\mathbb{C}_g \otimes \mathbb{C}_{g^{-1}} = \mathbb{C}_1 = \mathbb{C}_{g^{-1}} \otimes \mathbb{C}_g$ | $\pi \otimes \overline{\pi} = 1 \oplus ...$ | Dual object
+$F:(V \otimes W) \otimes U \xrightarrow{\sim}V \otimes (W \otimes U)$|$F: (\pi_1 \otimes \pi_2) \otimes \pi_3 \xrightarrow{\sim} \pi_1 \otimes (\pi_2 \otimes \pi_3)$|F-symbol|
+
+### $\mathsf{Fib}$ and $\mathsf{Ising}$
+Arguably the simplest fusion category besides the familiar groups or representations of groups is the Fibonacci fusion category. This contain 2 simple objects $1$ and $\tau$, with non-trivial fusion rule $\tau \otimes \tau = 1 \oplus \tau$. This fusion category is in fact **braided** as well, and actually **modular**.
+
+Another simple fusion category is the Ising category, commonly denoted $\mathsf{Ising}$. 3 simple objects form this category, namely $\{1, \psi, \sigma\}$, where $1$ and $\psi$ behave like the trivial charged representations of $\mathbb{Z}_2$, while $\sigma$ is the $\mathbb{Z}_2$ extension of this. The fusion rules reflect these: $1 \otimes \psi = \psi = \psi \otimes 1, \sigma \otimes X = \sigma = X \otimes \sigma$ for $X = 1, \psi$, and $\sigma \otimes \sigma = 1 \oplus \psi$. This fusion category is also **modular**. Both these modular fusion categories are already implemented in [TensorKitSectors](https://github.com/QuantumKitHub/TensorKitSectors.jl).