GRTensorIII Release 1.

10
For Maple 2016

GRTensorIII
A. Introduction and overview

Peter Musgrave
Denis Pollney
Kayll Lake

Nov 2016

Contents
1 Startup A3

2 Calculating components A3

3 Input of spacetimes A5

4 The Newman-Penrose formalism A6

5 Defining new tensors A8

Queen’s University at Kingston, Ontario

A. Introduction and overview A2

GRTensorIII is a package for the calculation and manipulation of components of tensors and
related objects. Rather than focus upon a specific type or method of calculation, the program has
been designed to operate efficiently for a wide range of applications and allows the use of a number
of different mathematical formalisms. Algorithms are optimized for the individual formalisms
and transformations between formalisms has been made simple and intuitive. Additionally, the
package allows for customization and expansion with the ability to define new objects, user-defined
algorithms, and add-on libraries.
Regardless of the algorithm or formalism used, it is often the case that only certain simplifica-
tions applied at a crucial stages can make some problems tractable. For this reason, GRTensorIII
has been designed to provide full control of the calculation path and of the simplifications to be
performed at each stage. Once a calculation is completed, a variety of commands are available
for the manipulation and simplification of results.
In designing the package, emphasis has also been placed on the interface, allowing simple user
input, as well as presenting readable output. Metrics and basis vectors are easily defined and can
be saved for later use. Calculations are specified in an intuitive manner using a minimal number
of commands.

This booklet introduces a number of characteristics and features of the GRTensorIII computer
algebra package, emphasizing its input and output facilities, the ability to define new tensor
objects, and the ability to use and switch between a number of different formalisms (classical
tensor methods, general bases, and null tetrads). This booklet itself is intended only as a brief
overview. More detailed information regarding the commands introduced here can be found in
Booklets B–F:
Booklet B: Specifying spacetimes
C: Calculating tensor components
D: Defining new tensors
E: Bases and tetrads
G: Hypersurfaces, Junctions and Shells
Together these articles are intended to serve as both a user’s guide and command reference for the
GRTensorIII package. Unfortunately because of this dual purpose, there are some shortfalls in
their ability to perform each task: Someone looking for tutorial information might find themselves
buried in uninteresting technical points, while experienced users will find some sections overly
pedagogic.
It is not intended that the booklets be read linearly from start to finish. To begin, only
the information from the first sections of the Specifying spacetimes and Calculating tensor
components booklets are needed to perform some sophisticated calculations. Once familiarity
with the interface is gained, the ability to define new tensors and build customized libraries,
described in Booklet D: Defining new tensors, greatly increase the power of the package. For the
first time user, probably the best way to approach the package is to study and execute some of
the demonstrations available in the worksheets directory provided with the package, referring to
these booklets and the online help as necessary.

Major Releases:

Release 2.00: Add junction and hypersurface capability.

GRTensorIII software and documentation is copyright 1994–2016 by the authors. GRTensorIII software and documentation
is provided free of charge and without warranty. The authors retain any and all rights to the software known as GRTensorIII
and its documentation. GRTensorIII development has been supported by the Natural Science and Engineering Research
Council of Canada and the Advisory Research Committee of Queen’s University. MapleV is a trademark of Waterloo
Maple Software.
A. Introduction and overview A3

Release 1.00: GRTensorIII is a adaptation of GRTensorII version 1.50 developed in

1994-1999. It is primarily a refactoring of internal data representation with some updates to the
”modern” Maple environment.

• move all variables inside a scoped Maple package

• include all extension objects from GRII (basic etc.) directly in the main package
• support Maple worksheet dialog based input
• remove some seldom used commands (grloaddef, grsavedef, grloadobj, grsaveobj)
• no changes have been made to the expressions used to define the standard tensor objects

The version of GRTensorIII described in these booklets runs within the Maple environment.
It has been tested with Maple 2016 in command line and worksheet mode. We encourage users
to check back periodically for new versions of software, documentation, and demonstrations, at
http:/github.com/grtensor/grtensor. This represents the ”official” version.

