AbstractTensors.jl

Tensor algebra abstract type interoperability with vector bundle parameter

The AbstractTensors package is intended for universal interoperability of the abstract TensorAlgebra type system. All TensorAlgebra{V} subtypes have type parameter V, used to store a TensorBundle value obtained from DirectSum.jl.

For example, this is mainly used in Grassmann.jl to define various SubAlgebra, TensorGraded and TensorMixed types, each with subtypes. Externalizing the abstract type helps extend the dispatch to other packages. By itself, this package does not impose any specifications or structure on the TensorAlgebra{V} subtypes and elements, aside from requiring V to be a Manifold. This means that different packages can create tensor types having a common underlying TensorBundle structure.

Additionally, TupleVector is provided as a light weight alternative to StaticArrays.jl.

If the environment variable STATICJL is set, the StaticArrays package is depended upon.

Interoperability

Since TensorBundle choices are fundamental to TensorAlgebra operations, the universal interoperability between TensorAlgebra{V} elements with different associated TensorBundle choices is naturally realized by applying the union morphism to operations.

function op(::TensorAlgebra{V},::TensorAlgebra{V}) where V
    # well defined operations if V is shared
end # but what if V ≠ W in the input types?

function op(a::TensorAlgebra{V},b::TensorAlgebra{W}) where {V,W}
    VW = V ∪ W        # VectorSpace type union
    op(VW(a),VW(b))   # makes call well-defined
end # this option is automatic with interop(a,b)

# alternatively for evaluation of forms, VW(a)(VW(b))

Some of operations like +,-,*,⊗,⊛,⊙,⊠,⨼,⨽,⋆ and postfix operators ⁻¹,ǂ,₊,₋,ˣ for TensorAlgebra elements are shared across different packages, some of the interoperability is taken care of in this package. Additionally, a universal unit volume element can be specified in terms of LinearAlgebra.UniformScaling, which is independent of V and has its interpretation only instantiated by the context of the TensorAlgebra{V} element being operated on.

Utility methods such as scalar, involute, norm, norm2, unit, even, odd are also defined.

Example with a new subtype

Suppose we are dealing with a new subtype in another project, such as

using AbstractTensors, DirectSum
struct SpecialTensor{V} <: TensorAlgebra{V} end
a = SpecialTensor{ℝ}()
b = SpecialTensor{ℝ'}()

To define additional specialized interoperability for further methods, it is necessary to define dispatch that catches well-defined operations for equal TensorBundle choices and a fallback method for interoperability, along with a Manifold morphism:

(W::Signature)(s::SpecialTensor{V}) where V = SpecialTensor{W}() # conversions
op(a::SpecialTensor{V},b::SpecialTensor{V}) where V = a # do some kind of operation
op(a::TensorAlgebra{V},b::TensorAlgebra{W}) where {V,W} = interop(op,a,b) # compat

which should satisfy (using the ∪ operation as defined in DirectSum)

julia> op(a,b) |> Manifold == Manifold(a) ∪ Manifold(b)
true

Thus, interoperability is simply a matter of defining one additional fallback method for the operation and also a new form TensorBundle compatibility morphism.

UniformScaling pseudoscalar

The universal interoperability of LinearAlgebra.UniformScaling as a pseudoscalar element which takes on the TensorBundle form of any other TensorAlgebra element is handled globally by defining the dispatch:

(W::Signature)(s::UniformScaling) = ones(ndims(W)) # interpret a unit pseudoscalar
op(a::TensorAlgebra{V},b::UniformScaling) where V = op(a,V(b)) # right pseudoscalar
op(a::UniformScaling,b::TensorAlgebra{V}) where V = op(V(a),b) # left pseudoscalar

This enables the usage of I from LinearAlgebra as a universal pseudoscalar element.

Tensor evaluation

To support a generalized interface for TensorAlgebra element evaluation, a similar compatibility interface is constructible.

(a::SpecialTensor{V})(b::SpecialTensor{V}) where V = a # conversion of some form
(a::SpecialTensor{W})(b::SpecialTensor{V}) where {V,W} = interform(a,b) # compat

which should satisfy (using the ∪ operation as defined in DirectSum)

julia> b(a) |> Manifold == Manifold(a) ∪ Manifold(b)
true

The purpose of the interop and interform methods is to help unify the interoperability of TensorAlgebra elements.

Deployed applications

The key to making the whole interoperability work is that each TensorAlgebra subtype shares a TensorBundle parameter (with all isbitstype parameters), which contains all the info needed at compile time to make decisions about conversions. So other packages need only use the vector space information to decide on how to convert based on the implementation of a type. If external methods are needed, they can be loaded by Requires when making a separate package with TensorAlgebra interoperability.

TupleVector

Statically sized tuple vectors for Julia

TupleVector provides a framework for implementing statically sized tuple vectors in Julia, using the abstract type TupleVector{N,T} <: AbstractVector{T}. Subtypes of TupleVector will provide fast implementations of common array and linear algebra operations. Note that here "statically sized" means that the size can be determined from the type, and "static" does not necessarily imply immutable.

The package also provides some concrete static vector types: Values which may be used as-is (or else embedded in your own type). Mutable versions Variables are also exported, as well as FixedVector for annotating standard Vectors with static size information.

Quick start

Add AbstractTensors from the Pkg REPL, i.e., pkg> add AbstractTensors. Then:

using AbstractTensors

# Create Values using various forms, using constructors, functions or macros
v1 = Values(1, 2, 3)
v1.v === (1, 2, 3) # Values uses a tuple for internal storage
v2 = Values{3,Float64}(1, 2, 3) # length 3, eltype Float64
v5 = zeros(Values{3}) # defaults to Float64
v7 = Values{3}([1, 2, 3]) # Array conversions must specify size

# Can get size() from instance or type
size(v1) == (3,)
size(typeof(v1)) == (3,)

# Supports all the common operations of AbstractVector
v7 = v1 + v2
v8 = sin.(v2)

# Indexing can also be done using static vectors of integers
v1[1] === 1
v1[:] === v1
typeof(v1[[1,2,3]]) <: Vector # Can't determine size from the type of [1,2,3]

Approach

The package provides a range of different useful built-in TupleVector types, which include mutable and immutable vectors based upon tuples, vectors based upon structs, and wrappers of Vector. There is a relatively simple interface for creating your own, custom TupleVector types, too.

This package also provides methods for a wide range of AbstractVector functions, specialized for (potentially immutable) TupleVectors. Many of Julia's built-in method definitions inherently assume mutability, and further performance optimizations may be made when the size of the vector is known to the compiler. One example of this is by loop unrolling, which has a substantial effect on small arrays and tends to automatically trigger LLVM's SIMD optimizations. In combination with intelligent fallbacks to the methods in Base, we seek to provide a comprehensive support for statically sized vectors, large or small, that hopefully "just works".

TupleVector is directly inspired from StaticArrays.jl.