From ba4e27b7449d0250bde4b0542be78e62ba39a079 Mon Sep 17 00:00:00 2001 From: Jutho Date: Sun, 3 Nov 2024 23:44:35 +0100 Subject: [PATCH] expand README and add release notes --- README.md | 133 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 130 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 52fb997f..d50d1a30 100644 --- a/README.md +++ b/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("TensorKit@0.12.7") +``` + +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