Initial docs update

docs/src/blocktensor.md

@@ -0,0 +1,82 @@
+## `AbstractBlockTensorMap`
+
+The main type of this package is `BlockTensorMap`, which is a generalization of `AbstractTensorMap` to the case where the tensor is a concatenation of other tensors.
+The design philosophy is to have the same interface as `AbstractTensorMap`, with the additional ability to query the individual tensors that make up the block tensor, as `AbstractArray{AbstractTensorMap}`.
+
+### Type hierarchy
+
+The type hierarchy of the `AbstractBlockTensorMap` consists of one abstract and two concrete subtypes of `AbstractBlockTensorMap`:
+
+```julia
+BlockTensorMap <: AbstractBlockTensorMap <: AbstractTensorMap
+SparseBlockTensorMap <: AbstractBlockTensorMap <: AbstractTensorMap
+```
+
+In particular, these structures hold the structural information as a `HomSpace` of `SumSpace`s, as defined in [`SumSpaces`](@ref), as well as the individual tensors that make up the block tensor.
+For `BlockTensorMap`, the list of tensors is dense, thus they are stored in an `Array{AbstractTensorMap,N}`, where `N` is the total number of indices of a tensor.
+For `SparseBlockTensorMap`, this is not the case, and the list of tensors is stored in a `Dict{CartesianIndex{N},AbstractTensorMap}`.
+
+The elementary constructors for these types are:
+
+```julia
+BlockTensorMap{TT}(undef, space::TensorMapSumSpace)
+SparseBlockTensorMap{TT}(undef, space::TensorMapSumSpace)
+```
+
+where `TT<:AbstractTensorMap` is the type of the individual tensors, and `space` is the `TensorMapSumSpace` that defines the structure of the block tensor.
+
+Similarly, they can be initialized from a list of tensors:
+
+```julia
+BlockTensorMap{TT}(tensors::AbstractArray{AbstractTensorMap,N}, space::TensorMapSumSpace)
+SparseBlockTensorMap{TT}(tensors::Dict{CartesianIndex{N},AbstractTensorMap}, space::TensorMapSumSpace)
+```
+
+!!!note In analogy to `TensorKit`, most of the functionality that requires a `space` object can equally well be called in terms of `codomain(space), domain(space)`, if that is more convenient.
+
+### Indexing
+
+For indexing operators, `AbstractBlockTensorMap` behaves like an `AbstractArray{AbstractTensorMap}`, and the individual tensors can be accessed via the `getindex` and `setindex!` functions.
+In particular, the `getindex` function returns a `TT` object, and the `setindex!` function expects a `TT` object.
+
+```julia
+
+```
+
+Slicing operations are also supported, and the `AbstractBlockTensorMap` can be sliced in the same way as an `AbstractArray{AbstractTensorMap}`.
+There is however one elementary difference: as the slices still contain tensors with the same amount of legs, there can be no reduction in the number of dimensions.
+In particular, in contrast to `AbstractArray`, scalar dimensions are not discarded:
+
+```julia
+
+```
+
+### VectorInterface.jl
+
+As part of the `TensorKit` interface, `AbstractBlockTensorMap` also implements `VectorInterface`.
+This means that you can efficiently add, scale, and compute the inner product of `AbstractBlockTensorMap` objects.
+
+```julia
+
+```
+
+### TensorOperations.jl
+
+The `TensorOperations.jl` interface is also implemented for `AbstractBlockTensorMap`.
+In particular, the `AbstractBlockTensorMap` can be contracted with other `AbstractBlockTensorMap` objects, as well as with `AbstractTensorMap` objects.
+In order for that mix to work, the `AbstractTensorMap` objects are automatically converted to `AbstractBlockTensorMap` objects with a single tensor, i.e. the sum spaces will be a sum of one space.
+
+```julia
+
+```
+
+### Factorizations
+
+Currently, there is only rudimentary support for factorizations of `AbstractBlockTensorMap` objects.
+In particular, the implementations are not yet optimized for performance, and the factorizations are typically carried out by mapping to a dense tensor, and then performing the factorization on that tensor.
+
+```julia
+
+```
+
+!!!note Most factorizations do not need to retain the additional imposed block structure. In particular, constructions of orthogonal bases will typically mix up the subspaces, and as such the resulting vector spaces will be `SumSpace`s of a single term.

docs/src/index.md

