====================================================================
CartesianTensor examples
====================================================================

CartesianTensor(i0,dim,R) provides Cartesian tensors with components
belonging to a commutative ring R.  Tensors can be described as a
generalization of vectors and matrices.  This gives a concise tensor
algebra for multilinear objects supported by the CartesianTensor
domain.  You can form the inner or outer product of any two tensors
and you can add or subtract tensors with the same number of components.  
Additionally, various forms of traces and transpositions are useful.

The CartesianTensor constructor allows you to specify the minimum
index for subscripting.  In what follows we discuss in detail how to
manipulate tensors.

Here we construct the domain of Cartesian tensors of dimension 2 over the
integers, with indices starting at 1.

  CT := CARTEN(i0 := 1, 2, Integer)
   CartesianTensor(1,2,Integer) 
                      Type: Domain

====================================================================
Forming tensors
====================================================================

Scalars can be converted to tensors of rank zero.

  t0: CT := 8
   8 
                      Type: CartesianTensor(1,2,Integer)

  rank t0
   0 
                      Type: NonNegativeInteger

Vectors (mathematical direct products, rather than one dimensional array
structures) can be converted to tensors of rank one.

  v: DirectProduct(2, Integer) := directProduct [3,4]
   [3, 4]
                      Type: DirectProduct(2,Integer)

  Tv: CT := v
   [3, 4]
                      Type: CartesianTensor(1,2,Integer)

Matrices can be converted to tensors of rank two.

  m: SquareMatrix(2, Integer) := matrix [ [1,2],[4,5] ]
   +1  2+
   |    |
   +4  5+
                      Type: SquareMatrix(2,Integer)

  Tm: CT := m
   +1  2+
   |    |
   +4  5+
                      Type: CartesianTensor(1,2,Integer)

  n: SquareMatrix(2, Integer) := matrix [ [2,3],[0,1] ]
   +2  3+
   |    |
   +0  1+
                      Type: SquareMatrix(2,Integer)

  Tn: CT := n
   +2  3+
   |    |
   +0  1+
                      Type: CartesianTensor(1,2,Integer)

In general, a tensor of rank k can be formed by making a list of
rank k-1 tensors or, alternatively, a k-deep nested list of lists.

  t1: CT := [2, 3]
   [2, 3]
                      Type: CartesianTensor(1,2,Integer)

  rank t1
   1 
                      Type: PositiveInteger

  t2: CT := [t1, t1]
   +2  3+
   |    |
   +2  3+
                      Type: CartesianTensor(1,2,Integer)

  t3: CT := [t2, t2]

    +2  3+ +2  3+
   [|    |,|    |]
    +2  3+ +2  3+
                      Type: CartesianTensor(1,2,Integer)

  tt: CT := [t3, t3]; tt := [tt, tt]
    ++2  3+  +2  3++ ++2  3+  +2  3++
    ||    |  |    || ||    |  |    ||
    |+2  3+  +2  3+| |+2  3+  +2  3+|
   [|              |,|              |]
    |+2  3+  +2  3+| |+2  3+  +2  3+|
    ||    |  |    || ||    |  |    ||
    ++2  3+  +2  3++ ++2  3+  +2  3++
                      Type: CartesianTensor(1,2,Integer)

  rank tt
   5 
                      Type: PositiveInteger

====================================================================
Multiplication
====================================================================

Given two tensors of rank k1 and k2, the outer product forms a new
tensor of rank k1+k2. Here

  Tmn(i,j,k,l) = Tm(i,j)Tn(k,l)

  Tmn := product(Tm, Tn)
    ++2  3+    +4  6+ +
    ||    |    |    | |
    |+0  1+    +0  2+ |
    |                 |
    |+8  12+  +10  15+|
    ||     |  |      ||
    ++0  4 +  +0   5 ++
                      Type: CartesianTensor(1,2,Integer)

The inner product (contract) forms a tensor of rank k1+k2-2.  This
product generalizes the vector dot product and matrix-vector product
by summing component products along two indices.

Here we sum along the second index of Tm and the first index of Tv. Here 

 Tmv = sum {j=1..dim} Tm(i,j) Tv(j)

 Tmv := contract(Tm,2,Tv,1)
   [11,32]
                      Type: CartesianTensor(1,2,Integer)

The multiplication operator * is scalar multiplication or an inner
product depending on the ranks of the arguments.

If either argument is rank zero it is treated as scalar multiplication.  
Otherwise, a*b is the inner product summing the last index of a with the 
first index of b.

  Tm*Tv
   [11,32]
                     Type: CartesianTensor(1,2,Integer)

This definition is consistent with the inner product on matrices
and vectors.

  Tmv = m * v
   [11,32] = [11,32]
                     Type: Equation CartesianTensor(1,2,Integer)

