Merge pull request #140 from Jutho/jh/tensorstructure

WIP: redesign tensormap structure

Author: Jutho

.github/workflows/CI.yml

@@ -21,8 +21,8 @@ jobs:
       fail-fast: false
       matrix:
         version:
-          - '1.10' # LTS version
-          # - '1' # TODO: add back when 1.10 is LTS
+          - '1'
+          - 'lts'
         os:
           - ubuntu-latest
           - macOS-latest

Changelog.md

@@ -3,9 +3,9 @@
 Features that are planned to be implemented before the release of v1.0.0, in no particular order.
 
 - [x] Separate `Sectors` module
-- [ ] Make `TrivialTensorMap` and `TensorMap` be the same
-- [ ] Simplify `TensorMap` type to hide `rowr` and `colr`
-- [ ] Change block order in `rowr` / `colr` to speed up particular contractions
+- [x] Make `TrivialTensorMap` and `TensorMap` be the same
+- [x] Simplify `TensorMap` type to hide `rowr` and `colr`
+- [x] Change block order in `rowr` / `colr` to speed up particular contractions
 - [x] Make `AdjointTensorMap` generic
 - [ ] Rewrite planar operations in order to be AD-compatible
 - [x] Fix rrules for fermionic tensors
@@ -47,3 +47,17 @@ as there are some changes in the API.
 
 This promotes TensorKitSectors to its own package, in order to make the dependencies
 lighter and to separate the concerns of the two packages.
+
+### FusionTree vertices
+
+In order to simplify the `FusionTree` struct, we removed the usage of anything other than
+`Int` as a vertex-label when working with `GenericFusion` sectors.
+
+### TensorStructure
+
+This PR changed the data structure of `TensorMap` to consist of a single vector of data,
+where all blocks and subblocks are various views into this object. This entails major
+simplifications for the outwards-facing interface, as now the `TensorMap` type requires less
+parameters, and the fusion-tree structure is more clearly considered as an implementation
+detail that can be left hidden to the user. Various other improvements and documentation
+work was also carried out.

Project.toml

@@ -1,13 +1,14 @@
 name = "TensorKit"
 uuid = "07d1fe3e-3e46-537d-9eac-e9e13d0d4cec"
 authors = ["Jutho Haegeman"]
-version = "1.0.0-DEV"
+version = "0.13.0"
 
 [deps]
 LRUCache = "8ac3fa9e-de4c-5943-b1dc-09c6b5f20637"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 PackageExtensionCompat = "65ce6f38-6b18-4e1d-a461-8949797d7930"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
+SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
 Strided = "5e0ebb24-38b0-5f93-81fe-25c709ecae67"
 TensorKitSectors = "13a9c161-d5da-41f0-bcbd-e1a08ae0647f"
 TensorOperations = "6aa20fa7-93e2-5fca-9bc0-fbd0db3c71a2"
@@ -32,11 +33,12 @@ LRUCache = "1.0.2"
 LinearAlgebra = "1"
 PackageExtensionCompat = "1"
 Random = "1"
+SparseArrays = "1"
 Strided = "2"
 TensorKitSectors = "0.1"
-TensorOperations = "5"
+TensorOperations = "5.1"
 Test = "1"
-TestExtras = "0.2"
+TestExtras = "0.2,0.3"
 TupleTools = "1.1"
 VectorInterface = "0.4"
 julia = "1.10"

docs/Project.toml

@@ -1,5 +1,9 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
+TensorKitSectors = "13a9c161-d5da-41f0-bcbd-e1a08ae0647f"
 
 [compat]
-Documenter = "0.25 - 0.30"
+Documenter = "1"
+Random = "1"
+TensorKitSectors = "0.1"

docs/make.jl

@@ -1,15 +1,20 @@
 using Documenter
-using TensorKit
+using Random
+using TensorKit, TensorKitSectors
 
-makedocs(; modules=[TensorKit],
+pages = ["Home" => "index.md",
+         "Manual" => ["man/intro.md", "man/tutorial.md", "man/categories.md",
+                      "man/spaces.md", "man/sectors.md", "man/tensors.md"],
+         "Library" => ["lib/sectors.md", "lib/spaces.md", "lib/tensors.md"],
+         "Index" => ["index/index.md"]]
+
+makedocs(; modules=[TensorKit, TensorKitSectors],
          sitename="TensorKit.jl",
          authors="Jutho Haegeman",
+         warnonly=[:missing_docs, :cross_references],
          format=Documenter.HTML(; prettyurls=get(ENV, "CI", nothing) == "true",
                                 mathengine=MathJax()),
-         pages=["Home" => "index.md",
-                "Manual" => ["man/intro.md", "man/tutorial.md", "man/categories.md",
-                             "man/spaces.md", "man/sectors.md", "man/tensors.md"],
-                "Library" => ["lib/sectors.md", "lib/spaces.md", "lib/tensors.md"],
-                "Index" => ["index/index.md"]])
+         pages=pages,
+         pagesonly=true)
 
 deploydocs(; repo="github.com/Jutho/TensorKit.jl.git", push_preview=true)

docs/src/lib/sectors.md

@@ -22,7 +22,6 @@ FermionNumber
 FermionSpin
 FibonacciAnyon
 IsingAnyon