GRTensorIII software is available with documentation and examples

from https://github.com/grtensor/grtensor. Source code is available from
https://github.com/grtensor/grtensor3src.

1 Startup
The GRTensorIII package is distributed as Maple package. To start the GRTensorIII package, in a
new Maple session ensure that the location of grtensor/lib is in the Maple path. It can be added by:

libname := libname, "path";

The package is loaded in the standard manner:

with(grtensor);

Build-in help pages can be viewed via:

?grtensor

The examples described below are designed to be run in a single GRTensorIII session.

2 Calculating components
Tensors are specified by their name and index configuration, using the abbreviations dn and up
to indicate covariant and contravariant indices, respectively. For instance, the Ricci tensor could
be referenced
(a)
R(dn,dn) (= Rab ), R(up,dn) (= Rab ), R(bup,bdn) (= R (b) ),
A. Introduction and overview A4

where the last example uses the labels bup and bdn to reference the components of the Ricci
tensor in terms of a basis rather than metric coordinates.
Three commands are used most frequently within a GRTensorIII session:
grcalc calculates the components of tensors;
grdisplay displays the components;
gralter applies simplification routines to tensors;
Thus, to calculate the covariant Ricci tensor for the predefined Kerr metric, we might use the
command sequence

> qload ( kerr ):

> grcalc ( R(dn,dn) ):
Calculating g(dn,dn,pdn) for kerr ... Done.
Calculating Chr(dn,dn,dn) for kerr ... Done.
Calculating detg for kerr ... Done.
Calculating g(up,up) for kerr ... Done.
Calculating Chr(dn,dn,up) for kerr ... Done.
Calculating R(dn,dn) for kerr ... Done.

> grdisplay ( R(dn,dn) ):

For the kerr spacetime:
Covariant Ricci

R r r = −a2 r2 − r2 sin( θ )2 + 2 r2 cos( θ )4 − 3 r2 cos( θ )2 + 2 r2 sin( θ )2 cos( θ )2 + a2 cos( θ )4
 .
2 
− a2 cos( θ )2 + a2 cos( θ )2 sin( θ )2 −1 + cos( θ )2 ( r2 − 2 m r + a2 ) r2 + a2 cos( θ )2

Rθθ = . . . etc.
At this point, since no simplifications of the results have been applied, the components of Rab
are not obviously zero as we would expect. The following commands are needed:

> gralter ( R(dn,dn), trig ):

> grdisplay ( R(dn,dn) ):

For the kerr spacetime:

Covariant Ricci
R(dn,dn) = All components are zero
The first command applies trigonometric simplification to the components of R(dn,dn). Upon
using grdisplay(), we see that the the simplification has indeed reduced the components to zero.
Note that for a more complicated metric, it may be the case that it is better to carry out
the computation in stages. That is, we can first calculate the Christoffel symbols and apply
simplifications, then the Ricci tensor, and finally, for instance, the Ricci scalar.
A number of alternate simplification routines exist within gralter(), including trigonometric,
radical, expansion and factorization techniques. The command grmap() can also be used to apply
any Maple function to the components of a tensor.
A. Introduction and overview A5

The commands listed in this Section are described in more detail in Booklet C: Calculat-
ing tensor components. The calculation of objects in a coordinate basis is described in Booklet
E: Bases and tetrads.

3 Input of spacetimes
Spacetimes are specified within GRTensorIII through use of the makeg() facility. They can be
entered in the following forms:
Metric, gab A n × n symmetric matrix;
Line element An equation of the standard form ds2 = . . .;

Non-holonomic basis A set of basis vectors (covariant or contravariant) with an inner product;
Null tetrad As described by the Newman-Penrose formalism.
As an illustrative (but computationally trivial) example, we consider the twisting Einstein-
Maxwell solution described on p. 135 of Kramer, et al. [1],
   