====================================================================
Selecting Components
====================================================================

For tensors of low rank (that is, four or less), components can be selected
by applying the tensor to its indices.

  t0()
   8
                     Type: PositiveInteger

  t1(1+1)
   3
                     Type: PositiveInteger

  t2(2,1)
   2
                     Type: PositiveInteger

  t3(2,1,2)
    3
                     Type: PositiveInteger

  Tmn(2,1,2,1)
    0
                     Type: NonNegativeInteger

A general indexing mechanism is provided for a list of indices.

  t0[]
    8
                     Type: PositiveInteger

  t1[2]
    3
                     Type: PositiveInteger

  t2[2,1]
    2
                     Type: PositiveInteger

The general mechanism works for tensors of arbitrary rank, but is
somewhat less efficient since the intermediate index list must be created.

  t3[2,1,2]
    3
                     Type: PositiveInteger

  Tmn[2,1,2,1]
    0
                     Type: NonNegativeInteger

====================================================================
Contraction
====================================================================

A "contraction" between two tensors is an inner product, as we have
seen above.  You can also contract a pair of indices of a single
tensor.  This corresponds to a "trace" in linear algebra.  The
expression contract(t,k1,k2) forms a new tensor by summing the
diagonal given by indices in position k1 and k2.

This is the tensor given by
  xTmn = sum{k=1..dim} Tmn(k,k,i,j)

  cTmn := contract(Tmn,1,2)
    +12  18+
    |      |
    +0   6 +
                         Type: CartesianTensor(1,2,Integer)

Since Tmn is the outer product of matrix m and matrix n, the above is
equivalent to this.

  trace(m) * n
    +12  18+
    |      |
    +0   6 +
                         Type: SquareMatrix(2,Integer)

In this and the next few examples, we show all possible contractions
of Tmn and their matrix algebra equivalents.

  contract(Tmn,1,2) = trace(m) * n
   +12  18+  +12  18+
   |      |= |      |
   +0   6 +  +0   6 +
                          Type: Equation CartesianTensor(1,2,Integer)

  contract(Tmn,1,3) = transpose(m) * n
   +2  7 +  +2  7 +
   |     |= |     |
   +4  11+  +4  11+
                          Type: Equation CartesianTensor(1,2,Integer)

  contract(Tmn,1,4) = transpose(m) * transpose(n)
   +14  4+  +14  4+
   |     |= |     |
   +19  5+  +19  5+
                          Type: Equation CartesianTensor(1,2,Integer)

  contract(Tmn,2,3) = m * n
   +2  5 +  +2  5 +
   |     |= |     |
   +8  17+  +8  17+
                          Type: Equation CartesianTensor(1,2,Integer)

  contract(Tmn,2,4) = m * transpose(n)
   +8   2+  +8   2+
   |     |= |     |
   +23  5+  +23  5+
                          Type: Equation CartesianTensor(1,2,Integer)

  contract(Tmn,3,4) = trace(n) * m
   +3   6 +  +3   6 +
   |      |= |      |
   +12  15+  +12  15+
                          Type: Equation CartesianTensor(1,2,Integer)

====================================================================
Transpositions
====================================================================

You can exchange any desired pair of indices using the transpose
operation.

Here the indices in positions one and three are exchanged, that is,
  tTmn(i,j,k,l) = Tmn(k,j,i,l)

  tTmn := transpose(Tmn,1,3)
   ++2  3 +  +4   6 ++
   ||     |  |      ||
   |+8  12+  +10  15+|
   |                 |
   |+0  1+    +0  2+ |
   ||    |    |    | |
   ++0  4+    +0  5+ +
                             Type: CartesianTensor(1,2,Integer)

If no indices are specified, the first and last index are exchanged.

  transpose Tmn
   ++2  8+   +4  10++
   ||    |   |     ||
   |+0  0+   +0  0 +|
   |                |
   |+3  12+  +6  15+|
   ||     |  |     ||
   ++1  4 +  +2  5 ++
                             Type: CartesianTensor(1,2,Integer)

This is consistent with the matrix transpose.

  transpose Tm = transpose m
   +1  4+  +1  4+
   |    |= |    |
   +2  5+  +2  5+
                             Type: Equation CartesianTensor(1,2,Integer)


If a more complicated reordering of the indices is required, then the
reindex operation can be used.  This operation allows the indices to
be arbitrarily permuted.

  rTmn(i,j,k,l) = Tmn(i,l,j,k)

  rTmn := reindex(Tmn, [1,4,2,3])
   ++2  0+   +3  1+ +
   ||    |   |    | |
   |+4  0+   +6  2+ |
   |                |
   |+8   0+  +12  4+|
   ||     |  |     ||
   ++10  0+  +15  5++
                              Type: CartesianTensor(1,2,Integer)

