improve tests and docs

Jutho · Jutho · commit 1a2f4be3464e · 2025-02-20T18:12:04.000+01:00
diff --git a/docs/src/lib/sectors.md b/docs/src/lib/sectors.md
@@ -113,7 +113,7 @@ Finally, these are used to define large manipulations of fusion-splitting tree p
 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
+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₂}
diff --git a/docs/src/lib/spaces.md b/docs/src/lib/spaces.md
@@ -108,6 +108,14 @@ isepimorphic
 isisomorphic
 ```
 
+Inserting trivial space factors or removing such factors for `ProductSpace` instances
+can be done with the following methods.
+```@docs
+insertleftunit(::ProductSpace, ::Val{i}) where {i}
+insertrightunit(::ProductSpace, ::Val{i}) where {i}
+removeunit(::ProductSpace, ::Val{i}) where {i}
+```
+
 There are also specific methods for `HomSpace` instances, that are used in determining
 the resuling `HomSpace` after applying certain tensor operations.
 
@@ -116,6 +124,7 @@ flip(W::HomSpace{S}, I) where {S}
 TensorKit.permute(::HomSpace{S}, ::Index2Tuple{N₁,N₂}) where {S,N₁,N₂}
 TensorKit.select(::HomSpace{S}, ::Index2Tuple{N₁,N₂}) where {S,N₁,N₂}
 TensorKit.compose(::HomSpace{S}, ::HomSpace{S}) where {S}
-insertleftunit(::HomSpace, ::Int)
-insertrightunit(::HomSpace, ::Int)
+insertleftunit(::HomSpace, ::Val{i}) where {i}
+insertrightunit(::HomSpace, ::Val{i}) where {i}
+removeunit(::HomSpace, ::Val{i}) where {i}
 ```
diff --git a/docs/src/lib/tensors.md b/docs/src/lib/tensors.md
@@ -137,6 +137,13 @@ Base.getindex(::AbstractTensorMap, ::Vararg{SliceIndex})
 Base.setindex!(::AbstractTensorMap, ::Any, ::Vararg{SliceIndex})
 ```
 
+The tensor data can also be filled with random numbers via
+```@docs
+Random.rand!
+Random.randn!
+Random.randexp!
+```
+
 ## `AbstractTensorMap` operations
 
 The operations that can be performed on an `AbstractTensorMap` can be organized into the
@@ -171,14 +178,15 @@ type `add_transform!`, for additional expert-mode options that allows for additi
 scaling, as well as the selection of a custom backend.
 
 ```@docs
-permute(::AbstractTensorMap, ::Index2Tuple{N₁,N₂}; ::Bool) where {N₁,N₂}
-braid(::AbstractTensorMap, ::Index2Tuple, ::IndexTuple; ::Bool)
-transpose(::AbstractTensorMap, ::Index2Tuple; ::Bool)
-repartition(::AbstractTensorMap, ::Int, ::Int; ::Bool)
+permute(::AbstractTensorMap, ::Index2Tuple{N₁,N₂}) where {N₁,N₂}
+braid(::AbstractTensorMap, ::Index2Tuple, ::IndexTuple)
+transpose(::AbstractTensorMap, ::Index2Tuple)
+repartition(::AbstractTensorMap, ::Int, ::Int)
 flip(t::AbstractTensorMap, I)
-twist(::AbstractTensorMap, ::Int; ::Bool)
-insertleftunit(::AbstractTensorMap, ::Int)
-insertrightunit(::AbstractTensorMap, ::Int)
+twist(::AbstractTensorMap, ::Int)
+insertleftunit(::AbstractTensorMap, ::Val{i}) where {i}
+insertrightunit(::AbstractTensorMap, ::Val{i}) where {i}
+removeunit(::AbstractTensorMap, ::Val{i}) where {i}
 ```
 
 ```@docs
