% Copyright The Numerical Algorithms Group Limited 1992-94. All rights reserved.
% !! DO NOT MODIFY THIS FILE BY HAND !! Created by ht.awk.
\newcommand{\CartesianTensorXmpTitle}{CartesianTensor}
\newcommand{\CartesianTensorXmpNumber}{9.7}
%
% =====================================================================
\begin{page}{CartesianTensorXmpPage}{9.7 CartesianTensor}
% =====================================================================
\beginscroll

\spadtype{CartesianTensor(i0,dim,R)}
provides Cartesian tensors with
components belonging to a commutative ring \spad{R}.
Tensors can be described as a generalization of vectors and matrices.
%-% \HDindex{tensor!Cartesian}{CartesianTensorXmpPage}{9.7}{CartesianTensor}
This gives a concise {\it tensor algebra} for multilinear objects
supported by the \spadtype{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 \spadtype{CartesianTensor} constructor allows you to specify the
minimum index for subscripting.
In what follows we discuss in detail how to manipulate tensors.

\xtc{
Here we construct the domain of Cartesian tensors of dimension 2 over the
integers, with indices starting at 1.
}{
\spadpaste{CT := CARTEN(i0 := 1, 2, Integer) \bound{CT i0}}
}

\subsubsection{Forming tensors}

\labelSpace{2pc}
\xtc{
Scalars can be converted to tensors of rank zero.
}{
\spadpaste{t0: CT := 8 \free{CT}\bound{t0}}
}
\xtc{
}{
\spadpaste{rank t0 \free{t0}}
}
\xtc{
Vectors (mathematical direct products, rather than one dimensional array
structures) can be converted to tensors of rank one.
}{
\spadpaste{v: DirectProduct(2, Integer) := directProduct [3,4] \bound{v}}
}
\xtc{
}{
\spadpaste{Tv: CT := v \free{v CT}\bound{Tv}}
}
\xtc{
Matrices can be converted to tensors of rank two.
}{
\spadpaste{m: SquareMatrix(2, Integer) := matrix [[1,2],[4,5]] \bound{m}}
}
\xtc{
}{
\spadpaste{Tm: CT := m \bound{Tm}\free{CT m}}
}
\xtc{
}{
\spadpaste{n: SquareMatrix(2, Integer) := matrix [[2,3],[0,1]] \bound{n}}
}
\xtc{
}{
\spadpaste{Tn: CT := n \bound{Tn}\free{CT n}}
}
\xtc{
In general, a tensor of rank \spad{k} can be formed by making a
list of rank \spad{k-1} tensors or, alternatively, a \spad{k}-deep nested
list of lists.
}{
\spadpaste{t1: CT := [2, 3] \free{CT}\bound{t1}}
}
\xtc{
}{
\spadpaste{rank t1 \free{t1}}
}
\xtc{
}{
\spadpaste{t2: CT := [t1, t1] \free{CT t1}\bound{t2}}
}
\xtc{
}{
\spadpaste{t3: CT := [t2, t2] \free{CT t2}\bound{t3}}
}
\xtc{
}{
\spadpaste{tt: CT := [t3, t3]; tt := [tt, tt] \free{CT t3}\bound{tt}}
}
\xtc{
}{
\spadpaste{rank tt \free{tt}}
}

\subsubsection{Multiplication}
%\head{subsection}{Multiplication}{ugxCartenMult}

Given two tensors of rank \spad{k1} and \spad{k2}, the outer
%-% \HDindex{tensor!outer product}{CartesianTensorXmpPage}{9.7}{CartesianTensor}
\spadfunFrom{product}{CartesianTensor} forms a new tensor of rank
\spad{k1+k2}.
\xtc{
Here
\texht{$T_{mn}(i,j,k,l) = T_m(i,j) \  T_n(k,l).$}{%
\spad{Tmn(i,j,k,l) = Tm(i,j)*Tn(k,l).}}
}{
\spadpaste{Tmn := product(Tm, Tn)\free{Tm Tn}\bound{Tmn}}
}

The inner product (\spadfunFrom{contract}{CartesianTensor}) forms a tensor
%-% \HDindex{tensor!inner product}{CartesianTensorXmpPage}{9.7}{CartesianTensor}
of rank \spad{k1+k2-2}.
This product generalizes the vector dot product and matrix-vector product
by summing component products along two indices.
\xtc{
Here we sum along the second index of \texht{$T_m$}{\spad{Tm}} and the
first index of \texht{$T_v$}{\spad{Tv}}.
Here
\texht{$T_{mv} = \sum_{j=1}^{\hbox{\tiny\rm dim}} T_m(i,j) \  T_v(j)$}{%
\spad{Tmv(i) = sum Tm(i,j) * Tv(j) for j in 1..dim.}}
}{
\spadpaste{Tmv := contract(Tm,2,Tv,1)\free{Tm Tv}\bound{Tmv}}
}

The multiplication operator \spadopFrom{*}{CartesianTensor} is scalar
multiplication or an inner product depending on the ranks of the
arguments.
\xtc{
If either argument is rank zero it is treated as scalar multiplication.
Otherwise, \spad{a*b} is the inner product summing the last index of
\spad{a} with the first index of \spad{b}.
}{
\spadpaste{Tm*Tv \free{Tm Tv}}
}
\xtc{
This definition is consistent with the inner product on matrices
and vectors.
}{
\spadpaste{Tmv = m * v \free{Tmv m v}}
}

\subsubsection{Selecting Components}
%\head{subsection}{Selecting Components}{ugxCartenSelect}

\labelSpace{2pc}
\xtc{
For tensors of low rank (that is, four or less), components can be selected
by applying the tensor to its indices.
}{
\spadpaste{t0()      \free{t0}}
}
\xtc{
}{
\spadpaste{t1(1+1)   \free{t1}}
}
\xtc{
}{
\spadpaste{t2(2,1)   \free{t2}}
}
\xtc{
}{
\spadpaste{t3(2,1,2) \free{t3}}
}
\xtc{
}{
\spadpaste{Tmn(2,1,2,1) \free{Tmn}}
}
\xtc{
A general indexing mechanism is provided for a list of indices.
}{
\spadpaste{t0[]        \free{t0}}
}
\xtc{
}{
\spadpaste{t1[2]        \free{t1}}
}
\xtc{
}{
\spadpaste{t2[2,1]      \free{t2}}
}
\xtc{
The general mechanism works for tensors of arbitrary rank, but is
somewhat less efficient since the intermediate index list must be created.
}{
\spadpaste{t3[2,1,2]    \free{t3}}
}
\xtc{
}{
\spadpaste{Tmn[2,1,2,1] \free{Tmn}}
}

\subsubsection{Contraction}
%\head{subsection}{Contraction}{ugxCartenContract}

A ``contraction'' between two tensors is an inner product, as we have
%-% \HDindex{tensor!contraction}{CartesianTensorXmpPage}{9.7}{CartesianTensor}
seen above.
You can also contract a pair of indices of a single tensor.
This corresponds to a ``trace'' in linear algebra.
The expression \spad{contract(t,k1,k2)} forms a new tensor by summing the
diagonal given by indices in position \spad{k1} and \spad{k2}.
\xtc{
This is the tensor given by
\texht{$xT_{mn} = \sum_{k=1}^{\hbox{\tiny\rm dim}} T_{mn}(k,k,i,j).$}{%
\spad{cTmn(i,j) = sum Tmn(k,k,i,j) for k in 1..dim.}}
}{
\spadpaste{cTmn := contract(Tmn,1,2) \free{Tmn}\bound{cTmn}}
}
\xtc{
Since \spad{Tmn} is the outer product of matrix \spad{m} and matrix \spad{n},
the above is equivalent to this.
}{
\spadpaste{trace(m) * n \free{m n}}
}
\xtc{
In this and the next few examples,
we show all possible contractions of \spad{Tmn} and their matrix
algebra equivalents.
}{
\spadpaste{contract(Tmn,1,2) = trace(m) * n      \free{Tmn m n}}
}
\xtc{
}{
\spadpaste{contract(Tmn,1,3) = transpose(m) * n  \free{Tmn m n}}
}
\xtc{
}{
\spadpaste{contract(Tmn,1,4) = transpose(m) * transpose(n) \free{Tmn m n}}
}
\xtc{
}{
\spadpaste{contract(Tmn,2,3) = m * n             \free{Tmn m n}}
}
\xtc{
}{
\spadpaste{contract(Tmn,2,4) = m * transpose(n)  \free{Tmn m n}}
}
\xtc{
}{
\spadpaste{contract(Tmn,3,4) = trace(n) * m      \free{Tmn m n}}
}

\subsubsection{Transpositions}
%\head{subsection}{Transpositions}{ugxCartenTranspos}

You can exchange any desired pair of indices using the
\spadfunFrom{transpose}{CartesianTensor} operation.

\labelSpace{1pc}
\xtc{
Here the indices in positions one and three are exchanged, that is,
\texht{$tT_{mn}(i,j,k,l) = T_{mn}(k,j,i,l).$}{%
\spad{tTmn(i,j,k,l) = Tmn(k,j,i,l).}}
}{
\spadpaste{tTmn := transpose(Tmn,1,3) \free{tTmn}}
}
\xtc{
If no indices are specified, the first and last index are exchanged.
}{
\spadpaste{transpose Tmn \free{Tmn}}
}
\xtc{
This is consistent with the matrix transpose.
}{
\spadpaste{transpose Tm = transpose m \free{Tm m}}
}

If a more complicated reordering of the indices is required, then the
\spadfunFrom{reindex}{CartesianTensor} operation can be used.
This operation allows the indices to be arbitrarily permuted.
\xtc{
This defines
\texht{$rT_{mn}(i,j,k,l) = \allowbreak T_{mn}(i,l,j,k).$}{%
\spad{rTmn(i,j,k,l) = Tmn(i,l,j,k).}}
}{
\spadpaste{rTmn := reindex(Tmn, [1,4,2,3]) \free{Tmn}\bound{rTmn}}
}

\subsubsection{Arithmetic}
%\head{subsection}{Arithmetic}{ugxCartenArith}

\labelSpace{2pc}
\xtc{
Tensors of equal rank can be added or subtracted so arithmetic
expressions can be used to produce new tensors.
}{
\spadpaste{tt := transpose(Tm)*Tn - Tn*transpose(Tm) \free{Tm Tn}\bound{tt2}}
}
\xtc{
}{
\spadpaste{Tv*(tt+Tn) \free{tt2 Tv Tn}}
}
\xtc{
}{
\spadpaste{reindex(product(Tn,Tn),[4,3,2,1])+3*Tn*product(Tm,Tm) \free{Tm Tn}}
}

\subsubsection{Specific Tensors}
%\head{subsection}{Specific Tensors}{ugxCartenSpecific}

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

\labelSpace{1pc}
\xtc{
The Kronecker delta satisfies
%-% \HDindex{Kronecker delta}{CartesianTensorXmpPage}{9.7}{CartesianTensor}
\texht{}{%
\begin{verbatim}
             +-
             |   1  if i  = j
delta(i,j) = |
             |   0  if i ^= j
             +-
\end{verbatim}
}%
}{
\spadpaste{delta:  CT := kroneckerDelta()   \free{CT}\bound{delta}}
}
\xtc{
This can be used to reindex via contraction.
}{
\spadpaste{contract(Tmn, 2, delta, 1) = reindex(Tmn, [1,3,4,2]) \free{Tmn delta}}
}

\xtc{
The Levi Civita symbol determines the sign of a permutation of indices.
}{
\spadpaste{epsilon:CT := leviCivitaSymbol() \free{CT}\bound{epsilon}}
}
Here we have:
\texht{}{%
\begin{verbatim}
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
\end{verbatim}
}
\xtc{
This property can be used to form determinants.
}{
\spadpaste{contract(epsilon*Tm*epsilon, 1,2) = 2 * determinant m \free{epsilon Tm m}}
}

\subsubsection{Properties of the CartesianTensor domain}
%\head{subsection}{Properties of the CartesianTensor domain}{ugxCartenProp}

\spadtype{GradedModule(R,E)} denotes ``\spad{E}-graded \spad{R}-module'',
that is, a collection of \spad{R}-modules indexed by an abelian monoid
\spad{E.}
%-% \HDexptypeindex{GradedModule}{CartesianTensorXmpPage}{9.7}{CartesianTensor}
An element \spad{g} of \spad{G[s]} for some specific \spad{s}
in \spad{E} is said to be an element of \spad{G} with
\spadfunFrom{degree}{GradedModule} \spad{s}.
Sums are defined in each module \spad{G[s]} so two elements of
\spad{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.

\spadtype{GradedAlgebra(R,E)} denotes ``\spad{E}-graded \spad{R}-algebra.''
%-% \HDexptypeindex{GradedAlgebra}{CartesianTensorXmpPage}{9.7}{CartesianTensor}
A graded algebra is a graded module together with a degree preserving
\spad{R}-bilinear map, called the \spadfunFrom{product}{GradedAlgebra}.

\begin{verbatim}
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)
\end{verbatim}

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

If \spad{V} is a vector space of dimension \spad{dim} over \spad{R},
then the tensor module \spad{T[k](V)} is defined as
\begin{verbatim}
T[0](V) = R
T[k](V) = T[k-1](V) * V
\end{verbatim}
where \spadop{*} denotes the \spad{R}-module tensor
\spadfunFrom{product}{GradedAlgebra}.
\spadtype{CartesianTensor(i0,dim,R)} is the graded algebra in which
the degree \spad{k} module is \spad{T[k](V)}.

\subsubsection{Tensor Calculus}
%\head{subsection}{Tensor Calculus}{ugxCartenCalculus}

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 \spadtype{CartesianTensor}
domain than it is by the \spadtype{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.
\endscroll
\autobuttons
\end{page}
%