====================================================================
Arithmetic
====================================================================

Tensors of equal rank can be added or subtracted so arithmetic
expressions can be used to produce new tensors.

  tt := transpose(Tm)*Tn - Tn*transpose(Tm)
   +- 6  - 16+
   |         |
   + 2    6  +
                              Type: CartesianTensor(1,2,Integer)


  Tv*(tt+Tn)
   [- 4,- 11]
                              Type: CartesianTensor(1,2,Integer)

  reindex(product(Tn,Tn),[4,3,2,1])+3*Tn*product(Tm,Tm)
   ++46   84 +  +57   114++
   ||        |  |        ||
   |+174  212+  +228  285+|
   |                      |
   | +18  24+    +17  30+ |
   | |      |    |      | |
   + +57  63+    +63  76+ +
                              Type: CartesianTensor(1,2,Integer)

====================================================================
Specific Tensors
====================================================================

Two specific tensors have properties which depend only on the dimension.

The Kronecker delta satisfies

             +-              -+
             |   1  if i  = j |
delta(i,j) = |                |
             |   0  if i ^= j |
             +-              -+


  delta:  CT := kroneckerDelta()
   +1  0+
   |    |
   +0  1+
                              Type: CartesianTensor(1,2,Integer)

This can be used to reindex via contraction.

  contract(Tmn, 2, delta, 1) = reindex(Tmn, [1,3,4,2])
   + +2  4+   +0  0++  + +2  4+   +0  0++
   | |    |   |    ||  | |    |   |    ||
   | +3  6+   +1  2+|  | +3  6+   +1  2+|
   |                |= |                |
   |+8   10+  +0  0+|  |+8   10+  +0  0+|
   ||      |  |    ||  ||      |  |    ||
   ++12  15+  +4  5++  ++12  15+  +4  5++
                             Type: Equation CartesianTensor(1,2,Integer)

The Levi Civita symbol determines the sign of a permutation of indices.

  epsilon:CT := leviCivitaSymbol()
   + 0   1+
   |      |
   +- 1  0+
                              Type: CartesianTensor(1,2,Integer)

Here we have:

  epsilon(i1,...,idim)
     = +1  if i1,...,idim is an even permutation of i0,...,i0+dim-1
     = -1  if i1,...,idim is an  odd permutation of i0,...,i0+dim-1
     =  0  if i1,...,idim is not   a permutation of i0,...,i0+dim-1

This property can be used to form determinants.

  contract(epsilon*Tm*epsilon, 1,2) = 2 * determinant m
   - 6= - 6
                            Type: Equation CartesianTensor(1,2,Integer)


====================================================================
Properties of the CartesianTensor domain
====================================================================

GradedModule(R,E) denotes "E-graded R-module", that is, a collection
of R-modules indexed by an abelian monoid E. An element g of G[s] for
some specific s in E is said to be an element of G with degree s.
Sums are defined in each module G[s] so two elements of G can be added
if they have the same degree.  Morphisms can be defined and composed
by degree to give the mathematical category of graded modules.

GradedAlgebra(R,E) denotes "E-graded R-algebra".  A graded algebra is
a graded module together with a degree preserving R-bilinear map,
called the product.

  degree(product(a,b))    = degree(a) + degree(b)

  product(r*a,b)          = product(a,r*b) = r*product(a,b)
  product(a1+a2,b)        = product(a1,b) + product(a2,b)
  product(a,b1+b2)        = product(a,b1) + product(a,b2)
  product(a,product(b,c)) = product(product(a,b),c)

The domain CartesianTensor(i0, dim, R) belongs to the category
GradedAlgebra(R, NonNegativeInteger).  The non-negative integer degree
is the tensor rank and the graded algebra product is the tensor outer
product.  The graded module addition captures the notion that only
tensors of equal rank can be added.

If V is a vector space of dimension dim over R, then the tensor module
T[k](V) is defined as

 T[0](V) = R
  T[k](V) = T[k-1](V) * V

where * denotes the R-module tensor product. CartesianTensor(i0,dim,R) 
is the graded algebra in which the degree k module is T[k](V).

====================================================================
Tensor Calculus
====================================================================

It should be noted here that often tensors are used in the context of
tensor-valued manifold maps.  This leads to the notion of covariant
and contravariant bases with tensor component functions transforming
in specific ways under a change of coordinates on the manifold.  This
is no more directly supported by the CartesianTensor domain than it is
by the Vector domain.  However, it is possible to have the components
implicitly represent component maps by choosing a polynomial or
expression type for the components.  In this case, it is up to the
user to satisfy any constraints which arise on the basis of this
interpretation.

See Also
o )show CartesianTensor

