Vectorize fusiontree manipulations

docs/make.jl

@@ -1,6 +1,7 @@
 using Documenter
 using Random
 using TensorKit
+using TensorKit: FusionTreePair, Index2Tuple
 using TensorKit.TensorKitSectors
 using TensorKit.MatrixAlgebraKit
 using DocumenterInterLinks

docs/src/lib/fusiontrees.md

@@ -13,8 +13,7 @@ FusionTree
 ## Methods for defining and generating fusion trees
 
 ```@docs
-fusiontrees(uncoupled::NTuple{N,I}, coupled::I,
-                     isdual::NTuple{N,Bool}) where {N,I<:Sector}
+fusiontrees(uncoupled::NTuple{N, I}, coupled::I, isdual::NTuple{N, Bool}) where {N, I<:Sector}
 ```
 
 ## Methods for manipulating fusion trees
@@ -25,31 +24,29 @@ insertat
 split
 merge
 elementary_trace
-planar_trace(f::FusionTree{I,N}, q1::IndexTuple{N₃}, q2::IndexTuple{N₃}) where {I<:Sector,N,N₃}
+planar_trace(f::FusionTree{I, N}, q::Index2Tuple{N₃, N₃}) where {I, N, N₃}
 artin_braid
-braid(f::FusionTree{I,N}, levels::NTuple{N,Int}, p::NTuple{N,Int}) where {I<:Sector,N}
-permute(f::FusionTree{I,N}, p::NTuple{N,Int}) where {I<:Sector,N}
+braid(f::FusionTree{I, N}, p::IndexTuple{N}, levels::IndexTuple{N}) where {I, N}
+permute(f::FusionTree{I, N}, p::IndexTuple{N}) where {I, N}
 ```
 
 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
+```@docs
 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
