WIP: implementation of DiagonalTensorMap (#174)

* start implementation of DiagonalTensorMap

* further progress on DiagonalTensorMap [skip ci]

* more fixes and first tests

* a bit more functionality and tests

* resolve conflict in Project.toml

* finegrain homespace permutation and selection

* fix and add more tests

* implement suggestions and more tests

* replace compose with mul! and compose_dest

* Also rename testfile

* Extend `mul!` to include `alfa` and `beta`

* Add TensorOperations specializations

* Add show for Diagonal

* changelog, docs and final fixes

---------

Co-authored-by: Lukas Devos <[email protected]>

Author: Jutho

Changelog.md

@@ -15,6 +15,24 @@ Features that are planned to be implemented before the release of v1.0.0, in no
 
 # Changelog
 
+## v0.14
+
+### `DiagonalTensorMap` and `reduceddim`
+
+This adds a `DiagonalTensorMap` type for representing tensor maps in which all of the
+blocks are diagonal. This only makes sense for maps between a single index in the domain and
+the codomain (which are furthermore required to be the same), as otherwise the fusion and
+splitting trees from the domain and codomain to the blocked sectors would itself be
+nondiagonal. This new type will be used to capture the singular values and eigenvalues as
+tensor maps in the corresponding decompositions. The number of free parameters in a
+`DiagonalTensorMap` instance on vector space `V` is equal to `reduceddim(V)`, a new function
+that sums up the degeneracy dimension `dim(V, c)` for each of the sectors `c` in `V`. This
+function can be useful by itself and is also exported from the `TensorKit` module. An
+instance of `DiagonalTensorMap` can then be created as `DiagonalTensorMap(data, V)` where
+`data` is a vector of length `reduceddim(V)`.
+
+## v0.13
+
 ### `AbstractTensorMap{E,S,N₁,N₂}`
 
 This adds the scalar type as a parameter to the `AbstractTensorMap` type. This is useful in

docs/src/lib/sectors.md

@@ -114,8 +114,7 @@ are then used in the index manipulation of `AbstractTensorMap` objects. The foll
 defined on fusion splitting tree pairs have an associated definition for tensors.
 ```@docs
 repartition
-transpose(f₁::FusionTree{I}, f₂::FusionTree{I},
-                        p1::IndexTuple{N₁}, p2::IndexTuple{N₂}) where {I<:Sector,N₁,N₂}
-braid(f₁::FusionTree{I}, f₂::FusionTree{I}, levels1::IndexTuple, levels2::IndexTuple, p1::IndexTuple{N₁}, p2::IndexTuple{N₂}) where {I<:Sector,N₁,N₂}
-permute(f₁::FusionTree{I}, f₂::FusionTree{I}, p1::IndexTuple{N₁}, p2::IndexTuple{N₂}) 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

@@ -59,7 +59,7 @@ const CU₁Space = CU1Space
 const SU₂Space = SU2Space
 ```
 
-## Methods
+## [Methods](@id s_spacemethods)
 
 Methods often apply similar to e.g. spaces and corresponding tensors or tensor maps, e.g.:
 
@@ -70,14 +70,15 @@ sectors
 hassector
 dim(::VectorSpace)
 dim(::ElementarySpace, ::Sector)
+reduceddim
 dim(P::ProductSpace{<:ElementarySpace,N}, sector::NTuple{N,<:Sector}) where {N}
 dim(::HomSpace)
 dims
-blocksectors(::ProductSpace)
+blocksectors(P::ProductSpace{S,N}) where {S,N}
 blocksectors(::HomSpace)
 hasblock
 blockdim
-fusiontrees(::ProductSpace, ::Sector)
+fusiontrees(P::ProductSpace{S,N}, blocksector::I) where {S,N,I}
 space
 ```
 
@@ -107,10 +108,11 @@ isisomorphic
 insertunit
 ```
 
-There are also specific methods for `HomSpace` instances, that mimic the effect of that
-operation on the corresponding tensor maps:
+There are also specific methods for `HomSpace` instances, that are used in determining
+the resuling `HomSpace` after applying certain tensor operations.
 
 ```@docs
-permute(::HomSpace, ::Index2Tuple)
-compose(::HomSpace{S}, ::HomSpace{S}) 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}
 ```

docs/src/lib/tensors.md

@@ -14,6 +14,7 @@ AbstractTensorMap
 The following concrete subtypes are provided within the TensorKit library:
 ```@docs
 TensorMap
+DiagonalTensorMap
 AdjointTensorMap
 BraidingTensor
 ```
@@ -201,6 +202,11 @@ contract!
 
 ## `TensorMap` factorizations
 
+The factorisation methods come in two flavors, namely a non-destructive version where you
+can specify an additional permutation of the domain and codomain indices before the
+factorisation is performed (provided that `sectorstyle(t)` has a symmetric braiding) as
+well as a destructive version The non-destructive methods are given first:
+
 ```@docs
 leftorth
 rightorth
@@ -209,7 +215,13 @@ rightnull
 tsvd
 eigh
 eig
+eigen
 isposdef
 ```
 
+The corresponding destructive methods have an exclamation mark at the end of their name,
+and only accept the `TensorMap` object as well as the method-specific algorithm and keyword
+arguments.
+
+
 TODO: document svd truncation types