expand README and add release notes

README.md

@@ -42,10 +42,137 @@ A Julia package for large-scale tensor computations, with a hint of category the
 [aqua-img]: https://raw.githubusercontent.com/JuliaTesting/Aqua.jl/master/badge.svg
 [aqua-url]: https://github.com/JuliaTesting/Aqua.jl
 
-Install via the package manager.
+## Release notes for v0.13
+
+TensorKit v0.13 brings a number of performance improvements, but also comes with a number of
+breaking changes:
+
+1. The scalar type (the `eltype` of the tensor data) is now an explicit parameter of the
+   the `TensorMap` type, and appears in the first position. As a consequence, `TensorMap{T}(undef, codomain ← domain)` can and should now be used to create a `TensorMap` with uninitialised data with scalar type `T`.
+
+2. The constructors for creating tensors with randomly initialised data, of the form
+   `TensorMap(randn, T, codomain ← domain)`, are being replaced with
+   `randn(T, codomain ← domain)`. Hence, we overload the methods `rand` and `randn` from
+   Base (actually, Random, and also `Random.randexp`) and mimick the `Array` constructors,
+   relying on the fact that we use spaces instead of integers to characterise the tensor
+   structure. As with integer-based `rand` and `randn`, a custom random number generator
+   from the `Random` module can be passed as the first argument, and the scalar type `T` is
+   optional, defaulting to `Float64`. The old constructors
+   `TensorMap(randn, T, codomain ← domain)` still exist in deprecation mode, and will be
+   removed in the 1.0 release.
+
+3. The `TensorMap` data structure has been changed (simplified), so that all tensor data now
+   resides in a single array of type `<:DenseVector`. While this should not does not lead to
+   breaking changes in the interface, it does mean that `TensorMap` objects from
+   TensorKit.jl v0.12.7 or earlier that were saved to disk using e.g. JLD2.jl, cannot simply
+   be read back in using the new version of TensorKit.jl. We provide a script below export
+   data in a format that can be read back in by TensorKit.jl v0.13.
+
+Major non-breaking changes include:
+
+* Support for [TensorOperations.jl v5](https://github.com/Jutho/TensorOperations.jl), and
+  with this the new backend and allocator support within the `@tensor` macro.
+* The part of TensorKit.jl that defines `Sector` type hierarchy and its corresponding
+  interface, as well as the implementation of all of the standard symmetries, has been
+  moved to a separate package called [TensorKitSectors.jl](https://github.com/QuantumKitHub/TensorKitSectors.jl),
+  so that it can also be used by other packages and is a more lightweight dependency.
+  TensorKitSectors.jl a direct dependency and is automatically installed when installing
+  TensorKit.jl. Furthermore, its public interface is re-exported by TensorKit.jl, so that
+  this should not have any observable consequences.
+* The `fusiontrees` iterator now iterates over `FusionTree` objects in a different order,
+  which will facilitate speeding up certain operations in the future. Furthermore, it now
+  also accepts a `ProductSpace` object as first input, instead of simply a tuple of `Sector`
+  objects. This also affects the data ordering in the `TensorMap` objects.
+* The structural information associated with a `TensorMap` object (or rather with the
+  `HomSpace` instance that represents the space to which the tensor belongs) is no longer
+  stored within the tensor, but is cached in a global (or task local) dictionary. As a
+  result, this information does not need to be recomputed when new `TensorMap` objects are
+  created, thus eliminating some overhead that can be significant in certain applications.
+
+### Transferring `TensorMap` data from older versions to v0.13:
+
+To export `TensorMap` data from TensorKit.jl v0.12.7 or earlier, you should first export the
+data there in a format that is explicit about how tensor data is associated with the
+structural part of the tensor, i.e. the splitting and fusion tree pairs. Therefore, on the 
+older version of TensorKit.jl, use the following code to save teh data
+
+```julia
+using JLD2
+filename = "choose_some_filename.jld2"
+t_dict = Dict(:space => space(t), :data => Dict((f₁, f₂) => t[f₁, f₂] for (f₁, f₂) in fusiontrees(t)))
+jldsave(filename; t_dict)
+```
+
+If you have already upgraded to TensorKit.jl v0.13, you can still install the old version in
+a separate environment, for example a temporary environment. To do this, run
+
+```julia
+]activate --temp
+]add TensorKit@0.12.7
+```
+
+or
+
+```julia
+import Pkg
+Pkg.activate(; temp = true)
+Pkg.add("[email protected]")
+```
+
+Then, in the environment where you have TensorKit.jl v0.13 installed, you can read in the
+data and reconstruct the tensor as follows:
+
+```julia
+using JLD2
+filename = "choose_some_filename.jld2"
+t_dict = jldload(filename)
+T = eltype(valtype(t_dict[:data]))
+t = TensorMap{T}(undef, t_dict[:space])
+for ((f₁, f₂), val) in t_dict[:data]
+    t[f₁, f₂] .= val
+end
+```
+
+## Overview
+
+TensorKit.jl is a package that provides a types and methods to represent and manipulate
+tensors with symmetries. The emphasis is on the structure and functionality needed to build
+tensor network algorithms for the simulation of quantum many-body systems. Such tensors are
+typically invariant under a symmetry group which acts via specific representions on each of
+the indices of the tensor. TensorKit.jl provides the functionality for constructing such
+tensors and performing typical operations such as tensor contractions and decompositions,
+thereby preserving the symmetries and exploiting them for optimal performance.
+
+While most common symmetries are already shipped with TensorKit.jl, there exist several extensions: [SUNRepresentations.jl](https://github.com/maartenvd/SUNRepresentations.jl) provides support for SU(N), while [CategoryData.jl](https://github.com/lkdvos/CategoryData.jl) incorporates a large collection of *small* fusion categories.
+Additionally, for libraries that implement tensor network algorithms on top of TensorKit.jl, check out [MPSKit.jl](https://github.com/maartenvd/MPSKit.jl), [MERAKit.jl](https://github.com/mhauru/MERAKit.jl) and [PEPSKit.jl](https://github.com/quantumghent/PEPSKit.jl).
 
 Check out the [tutorial](https://jutho.github.io/TensorKit.jl/stable/man/tutorial/) and the full [documentation](https://jutho.github.io/TensorKit.jl/stable).
 
+## Installation
+`TensorKit.jl` can be installed with the Julia package manager.
+From the Julia REPL, type `]` to enter the Pkg REPL mode and run:
+```
+pkg> add TensorKit
+```
 
-While most common symmetries are already shipped with TensorKit.jl, there exist several extensions: [SUNRepresentations.jl](https://github.com/maartenvd/SUNRepresentations.jl) provides support for SU(N), while [CategoryData.jl](https://github.com/lkdvos/CategoryData.jl) incorporates a large collection of *small* fusion categories.
-Additionally, for libraries that implement tensor network algorithms on top of TensorKit.jl, check out [MPSKit.jl](https://github.com/maartenvd/MPSKit.jl), [MERAKit.jl](https://github.com/mhauru/MERAKit.jl) and [PEPSKit.jl](https://github.com/quantumghent/PEPSKit.jl).
+Or, equivalently, via the `Pkg` API:
+```julia
+julia> import Pkg; Pkg.add("TensorKit.jl")
+```
+
+## Documentation
+
+-   [**STABLE**][docs-stable-url] - **documentation of the most recently tagged version.**
+-   [**DEVEL**][docs-dev-url] - *documentation of the in-development version.*
+
+## Project Status
+
+The package is tested against Julia versions `1.8`, `1.10` and the latest `1.x` release, as
+well as against teh nightly builds of the Julia `master` branch on Linux, macOS, and Windows
+platforms with a 64-bit architecture.
+
+## Questions and Contributions
+
+Contributions are very welcome, as are feature requests and suggestions. Please open an [issue][issues-url] if you encounter any problems.
+
+[issues-url]: https://github.com/Jutho/TensorKit.jl/issues