Documentation overhaul

.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/TensorKitSectors.jl/previews/PR${{ github.event.number }}/)'
+          comment-tag: 'preview-doc'

docs/Project.toml

@@ -1,6 +1,7 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 TensorKitSectors = "13a9c161-d5da-41f0-bcbd-e1a08ae0647f"
+TensorOperations = "6aa20fa7-93e2-5fca-9bc0-fbd0db3c71a2"
 
 [compat]
 Documenter = "1"

docs/make.jl

@@ -19,6 +19,46 @@ makedocs(;
     ),
     pages = [
         "Home" => "index.md",
+        "Sector Interface" => [
+            "Overview" => "interface/overview.md",
+            "Required Methods" => "interface/required.md",
+            "Optional Methods" => "interface/optional.md",
+            "Traits and Styles" => "interface/traits.md",
+            "Implementation Guidelines" => "interface/guidelines.md",
+        ],
+        "Sector Types" => [
+            "Overview" => "sectors.md",
+            "Abelian Groups" => [
+                "Trivial" => "sectors/abelian/trivial.md",
+                "ℤₙ (Cyclic)" => "sectors/abelian/zn.md",
+                "U₁" => "sectors/abelian/u1.md",
+            ],
+            "Non-Abelian Groups" => [
+                "SU₂" => "sectors/nonabelian/su2.md",
+                "CU₁" => "sectors/nonabelian/cu1.md",
+                "Dₙ (Dihedral)" => "sectors/nonabelian/dn.md",
+                "A₄ (Alternating)" => "sectors/nonabelian/a4.md",
+                "Heisenberg" => "sectors/nonabelian/heisenberg.md",
+            ],
+            "Anyonic Sectors" => [
+                "PlanarTrivial" => "sectors/anyons/planartrivial.md",
+                "Fibonacci" => "sectors/anyons/fibonacci.md",
+                "Ising" => "sectors/anyons/ising.md",
+            ],
+            "Fermionic Sectors" => [
+                "Fermion Parity" => "sectors/fermions/parity.md",
+                "Fermion Number" => "sectors/fermions/number.md",
+                "Fermion Spin" => "sectors/fermions/spin.md",
+            ],
+            "Group Elements" => [
+                "ℤₙ (Cyclic)" => "sectors/groupelement/znelement.md",
+            ],
+            "Composite Sectors" => [
+                "Product" => "sectors/composite/product.md",
+                "Named" => "sectors/composite/named.md",
+                "Time-Reversed" => "sectors/composite/timereversed.md",
+            ],
+        ],
         "Library" => "lib.md",
     ],
     checkdocs = :exports,

docs/src/index.md

@@ -2,11 +2,20 @@
 
 A Julia package for working with objects in fusion categories.
 
