perform substitution of covariant/contravariant tensor indices in tensorial expressions - Maple Programming Help

Online Help

All Products    Maple    MapleSim

Home : Support : Online Help : Physics : Physics/SubstituteTensorIndices

Physics[SubstituteTensorIndices] - perform substitution of covariant/contravariant tensor indices in tensorial expressions

Calling Sequence

SubstituteTensorIndices(mu = .., ... expression)




any algebraic tensorial expression typically having some free and some repeated indices

mu = ...


the substitution equation, or a set {...} or list [...] of them

evaluatetensor = ...


optional - can be true (default) or false, to indicate whether to evaluate the tensors after substituting on them

evaluateexpression = ...


optional - can be true or false (default), to indicate whether to evaluate expression after substituting the indices in its tensors

covariantandcontravariant = ...


optional - can be true (default) or false, to indicate whether to substitute both covariant and contravariant indices when only one of them is given on the left-hand sides of the substitution equations



The SubstituteTensorIndices substitutes indices in tensors - the ones displayed when you enter Define(); see Define to define one. Nowhere else are the indices substituted, and the substitution can be performed on a covariant index, the corresponding contravariant one, or on both.


The first argument is a substitution equation with an index on the left-hand side, or a set or list of them. All the substitution equations are expected in this first argument. The second argument is the target, where the substitutions are to be performed.


The tensors where indices are substituted are re-evaluated after substitution; this re-evaluation can optionally be suppressed giving the argument evaluatetensor = false. The expression where these re-evaluated tensors are introduce is by default not re-evaluated; you can change that passing the optional argument evaluateexpression = true.


By default both covariant and contravariant indices are substituted, even if the substitution equation has only one of them on the left-hand side; this behavior is convenient both when substituting contracted or free indices. To substitute only the kind of index found on the left-hand side of the substitution equation use covariantandcontravariant = false.


To check and determine the free and repeated indices of an expression use Check.


When substituting indices by numerical values, contravariant values are prefixed with ~, say as in ~1; otherwise, say as in 1, the value is interpreted as covariant. Hence, the equation ~nu = 1 will also transform ~nu into covariant. Substituting the natural way, say as in nu = 1, will automatically substitute both nu = 1 and also ~nu = ~1 keeping the covariant/contravariant character unchanged.


When the right-hand side of a substitution equation is a contravariant index, so suffixed with ~, say as in ~nu = ~1, note the separation between = and ~; that separation is important because ~ is also the element-wise operator and so =~ has other specific meaning.



Setup(mathematicalnotation = true);



Define a couple of arbitrary spacetime tensors for exploration purposes

Define(A, B);

Defined objects with tensor properties



Enter, for example, this tensorial expression, with a contravariant free index ρ

g_[alpha, mu] * A[~mu] * g_[~alpha, ~nu] * B[nu, sigma, ~rho];



To check the repeated and free indices in an expression use Check

Check((3), all);

The repeated indices per term are: ...,...,..., the free indices are: ...



So (3) has α and the contravariant ρ as free indices. Substitute now α=β: the standard subs command will only substitute the covariant α

subs(alpha = beta, (3));



Consequently, the resulting expression is not equivalent to (3): it now has four free indices

Check((5), all);

The repeated indices per term are: ...,...,..., the free indices are: ...



To substitute both covariant and contravariant repeated indices obtaining an expression equivalent to original one use

SubstituteTensorIndices(alpha = beta, (3));



Check((7), all);

The repeated indices per term are: ...,...,..., the free indices are: ...



Substitute now the contravariant ρ by τ; the standard subs command will fail because contravariant indices are prefixed by ~, so this returns (3) as given

subs(rho = beta, (3));



To make it work with subs you would need to substitute ~rho = ~beta instead. Using SubstituteTensorIndices you get the desired result regardless of this subtlety

SubstituteTensorIndices(rho = beta, (3));



Check((10), all);

The repeated indices per term are: ...,...,..., the free indices are: ...



To substitute several indices at once, enclose the substitution equations in a set or a list

SubstituteTensorIndices([rho = beta, alpha = gamma], (3));



After substituting, tensors are re-evaluated; in this example, ν becomes 1 and the normalized form of g_ is presented with it in the first place, so switching places with μ

g_[mu, nu];



SubstituteTensorIndices(nu = 1, (13));



To avoid this re-evaluation of tensors in the result use evaluatetensor = false

SubstituteTensorIndices(nu=1, (13), evaluatetensor = false);




See Also

Check, Define, element-wise operator, g_, Physics, Physics conventions, Physics examples, Physics Updates, Tensors - a complete guide, Mini-Course Computer Algebra for Physicists, SubstituteTensor



Landau, L.D., and Lifshitz, E.M. The Classical Theory of Fields, Course of Theoretical Physics Volume 2, fourth revised English edition. Elsevier, 1975.



The Physics[SubstituteTensorIndices] command was introduced in Maple 16.


For more information on Maple 16 changes, see Updates in Maple 16.