Merge pull request #137 from lkdvos/v4

Version 4 (WIP)

Author: Jutho

.github/workflows/ci.yml

@@ -10,7 +10,6 @@ jobs:
       fail-fast: false
       matrix:
         version:
-          - '1.4' # minimal version
           - '1.6' # LTS version
           - '1' # automatically expands to the latest stable 1.x release of Julia
         os:

.github/workflows/docs.yml

@@ -12,7 +12,7 @@ jobs:
       - uses: actions/checkout@v2
       - uses: julia-actions/setup-julia@latest
         with:
-          version: '1.6'
+          version: '1'
       - name: Install dependencies
         run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
       - name: Build and deploy

.github/workflows/format_check.yml

@@ -0,0 +1,42 @@
+name: format-check
+
+on:
+  push:
+    branches:
+      - 'master'
+      - 'release-'
+    tags: '*'
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        julia-version: [1]
+        julia-arch: [x86]
+        os: [ubuntu-latest]
+    steps:
+      - uses: julia-actions/setup-julia@latest
+        with:
+          version: ${{ matrix.julia-version }}
+
+      - uses: actions/checkout@v1
+      - name: Install JuliaFormatter and format
+        # This will use the latest version by default but you can set the version like so:
+        #
+        # julia  -e 'using Pkg; Pkg.add(PackageSpec(name="JuliaFormatter", version="0.13.0"))'
+        run: |
+          julia  -e 'using Pkg; Pkg.add(PackageSpec(name="JuliaFormatter"))'
+          julia  -e 'using JuliaFormatter; format(".", verbose=true)'
+      - name: Format check
+        run: |
+          julia -e '
+          out = Cmd(`git diff --name-only`) |> read |> String
+          if out == ""
+              exit(0)
+          else
+              @error "Some files have not been formatted !!!"
+              write(stdout, out)
+              exit(1)
+          end'

.gitignore

@@ -1,3 +1,4 @@
 *.jl.cov
 *.jl.*.cov
 *.jl.mem
+Manifest.toml

LICENSE.md

@@ -1,18 +1,18 @@
 The TensorOperations.jl package is licensed under the MIT "Expat" License:
 
 > Copyright (c) 2014: Jutho Haegeman.
->
+> 
 > Permission is hereby granted, free of charge, to any person obtaining
 > a copy of this software and associated documentation files (the
 > "Software"), to deal in the Software without restriction, including
 > without limitation the rights to use, copy, modify, merge, publish,
 > distribute, sublicense, and/or sell copies of the Software, and to
 > permit persons to whom the Software is furnished to do so, subject to
 > the following conditions:
->
+> 
 > The above copyright notice and this permission notice shall be
 > included in all copies or substantial portions of the Software.
->
+> 
 > THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 > EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 > MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

Project.toml

@@ -1,27 +1,49 @@
 name = "TensorOperations"
 uuid = "6aa20fa7-93e2-5fca-9bc0-fbd0db3c71a2"
 authors = ["Jutho Haegeman"]
-version = "3.2.5"
+version = "4.0.0"
 
 [deps]
+ChainRulesCore = "d360d2e6-b24c-11e9-a2a3-2a2ae2dbcce4"
+LRUCache = "8ac3fa9e-de4c-5943-b1dc-09c6b5f20637"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+Requires = "ae029012-a4dd-5104-9daa-d747884805df"
 Strided = "5e0ebb24-38b0-5f93-81fe-25c709ecae67"
 TupleTools = "9d95972d-f1c8-5527-a6e0-b4b365fa01f6"
-LRUCache = "8ac3fa9e-de4c-5943-b1dc-09c6b5f20637"
+VectorInterface = "409d34a3-91d5-4945-b6ec-7529ddf182d8"
+cuTENSOR = "011b41b2-24ef-40a8-b3eb-fa098493e9e1"
+
+[weakdeps]
+ChainRulesCore = "d360d2e6-b24c-11e9-a2a3-2a2ae2dbcce4"
 Requires = "ae029012-a4dd-5104-9daa-d747884805df"
-CUDA = "052768ef-5323-5732-b1bb-66c8b64840ba"
+cuTENSOR = "011b41b2-24ef-40a8-b3eb-fa098493e9e1"
+
+[extensions]
+TensorOperationsChainRulesCoreExt = "ChainRulesCore"
+TensorOperationscuTENSORExt = "cuTENSOR"
 
 [compat]
-Strided = "1"
-TupleTools = "1.1"
+Aqua = "0.6"
+CUDA = "4"
+ChainRulesCore = "1"
+DynamicPolynomials = "0.5"
 LRUCache = "1"
-Requires = "0.5,1"
-CUDA = "1,2,3"
-julia = "1.4"
+Requires = "1"
+Strided = "2"
+TupleTools = "1.1"
+VectorInterface = "0.2"
+cuTENSOR = "1"
+julia = "1.6"
 
 [extras]
