insertunit and removeunit using Val (#224)

* insertunit and removeunit using Val

* more homspace tests

* improve tests and docs

Author: Jutho

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₂}

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}
 ```

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

src/spaces/homspace.jl

@@ -174,52 +174,58 @@ function compose(W::HomSpace{S}, V::HomSpace{S}) where {S}
 end
 
 """
-    insertleftunit(W::HomSpace, i::Int=numind(W) + 1; conj=false, dual=false)
+    insertleftunit(W::HomSpace, i=numind(W) + 1; conj=false, dual=false)
 
-Insert a trivial vector space, isomorphic to the underlying field, at position `i`.
+Insert a trivial vector space, isomorphic to the underlying field, at position `i`,
+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}).
 """
-@constprop :aggressive function insertleftunit(W::HomSpace, i::Int=numind(W) + 1;
-                                               conj::Bool=false, dual::Bool=false)
+function insertleftunit(W::HomSpace, ::Val{i}=Val(numind(W) + 1);
+                        conj::Bool=false, dual::Bool=false) where {i}
     if i ≤ numout(W)
-        return insertleftunit(codomain(W), i; conj, dual) ← domain(W)
+        return insertleftunit(codomain(W), Val(i); conj, dual) ← domain(W)
     else
-        return codomain(W) ← insertleftunit(domain(W), i - numout(W); conj, dual)
+        return codomain(W) ← insertleftunit(domain(W), Val(i - numout(W)); conj, dual)
     end
 end
 
 """
-    insertrightunit(W::HomSpace, i::Int=numind(W); conj=false, dual=false)
+    insertrightunit(W::HomSpace, i=numind(W); conj=false, dual=false)
 
-Insert a trivial vector space, isomorphic to the underlying field, after position `i`.
+Insert a trivial vector space, isomorphic to the underlying field, after position `i`,
+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}).
 """
-@constprop :aggressive function insertrightunit(W::HomSpace, i::Int=numind(W);
-                                                conj::Bool=false, dual::Bool=false)
+function insertrightunit(W::HomSpace, ::Val{i}=Val(numind(W));
+                         conj::Bool=false, dual::Bool=false) where {i}
     if i ≤ numout(W)
-        return insertrightunit(codomain(W), i; conj, dual) ← domain(W)
+        return insertrightunit(codomain(W), Val(i); conj, dual) ← domain(W)
     else
-        return codomain(W) ← insertrightunit(domain(W), i - numout(W); conj, dual)
+        return codomain(W) ← insertrightunit(domain(W), Val(i - numout(W)); conj, dual)
     end
 end
 
 """
-    removeunit(P::HomSpace, i::Int)
+    removeunit(P::HomSpace, i)
 
-This removes a trivial tensor product factor at position `1 ≤ i ≤ N`.
-For this to work, that factor has to be isomorphic to the field of scalars.
+This removes a trivial tensor product factor at position `1 ≤ i ≤ N`, where `i`
+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}).
 """
-@constprop :aggressive function removeunit(P::HomSpace, i::Int)
+function removeunit(P::HomSpace, ::Val{i}) where {i}
     if i ≤ numout(P)
-        return removeunit(codomain(P), i) ← domain(P)
+        return removeunit(codomain(P), Val(i)) ← domain(P)
     else
-        return codomain(P) ← removeunit(domain(P), i - numout(P))
+        return codomain(P) ← removeunit(domain(P), Val(i - numout(P)))
     end
 end
 

src/spaces/productspace.jl

@@ -248,13 +248,14 @@ fuse(P::ProductSpace{S}) where {S<:ElementarySpace} = fuse(P.spaces...)
 """
     insertleftunit(P::ProductSpace, i::Int=length(P) + 1; conj=false, dual=false)
 
-Insert a trivial vector space, isomorphic to the underlying field, at position `i`.
+Insert a trivial vector space, isomorphic to the underlying field, at position `i`,
+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, i::Int=length(P) + 1;
-                        conj::Bool=false, dual::Bool=false)
+function insertleftunit(P::ProductSpace, ::Val{i}=Val(length(P) + 1);
+                        conj::Bool=false, dual::Bool=false) where {i}
     u = oneunit(spacetype(P))
     if dual
         u = TensorKit.dual(u)
@@ -266,15 +267,16 @@ function insertleftunit(P::ProductSpace, i::Int=length(P) + 1;
 end
 
 """
-    insertrightunit(P::ProductSpace, i::Int=lenght(P); conj=false, dual=false)
+    insertrightunit(P::ProductSpace, i=lenght(P); conj=false, dual=false)
 
-Insert a trivial vector space, isomorphic to the underlying field, after position `i`.
+Insert a trivial vector space, isomorphic to the underlying field, after position `i`,
+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, i::Int=length(P);
-                         conj::Bool=false, dual::Bool=false)
+function insertrightunit(P::ProductSpace, ::Val{i}=Val(length(P));
+                         conj::Bool=false, dual::Bool=false) where {i}
     u = oneunit(spacetype(P))
     if dual
         u = TensorKit.dual(u)
@@ -288,12 +290,14 @@ end
 """
     removeunit(P::ProductSpace, i::Int)
 
-This removes a trivial tensor product factor at position `1 ≤ i ≤ N`.
+This removes a trivial tensor product factor at position `1 ≤ i ≤ N`, where `i`
+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, i::Int)
+function removeunit(P::ProductSpace, ::Val{i}) where {i}
     1 ≤ i ≤ length(P) || _boundserror(P, i)
     isisomorphic(P[i], oneunit(P[i])) || _nontrivialspaceerror(P, i)
     return ProductSpace{spacetype(P)}(TupleTools.deleteat(P.spaces, i))

src/spaces/vectorspaces.jl

@@ -201,6 +201,18 @@ function Base.conj(V::ElementarySpace)
     return V
 end
 
+# In the following, X can be a ProductSpace, a HomSpace or an AbstractTensorMap
+# TODO: should we deprecate those in the future?
+@constprop :aggressive function insertleftunit(X, i::Int; kwargs...)
+    return insertleftunit(X, Val(i); kwargs...)
+end
+@constprop :aggressive function insertrightunit(X, i::Int; kwargs...)
+    return insertrightunit(X, Val(i); kwargs...)
+end
+@constprop :aggressive function removeunit(X, i::Int; kwargs...)
+    return removeunit(X, Val(i); kwargs...)
+end
+
 # trait to describe the inner product type of vector spaces
 abstract type InnerProductStyle end
 struct NoInnerProduct <: InnerProductStyle end # no inner product

src/tensors/indexmanipulations.jl

@@ -292,81 +292,84 @@ See [`twist!`](@ref) for storing the result in place.
 """
 twist(t::AbstractTensorMap, i; inv::Bool=false) = twist!(copy(t), i; inv)
 
+# Methods which change the number of indices, implement using `Val(i)` for type inference
 """
-    insertleftunit(tsrc::AbstractTensorMap, i::Int=numind(t) + 1;
+    insertleftunit(tsrc::AbstractTensorMap, i=numind(t) + 1;
                    conj=false, dual=false, copy=false) -> tdst
 
-Insert a trivial vector space, isomorphic to the underlying field, at position `i`.
+Insert a trivial vector space, isomorphic to the underlying field, at position `i`,
+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.
 
 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}).
 """
-@constprop :aggressive function insertleftunit(t::AbstractTensorMap, i::Int=numind(t) + 1;
-                                               copy::Bool=true, conj::Bool=false,
-                                               dual::Bool=false)
-    W = insertleftunit(space(t), i; conj, dual)
-    tdst = similar(t, W)
-    for (c, b) in blocks(t)
-        copy!(block(tdst, c), b)
+function insertleftunit(t::AbstractTensorMap, ::Val{i}=Val(numind(t) + 1);
+                        copy::Bool=false, conj::Bool=false, dual::Bool=false) where {i}
+    W = insertleftunit(space(t), Val(i); conj, dual)
+    if t isa TensorMap
+        return TensorMap{scalartype(t)}(copy ? Base.copy(t.data) : t.data, W)
+    else
+        tdst = similar(t, W)
+        for (c, b) in blocks(t)
+            copy!(block(tdst, c), b)
+        end
+        return tdst
     end
-    return tdst
-end
-@constprop :aggressive function insertleftunit(t::TensorMap, i::Int=numind(t) + 1;
-                                               copy::Bool=false, conj::Bool=false,
-                                               dual::Bool=false)
-    W = insertleftunit(space(t), i; conj, dual)
-    return TensorMap{scalartype(t)}(copy ? Base.copy(t.data) : t.data, W)
 end
 
 """
-    insertrightunit(tsrc::AbstractTensorMap, i::Int=numind(t);
+    insertrightunit(tsrc::AbstractTensorMap, i=numind(t);
                     conj=false, dual=false, copy=false) -> tdst
 
-Insert a trivial vector space, isomorphic to the underlying field, after position `i`.
+Insert a trivial vector space, isomorphic to the underlying field, after position `i`,
+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.
 
 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}).
 """
-@constprop :aggressive function insertrightunit(t::AbstractTensorMap, i::Int=numind(t);
-                                                copy::Bool=true, kwargs...)
-    W = insertrightunit(space(t), i; kwargs...)
-    tdst = similar(t, W)
-    for (c, b) in blocks(t)
-        copy!(block(tdst, c), b)
+function insertrightunit(t::AbstractTensorMap, ::Val{i}=Val(numind(t));
+                         copy::Bool=false, conj::Bool=false, dual::Bool=false) where {i}
+    W = insertrightunit(space(t), Val(i); conj, dual)
+    if t isa TensorMap
+        return TensorMap{scalartype(t)}(copy ? Base.copy(t.data) : t.data, W)
+    else
+        tdst = similar(t, W)
+        for (c, b) in blocks(t)
+            copy!(block(tdst, c), b)
+        end
+        return tdst
     end
-    return tdst
-end
-@constprop :aggressive function insertrightunit(t::TensorMap, i::Int=numind(t);
-                                                copy::Bool=false, kwargs...)
-    W = insertrightunit(space(t), i; kwargs...)
-    return TensorMap{scalartype(t)}(copy ? Base.copy(t.data) : t.data, W)
 end
 
 """
-    removeunit(tsrc::AbstractTensorMap, i::Int; copy=false) -> tdst
+    removeunit(tsrc::AbstractTensorMap, i; copy=false) -> tdst
 
-This removes a trivial tensor product factor at position `1 ≤ i ≤ N`.
+This removes a trivial tensor product factor at position `1 ≤ i ≤ N`, where `i`
+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.
 
 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}).
 """
-@constprop :aggressive function removeunit(t::TensorMap, i::Int; copy::Bool=false)
-    W = removeunit(space(t), i)
-    return TensorMap{scalartype(t)}(copy ? Base.copy(t.data) : t.data, W)
-end
-@constprop :aggressive function removeunit(t::AbstractTensorMap, i::Int; copy::Bool=true)
-    W = removeunit(space(t), i)
-    tdst = similar(t, W)
-    for (c, b) in blocks(t)
-        copy!(block(tdst, c), b)
+function removeunit(t::AbstractTensorMap, ::Val{i}; copy::Bool=false) where {i}
+    W = removeunit(space(t), Val(i))
+    if t isa TensorMap
+        return TensorMap{scalartype(t)}(copy ? Base.copy(t.data) : t.data, W)
+    else
+        tdst = similar(t, W)
+        for (c, b) in blocks(t)
+            copy!(block(tdst, c), b)
+        end
+        return tdst
     end
-    return tdst
 end
 
 # Fusing and splitting

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,