Tensorial.jl

Statically sized tensors and related operations for Julia

Tensorial.jl provides statically sized Tensor type that is compatible with AbstractArray, similar to SArray from StaticArrays.jl.
In addition to supporting basic AbstractArray operations, the package offers a tensorial interface and several advanced features:

Contraction, tensor product (⊗), and a flexible @einsum macro for Einstein summation convention
A @Symmetry macro to define the tensor symmetries, eliminating unnecessary calculations
Automatic differentiation via gradient and hessian functions, leveraging ForwardDiff.jl
Performance comparable to SArray (see benchmarks)

Documentation

Breaking changes (v0.18)

Starting from version 0.18, Tensorial.jl is now built on TensorCore.jl. The breaking changes are as follows:

Single contraction: ⋅ has been replaced by ⊡ (⋅ now behaves as in LinearAlgebra).
Double contraction: ⊡ has been replaced by ⊡₂ (which can be typed by \boxdot<tab>\_2<tab>).
Broadcasting: Scalar-like behavior has been removed. Broadcasting now behaves the same as with other AbstractArrays.
mean: The specialized mean definition in Statistics has been removed.

Quick start

julia> using Tensorial
julia> x = Vec{3}(rand(3)); # constructor similar to SArray.jl
julia> A = @Mat rand(3,3); # @Vec, @Mat and @Tensor, analogous to @SVector, @SMatrix and @SArray
julia> A ⊡ x ≈ A * x # single contraction (⊡)
true
julia> A ⊡₂ A ≈ A ⋅ A # double contraction (⊡₂)
true
julia> x ⊗ x ≈ x * x' # tensor product (⊗)
true
julia> (@einsum x[i] * A[j,i] * x[j]) ≈ x ⋅ (A' * x) # Einstein summation (@einsum)
true
julia> S = rand(Tensor{Tuple{@Symmetry{3,3}}}); # specify symmetry S₍ᵢⱼ₎
julia> SS = rand(Tensor{Tuple{@Symmetry{3,3}, @Symmetry{3,3}}}); # SS₍ᵢⱼ₎₍ₖₗ₎
julia> inv(SS) ⊡₂ S ≈ @einsum inv(SS)[i,j,k,l] * S[k,l] # it just works
true
julia> δ = one(Mat{3,3}) # identity tensor
3×3 Tensor{Tuple{3, 3}, Float64, 2, 9}:
 1.0  0.0  0.0
 0.0  1.0  0.0
 0.0  0.0  1.0
julia> gradient(identity, S) ≈ one(SS) # ∂Sᵢⱼ/∂Sₖₗ = (δᵢₖδⱼₗ + δᵢₗδⱼₖ) / 2
true

Other tensor packages

Inspiration

Some functionalities are inspired from the following packages:

Citation

If you find Tensorial.jl useful in your work, I kindly request that you cite it as below:

@software{NakamuraTensorial2024,
    title = {Tensorial.jl: a {J}ulia package for tensor operations},
   author = {Nakamura, Keita},
      doi = {10.5281/zenodo.13955151},
     year = {2024},
      url = {https://github.com/KeitaNakamura/Tensorial.jl}
  licence = {MIT},
}