diff --git a/src/spaces/homspace.jl b/src/spaces/homspace.jl
@@ -180,7 +180,8 @@ Insert a trivial vector space, isomorphic to the underlying field, at position `
 which can be specified as an `Int` or as `Val(i)` for improved type stability.
 More specifically, adds a left monoidal unit or its dual.
 
-See also [`insertrightunit`](@ref), [`removeunit`](@ref).
+See also [`insertrightunit`](@ref insertrightunit(::HomSpace, ::Val{i}) where {i}),
+[`removeunit`](@ref removeunit(::HomSpace, ::Val{i}) where {i}).
 """
 function insertleftunit(W::HomSpace, ::Val{i}=Val(numind(W) + 1);
                         conj::Bool=false, dual::Bool=false) where {i}
@@ -198,7 +199,8 @@ Insert a trivial vector space, isomorphic to the underlying field, after positio
 which can be specified as an `Int` or as `Val(i)` for improved type stability.
 More specifically, adds a right monoidal unit or its dual.
 
-See also [`insertleftunit`](@ref), [`removeunit`](@ref).
+See also [`insertleftunit`](@ref insertleftunit(::HomSpace, ::Val{i}) where {i}),
+[`removeunit`](@ref removeunit(::HomSpace, ::Val{i}) where {i}).
 """
 function insertrightunit(W::HomSpace, ::Val{i}=Val(numind(W));
                          conj::Bool=false, dual::Bool=false) where {i}
@@ -216,7 +218,8 @@ This removes a trivial tensor product factor at position `1 ≤ i ≤ N`, where
 can be specified as an `Int` or as `Val(i)` for improved type stability.
 For this to work, the space at position `i` has to be isomorphic to the field of scalars.
 
-This operation undoes the work of [`insertleftunit`](@ref) or [`insertrightunit`](@ref).
+This operation undoes the work of [`insertleftunit`](@ref insertleftunit(::HomSpace, ::Val{i}) where {i}) 
+and [`insertrightunit`](@ref insertrightunit(::HomSpace, ::Val{i}) where {i}).
 """
 function removeunit(P::HomSpace, ::Val{i}) where {i}
     if i ≤ numout(P)
diff --git a/src/spaces/productspace.jl b/src/spaces/productspace.jl
@@ -252,7 +252,7 @@ Insert a trivial vector space, isomorphic to the underlying field, at position `
 which can be specified as an `Int` or as `Val(i)` for improved type stability.
 More specifically, adds a left monoidal unit or its dual.
 
-See also [`insertrightunit`](@ref), [`removeunit`](@ref).
+See also [`insertrightunit`](@ref insertrightunit(::ProductSpace, ::Val{i}) where {i}), [`removeunit`](@ref removeunit(::ProductSpace, ::Val{i}) where {i}).
 """
 function insertleftunit(P::ProductSpace, ::Val{i}=Val(length(P) + 1);
                         conj::Bool=false, dual::Bool=false) where {i}
@@ -273,7 +273,7 @@ Insert a trivial vector space, isomorphic to the underlying field, after positio
 which can be specified as an `Int` or as `Val(i)` for improved type stability.
 More specifically, adds a right monoidal unit or its dual.
 
-See also [`insertleftunit`](@ref), [`removeunit`](@ref).
+See also [`insertleftunit`](@ref insertleftunit(::ProductSpace, ::Val{i}) where {i}), [`removeunit`](@ref removeunit(::ProductSpace, ::Val{i}) where {i}).
 """
 function insertrightunit(P::ProductSpace, ::Val{i}=Val(length(P));
                          conj::Bool=false, dual::Bool=false) where {i}
@@ -294,7 +294,8 @@ This removes a trivial tensor product factor at position `1 ≤ i ≤ N`, where
 can be specified as an `Int` or as `Val(i)` for improved type stability.
 For this to work, that factor has to be isomorphic to the field of scalars.
 
-This operation undoes the work of [`insertunit`](@ref).
+This operation undoes the work of [`insertleftunit`](@ref insertleftunit(::ProductSpace, ::Val{i}) where {i}) 
+and [`insertrightunit`](@ref insertrightunit(::ProductSpace, ::Val{i}) where {i}).
 """
 function removeunit(P::ProductSpace, ::Val{i}) where {i}
     1 ≤ i ≤ length(P) || _boundserror(P, i)
diff --git a/src/tensors/indexmanipulations.jl b/src/tensors/indexmanipulations.jl
@@ -303,7 +303,8 @@ More specifically, adds a left monoidal unit or its dual.
 
 If `copy=false`, `tdst` might share data with `tsrc` whenever possible. Otherwise, a copy is always made.
 
-See also [`insertrightunit`](@ref) and [`removeunit`](@ref).
+See also [`insertrightunit`](@ref insertrightunit(::AbstractTensorMap, ::Val{i}) where {i}),
+[`removeunit`](@ref removeunit(::AbstractTensorMap, ::Val{i}) where {i}).
 """
 function insertleftunit(t::AbstractTensorMap, ::Val{i}=Val(numind(t) + 1);
                         copy::Bool=false, conj::Bool=false, dual::Bool=false) where {i}