-repartition(::FusionTree{I,N₁}, ::FusionTree{I,N₂}, ::Int) where {I<:Sector,N₁,N₂}
-transpose(::FusionTree{I}, ::FusionTree{I}, ::IndexTuple{N₁}, ::IndexTuple{N₂}) where {I<:Sector,N₁,N₂}
-braid(::FusionTree{I}, ::FusionTree{I}, ::IndexTuple, ::IndexTuple, ::IndexTuple{N₁}, ::IndexTuple{N₂}) where {I<:Sector,N₁,N₂}
-permute(::FusionTree{I}, ::FusionTree{I}, ::IndexTuple{N₁}, ::IndexTuple{N₂}) where {I<:Sector,N₁,N₂}
+repartition(src::Union{FusionTreePair, FusionTreeBlock}, N::Int)
+Base.transpose(src::Union{FusionTreePair, FusionTreeBlock}, p::Index2Tuple)
+braid(src::Union{FusionTreePair, FusionTreeBlock}, p::Index2Tuple, levels::Index2Tuple)
+permute(src::Union{FusionTreePair, FusionTreeBlock}, p::Index2Tuple)
 ```

docs/src/man/sectors.md

@@ -1038,7 +1038,7 @@ value pair.
 With the elementary `artin_braid`, we can then compute a more general braid. For this, we
 provide an interface
 
-[`braid(f::FusionTree{I,N}, levels::NTuple{N,Int}, permutation::NTuple{N,Int})`](@ref braid(f::FusionTree{I,N}, levels::NTuple{N,Int}, p::NTuple{N,Int}) where {I<:Sector,N})
+[`braid(f::FusionTree{I, N}, permutation::IndexTuple{N}, levels::NTuple{N,Int})`](@ref braid(::FusionTree{I, N}, ::IndexTuple{N}, ::IndexTuple{N}) where {I, N})
 
 where the braid is specified as a permutation, such that the new sector at position `i` was
 originally at position `permutation[i]`, and where every uncoupled sector is also assigned
@@ -1065,7 +1065,7 @@ the braiding or its inverse (i.e. lines crossing over or under each other in the
 notation) and the whole operation simplifies down to a permutation. We then also support
 the interface
 
-[`permute(f::FusionTree{I,N}, permutation::NTuple{N,Int})`](@ref permute(f::FusionTree{I,N}, p::NTuple{N,Int}) where {I<:Sector,N})
+[`permute(f::FusionTree{I, N}, permutation::IndexTuple{N})`](@ref permute(::FusionTree{I, N}, ::IndexTuple{N}) where {I, N})
 
 Other manipulations which are sometimes needed are
 
@@ -1159,7 +1159,8 @@ the splitting tree.
 
 The `FusionTree` interface to duality and line bending is given by
 
-[`repartition(f1::FusionTree{I,N₁}, f2::FusionTree{I,N₂}, N::Int)`](@ref repartition)
+[`repartition(f::FusionTreePair{I,N₁,N₂}, N::Int)`](@ref repartition(::Union{FusionTreePair,
+FusionTreeBlock}, ::Int))
 
 which takes a splitting tree `f1` with `N₁` outgoing sectors, a fusion tree `f2` with `N₂`
 incoming sectors, and applies line bending such that the resulting splitting and fusion
@@ -1184,7 +1185,7 @@ With this basic function, we can now perform arbitrary combinations of braids or
 permutations with line bendings, to completely reshuffle where sectors appear. The
 interface provided for this is given by
 
-[`braid(f1::FusionTree{I,N₁}, f2::FusionTree{I,N₂}, levels1::NTuple{N₁,Int}, levels2::NTuple{N₂,Int}, p1::NTuple{N₁′,Int}, p2::NTuple{N₂′,Int})`](@ref braid(::FusionTree{I}, ::FusionTree{I}, ::IndexTuple, ::IndexTuple, ::IndexTuple{N₁}, ::IndexTuple{N₂}) where {I<:Sector,N₁,N₂})
+[`braid((f₁, f₂)::FusionTreePair, (p1, p2)::Index2Tuple, (levels1, levels2)::Index2Tuple)`](@ref braid(::TensorKit.FusionTreePair, ::Index2Tuple, ::Index2Tuple))
 
 where we now have splitting tree `f1` with `N₁` outgoing sectors, a fusion tree `f2` with
 `N₂` incoming sectors, `levels1` and `levels2` assign a level or depth to the corresponding
@@ -1211,7 +1212,7 @@ As before, there is a simplified interface for the case where
 `BraidingStyle(I) isa SymmetricBraiding` and the levels are not needed. This is simply
 given by
 
-[`permute(f1::FusionTree{I,N₁}, f2::FusionTree{I,N₂}, p1::NTuple{N₁′,Int}, p2::NTuple{N₂′,Int})`](@ref permute(::FusionTree{I}, ::FusionTree{I}, ::IndexTuple{N₁}, ::IndexTuple{N₂}) where {I<:Sector,N₁,N₂})
+[`permute((f₁, f₂)::FusionTreePair, (p1, p2)::Index2Tuple)`](@ref permute(::Union{FusionTreePair, FusionTreeBlock}, ::Index2Tuple))
 
 The `braid` and `permute` routines for double fusion trees will be the main access point for
 corresponding manipulations on tensors. As a consequence, results from this routine are

src/TensorKit.jl

@@ -123,8 +123,8 @@ using OhMyThreads
 using ScopedValues
 
 using TensorKitSectors
-import TensorKitSectors: dim, BraidingStyle, FusionStyle, ⊠, ⊗
-import TensorKitSectors: dual, type_repr
+import TensorKitSectors: dim, BraidingStyle, FusionStyle, ⊠, ⊗, ×
+import TensorKitSectors: dual, type_repr, fusiontensor
 import TensorKitSectors: twist
 
 using Base: @boundscheck, @propagate_inbounds, @constprop,
@@ -215,6 +215,19 @@ function set_num_transformer_threads(n::Int)
     return TRANSFORMER_THREADS[] = n
 end
 
+const TREEMANIPULATION_THREADS = Ref(1)
+
+get_num_manipulation_threads() = TREEMANIPULATION_THREADS[]
+
+function set_num_manipulation_threads(n::Int)
+    N = Base.Threads.nthreads()
+    if n > N
+        n = N
+        Strided._set_num_threads_warn(n)
+    end
+    return TREEMANIPULATION_THREADS[] = n
+end
+
 # Definitions and methods for tensors
 #-------------------------------------
 # general definitions

src/auxiliary/auxiliary.jl

@@ -27,6 +27,20 @@ function permutation2swaps(perm)
     return swaps
 end
 
+# one-argument version: check whether `p` is a cyclic permutation (of `1:length(p)`)
+function iscyclicpermutation(p)
+    N = length(p)
+    @inbounds for i in 1:N
+        p[mod1(i + 1, N)] == mod1(p[i] + 1, N) || return false
+    end
+    return true
+end
+# two-argument version: check whether `v1` is a cyclic permutation of `v2`
+function iscyclicpermutation(v1, v2)
+    length(v1) == length(v2) || return false
+    return iscyclicpermutation(indexin(v1, v2))
+end
+
 _kron(A, B, C, D...) = _kron(_kron(A, B), C, D...)
 function _kron(A, B)
     sA = size(A)
@@ -61,6 +75,7 @@ end
 # used in indexmanipulations: avoids the overhead of Strided.jl
 function _copyto!(A::StridedView{<:Any, 1}, B::StridedView{<:Any, 2})
     length(A) == length(B) || throw(DimensionMismatch())
+    @assert A.op === identity
 
     Adata = parent(A)
     Astr = stride(A, 1)
@@ -73,7 +88,7 @@ function _copyto!(A::StridedView{<:Any, 1}, B::StridedView{<:Any, 2})
     @inbounds for _ in axes(B, 2)
         IB = IB_1
         for _ in axes(B, 1)
-            Adata[IA += Astr] = Bdata[IB += Bstr[1]]
+            Adata[IA += Astr] = B.op(Bdata[IB += Bstr[1]])
         end
         IB_1 += Bstr[2]
     end