-This package provides functionality for defining objects in fusion categories, along with
-their topological data. This includes the fusion rules, the associators, and the braiding.
-In particular, this is the data that is needed to define (symmetric) tensors, which are
-defined over vector spaces graded by these objects. For the full functionality, we refer to
-[TensorKit.jl](https://github.com/QuantumKitHub/TensorKit.jl) and [its
-documentation](https://quantumkithub.github.io/TensorKit.jl/stable/).
-
-Install via the package manager.
+This package provides functionality for defining objects in fusion categories, along with their topological data.
+This includes the fusion rules, the associators, and the braiding.
+In particular, this is the data that is needed to define (symmetric) tensors, which are defined over vector spaces graded by these objects.
+For the full functionality, we refer to [TensorKit.jl](https://github.com/QuantumKitHub/TensorKit.jl) and [its documentation](https://quantumkithub.github.io/TensorKit.jl/stable/).
+
+## Installation
+
+Install via the package manager, by entering the Pkg REPL mode with `]` and running:
+
+```julia-repl
+pkg> add TensorKitSectors
+```
+
+## Where to go next
+
+- **[Sector Interface](@ref)** — the methods a sector type must (and may) implement, and the traits that control its behavior. Start here to implement a new sector.
+- **[Sector Types](@ref)** — the concrete sectors shipped with this package (groups, anyons, fermions, and composites), with a summary table and a page per type.

docs/src/interface/guidelines.md

@@ -0,0 +1,63 @@
+```@meta
+CollapsedDocStrings = true
+```
+
+# Implementation Guidelines
+
+This section provides practical advice for implementing new sector types efficiently and correctly.
+
+## Helper Type: SectorProductIterator
+
+Instead of materializing all fusion outputs in a tuple or array, one can use `SectorProductIterator` for type-stable, lazy iteration.
+
+```@docs; canonical = false
+TensorKitSectors.SectorProductIterator
+```
+
+This is enabled by default, and new sectors should provide implementations for the following functions:
+
+```julia
+Base.iterate(ab::SectorProductIterator{I}, [state]) = ...
+# optional optimizations:
+Base.IteratorSize(::Type{SectorProductIterator{I}}) = HasLength()
+Base.length(ab::SectorProductIterator{I}) = ...
+```
+
+This has the benefit of helping with type stability, and has a pretty-printing overload:
+
+```@example
+using TensorKitSectors # hide
+SU2Irrep(1) ⊗ SU2Irrep(1)
+```
+
+## Shape of Topological Data
+
+The size of [`Fsymbol`](@ref) and [`Rsymbol`](@ref) data depends on the fusion multiplicities ([`Nsymbol`](@ref)).
+For multiplicity‑free sectors scalars are sufficient; for generic fusion we need arrays.
+Therefore, we distinguish the behavior through the [`FusionStyle`](@ref).
+
+
+### [`MultiplicityFreeFusion`](@ref)
+
+- `Nsymbol(a, b, c)`: Returns a `Bool`.
+- `Fsymbol(a, b, c, d, e, f)`: Returns a scalar of type `sectorscalartype(I)`.
+- `Rsymbol(a, b, c)`: Returns a scalar of type `sectorscalartype(I)`.
+
+Additionally, if the [`Fsymbol`](@ref) and [`Rsymbol`](@ref) do not correspond to valid fusion channels, the result is ``0``.
+Therefore, computing the number of valid fusion channels for both diagrams as the product of the relevant [`Nsymbol`](@ref)s, we have:
+
+```math
+\left(N^{ab}_e N^{ec}_d = 0 ∨ N^{af}_d N^{bc}_f = 0\right) ⟹ (F_{abc}^d)^e_f = 0
+```
+
+```math
+N^{ab}_c = 0 ⟹ R^{ab}_c = 0
+```
+
+### [`GenericFusion`](@ref)
+
+- `Nsymbol(a, b, c)`: Returns a positive `Integer`.
+- `Fsymbol(a, b, c, d, e, f)`: Returns a ``N^{ab}_e × N^{ec}_d × N^{af}_d × N^{bc}_f`` array of `sectorscalartype(I)` elements.
+- `Rsymbol(a, b, c)`: Returns a ``N^{ab}_c × N^{ba}_c`` array of `sectorscalartype(I)` elements.
+
+Here invalid fusion channels will necessarily lead to empty arrays.

docs/src/interface/optional.md

@@ -0,0 +1,98 @@
+```@meta
+CollapsedDocStrings = true
+```
+
+# Optional Methods
+
+Most of the following methods have default implementations derived from the required methods, but can be overridden for performance or to provide additional functionality.
+The exception is [`fusiontensor`](@ref), which has no default: it is genuinely optional and, when needed, must be supplied explicitly (see the Fusion Basis section below).
+
+## Quantum Dimensions
+
+The quantum dimension of a sector is a fundamental invariant that determines the behavior of fusions and braiding.
+The default implementation extracts the dimension from [`Fsymbol`](@ref) via the quantum dimension formula.
+
+```math
+d_a = \left| \frac{1}{(F_{a \bar{a} a}^a)^{1_a}_{_a1} } \right|
+```
+
+For many common sectors, however, the dimension is known directly from representation theory.
+In these cases, it can be beneficial to overload [`dim`](@ref) to bypass computing F-symbols, either for performance reasons or to enforce tighter output types.
+For example, dimensions of irreducible representations of groups are always integers.
+
+```@docs; canonical = false
+dim
+sqrtdim
+invsqrtdim
+```
+
+## Frobenius-Schur Indicators
+
+The Frobenius-Schur indicator and phase characterize the self-duality properties of sectors.
+The Frobenius-Schur phase ``κ_a`` is obtained from the F-symbol as
+
+```math
+κ_a = \text{sign}\left( (F_{a \bar{a} a}^a)^{1_a}_{_a1} \right)
+```
+
+and is the category-theoretic quantity that appears in line-bending operations.
+The Frobenius-Schur indicator ``ν_a`` coincides with ``κ_a`` for self-dual sectors (``a = \bar{a}``) and is ``0`` otherwise; it distinguishes real, complex, and quaternionic representations.
+
+```@docs; canonical = false
+frobenius_schur_indicator
+frobenius_schur_phase
+```
+
+## Scalar Type
+
+Various utility functions exist for determining what number type is used in various parts of the topological data.
+
+```@docs; canonical = false
+fusionscalartype
+braidingscalartype
+dimscalartype
+sectorscalartype
+```
+
+!!! note
+    While there is a fallback definition that tries to determine the result from computing the functions on the unit sector,
+    it is often a good idea to define this method explicitly to avoid depending on compiler heuristics to constant-fold these calls.
+
+## Topological Data Symbols
+
+The [`Asymbol`](@ref), [`Bsymbol`](@ref) and [`twist`](@ref) are derived from F- and R-symbols but are often occurring combinations.
+The A-symbol and B-symbol relate different ways of bending strands, while the twist is the topological spin (quantum dimension phase) of a sector.
+
+The A-symbol ``A^{ab}_c`` relates splitting and fusion vertices:
+```math
+A^{ab}_c = \sqrt{\frac{d_a d_b}{d_c}} \, \overline{κ_a (F_{\bar{a} a b}^b)^1_c}
+```
+
+The B-symbol ``B^{ab}_c`` relates splitting and fusion vertices:
+```math
+B^{ab}_c = \sqrt{\frac{d_a d_b}{d_c}} (F_{a b \bar{b}}^a)^c_1
+```
+
+The twist ``θ_a`` of a sector is the topological spin phase, computed as the trace of the R-matrix for braiding a sector with itself:
+```math
+θ_a = \frac{1}{d_a} \sum_{b ∈ a ⊗ a} d_b \text{tr}(R^{aa}_b)
+```
+
+```@docs; canonical = false
+Asymbol
+Bsymbol
+twist
+```
+
+## Fusion Basis
+
+The fusion tensor provides explicit matrix elements for the tensor product of representations.
+It is a rank-4 array whose components are the Clebsch-Gordan coefficients for fusing sector `a` and `b` into `c`.
+The fusion tensor is not uniquely determined by topological data alone, instead the topological data can be extracted from it when it is available.
+However, there is not always a concrete representation of these tensors in terms of simple `Array` objects, and the exact representation is not important for TensorKit.jl.
+For this reason, it is optional: TensorKit can work with the topological data alone.
+Note however that they are still required whenever we want to convert symmetric tensors to and from dense arrays.
+
+```@docs; canonical = false
+fusiontensor
+```

docs/src/interface/overview.md

@@ -0,0 +1,32 @@
+# Sector Interface
+
+## Introduction
+
+A `Sector` is a label for the different *symmetry charges* or *quantum numbers* that organize graded vector spaces.
+In particular, these are the labels used to decompose vector spaces as:
+
+```math
+V = \bigoplus_{a ∈ \text{Sectors}} ℂ^{n_a} ⊗ V_a
+```
+
+where ``n_a`` is the multiplicity of sector ``a`` and ``V_a`` is the associated vector space.
+
+Sectors encode the structural rules TensorKit needs:
+- **Objects**: the labels themselves (irreps, anyons, …)
+- **Fusion rules**: which labels appear in ``a ⊗ b → \bigoplus_c N^{ab}_c c``
+- **Associativity**: how different parenthesizations are related
+- **Braiding**: how labels behave under exchange (if supported)
+
+More rigorously, a `Sector` represents the isomorphism classes of simple objects in unitary and pivotal fusion categories.
+This package defines an interface for accessing the topological data that is associated to these categories.
+This section explains the required and optional methods needed to create a new sector type.
+Once this interface is fulfilled, TensorKit.jl will create symmetric tensors that correspond to the implemented sector.
+
+## Organization
+
+The interface documentation is divided into several pages:
+
+- **[Required Methods](required.md)**: The minimum interface needed for a valid sector type
+- **[Optional Methods](optional.md)**: Additional methods with default implementations that can be specialized
+- **[Traits and Styles](traits.md)**: Compile-time properties that control behavior and optimizations
+- **[Implementation Guidelines](guidelines.md)**: Practical advice and helper types for implementing sectors