Wolfram Function Repository

Instant-use add-on functions for the Wolfram Language

Function Repository Resource:

 ToTensor

Source Notebook

Convert an expression involving ArrayDot, Dot, Transpose, Tr or MatrixPower into an equivalent expression using TensorContract

Contributed by: Carl Woll

ResourceFunction["ToTensor"][expr]

converts ArrayDot,Dot,Transpose,Tr and MatrixPower subexpressions into equivalent forms using TensorContract.

Details and Options

ResourceFunction["ToTensor"] will use rank information given by VectorSymbol, MatrixSymbol and ArraySymbol.
ResourceFunction["ToTensor"] makes no assumptions about the rank of symbols representing tensors. Use the Assumptions option or $Assumptions to define rank information for the involved symbols.
The input and output of ResourceFunction["ToTensor"] will evaluate to the same array when given explicit arrays as input.
Only Tr expressions representing traces of the first two levels of an array have equivalent TensorContract representations.

Examples

Basic Examples (2) 

Specify the properties of symbolic arrays:

In[1]:=
$Assumptions = (A | X) \[Element] Matrices[{d, d}];

A tensor built using Tr and Dot:

In[2]:=
e = Tr[Transpose[A] . X]
Out[2]=

Convert to an equivalent form using TensorContract:

In[3]:=
t = ResourceFunction["ToTensor"][e]
Out[3]=

Verify that the tensor calculation gives the same results as the equivalent matrix calculation:

In[4]:=
SeedRandom[1] Block[{A = RandomReal[1, {3, 3}], X = RandomReal[1, {3, 3}]}, {e, t} ]
Out[5]=

A tensor built using ArrayDot, Transpose and ArraySymbol:

In[6]:=
e = ArrayDot[ArraySymbol["A", {d, d, d}], ArraySymbol["B", {d, d, d}], 2]
Out[6]=

Convert to an equivalent form using TensorContract:

In[7]:=
t = ResourceFunction["ToTensor"][e]
Out[7]=

Check:

In[8]:=
SeedRandom[1]; rules = {ArraySymbol["A", {d, d, d}] -> RandomReal[1, {3, 3, 3}], ArraySymbol["B", {d, d, d}] -> RandomReal[1, {3, 3, 3}]}; e /. rules t /. rules
Out[9]=
Out[10]=

Scope (2) 

Check equivalence of forms, assuming the two matrices A and B are square:

In[11]:=
$Assumptions = (A | B) \[Element] Matrices[{d, d}]; ResourceFunction["ToTensor"][ A . Transpose[B] == TensorContract[TensorProduct[A, B], {{2, 4}}] ]
Out[11]=

A tensor consisting of Dot, Tr and MatrixPower:

In[12]:=
t = Tr[A . MatrixPower[B, 2]] A . MatrixPower[B, 2]
Out[12]=

Evaluate, assuming the two matrices are square:

In[13]:=
ResourceFunction["ToTensor"][t, Assumptions -> (A | B) \[Element] Matrices[{d, d}]]
Out[13]=

Applications (2) 

TensorReduce is unable to reduce some mixed expressions consisting of both TensorContract and Dot:

In[14]:=
$Assumptions = (R | r) \[Element] Vectors[{d}]; expr = R . r - TensorContract[R\[TensorProduct]r, {{1, 2}}]; TensorReduce[expr]
Out[16]=

Using ToTensor trivially simplifies the expression:

In[17]:=
ResourceFunction["ToTensor"][expr]
Out[17]=

Possible Issues (2) 

Rank information for symbolic tensors must be specified using the Assumptions option or using $Assumptions:

In[18]:=
$Assumptions = True; ResourceFunction["ToTensor"][MatrixPower[A, 2]]
Out[19]=

Here the assumptions are added correctly:

In[20]:=
ResourceFunction["ToTensor"][MatrixPower[A, 2], Assumptions -> A \[Element] Arrays[{4, 4, 4}]]
Out[20]=

Only Tr expression representing traces of the first two levels of an array have equivalent TensorContract representations:

In[21]:=
ResourceFunction["ToTensor"][Tr[A] . A, Assumptions -> A \[Element] Arrays[{d, d, d}]]
Out[21]=

Publisher

Carl Woll

Version History

  • 1.2.0 – 17 April 2025
  • 1.1.0 – 14 December 2021
  • 1.0.0 – 16 October 2019

Related Resources

License Information