2 a dy a dy
kds = −2 x du − dt + a(tdx + dy)/x + f (t) x du −
(a + 1)x (a + 1)x
+ (dx2 + dy 2 )(t2 + 1)/2x2 ,

We can enter this metric directly in this form using makeg(), giving it the name ‘sm’:

In Maple worksheets the following prompts will appear in dialog boxes. In the example here
we show the responses in command-line mode.

> makeg ( sm ):
Makeg 2.0: GRTensorIII metric/basis entry utility
To quit makeg, type ’exit’ at any prompt.

Do you wish to enter a 1) metric [g(dn,dn)],

2) line element [ds],
3) non-holonomic basis [e1...e4], or
4) null tetrad [l,n,m,mbar]?
> 2:
Enter coordinates as a LIST (e.g. [r,theta,phi,t]):
> [ t, x, y, u ]:

Enter the line element using ’d[coord]’ to indicate differentials.

(for example, r^2*(d[theta]^2 + sin(theta)^2*d[phi]^2)
[Type ’exit’ to quit makeg]
ds^2 =

> 1/k*(-2*(x^a*d[u] - d[y]/((a+1)*x))*(d[t] + a*(t*d[x]

+ d[y])/x + f(t)*(x^a*d[u]-d[y]/((a+1)*x))) + (d[x]^2 +
A. Introduction and overview A6

d[y]^2)*(t^2+1)/(2*x^2)):

Note that in the above expression the coordinate differentials are labeled using the variables
d[coordinate], allowing the line element to be entered in exactly the form that it is given in
[1]. The output from makeg is:

xa dt du 1 t2
 
2 dt dy 1 1 a t dx dy
ds = 2 −2 + 2
+ 2
dx2 + 2
k(a + 1)x k 2 kx 2 kx k(a + 1)x2
a
1 t2
 
x a t dx du a f (t) 1 1
−2 + 2 −2 + + dy 2
kx k(a + 1)x2 k(a + 1)2 x2 2 kx2 2 kx2
 a
xa f (t) (xa )2 f (t)du2

x a
+2 − +2 dy du − 2
kx k(a + 1)x k
makeg completed.
The parameter values can now be set for the particular Type-III case studied by Siklos and
MacCallum [2] (referred to in [1] on p. 135):

> a := 1/2: k := -32/(78*lambda): f(t) := (13*t^2+17)/32:

For this metric, we calculate the (rather uninteresting, in this case) components of the Ricci tensor:

> grcalc ( R(dn,dn) ):

> grdisplay ( ):
For the sm metric:
39 √
0 0 − 13 1
16 x
 
8 x
39 t2 +1 13 t 39 √t
 0 − 32 x2 − 16 x2 32 x

Rab =  13 1
 
13 t 65 5+t2 13 5+13t 2
 −8 x − 16 − 192 − 128 √

x2 x2 x 
39 √ 39 √t 13 5+13t 2
39 2
16 x 32 x − 128 √
x 256 x(13t + 17)

The specification of metrics and bases is described more fully in Booklet B: Specifying space-
times. The grcalc(), gralter() and grdisplay() commands are the subject of Booklet C:
Calculating tensor components.

4 The Newman-Penrose formalism

A more complicated problem is that of determining the Petrov type of this metric. In order to
do this in GRTensorIII, the metric must be cast in the form of a Newman-Penrose (NP) null
tetrad. Since no tetrad obviously presents itself from the form of the metric given above, we can
use the command nptetrad() to generate one. This command constructs a set of null basis
vectors satisfying the properties of a basis for the Newman-Penrose formalism.1 Naturally, this
tetrad may not be optimal for further calculation, but is often a good start to which further
simplifications can be applied.

1 Since
the -2 signature convention of the NP formalism conflicts with the +2 Landau-Lifschitz convention
recommended for metrics in GRTensorIII, the construction of the tetrad also involves a signature change. This is
carried out automatically if requested.
A. Introduction and overview A7

> nptetrad([u,t]):
The metric signature of the sm spacetime is +2.
In order to create an NP-tetrad, the signature of g(dn,dn) will be changed
to -2.
Continue? (1=yes):
> 1:
The signature of the sm spacetime is now -2.

Null tetrad (covariant components)

3 λ ( −7 + 13 t2 )
 
9 √ 9 λt 9
la = − λ x − √ √ − λ x (13t2 + 17)
4 8 x 64 x 128
 
2 1
na = 0 0 − 1
3 x3/2
 
3/4 i(t2 +1)λ (t2 +1)λ
ma = 0 √ 3/4 √ 2 0
x −(t2 +1)λ x −(t +1)λ
 
−3/4 i(t2 +1)λ (t2 +1)λ
mbar a = 0 √ 3/4 √ 2 0
x −(t2 +1)λ x −(t +1)λ

The null tetrad has been stored as e(bdn,dn).

From this point we can proceed to determine the Petrov type of our example metric by first
calculating the spin coefficients (NPSpin and their conjugates NPSpinbar) and the Weyl scalars
(WeylSc) [3].

> grcalc ( NPSpin, NPSpinbar ):

> grcalc ( WeylSc ):
> gralter ( , factor ):
> grdisplay ( ):
5 I x ( 13 t2 + 10 I t + 11 )
Ψ0 = −
64 ( t + I ) ( −t + I )2
√ 2
−5/8 i x (t + i) λ2 (−t + i)
Ψ1 = 5/2
(− (t2 + 1) λ)
Ψ2 = 0
Ψ3 = 0
Ψ4 = 0
Note that the calculation of NPSpin and NPSpinbar did not need to be specified in a separate
step, since this the calculation of these objects implicit in the calculation of WeylSc. However,
in general a good rule of thumb is to calculate these quantities first and simplify them fully (not
required in this case) before proceeding to the curvature scalars.

> grcalc ( Petrov ):

> grdisplay ( ):
A. Introduction and overview A8

For the sm spacetime:

Petrov Type = III (or simpler)
Note the caveat ‘or simpler’ in the final line of output. The calculation of the Petrov type involves
determining whether a number of intermediate quantities can be evaluated to zero [4]. It is
sometimes the case that complicated ways of expressing zero do not, in fact, reduce to zero within
the computer algebra system. In such cases it will return a Petrov type which is unnecessarily
specialized. To determine the reliability of the computer’s evaluation, the PetrovReport()
command is provided, which details the intermediate calculations performed in the determination
of the Petrov type.

> PetrovReport():
The conclusion ’Petrov type = III (or simpler)’ for the sm metric
was based on the following results:
Weyl scalar Psi0 could not be evaluated to zero.
Weyl scalar Psi1 could not be evaluated to zero.
Weyl scalar Psi2 = 0
Weyl scalar Psi3 = 0
Weyl scalar Psi4 = 0
– – – > Therefore the metric is Petrov III (or simpler).
We see from the previous output that the indeed the calculations have been carried out correctly
(all of the terms which the computer believes to be non-zero are actually non-zero).
The use of null tetrads and general bases is treated in more detail in Booklet E: Bases and
tetrads.

5 Defining new tensors

Finally, we describe a facility which exists within GRTensorIII for defining tensors which are not
part of the standard object libraries. Here we define the Bel-Robinson tensor,
∗
Tcdef := Cacdb C a ef b + Cacdb C ∗a ef b ,
as well as it’s trace and its divergence using the command grdef():

> grdef (‘T{(c d e f)} := C{a c d b}*C{^a e f^b}+ Cstar{a c d b}

*Cstar{^a e f^b}‘):
> grdef (‘TT{(c d)} := T{^a a c d}‘):
> grdef (‘TC{(b c d)} := T{^a b c d ;a}‘):

In the strings defining these tensors, contravariant indices are indicated by preceding them with a
caret, ‘^’, while covariant differentiation is indicated as usual, with a semi-colon, ‘;’. The braces
on the left-hand side of the assignment in each command indicate that the newly defined tensors
should be assumed to be symmetric under interchange of their indices. The calculation functions
which are automatically generated by grdef() will take these symmetries into account to improve
the efficiency of calculations.
We now load the Kerr-Newman metric and calculate these objects:

> qload(newkn):
A. Introduction and overview A9

Coordinates:
xa = [ r u φ t ]
Line element
 
(a2 −u2 )(2mr−Q2 )
2 2
(r + u )dr2 2 2
(r + u )du 2 (a2 − u2 ) r2 + a2 + r 2 +u2 dφ2
ds2 = + +
r2 − 2mr + a2 + Q2 a 2 − u2 a2
(a2 − u2 )(2mr − Q2 )dφdt 2mr − Q2
 
− + −1 + dt2
a(r2 + u2 ) r2 + u2

Kerr–Newman Solution in Boyer–Lindquist coordinates (u = a ∗ cos(θ))

> grcalc ( T(dn,dn,dn,dn) ):

We display a component (e.g. Trrrr ):

> grcomponent ( T(dn,dn,dn,dn), [r,r,r,r] ):

m2 r2 − 2mrQ2 + m2 u2 + Q4
6
(r2 + u2 )2 (r2 − 2mr + a2 + Q2 )2

We now check that T a acd = 0 and that ∇a T a bcd = 0 in vacuum:

> grcalc ( TT(dn,dn) ):

> grdisplay( ):
TT(dn,dn) = All components are zero
> Q:=0:
> grcalc ( TC(dn,dn,dn) ):
> grdisplay( ):
TC(dn,dn,dn) = All components are zero
A more thorough discussion of the definition of tensors in GRTensorIII is to be found in
Booklet D: Defining new tensors.
A. Introduction and overview A10

Conventions
GRTensorIII can perform tensor calculations in any number of dimensions and for symmetric met-
rics of arbitrary signature. Tensor indices generally take values from 1 . . . n in an n-dimensional
spacetime.
In its definitions of curvature tensors, GRTensorIII follows the Landau-Lifshitz spacelike con-
ventions. That is, the curvature (Riemann) tensor is defined by

∂Γabd ∂Γabc
Ra bcd := c
− + Γaec Γebd − Γaed Γebc ,
∂x ∂xd
the Ricci tensor by
Rab := Rc acb ,
and the Einstein tensor by
1
Gab := Rab − Rgab .
2
Although spacetimes of any signature can be defined, for four dimensional Lorentzian metrics
the signature +2 is recommended. Most standard curvature calculations will be carried out
correctly regardless of the signature convention. However, some tensors (in particular the vector
operators of Booklet C: Calculating tensor components) which depend on the normalization of
timelike or spacelike vectors can be affected by the choice of signature. If a signature other
than +2 is employed, users should carefully check tensor definitions for signature dependent terms.

The only deviation from this standard signature is in the specification of the Newman-Penrose
formalism, which follows the original definitions of [3], and thus requires a -2 signature for
spacetimes.

References
[1] D. Kramer, H. Stephani, Herlt E., and M. MacCallum. Exact Solutions of Einstein’s Field
Equations. Cambridge University Press, Cambridge, 1980.
[2] M. A. H. MacCallum and S. T. C. Siklos. Algebraically-special hypersurface-homogeneous
Einstein spaces in general relativity. J. Geom. Phys, 8:221–242, 1981.
[3] E. T. Newman and R. Penrose. An approach to gravitational radiation by a method of spin
coefficients. J. Math. Phys., 3:896–902, 1962. (Errata 4:998, 1963).
[4] F. W. Letniowski and R. G. McLenaghan. An improved algorithm for quartic equation clas-
sification and Petrov classification. Gen. Rel. Grav., 20:463–483, 1988.