+Aqua = "4c88cf16-eb10-579e-8560-4a9242c79595"
+CUDA = "052768ef-5323-5732-b1bb-66c8b64840ba"
+DynamicPolynomials = "7c1d4256-1411-5781-91ec-d7bc3513ac07"
+Logging = "56ddb016-857b-54e1-b83d-db4d58db5568"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+Zygote = "e88e6eb3-aa80-5325-afca-941959d7151f"
+cuTENSOR = "011b41b2-24ef-40a8-b3eb-fa098493e9e1"
 
 [targets]
-test = ["Test", "Random"]
+test = ["Test", "Random", "DynamicPolynomials", "Zygote", "CUDA", "cuTENSOR", "Aqua", "Logging"]

README.md

@@ -1,85 +1,75 @@
 <img src="https://github.com/Jutho/TensorOperations.jl/blob/master/docs/src/assets/logo.svg" width="150">
-
 # TensorOperations.jl
-
 Fast tensor operations using a convenient Einstein index notation.
 
-| **Documentation** | **Build Status** |
-|:-----------------:|:----------------:|
-| [![][docs-stable-img]][docs-stable-url] [![][docs-dev-img]][docs-dev-url] | [![CI][ci-img]][ci-url] [![CI (Julia nightly)][ci-julia-nightly-img]][ci-julia-nightly-url] [![][codecov-img]][codecov-url] |
-
-| **Digital Object Identifier** | **Downloads** |
-|:-----------------------------:|:-------------:|
-[![DOI][doi-img]][doi-url] | [![TensorOperations Downloads][genie-img]][genie-url]
-
-[docs-dev-img]: https://img.shields.io/badge/docs-dev-blue.svg
-[docs-dev-url]: https://jutho.github.io/TensorOperations.jl/latest
-
 [docs-stable-img]: https://img.shields.io/badge/docs-stable-blue.svg
 [docs-stable-url]: https://jutho.github.io/TensorOperations.jl/stable
+[docs-dev-img]: https://img.shields.io/badge/docs-dev-blue.svg
+[docs-dev-url]: https://jutho.github.io/TensorOperations.jl/latest
+[ci-img]: https://github.com/Jutho/TensorOperations.jl/workflows/CI/badge.svg
+[ci-url]:
+  https://github.com/Jutho/TensorOperations.jl/actions?query=workflow%3ACI
+[ci-julia-nightly-img]:
+  https://github.com/Jutho/TensorOperations.jl/workflows/CI%20(Julia%20nightly)/badge.svg
+[ci-julia-nightly-url]:
+  https://github.com/Jutho/TensorOperations.jl/actions?query=workflow%3A%22CI+%28Julia+nightly%29%22
+[codecov-img]:
+  https://codecov.io/gh/Jutho/TensorOperations.jl/branch/master/graph/badge.svg
+[codecov-url]: https://codecov.io/gh/Jutho/TensorOperations.jl
+[doi-img]: https://zenodo.org/badge/DOI/10.5281/zenodo.3245497.svg
+[doi-url]: https://doi.org/10.5281/zenodo.3245497
+[downloads-img]:
+  https://shields.io/endpoint?url=https://pkgs.genieframework.com/api/v1/badge/TensorOperations
+[downloads-url]: https://pkgs.genieframework.com?packages=TensorOperations
 
-[github-img]: https://github.com/Jutho/TensorOperations.jl/workflows/CI/badge.svg
-[github-url]: https://github.com/Jutho/TensorOperations.jl/actions?query=workflow%3ACI
+|                             **Documentation**                             |                                                      **Build Status**                                                       |
+| :-----------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------------------------: |
+| [![][docs-stable-img]][docs-stable-url] [![][docs-dev-img]][docs-dev-url] | [![CI][ci-img]][ci-url] [![CI (Julia nightly)][ci-julia-nightly-img]][ci-julia-nightly-url] [![][codecov-img]][codecov-url] |
 
-[ci-img]: https://github.com/Jutho/TensorOperations.jl/workflows/CI/badge.svg
-[ci-url]: https://github.com/Jutho/TensorOperations.jl/actions?query=workflow%3ACI
+| **Digital Object Identifier** |                         **Downloads**                         |
+| :---------------------------: | :-----------------------------------------------------------: |
+|  [![DOI][doi-img]][doi-url]   | [![TensorOperations Downloads][downloads-img]][downloads-url] |
 
-[ci-julia-nightly-img]: https://github.com/Jutho/TensorOperations.jl/workflows/CI%20(Julia%20nightly)/badge.svg
-[ci-julia-nightly-url]: https://github.com/Jutho/TensorOperations.jl/actions?query=workflow%3A%22CI+%28Julia+nightly%29%22
+## What's new in v4
 
-[codecov-img]: https://codecov.io/gh/Jutho/TensorOperations.jl/branch/master/graph/badge.svg
-[codecov-url]: https://codecov.io/gh/Jutho/TensorOperations.jl
+- Moved CUDA to a package extension, to avoid unnecessary dependencies for Julia versions >= 1.9
 