@@ -329,7 +330,8 @@ More specifically, adds a right monoidal unit or its dual.
 
 If `copy=false`, `tdst` might share data with `tsrc` whenever possible. Otherwise, a copy is always made.
 
-See also [`insertleftunit`](@ref) and [`removeunit`](@ref).
+See also [`insertleftunit`](@ref insertleftunit(::AbstractTensorMap, ::Val{i}) where {i}),
+[`removeunit`](@ref removeunit(::AbstractTensorMap, ::Val{i}) where {i}).
 """
 function insertrightunit(t::AbstractTensorMap, ::Val{i}=Val(numind(t));
                          copy::Bool=false, conj::Bool=false, dual::Bool=false) where {i}
@@ -354,7 +356,8 @@ For this to work, that factor has to be isomorphic to the field of scalars.
 
 If `copy=false`, `tdst` might share data with `tsrc` whenever possible. Otherwise, a copy is always made.
 
-This operation undoes the work of [`insertunit`](@ref).
+This operation undoes the work of [`insertleftunit`](@ref insertleftunit(::AbstractTensorMap, ::Val{i}) where {i}) 
+and [`insertrightunit`](@ref insertrightunit(::AbstractTensorMap, ::Val{i}) where {i}).
 """
 function removeunit(t::AbstractTensorMap, ::Val{i}; copy::Bool=false) where {i}
     W = removeunit(space(t), Val(i))
diff --git a/src/tensors/tensor.jl b/src/tensors/tensor.jl
@@ -194,14 +194,14 @@ for randf in (:rand, :randn, :randexp, :randisometry)
         
     Generate a tensor `t` with entries generated by `$randf`.
 
-    See also [`($randf)!`](@ref).
+    See also [`Random.$(randf)!`](@ref).
     """
     _docstr! = """
         $(randf)!([rng=default_rng()], t::AbstractTensorMap) -> t
         
     Fill the tensor `t` with entries generated by `$(randf)!`.
 