-FusionTree
 ```
 
 ## Useful constants
@@ -35,16 +34,50 @@ Irrep
 Base.one(::Sector)
 dual(::Sector)
 Nsymbol
+⊗
 Fsymbol
 Rsymbol
 Bsymbol
 dim(::Sector)
 frobeniusschur
 twist(::Sector)
 Base.isreal(::Type{<:Sector})
-TensorKit.vertex_labeltype
-TensorKit.vertex_ind2label
-⊠(::Sector, ::Sector)
+TensorKitSectors.sectorscalartype
+deligneproduct(::Sector, ::Sector)
+```
+
+Compile all revelant methods for a sector:
+
+```@docs
+TensorKitSectors.precompile_sector
+```
+
+
+## Types and methods for groups
+
+Types and constants:
+
+```julia
+# TODO: add documentation for the following types
+Group
+TensorKitSectors.AbelianGroup
+U₁
+ℤ{N} where N
+SU{N} where N
+const SU₂ = SU{2}
+ProductGroup
+```
+
+Specific methods:
+
+```@docs
+×
+```
+
+
+## Methods for defining and generating fusion trees
+```@docs
+FusionTree
 fusiontrees(uncoupled::NTuple{N,I}, coupled::I,
                      isdual::NTuple{N,Bool}) where {N,I<:Sector}
 ```
@@ -63,16 +96,23 @@ braid(f::FusionTree{I,N}, levels::NTuple{N,Int}, p::NTuple{N,Int}) where {I<:Sec
 permute(f::FusionTree{I,N}, p::NTuple{N,Int}) where {I<:Sector,N}
 ```
 
-These can be composed to manipulate fusion-splitting tree pairs, for which the following
-methods are defined:
+These can be composed to implement elementary manipulations of fusion-splitting tree pairs,
+according to the following methods
+
+```julia
+# TODO: add documentation for the following methods
+TensorKit.bendright
+TensorKit.bendleft
+TensorKit.foldright
+TensorKit.foldleft
+TensorKit.cycleclockwise
+TensorKit.cycleanticlockwise
+```
 
+Finally, these are used to define large manipulations of fusion-splitting tree pairs, which
+are then used in the index manipulation of `AbstractTensorMap` objects. The following methods
+defined on fusion splitting tree pairs have an associated definition for tensors.
 ```@docs
-bendright
-bendleft
-foldright
-foldleft
-cycleclockwise
-cycleanticlockwise
 repartition
 transpose(f₁::FusionTree{I}, f₂::FusionTree{I},
                         p1::IndexTuple{N₁}, p2::IndexTuple{N₂}) where {I<:Sector,N₁,N₂}

docs/src/lib/spaces.md

@@ -6,6 +6,8 @@ CurrentModule = TensorKit
 
 ## Type hierarchy
 
+The following types are defined to characterise vector spaces and their properties:
+
 ```@docs
 Field
 VectorSpace
@@ -19,21 +21,48 @@ ProductSpace
 HomSpace
 ```
 
+together with the following specific types for encoding the inner product structure of
+a space:
+
+```@docs
+InnerProductStyle
+```
+
 ## Useful constants
+
+The following constants are defined to easily create the concrete type of `GradedSpace`
+associated with a given type of sector.
+
 ```@docs
 Vect
 Rep
-ZNSpace{N}
-Z2Space
-Z3Space
-Z4Space
-U1Space
-SU2Space
-CU1Space
+```
+
+In this respect, there are also a number of type aliases for the `GradedSpace` types
+associated with the most common sectors, namely
+
+```julia
+const ZNSpace{N} = Vect[ZNIrrep{N}]
+const Z2Space = ZNSpace{2}
+const Z3Space = ZNSpace{3}
+const Z4Space = ZNSpace{4}
+const U1Space = Rep[U₁]
+const CU1Space = Rep[CU₁]
+const SU2Space = Rep[SU₂]
+
+# Unicode alternatives
+const ℤ₂Space = Z2Space
+const ℤ₃Space = Z3Space
+const ℤ₄Space = Z4Space
+const U₁Space = U1Space
+const CU₁Space = CU1Space
+const SU₂Space = SU2Space
 ```
 
 ## Methods
+
 Methods often apply similar to e.g. spaces and corresponding tensors or tensor maps, e.g.:
+
 ```@docs
 field
 sectortype
@@ -42,33 +71,46 @@ hassector
 dim(::VectorSpace)
 dim(::ElementarySpace, ::Sector)
 dim(P::ProductSpace{<:ElementarySpace,N}, sector::NTuple{N,<:Sector}) where {N}
+dim(::HomSpace)
 dims
 blocksectors(::ProductSpace)
 blocksectors(::HomSpace)
+hasblock
 blockdim
+fusiontrees(::ProductSpace, ::Sector)
 space
 ```
 
 The following methods act specifically on `ElementarySpace` spaces:
+
 ```@docs
 isdual
 dual
 conj
 flip
-:⊕
+⊕
 oneunit
 supremum
 infimum
 ```
+
 while the following also work on both `ElementarySpace` and `ProductSpace`
 
 ```@docs
+one(::VectorSpace)
 fuse
-:⊗
+⊗(::VectorSpace, ::VectorSpace)
 ⊠(::VectorSpace, ::VectorSpace)
-one
 ismonomorphic
 isepimorphic
 isisomorphic
 insertunit
 ```
+
+There are also specific methods for `HomSpace` instances, that mimic the effect of that
+operation on the corresponding tensor maps:
+
+```@docs
+permute(::HomSpace, ::Index2Tuple)
+compose(::HomSpace{S}, ::HomSpace{S}) where {S}
+```