-[doi-img]: https://zenodo.org/badge/DOI/10.5281/zenodo.3245497.svg
-[doi-url]: https://doi.org/10.5281/zenodo.3245497
+- The cache for temporaries has been removed, but support for something similar is now provided through explicit allocating and freeing calls within the macro.
 
-[genie-img]: https://shields.io/endpoint?url=https://pkgs.genieframework.com/api/v1/badge/TensorOperations
-[genie-url]: https://pkgs.genieframework.com?packages=TensorOperations
+- The interface for custom types has been changed and thoroughly documented, making it easier to know what to implement. This has as a consequence that more general element types of tensors are now also possible.
 
-## What's new in v3
+- There is a new interface to work with backends, to allow for dynamic switching between different implementations of the TensorOperations interface.
 
-*   Switched to CUDA.jl instead of CuArrays.jl, which effectively restricts support to
-    Julia 1.4 and higher.
-*   The default cache size for intermediate results is now the minimum of either 4GB or one
-    quarter of your total memory (obtained via `Sys.total_memory()`). Furthermore, the
-    structure (i.e. `size`) and `eltype` of the temporaries is now also used as lookup key
-    in the LRU cache, such that you can run the same code on different objects with
-    different sizes or element types, without constantly having to reallocate the
-    temporaries. Finally, the task rather than `threadid` is used to make the cache
-    compatible with concurrency at any level.
+- The `@tensor` macro now accepts keyword arguments to facilitate a variety of options that help with debugging, contraction cost and type wrapping.
 
-    As a consequence, different objects for the same temporary location can now be cached,
-    such that the cache can grow out of size quickly. Once the cache is not able to hold all
-    the temporary objects needed for your simulation, it might actually deteriorate
-    perfomance, and you might be better off disabling the cache alltogether with
-    `TensorOperations.disable_cache()`.
+- Some support for Automatic Differentiation has been added by adding reverse-mode chainrules.
 
-> **WARNING:** TensorOperations 3.0 contains breaking changes if you did implement support
-for custom array / tensor types by overloading `checked_similar_from_indices` etc.
+> **WARNING:** TensorOperations 4.0 contains breaking changes and is in general incompatible with previous versions.
 
 ### Code example
-TensorOperations.jl is mostly used through the `@tensor` macro which allows one to express
-a given operation in terms of
-[index notation](https://en.wikipedia.org/wiki/Abstract_index_notation) format, a.k.a.
-[Einstein notation](https://en.wikipedia.org/wiki/Einstein_notation)
+
+TensorOperations.jl is mostly used through the `@tensor` macro which allows one
+to express a given operation in terms of
+[index notation](https://en.wikipedia.org/wiki/Abstract_index_notation) format,
+a.k.a. [Einstein notation](https://en.wikipedia.org/wiki/Einstein_notation)
 (using Einstein's summation convention).
 
 ```julia
 using TensorOperations
-α=randn()
-A=randn(5,5,5,5,5,5)
-B=randn(5,5,5)
-C=randn(5,5,5)
-D=zeros(5,5,5)
+α = randn()
+A = randn(5, 5, 5, 5, 5, 5)
+B = randn(5, 5, 5)
+C = randn(5, 5, 5)
+D = zeros(5, 5, 5)
 @tensor begin
-    D[a,b,c] = A[a,e,f,c,f,g]*B[g,b,e] + α*C[c,a,b]
-    E[a,b,c] := A[a,e,f,c,f,g]*B[g,b,e] + α*C[c,a,b]
+    D[a, b, c] = A[a, e, f, c, f, g] * B[g, b, e] + α * C[c, a, b]
+    E[a, b, c] := A[a, e, f, c, f, g] * B[g, b, e] + α * C[c, a, b]
 end
 ```
 
-In the second to last line, the result of the operation will be stored in the preallocated
-array `D`, whereas the last line uses a different assignment operator `:=` in order to
-define and allocate a new array `E` of the correct size. The contents of `D` and `E` will
-be equal.
+In the second to last line, the result of the operation will be stored in the
+preallocated array `D`, whereas the last line uses a different assignment
+operator `:=` in order to define and allocate a new array `E` of the correct
+size. The contents of `D` and `E` will be equal.
 
 For more information, please see the documentation.

docs/make.jl

@@ -5,11 +5,13 @@ makedocs(; modules=[TensorOperations],
          sitename="TensorOperations.jl",
          authors="Jutho Haegeman",
          format=Documenter.HTML(; prettyurls=get(ENV, "CI", nothing) == "true"),
-         pages=["Home" => ["index.md",
-                           "indexnotation.md",
-                           "functions.md",
-                           "cache.md",
-                           "implementation.md"]])
+         pages=["Home" => "index.md",
+                "Manual" => ["man/indexnotation.md",
+                             "man/functions.md",
+                             "man/interface.md",
+                             "man/implementation.md",
+                             "man/autodiff.md"],
+                "Index" => "index/index.md"])
 
 # Documenter can also automatically deploy documentation to gh-pages.
 # See "Hosting Documentation" and deploydocs() in the Documenter manual