-    See also [`($randf)`](@ref).
+    See also [`Random.$(randf)`](@ref).
     """
 
     if randf != :randisometry
@@ -467,6 +467,8 @@ Return a view into the data slice of `t` corresponding to the splitting - fusion
 `(dims(codomain(t), f₁.uncoupled)..., dims(domain(t), f₂.uncoupled))` is returned which
 represents the slice of `block(t, c)` whose row indices correspond to `f₁.uncoupled` and
 column indices correspond to `f₂.uncoupled`.
+
+See also [`Base.setindex!(::TensorMap{T,S,N₁,N₂}, ::Any, ::FusionTree{I,N₁}, ::FusionTree{I,N₂}) where {T,S,N₁,N₂,I<:Sector}`](@ref)
 """
 @inline function Base.getindex(t::TensorMap{T,S,N₁,N₂},
                                f₁::FusionTree{I,N₁},
@@ -503,7 +505,7 @@ Copies `v` into the  data slice of `t` corresponding to the splitting - fusion t
 of size `(dims(codomain(t), f₁.uncoupled)..., dims(domain(t), f₂.uncoupled))` using
 `Base.copy!`.
 
-See also [`Base.getindex(::TensorMap{T,S,N₁,N₂,I<:Sector}, ::FusionTree{I<:Sector,N₁}, ::FusionTree{I<:Sector,N₂})`](@ref)
+See also [`Base.getindex(::TensorMap{T,S,N₁,N₂}, ::FusionTree{I,N₁}, ::FusionTree{I,N₂}) where {T,S,N₁,N₂,I<:Sector}`](@ref)
 """
 @propagate_inbounds function Base.setindex!(t::TensorMap{T,S,N₁,N₂},
                                             v,
diff --git a/test/tensors.jl b/test/tensors.jl
@@ -1,54 +1,3 @@
-Vtr = (ℂ^3,
-       (ℂ^4)',
-       ℂ^5,
-       ℂ^6,
-       (ℂ^7)')
-Vℤ₂ = (ℂ[Z2Irrep](0 => 1, 1 => 1),
-       ℂ[Z2Irrep](0 => 1, 1 => 2)',
-       ℂ[Z2Irrep](0 => 3, 1 => 2)',
-       ℂ[Z2Irrep](0 => 2, 1 => 3),
-       ℂ[Z2Irrep](0 => 2, 1 => 5))
-Vfℤ₂ = (ℂ[FermionParity](0 => 1, 1 => 1),
-        ℂ[FermionParity](0 => 1, 1 => 2)',
-        ℂ[FermionParity](0 => 3, 1 => 2)',
-        ℂ[FermionParity](0 => 2, 1 => 3),
-        ℂ[FermionParity](0 => 2, 1 => 5))
-Vℤ₃ = (ℂ[Z3Irrep](0 => 1, 1 => 2, 2 => 2),
-       ℂ[Z3Irrep](0 => 3, 1 => 1, 2 => 1),
-       ℂ[Z3Irrep](0 => 2, 1 => 2, 2 => 1)',
-       ℂ[Z3Irrep](0 => 1, 1 => 2, 2 => 3),
-       ℂ[Z3Irrep](0 => 1, 1 => 3, 2 => 3)')
-VU₁ = (ℂ[U1Irrep](0 => 1, 1 => 2, -1 => 2),
-       ℂ[U1Irrep](0 => 3, 1 => 1, -1 => 1),
-       ℂ[U1Irrep](0 => 2, 1 => 2, -1 => 1)',
-       ℂ[U1Irrep](0 => 1, 1 => 2, -1 => 3),
-       ℂ[U1Irrep](0 => 1, 1 => 3, -1 => 3)')
-VfU₁ = (ℂ[FermionNumber](0 => 1, 1 => 2, -1 => 2),
-        ℂ[FermionNumber](0 => 3, 1 => 1, -1 => 1),
-        ℂ[FermionNumber](0 => 2, 1 => 2, -1 => 1)',
-        ℂ[FermionNumber](0 => 1, 1 => 2, -1 => 3),
-        ℂ[FermionNumber](0 => 1, 1 => 3, -1 => 3)')
-VCU₁ = (ℂ[CU1Irrep]((0, 0) => 1, (0, 1) => 2, 1 => 1),
-        ℂ[CU1Irrep]((0, 0) => 3, (0, 1) => 0, 1 => 1),
-        ℂ[CU1Irrep]((0, 0) => 1, (0, 1) => 0, 1 => 2)',
-        ℂ[CU1Irrep]((0, 0) => 2, (0, 1) => 2, 1 => 1),
-        ℂ[CU1Irrep]((0, 0) => 2, (0, 1) => 1, 1 => 2)')
-VSU₂ = (ℂ[SU2Irrep](0 => 3, 1 // 2 => 1),
-        ℂ[SU2Irrep](0 => 2, 1 => 1),
-        ℂ[SU2Irrep](1 // 2 => 1, 1 => 1)',
-        ℂ[SU2Irrep](0 => 2, 1 // 2 => 2),
-        ℂ[SU2Irrep](0 => 1, 1 // 2 => 1, 3 // 2 => 1)')
-VfSU₂ = (ℂ[FermionSpin](0 => 3, 1 // 2 => 1),
-         ℂ[FermionSpin](0 => 2, 1 => 1),
-         ℂ[FermionSpin](1 // 2 => 1, 1 => 1)',
-         ℂ[FermionSpin](0 => 2, 1 // 2 => 2),
-         ℂ[FermionSpin](0 => 1, 1 // 2 => 1, 3 // 2 => 1)')
-# VSU₃ = (ℂ[SU3Irrep]((0, 0, 0) => 3, (1, 0, 0) => 1),
-#     ℂ[SU3Irrep]((0, 0, 0) => 3, (2, 0, 0) => 1)',
-#     ℂ[SU3Irrep]((1, 1, 0) => 1, (2, 1, 0) => 1),
-#     ℂ[SU3Irrep]((1, 0, 0) => 1, (2, 0, 0) => 1),
-#     ℂ[SU3Irrep]((0, 0, 0) => 1, (1, 0, 0) => 1, (1, 1, 0) => 1)')
-
 for V in (Vtr, Vℤ₂, Vfℤ₂, Vℤ₃, VU₁, VfU₁, VCU₁, VSU₂, VfSU₂)#, VSU₃)
     V1, V2, V3, V4, V5 = V
     @assert V3 * V4 * V2 ≿ V1' * V5' # necessary for leftorth tests
