Constructing Tensors

Tensorial values can be constructed from literal values, ordinary Julia arrays, or index formulas. For most code, start with the literal macros. Use typed constructors when the tensor shape is part of the API you want to express.

Literal macros

@Vec, @Mat, and @Tensor build Tensorial values from Julia literals or array expressions. They are analogous to StaticArrays.jl's @SVector, @SMatrix, and @SArray, but the result is a Tensorial tensor type.

julia> using Tensorial
julia> x = @Vec [1.0, 2.0, 3.0]3-element Vec{3, Float64}:
 1.0
 2.0
 3.0
julia> A = @Mat [1.0 2.0; 3.0 4.0; 5.0 6.0]3×2 Mat{3, 2, Float64, 6}:
 1.0  2.0
 3.0  4.0
 5.0  6.0
julia> C = @Tensor rand(2, 2, 2);
julia> typeof(C)Tensor{Tuple{2, 2, 2}, Float64, 3, 8}

From arrays

Use explicit constructors when the tensor size should be visible in the type:

julia> Vec{3}([1.0, 2.0, 3.0])3-element Vec{3, Float64}:
 1.0
 2.0
 3.0
julia> Mat{3,2}([1.0 2.0; 3.0 4.0; 5.0 6.0])3×2 Mat{3, 2, Float64, 6}:
 1.0  2.0
 3.0  4.0
 5.0  6.0
julia> Mat{3,2,Float64}([1 2; 3 4; 5 6])3×2 Mat{3, 2, Float64, 6}:
 1.0  2.0
 3.0  4.0
 5.0  6.0

The element type can be supplied explicitly, as in Mat{3,2,Float64}. If it is omitted, Tensorial uses the element type of the input.

Construct symmetric tensors

Use a symmetric tensor constructor when the input data is already symmetric:

julia> SymmetricSecondOrderTensor{2}([1.0 2.0; 2.0 4.0])2×2 SymmetricSecondOrderTensor{2, Float64, 3}:
 1.0  2.0
 2.0  4.0

If the input is not symmetric and you want its symmetric part, use symmetric:

julia> B = @Mat [1.0 3.0; 2.0 4.0]2×2 Tensor{Tuple{2, 2}, Float64, 2, 4}:
 1.0  3.0
 2.0  4.0
julia> symmetric(B)2×2 SymmetricSecondOrderTensor{2, Float64, 3}:
 1.0  2.5
 2.5  4.0

For the general @Symmetry size notation, see Tensor Types and Spaces.

From functions

For tensors defined by an index formula, pass a function whose arguments are the tensor indices:

julia> δ = one(Mat{2,2})2×2 Tensor{Tuple{2, 2}, Float64, 2, 4}:
 1.0  0.0
 0.0  1.0
julia> I = SymmetricFourthOrderTensor{2}((i, j, k, l) ->
           (δ[i,k] * δ[j,l] + δ[i,l] * δ[j,k]) / 2)2×2×2×2 SymmetricFourthOrderTensor{2, Float64, 9}:
[:, :, 1, 1] =
 1.0  0.0
 0.0  0.0

[:, :, 2, 1] =
 0.0  0.5
 0.5  0.0

[:, :, 1, 2] =
 0.0  0.5
 0.5  0.0

[:, :, 2, 2] =
 0.0  0.0
 0.0  1.0
julia> I == one(SymmetricFourthOrderTensor{2})true

This form is useful for identity tensors, projectors, and other tensors that are clearer as indexed formulas than as stored component tuples.

Special tensors

Use zero and one for typed zero and identity tensors:

julia> zero(Vec{3})3-element Vec{3, Float64}:
 0.0
 0.0
 0.0
julia> one(Mat{2,2})2×2 Tensor{Tuple{2, 2}, Float64, 2, 4}:
 1.0  0.0
 0.0  1.0
julia> one(SymmetricFourthOrderTensor{2})2×2×2×2 SymmetricFourthOrderTensor{2, Float64, 9}:
[:, :, 1, 1] =
 1.0  0.0
 0.0  0.0

[:, :, 2, 1] =
 0.0  0.5
 0.5  0.0

[:, :, 1, 2] =
 0.0  0.5
 0.5  0.0

[:, :, 2, 2] =
 0.0  0.0
 0.0  1.0

The Levi-Civita tensor is available with levicivita:

julia> E = levicivita();
julia> E[1,2,3]1
julia> E[1,3,2]-1

For constructor docstrings, see Constructors and special tensors.