Documentation for index-manipulation and contraction API rework by lkdvos · Pull Request #438 · QuantumKitHub/TensorKit.jl

lkdvos · 2026-05-19T20:10:53Z

Stacked on top of #416. Contains the documentation portion of that PR:

New manual pages: indexmanipulations.md, contractions.md, linearalgebra.md, factorizations.md
New SVG asset: img/tensor-fermioniccontraction.svg
Removal of the old tensormanipulations.md
Page-tree restructure in docs/make.jl (new "Tensors" group)
CollapsedDocStrings = true added to lib/{fusiontrees,sectors,spaces}.md
Minor wording tweak in man/tensors.md

Additionally, I finally got around to putting in some information in the documentation section of the fermionic/anyonic contractions pages, let me know what you think.
Ultimately the dream would be to be able to (finally) submit this version to SciPost codebases.

Merge order: #416 first, then this PR. Once #416 lands, the base of this PR will fast-forward to main.

github-actions · 2026-05-19T20:18:54Z

After the build completes, the updated documentation will be available here

borisdevos · 2026-05-20T08:40:28Z

The additional text to contractions is a lifesaver, I actually finally understand why some of my planar diagrams weren't considered to be planar! 😄

Jutho · 2026-05-20T14:36:50Z

I'll had a first quick look and this looks very well written indeed. This will be extremely useful (and is definitely long overdue).

The only comment that is maybe missing is that the @planar contraction in combination with Fermionic() tensors is "equivalent" (or at least closer to) to the "trace" framework, i.e. not twists are inserted and therefore composition of morphisms just works as expected (in particular, e.g. inner products, isometry checks of orthogonal factorizations, ...). This is also why @plansor only resorts to @tensor in the Bosonic case, and not in the Fermionic one.

borisdevos · 2026-06-01T15:19:14Z

Can I also go through this if that's alright? I can make time for this tomorrow!

lkdvos · 2026-06-01T17:18:30Z

Sure, I can leave this open if you like. I still have some typos etc that I'd like to push this evening, otherwise for me it would be easiest if you just apply your suggestions tomorrow (or the day after 🤷) and merge.

borisdevos · 2026-06-02T12:34:03Z

+
+`AbstractTensorMap` instances `t` represent linear maps, i.e. homomorphisms in a `𝕜`-linear category, just like matrices.
+To a large extent, they follow the interface of `Matrix` in Julia's `LinearAlgebra` standard library.
+Many methods from `LinearAlgebra` are (re)exported by TensorKit.jl, and can then us be used without `using LinearAlgebra` explicitly.


Suggested change

Many methods from `LinearAlgebra` are (re)exported by TensorKit.jl, and can then us be used without `using LinearAlgebra` explicitly.

Many methods from `LinearAlgebra` are (re)exported by TensorKit.jl, and can thus be used without `using LinearAlgebra` explicitly.

borisdevos · 2026-06-02T12:38:15Z

+The tensor product of two `TensorMap` instances `t1` and `t2` is obtained as `t1 ⊗ t2` and results in a new `TensorMap` with `codomain(t1 ⊗ t2) = codomain(t1) ⊗ codomain(t2)` and `domain(t1 ⊗ t2) = domain(t1) ⊗ domain(t2)`.
+If we have two `TensorMap{T, S, N, 1}` instances `t1` and `t2` with the same codomain, we can combine them in a way that is analogous to `hcat`, i.e. we stack them such that the new tensor `catdomain(t1, t2)` has also the same codomain, but has a domain which is `domain(t1) ⊕ domain(t2)`.
+Similarly, if `t1` and `t2` are of type `TensorMap{T, S, 1, N}` and have the same domain, the operation `catcodomain(t1, t2)` results in a new tensor with the same domain and a codomain given by `codomain(t1) ⊕ codomain(t2)`, which is the analogy of `vcat`.
+Note that direct sum only makes sense between `ElementarySpace` objects, i.e. there is no way to give a tensor product meaning to a direct sum of tensor product spaces.


Suggested change

Note that direct sum only makes sense between `ElementarySpace` objects, i.e. there is no way to give a tensor product meaning to a direct sum of tensor product spaces.

Note that the direct sum only makes sense between `ElementarySpace` objects, i.e. there is no way to give a tensor product meaning to a direct sum of tensor product spaces.

borisdevos · 2026-06-02T12:39:38Z

+using LinearAlgebra
+```
+
+As tensors are linear maps, they suport various kinds of factorizations.


Suggested change

As tensors are linear maps, they suport various kinds of factorizations.

As tensors are linear maps, they support various kinds of factorizations.

Split the consolidated tensormanipulations.md page into dedicated indexmanipulations, contractions, factorizations, and linearalgebra pages, and wire them into the docs navigation.

Document contraction behavior for fermionic and anyonic sectors, including a note on @planar for Fermionic, with an accompanying illustration.

Co-authored-by: Jutho <Jutho@users.noreply.github.com>

lkdvos · 2026-06-03T20:33:05Z

If there are no further comments, happy to merge this!

lkdvos force-pushed the ld-indexmanipulations branch from cae3748 to 26c844a Compare May 19, 2026 20:12

lkdvos force-pushed the ld-indexmanipulations-docs branch from c76bbc3 to 01552fb Compare May 19, 2026 20:13

lkdvos added the documentation label May 19, 2026

lkdvos marked this pull request as draft May 19, 2026 20:17

lkdvos force-pushed the ld-indexmanipulations branch from 26c844a to 35f4d65 Compare May 30, 2026 18:20

Base automatically changed from ld-indexmanipulations to main May 30, 2026 19:36

lkdvos force-pushed the ld-indexmanipulations-docs branch from ff8cf8e to ea24798 Compare May 30, 2026 19:54

lkdvos marked this pull request as ready for review May 30, 2026 19:54

lkdvos requested a review from Jutho May 30, 2026 19:54