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

@@ -4,25 +4,30 @@ authors = ["Boris De Vos, Laurens Lootens and Lukas Devos"]
 version = "0.1.0"
 
 [deps]
-Artifacts = "56f22d72-fd6d-98f1-02f0-08ddc0907c33"
-JSON3 = "0f8b85d8-7281-11e9-16c2-39a750bddbf1"
+DelimitedFiles = "8bb1440f-4735-579b-a4ab-409b98df4dab"
+Pkg = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"
+TensorKit = "07d1fe3e-3e46-537d-9eac-e9e13d0d4cec"
 TensorKitSectors = "13a9c161-d5da-41f0-bcbd-e1a08ae0647f"
 
 [compat]
 Aqua = "0.8.9"
-Artifacts = "1.10, 1"
-JSON3 = "1.14.1"
+DelimitedFiles = "1.9"
+Pkg = "1"
+Random = "1"
 SafeTestsets = "0.1"
-TensorKitSectors = "0.1.2"
+TensorKit = "0.16"
+TensorKitSectors = "0.3"
 Test = "1.10"
 TestExtras = "0.3"
 julia = "1.10"
 
 [extras]
 Aqua = "4c88cf16-eb10-579e-8560-4a9242c79595"
+LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 SafeTestsets = "1bc83da4-3b8d-516f-aca4-4fe02f6d838f"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 TestExtras = "5ed8adda-3752-4e41-b88a-e8b09835ee3a"
 
 [targets]
-test = ["Aqua", "SafeTestsets", "Test", "TestExtras"]
+test = ["Aqua", "LinearAlgebra", "Random", "SafeTestsets", "Test", "TestExtras"]

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,27 @@
+using Documenter
+using DocumenterCitations
+# using TensorKitSectors, TensorKit
+using MultiTensorKit
+
+pages = ["Home" => "index.md",
+         "Manual" => ["man/fusioncats.md", "man/multifusioncats.md", "man/extension.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,41 @@
+# 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", "man/extension.md", "man/implementation.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.
+In particular, TensorKit v0.16.0 and MPSKit v0.13.9 contain the necessary functionality to deal with the multifusion categorical structure provided by MultiTensorKit.
+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/extension.md

@@ -0,0 +1,96 @@
+# [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/).
+
+## As a `Sector`
+MultiTensorKit is at its core an extension to [TensorKitSectors](https://github.com/QuantumKitHub/TensorKitSectors.jl), as it simply provides a new `Sector`, i.e. simple objects of a multifusion category, named `BimoduleSector`.
+
+````julia
+struct BimoduleSector{Name} <: Sector
+    i::Int
+    j::Int
+    label::Int
+end
+````
+
+`i` and `j` specify which subcategory $\mathcal{C}_{ij}$ we are considering, and `label` selects a particular simple object within that subcategory.
+`Name` selects which multifusion category to work with, and is a `Symbol`.
+As of now, only `:A4` is available, referring to the multifusion category consisting of $\mathsf{Rep(A_4)}$ as the largest fusion category,  and all its Morita dual fusion categories and corresponding bimodule categories.
+The fusion of these `BimoduleSector`s is then defined by the fusion rules of the multifusion category.
+In particular,
+````julia
+a = BimoduleSector{:A4}(i, j, label1)
+b = BimoduleSector{:A4}(k, l, label2)
+a ⊗ b # empty unless j == k
+````
+
+The fusion rules are read in via the artifact labeled "fusiondata", and are extracted at runtime when calling the fusion of two `BimoduleSector`s (or `Nsymbol`) for the first time.
+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.
+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.
+
+Due to the nature of the multifusion category, it is currently not possible to define a non-trivial braiding on the `BimoduleSector`s, so these are set to be non-braided: `TensorKitSectors.BraidingStyle(::Type{<:BimoduleSector}) = NoBraiding()`.
+This is especially important when working with matrix product states, as all algorithms are required to remain planar, since no (half-)braiding is available to perform crossings of fusion trees.
+
+## As a symmetry in TensorKit
+Since `BimoduleSector`s are `Sector`s, they can be used as symmetries in TensorKit.
+This way, we can construct symmetric tensors with the symmetries of the multifusion category, which are more general than those of the fusion categories.
+In particular, the vector spaces graded by these `BimoduleSector`s are not only graded by the simple objects of the fusion categories, but also by the simple objects of the bimodule categories.
+This allows for more general tensor network simulations of quantum many-body systems with symmetries which go beyond those of fusion categories.
+
+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 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 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 [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 matrix product state to the virtual spaces of a Hamiltonian written as an matrix product operator.
+Additionally, multiple tensor contractions made use of braiding tensors to perform crossings of legs of the MPSs/MPOs.
+Since no (half-)braiding is available for the `BimoduleSector`s, all algorithms had to be made planar, and thus all braiding tensors were removed.
+Since all braidings were trivial, this was dealt with by simply removing the braiding tensors and replacing the crossing of legs with a termination and reintroduction of the legs without crossing by aid of `removeunit`, `insertleftunit` and `insertrightunit`.
+
+At the level of the MPS, the correct unit object can be identified through the use of `leftunit(ψ::AbstractMPS)` and `rightunit(ψ::AbstractMPS)`.
+When the virtual space of the MPS is graded by a diagonal `BimoduleSector`, i.ea unitary fusion category, then these all coincide with the unique unit object of that fusion category.
+However, when the virtual space is graded by an off-diagonal `BimoduleSector`, i.e. a bimodule category, then the left and right units are different, and thus it is important to identify the correct one when performing MPS algorithms.
+For example, Hamiltonians should always have the same coloring as the right unit of the MPS, since they are contracted at the physical level of the MPS.
+Similarly, excitations of an MPS are labeled by `BimoduleSector`s with the same coloring as the left unit of the MPS, since the auxiliary charge leg of the excitation is attached on the other side of the MPS to the virtual level.
+This is illustrated in the following figure.
+
+```@raw html
+<img src="../img/anyonchain_excitation.svg" alt="" width="70%"/>
+```
+
+Here, $\mathcal{D}$ is the fusion category grading the physical space of the MPS, $\mathcal{R}$ is the right $\mathcal{D}$-module category grading the virtual space of the MPS.
+$\mathcal{E}$ is the Morita dual fusion category of $\mathcal{D}$ with respect to $\mathcal{R}$, which is the category labelling the excitations of the MPS.
+In this case, the left unit of the MPS is in $\mathcal{E}$, and the right unit in $\mathcal{D}$.