@@ -0,0 +1,36 @@
+# BlockTensorKit.jl
+
+*A Julia package for handling arrays-of-tensors, built on top of [TensorKit.jl](https://github.com/Jutho/TensorKit.jl)*
+
+```@meta
+CurrentModule = TensorKit
+```
+
+## Package summary
+
+In the context of developing efficient tensor network algorithms, it can sometimes be convenient to write a tensor as a concatenation of other tensors, without explicitly merging them.
+This is helpful whenever there are some guarantees on the resulting structure, such as sparsity patterns, triangular structures, or just as a way of keeping things organized.
+One particular example, for which this package is primarily developed, is the construction of Matrix Product Operators (MPOs) that represent a sum of local operators, both on 1-dimensional geometries, but also for more general tree-like geometries.
+In those cases, the combination of an upper-triangular blocked structure, as well as efficient usage of the sparsity, can not only greatly speed up runtime, but also facilitates rapid development of novel algorithms.
+
+Mathematically speaking, we can consider these blocked tensors as acting on direct sums of vector spaces, where the indiviual vector spaces are supplied by TensorKit.
+This leads to a very natural generalization of `AbstractTensorMap`, which is able to handle arbitrary symmetries.
+
+BlockTensorKit.jl aims to provide a convenient interface to such blocked tensors.
+In particular, the central types of this package (`<:AbstractBlockTensorMap`) could be describes as having both `AbstractArray`-like interfaces, which allow indexing as well as slicing operations, and `AbstractTensorMap`-like interfaces, allowing linear algebra routines, tensor contraction and tensor factorization.
+The goal is to abstract away the need to deal with the inner structures of such tensors as much as possible, and have the ability to replace `AbstractTensorMap`s with `AbstractBlockTensorMap` without having to change the high-level code.
+
+As these kinds of operations typically appear in performance-critical sections of the code, computational efficiency and performance are high on the priority list.
+As such, a secondary aim of this package is to provide different algorithms that enable maximal usage of sparsity, multithreading, and other tricks to obtain close-to-maximal performance.
+
+## Contents of the manual
+
+The manual fort his package is separated into 4 large parts.
+The first part focusses on the spacetype that underlies these tensors, which contain the necessary information to construct them.
+This is followed by a section on `BlockTensorMap`, highlighting the capabilities and interface.
+Then, we elaborate on `SparseBlockTensorMap`, which contains the sparse variant.
+Finally, we collect all docstrings.
+
+```@contents
+Pages = ["sumspaces.md", "blocktensor.md", "sparseblocktensor.md", "lib.md"]
+```

docs/src/lib.md

@@ -0,0 +1,5 @@
+## Library index
+
+```@autodocs
+
+```

docs/src/sumspaces.md

@@ -0,0 +1,44 @@
+## Direct Sum Spaces
+
+The underlying concept that defines any array (or operator) that has some blocked structure is that of a direct sum of vector spaces.
+These spaces are a natural extension of the `TensorKit` vector spaces, and you can think of them as a way to lazily concatenate multiple vector spaces into one.
+
+### `SumSpace`
+
+In `BlockTensorKit`, we provide a type `SumSpace` that allows you to define such direct sums.
+They can be defined either directly via the constructor, or by using the `⊕` operator.
+
+```@example sumspaces
+
+```
+
+Essentially, that is all there is to it, and you can now use these `SumSpace` objects much in the same way as you would use an `IndexSpace` object in `TensorKit`.
+In particular, it adheres to the interface of `ElementarySpace`, which means that you can query the properties as you would expect.
+
+```@example sumspaces
+
+```
+
+The main difference is that the object retains the information about the individual spaces, and you can query them by indexing into the object.
+
+```@example sumspaces
+
+```
+
+### `ProductSumSpace` and `TensorMapSumSpace`
+
+Because these objects are naturally `ElementarySpace` objects, they can be used in the construction of `ProductSpace` and `HomSpace` objects, and in particular, they can be used to define the spaces of `TensorMap` objects.
+
+```@example sumspaces
+
+```
+
+### `SumSpaceIndices`
+
+Finally, since the `SumSpace` object is the underlying structure of a blocked tensor, it can be convenient to have a way to obtain the vector spaces of the constituent parts.
+For this, we provide the `SumSpaceIndices` object, which can be used to efficiently iterate over the indices of the individual spaces.
+In particular, we expose the `eachspace` function, similar to `eachindex`, to obtain such an iterator.
+
+```@example sumspaces
+
+```