K.

Eng
A. Marthinsen
H. Z. Munthe-Kaas

DiMan

User's Guide
Version 1.6

March 10, 1999

ISSN 0333-3590
REPORT NO 166
March 1999
Department of Informatics, University of Bergen, Norway

Preface
DiMan is a MATLAB toolbox for solving Ordinary Dierential Equations on manifolds, based

on the concept of 'Coordinate Free Numerics'. This is, loosely speaking, the idea that (whenever
possible) it is important to formulate numerical algorithms generically, independent of special
representations and coordinate systems. DiMan inherits its basic design philosophy from the
C++ package SOPHUS. The SOPHUS project was initiated by Magne Haveraaen and Hans
Munthe-Kaas, University of Bergen, and aims at solving tensor eld equations on sequential and
parallel computers.
Some of the mathematical background of DiMan is described in Appendix A. This chapter,
however, is included for the sake of completeness. The user can read the rest of the manual and
use DiMan without having studied this chapter.
The writing of this toolbox was initiated as a project within the SYNODE project, and a number
of papers describing the numerical methods in DiMan is available on the SYNODE home page
at URL http://www.math.ntnu.no/num/synode/.
We will thank Antonella Zanna for reading an earlier version of this User's Guide and always
giving helpful suggestions, and Martine T. Monsen for extensive proof reading.
Kenth Eng

Arne Marthinsen

Hans Z. Munthe-Kaas

Contents
1 Introduction
2 The DiMan environment

2.1 Object orientation and mathematics . . . . .

2.2 Object orientation in MATLAB and DiMan
2.3 Structure of DiMan . . . . . . . . . . . . . .
2.3.1 Functor classes . . . . . . . . . . . . .
2.4 Objects in DiMan . . . . . . . . . . . . . . .
2.4.1 The domain object . . . . . . . . . . .
2.4.2 The eld object . . . . . . . . . . . . .
2.4.3 The time stepper object . . . . . . . .
2.4.4 The ow object . . . . . . . . . . . . .
2.5 How to get help in DiMan . . . . . . . . . .

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

How to get started . . . . . . . . . . . . . . . . . . . . . . . . . . . .

How to solve dierential equations in DiMan { A 5-step procedure
A detailed example . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ODEs as in nitesimal generators . . . . . . . . . . . . . . . . . . . .

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

3 How to use DiMan

3.1
3.2
3.3
3.4

4 Domain

4.1 Homogeneous spaces . . . . . . .

4.2 Lie algebras . . . . . . . . . . . .
4.2.1 The free Lie algebra . . .
4.3 Lie groups . . . . . . . . . . . . .
4.4 My domain is not implemented!?

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

5 Field

1
3

3
4
5
5
6
6
6
7
7
8

11
11
12
13
17

21
21
22
22
23
24

25

5.1 Vector eld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

6 Flow

6.1 Time stepping . . . . . . . . . . . . . . . . . . . . . .

6.1.1 My time stepper is not implemented!? . . . .
6.2 Implicit methods | Solution of nonlinear equations
6.3 Variable step sizing . . . . . . . . . . . . . . . . . . .

7 Auxiliary
7.1
7.2
7.3
7.4

Demos . . . . . . . .
Documentation . . .
Examples . . . . . .
Utilities . . . . . . .
7.4.1 flowtools .
7.4.2 lafreeutil .

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

27
28
30
30
30

33
33
34
34
36
36
37

vi

CONTENTS
7.5 Eciency and speed-up of DiMan . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
7.5.1 Speed-up through MEX- les . . . . . . . . . . . . . . . . . . . . . . . . . . 38
7.5.2 Speed-up by use of the free Lie algebra . . . . . . . . . . . . . . . . . . . . . 39

A The mathematical building blocks of DiMan

A.1 Homogeneous spaces . . . . . . . . . . . . . . . . . .

A.2 Computing ows of vector elds . . . . . . . . . . . .
A.2.1 Classical Runge{Kutta methods . . . . . . .
A.2.2 Munthe-Kaas methods . . . . . . . . . . . . .
A.2.3 Magnus series methods . . . . . . . . . . . . .
A.2.4 Quadrature methods on quadratic Lie groups
A.2.5 Fer expansion methods . . . . . . . . . . . . .
A.2.6 Crouch{Grossman methods . . . . . . . . . .

B Available time stepper schemes

C Summary of virtual superclass functions
C.1
C.2
C.3
C.4
C.5
C.6

Index

Functions in @liealgebra .
Functions in @liegroup . .
Functions in @hmanifold .
Functions in @vectorfield
Functions in @flow . . . . .
Functions in @timestepper

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.

45

45
47
47
47
49
51
52
54

57
59
59
61
63
64
65
66

67

Chapter 1

Introduction
DiMan is an object oriented MATLAB toolbox designed to solve dierential equations evolving
on manifolds. DiMan 1.6 addresses primarily the issue of solving ordinary dierential equations.

The solution techniques implemented fall into the category of geometric integrators { a very active
area of research during the last few years. The essence of geometric integration is to construct
numerical methods that respect underlying constraints, for instance the con guration space of
a mechanical problem, and to render correctly geometric structures and invariants important to
the underlying continous problem. Hence, the DiMan toolbox collects some of the most recent
and sophisticated methods for solving ODEs in the sense of geometric integration. DiMan is
an ongoing project and an overall goal for future work is to also include geometric integration
techniques for partial dierential equations evolving on in nite dimensional manifolds.
To understand the workings of DiMan, a geometric understanding of ordinary dierential equations evolving on a manifold is of great importance. Consider the ordinary dierential equation
y = F(t y)
0

y(0) = y0

(1.1)

evolving in Euclidean space. That is y 2 Rn and F(t y) is a vector eld assigning to each point
in Rn and time t 2 R, a vector F. The geometric interpretation of nding a solution to equation
(1.1) is to nd a curve y(t) starting at the point y0 in Euclidean space, having as its tangent at
every succeeding point and time the vector speci ed by the vector eld F. Hence, we want to
follow a curve in space that starts at the inital point y0 , evolving in the direction prescribed by
the vector eld.
This same description can be used for an ordinary dierential equation evolving on a manifold.
The only dierence is that the manifold is in general a non-linear space, and not a linear vector
space. The simplest example of a manifold is the sphere. A vector eld over the manifold will
at each point attach a tangent vector, just like in the Euclidean case. A solution of this ODE is
a curve through the initial point y0 , that evolves on the manifold in the direction given by the
tangent vector.
There is a well established theory for solving (1.1) on a Euclidean space, a fact to be extensively
exploited in one of the methods discussed in Appendix A. A well-known family of methods are
the Runge{Kutta methods 12]. There are also splitting methods and composition methods, see
for instance 23, 24], but in DiMan we will among the classical methods mainly be concerned
with the Runge-Kutta family.

Introduction

Availability of DiMan
DiMan 1.6 is available according to the Licence Agreement. Problem reports should be submitted

by email to:

[email protected]

Up to date information and documentation on DiMan is found on WWW at URL:

http://www.math.ntnu.no/num/diffman/

The Authors
The authors of DiMan are

Kenth Eng

Department of Informatics
University of Bergen
N-5020 Bergen, Norway
Email: [email protected]
WWW: http://www.ii.uib.no/~kenth/

Arne Marthinsen

Department of Mathematical Sciences

Norwegian University of Science and Technology
N-7491 Trondheim, Norway
Email: [email protected]
WWW: http://www.math.ntnu.no/~arnema/

Hans Z. Munthe-Kaas

Department of Informatics
University of Bergen
N-5020 Bergen, Norway
Email: [email protected]
WWW: http://www.ii.uib.no/~hans/

Acknowledgement
This work was in part sponsored by the Norwegian Research Council under contract no. 111038/410
through the SYNODE project. The SYNODE project is found on WWW at URL:
http://www.math.ntnu.no/num/synode/

Licence Agreement
DiMan 1.6 is provided free of charge for non-commercial purposes.

Chapter 2

The DiMan environment

In this chapter we will go through basic concepts in object orientation and explain how these
things are done in MATLAB. We will outline the general structure of DiMan and discuss the
four dierent types of objects used in DiMan. The last section, probably the most important
section in the whole user's guide, discusses how to go about getting the necessary help in DiMan.

2.1 Object orientation and mathematics

A class is simply a collection of 'elements' with equal properties. In mathematical terms one
would say that a class is a set. The 'elements' of a class is usually called objects, and the common
properties of the objects specify the class. Mathematically, the properties of a class can be stated
as relations that the object must satisfy in order to be a member of the class. Another very
important and interesting aspect of object orientation is that it allows for information hiding. An
object typically consists of a public and a private part. The public part can be accessed from
the outside of the class, whereas the private part cannot. This enables us to hide implementation
speci c issues for the particular class in the private part, and to easily make changes to it, without
altering the public interface of the class.
This then, naturally brings up the issue of specifying a class. A class speci cation can be divided
up into a 'what' part and a 'how' part. 'what' describes the interaction of the class with the
surroundings what is the public interface of the class, 'what' is the class supposed to do? 'how'
the class is implemented is an issue related to the private section of the class. The surroundings
do not need to know about implementational issues as long as the interaction of the class is as
speci ed by the public interface.
This distinction between 'what's and 'how's of objects (elements) is ubiquitous in pure mathematics. This is also the reason why abstract mathematical concepts are so well suited for implementation in object oriented programming languages, see 13, 28]. Coordinate free constructions
in mathematics, e.g. tensors, tries to capture what the operation of an object is regardless of the
coordinate system. The tensor class is then speci ed by properties independent of the coordinate
systems, and the dierent choices of coordinates used in an actual implementation on a computer
is deferred to the private part of the class. Hence, a speci cation of a class emphasizes and extracts
the important features of a class, and this conforms very well with algebraic techniques so rampant
in pure mathematics.
Thinking in these terms gives rise to the rather contradictory term 'coordinate free numerics'
28, 29]. What is a coordinate free algorithm? The whole idea is to device algorithms speci ed
by algebraic operations not dependent on the particular representation of the object. All the

The DiMan environment

methods in DiMan are de ned on groups and they are all very good examples of coordinate free
algorithms. The group elements can have very dierent representations, but the algorithms are
all expressed through algebraically de ned operations such as group multiplication and Lie-group
actions.

2.2 Object orientation in MATLAB and DiMan

In MATLAB a class is de ned by creating a directory @myclass, where myclass is the name
of the class. The pre x @ simply tells MATLAB that this is a class directory. All the public
class functions are put in this directory, while the private class functions are put in a directory
@myclass/private.
Where the le is located within the class directory tree distinguishes the
m- le from being a public or private function.
Every class must have its own unique constructor. The constructor is implemented in an m- le
called myclass.m, the same name as the class itself. In MATLAB, a class object is represented as
a MATLAB struct, where a struct is the same as a struct in C or a record in PASCAL. This struct
can have an arbitrary number of elds. To turn a MATLAB struct into an object of @myclass
the function class must be called within the constructor m- le:
obj.field1 = n1

obj.field2 = n2

obj = class(obj,'myclass')

The user can not access the structure elds of the object directly in MATLAB. Attempting to
do this will result in an error. Hence, the elds of the object struct can be viewed as part of the
data representation of the object, and is private to the class. For the user to interact with the
information contained in the elds of the object struct, the class must have implemented public
m- les speci cally doing this.
Public functions making up the interface of a class are naturally divided up into three categories:
constructors, observers, and generators. In MATLAB there is only one constructor, but
in other object oriented programming languages like C++ it is possible to have more than one
constructor. The observers of a class are the public functions that extract information from the
class objects without altering the object itself. The generators of a class are those public functions
which change properties of the class objects, or create new objects of the same or other classes.
In DiMan you will typically nd this partition of the public functions when reading a class
speci cation.
In DiMan the object orientation is applied in several dierent ways. The domain points (elements
of a manifold) are treated as members of a class. Depending on the speci c properties of the
domain, there are several types of domains implemented in DiMan. Each of the dierent types
of domains are collections of algebraically similar domain classes i.e. it is a category in the strict
mathematical sense. The integration methods used to solve the ODEs are called time steppers,
and the dierent time stepper methods are treated as dierent classes. Flows and vector elds are
also implemented as two classes.
In DiMan 1.6 there are three categories of domains implemented: Homogeneous spaces, Lie
algebras, and Lie groups. Each domain category is further divided up into domain classes of
that particular type. Hence, each of the classes within a particular domain type has similar
characteristics, but there are dierences that partitions them into individual classes. These similar
characteristics of the classes of a speci c domain type are what de nes the domain category. Trying
to de ne and specify the domain category is done through the introduction of a virtual superclass in
each domain category. The virtual superclass de nes and takes care of operations that are common
to all the classes in the domain category. This is obtained through the concept of inheritance in

2.3 Structure of DiMan

object orientation. The virtual superclass is the parent class of all the other classes in the domain
category, and all the child classes inherit the parents' functions. That means that one can apply
the public functions of the virtual superclass on an object of a child class. If the child class needs
speci c implemented versions of any of the public functions of the parent class, this is achieved
through overloading. Supply a public function to the child class with a matching name, and
MATLAB will use this version of the public function instead of the one supplied by the parent
class.

2.3 Structure of DiMan

The general structure of DiMan is reected in the way the directories are organized. The structure
is very modular and it is therefore very easy to add new classes of your own. In the DiMan root
directory you will nd 3 m- les and 4 directories. The directories are:
auxiliary/
domain/
field/
flow/

The auxiliary directory includes 4 subdirectories which contain the DiMan documentation,
command line examples, demos, and utility functions. As the name of this directory reects its
contents are not vital to the workings of DiMan.
The domain directory, however, contains the domain categories, which are very important building
blocks of DiMan. Think of a domain as a dierentiable manifold. Creating a domain category
is done by creating a subdirectory in the domain directory. In DiMan 1.6 there are 3 domain
categories implemented: homogeneous spaces, Lie algebras, and Lie groups. The classes of a
domain category are put in this subdirectory along with a virtual superclass specifying the domain
category.
The field directory contains eld classes de ned over domain classes. Think of this directory as
the eld category. Since DiMan 1.6 only solves ordinary dierential equations, the only eld class
implemented so far is @vectorfield. The eld category is subject to change in future releases of
DiMan, but @vectorfield will stay the same. In order to solve some PDEs it is interesting to
be able to de ne tensor elds over manifolds, hence a tensor eld class is very likely to be added
in a future release of DiMan.
The flow directory collects classes pertinent to the continuous ow. The numerical methods are
treated as time steppers, and they are all placed in the subdirectory timesteppers found in the
flow directory. The ow class is a virtual superclass with no subclasses since all the numerics are
placed within the time steppers. The reason for this distinction between ow and time stepper
is an attempt to isolate features common to all the numerical methods (the time steppers), e.g.
variable time stepping, and place these features in the ow class.

2.3.1 Functor classes

In DiMan the dierent domain types are viewed as categories. A function on a category is called
a functor. Examples of internal functors are the direct product, semi-direct product, and tangent
map. The direct product functor will take n domain classes as input, and create a new domain
object the direct product of the domains. The semi-direct functor works in an analogous way. The
tangent functor takes a domain manifold and turns it into the tangent bundle of that manifold.
The tangent bundle is also a manifold hence, it is a domain.

The DiMan environment

In DiMan we call classes that automatically generate new domains from other ones functor
classes. The choice of name should be clear from the above discussion. In DiMan 1.6 you will
nd one of the above functorial constructors implemented the direct product of domains. The
functor classes in question are @ladirprod and @lgdirprod. The next release of DiMan will
include the semi-direct product functor and the tangent functor.

2.4 Objects in DiMan

In DiMan you will encounter 4 dierent types of objects: domain, eld, time stepper, and
ow objects. Each object is de ned in such a way as to capture the mathematical essentials of
a manifold, the eld de ning the dierential equation, the numerical time stepper algorithm, and
the ow operator, respectively. We will discuss each one of these objects in the following.

2.4.1 The domain object

Every domain object (e.g. objects of the type Lie algebra, Lie group, or homogeneous space) is
built up as a MATLAB struct with two elds: shape and data. Generically, every domain object
is represented as:
domainobject =
shape:
data:

A domain object speci es a speci c point in a speci c manifold. It is often useful to create a single
class for representing a family of manifolds, e.g. all Lie algebras gl(n) are represented by the same
class @lagl. The shape speci es the particular manifold in the family (in this case n), while the
data part represents a particular point in this manifold (in this case n by n matrices. The shape
is in computer science called a dynamic subtyping of the class. If an object has an empty data
eld, it is taken to only represent the space (the subtype).
A second example is the dynamic subtyping of the homogeneous space @hmlie. This is the
homogeneous space obtained by any Lie group acting on itself by left multiplication. Considering
all the dierent Lie groups and Lie algebras, the shape is chosen to be an object of the particular
group or algebra. Since all Lie groups and Lie algebras themselves are dynamically subtyped, the
shape of @hmlie must be a Lie group or Lie algebra object with a pre-set shape. This is because
we need to know a 'size' measure on the domain objects that are acting on themselves.
The user cannot access the contents of the shape and data elds of a domain object directly, since
the elds belong to the private part of the domain class. In order to do this the user must use the
public functions getshape and getdata to return the contents of the elds, and setshape and
setdata to update the values of the private elds.

2.4.2 The eld object

A eld is de ned over a manifold. Some examples of elds are vector elds, tensor elds, and
divergence free vector elds. A vector eld is a mathematical construction which assigns a vector
to every element of the manifold. Likewise for a tensor eld, a tensor is assigned to each element
of the manifold. From this it is natural to conclude, since the output from dierent elds is not
similar, that a generic eld object only contains information about the manifold over which the
eld is de ned:

2.4 Objects in DiMan

fieldobject =
domain:

To de ne an ordinary dierential equation we only need the notion of a vector eld. Tensor elds
are mainly used in partial dierential equations. DiMan 1.6 is only devoted to the solution of
ODEs evolving on manifolds. Hence, the only eld class implemented is @vectorfield. The
generic representation of a vector eld object is:
vectorfieldobject =
domain:
eqntype:
fm2g:

Compared to the above eld object, two more struct elds have been added in the vector eld
object. In DiMan 1.6 every vector eld over a manifold is represented by a function  : R M !
g. This function is called fm2g, (function from M to g). If the function fm2g only depends on
time, the ODE is said to be linear or of Lie type, and it is said to be general if the function fm2g
depends on both time and con guration. The eqntype provides this information.

2.4.3 The time stepper object

This is where all the numerics are hidden. A time stepper is the numerical algorithm used in
advancing the solution of the dierential equation one step along the integral curve of the ow.
There are dierent approaches in constructing these time steppers and a list of the available time
steppers in DiMan 1.6 is found in Appendix B.
Common for all the time steppers is that they work locally on the domain manifold, and because
of this they need to know local coordinates on the Lie group manifold. Another common feature
is that the time steppers naturally divide up into classes of methods. The steppers belonging to
one particular class are typically distinguished by the order of approximation the method yields.
Hence, it is important to also be able to choose a method of the preferred order.
The generic representation of a time stepper object takes the form:
timestepperobject =
coordinate:
method:

2.4.4 The ow object

Mathematically, the ow is an operator de ned by the vector eld. Given the ordinary dierential
equation
y = F(y) y(0) = p 2 M
the ow operator of this dierential equation is the operator "Ft : M ! M satisfying
d
dt "Ft(p) = F ("Ft(p)):
The classical solution of a dierential equation is an integral curve of the vector eld generating
the ow operator. This integral curve is found by evaluating the ow operator in the initial point
on the manifold.
The generic representation of a ow object is:
0

The DiMan environment

flowobject =
vectorfield:
timestepper:
defaults:

The ow object must, of course, know the vector eld de ning it. Next, it needs to know a time
stepper object. The choice of time stepper speci es the numerical algorithm to be used in the
solution of the dierential equation. This is really all the information that the ow object needs to
know. However, for convenience, constants used in variable time stepping and nonlinear equation
solving are collected in the ow object in the third eld defaults. Unless the user changes any
of these constants with the setdefaults function, the default values set by the ow constructor
will be used.

2.5 How to get help in DiMan

In MATLAB there are three ways to get online help. The rst two provide simple help information
on MATLAB functions, while the third is a huge collection of documentation stored in hypertext
format which you access with a Web browser.
HELP
- Function help, display help text at command line
HELPWIN - Function help, separate window for navigation
HELPDESK - Comprehensive hypertext documentation and troubleshooting

In DiMan you will also have the possibility of using a window based help system called dmhelp.
DMHELP

- An extended and improved version of HELPWIN

This help system is based on the helpwin system in MATLAB, but several new features have
been added: Access information about all the dierent classes and class functions, view the source
code of m- les, view this User's guide online in pdf, go to the DiMan home page on WWW,
etc. Please note that dmhelp can only be invoked once you have started the DiMan toolbox, see
Section 3.1.

Figure 2.1: The DiMan Help Window.

Once you have started up DiMan you issue the command
>> dmhelp

2.5 How to get help in DiMan

in order to just launch the DiMan Help Window, or type the command
>> dmhelp topic

to launch the DiMan Help Window with the help information about topic.
Once the DiMan Help Window system has been launched, see Figure 2.1, you can type any
help topic in the upper left box of the Help Window and press 'Enter'. If the help topic has help
information this will be displayed. If a line in the main text of the Help Window starts with a
help topic followed by ' - ', you can also click on it directly in order to access the help information.
Consider the following examples. If you see lines in the main text Help Window looking like these,
you just click on them directly in order to go to that help topic:
plot
liealgebra
@liealgebra
@lagl
@lafree/order

Help on any matlab functions.

Help on the _directory_ 'liealgebra'.
Info on the _class_ 'liealgebra'.
Info on the Lie algebra gl(n).
Function 'order.m' in class 'lafree'.

The other option is to type the name of the help topic in the box in the upper left corner, and
access the same information this way.
The rst time you launch the DiMan Help Window it might take some time before it appears.
If you in a MATLAB session want to close the Help Window after you have nished using it, we
urge you to use the 'Close' button in the window. The reason for this is that in case you want to
launch the Help Window again in the same session, MATLAB will use the same window. Hitting
the 'Close' button causes MATLAB to turn the visibility of the window o, and MATLAB does
not have to recreate the window again when you re-enter the command dmhelp.
If none of the above commands seems to give you the desired explanations, you can also try the
MATLAB commands: demo, lookfor, which, and general.

Chapter 3

How to use DiMan

This chapter will teach you the basics of solving dierential equations in DiMan. The rst
section shows you how to initialize DiMan and get the toolbox up and running. The next section
describes a 5-step procedure to be followed when solving dierential equation in DiMan, followed
by a section taking you through a very detailed example demonstrating the 5-step procedure in
practice. We end this chapter by discussing ODEs represented as in nitesimal generators.

3.1 How to get started

The very rst thing to do is to initialize the DiMan toolbox. Make sure that you are located in
the DiMan directory, or that this directory is included in the MATLAB path. You can easily
include the following command in your startup.m le, or issue it at the MATLAB prompt:
>> addpath('/local/path/on/your/machine/DiffMan')

Initializing DiMan is done simply by typing the command:

>> dminit

The result of this command is that all necessary paths are set and the following is displayed in
MATLAB:
DiffMan Version 1.6 is initialized - 1999.03.10
Please report any problems and/or bugs to:
[email protected]
For more information and how to get started, try:
>> dmtutorial
>> dmhelp
>> demo
>>

The DiMan facility dmtutorial will launch a window where you can choose to run dierent
kinds of tutorials. One of these tutorials will guide you through 'How to solve ODEs in DiMan '.

12

How to use DiMan

This is the 5-step procedure presented in the next section. The other tutorials will guide you
through other important aspects of the DiMan toolbox essential to the user. For further details,
see Section 7.1.
dmhelp is a substantially improved version of the helpwin facility in MATLAB. dmhelp will launch
a DiMan help window where you can get help on every function and class in DiMan, and also
every other function in MATLAB. Hence, when working with DiMan we urge you to use dmhelp
instead of the MATLAB functions helpwin and help. For more information about the workings
of dmhelp, see Section 2.5.
The MATLAB demo utility will include DiMan among its toolboxes. Running the DiMan
demos is another convenient way of launching the DiMan tutorials, and running all the DiMan
command line examples.

3.2 How to solve dierential equations in DiMan { A 5step procedure

Once DiMan is initialized you can start solving dierential equations.
In DiMan we are exclusively working with objects, and these objects are members of dierent
classes. To create an object of a particular class, invoke the constructor of that class. The
constructor always has the same name as the class.
The 5-step procedure for solving dierential equations in DiMan is the following:
1) Construct an initial domain object y in a homogeneous space. In order to solve an
initial value problem, DiMan needs to know an initial condition. The initial domain object
serves this purpose.
2) Construct a vector eld object vf over the domain object y. DiMan nds numerically the integral curve of this vector eld through the initial domain object. A vector
eld object consists of three parts: domain, eqntype, and fm2g. Set these properties of the
vector eld object by the functions setdomain, seteqntype, and setfm2g. See Section 5.1
for more information.
3) Construct a time stepper object ts. The time stepper class determines the numerical
method used to advance the numerical solution along the integral line. A time stepper
object consists of two parts: coordinate and method. Set these properties of the time
stepper object by the functions setcoordinate and setmethod. See Chapter 6 for more
information.
4) Construct a ow object f. The ow object is de ned by the vector eld object. Since we
are doing numerical computations the ow object also needs to know how to step forward,
hence the ow object f also needs to know the time stepper object. To set the two properties
of the ow object, use the functions setvectorfield and settimestepper.
5) Solve the ODE. Solving the ODE de ned by the ow object in DiMan is simply done by
evaluating the ow object at the initial domain object, start time, end time, and step size:
>> output = f(y,tstart,tfinal,h)

Variable step size is indicated by using negative values for h. The initial step is then of length
jhj. output is a MATLAB structure that consists of three elds: output.y is a vector of domain
objects, output.t is a vector of time points, and output.rej is a vector indicating rejection of a
time step in variable time stepping.

3.3 A detailed example

13

Detailed mathematical information and de nitions of ows and vector elds are found in Appendix A.
The 5-step procedure will be demonstrated on an example in the next section.

3.3 A detailed example

Consider solving the following dierential equation on the sphere S 2 :
2
3
23
t ;0:4 cos(t)
0
dy = 4 ;0t
5 y(t)
405 
0
0:1t
y(0)
=
dt
0:4 cos(t) ;0:1t
0
1

(3.1)

where y 2 R3 is a vector of unit length, and the matrix on the right hand side is a map from R
into so(3).
The homogeneous manifold in question is @hmnsphere which consists of the sphere manifold S 2 ,
the Lie algebra of O(3) which is so(3), and the action # : (v m) ! exp(v)  m of so(3) on S 2 . The
elements of the manifold S 2 are vectors of unit length.

Step #1: Construct an initial domain object y in @hmnsphere

The initial domain object is created by calling the constructor of @hmnsphere. This constructor
can take an integer or a laso object as an argument and thereby specifying the shape of the
manifold object.
>> y = hmnsphere(3)
y =
Class: hmnsphere
Shape-object information:
Class: laso
Shape: 3

The shape of an object in @hmnsphere consists of an object in the Lie algebra laso. The integer
supplied to the constructor sets the shape of this Lie algebra object which comprises the shape of
the @hmnsphere object. If an argument to the constructor is not supplied, the shape can be set
later by using the setshape function.
As mentioned in the beginning of this Section, the data representation of an object in @hmnsphere
is a vector of unit length. If the initial condition for the ODE on the sphere is the North pole, the
data of the initial object must be set equal to the North pole vector.
>> setdata(y,0 0 1]')

>> y
y =
Class: hmnsphere
Shape-object information:
Class: laso
Shape: 3
Data:
0
0
1

The rst step is now completed.

14

How to use DiMan

Step #2: Construct a vector eld object vf over the domain object y

A vector eld is de ned over a domain. The constructor of @vectorfield is called with the domain
object as input:
>> vf = vectorfield(y)
vf =
Class: vectorfield
Domain: hmnsphere
Shape-object information:
Class: laso
Shape: 3
Eqn type:
General

Already, vf contains a lot of information. Since the domain object was supplied as an argument for the vector eld constructor, the domain information is already set. The shape of the
@hmnsphere object is a laso object, and the information about this Lie algebra object is displayed
as Shape-object information. Further, the equation type of the generator map for the vector
eld is set to be 'General'. This is the default value. However, equation (3.1) is of linear type, so
the type should be changed to 'Linear' in order to speed up the calculations.
>> seteqntype(vf,'Linear')

The generator map of equation (3.1) is the matrix on the right hand side of the equation. The
m- le vfex5.m contains the MATLAB necessary code to implement the generator map.
>> setfm2g(vf,'vfex5')

What does this m- le vfex5.m look like? To view the le, you can type type vfex5.m at the
MATLAB prompt, or use dmhelp and push the button View src. Either way the output is:
function la] = vfex5(t,y)
% VFEX5 - Generator map from RxM to liealgebra. Linear type.
la = liealgebra(y)

dat = 0 t -0.4*cos(t)
-t 0 .1*t
.4*cos(t) -.1*t 0]

setdata(la,dat)

return

All the generator map function les that you write on your own must have this generic structure:
The le must support two arguments the rst is a scalar - time, and the second is a domain
object from the homogeneous space. Output must be a Lie algebra object. To nd the correct Lie
algebra of the domain object, call liealgebra(y), which will return an object in the correct Lie
algebra with preset shape information. Edit the data dat, and call setdata(la,dat) in order to
set the data representation of the Lie algebra object.
Now the vector eld object vf displays as:
>> vf
vf =
Class: vectorfield
Domain: hmnsphere
Shape-object information:

3.3 A detailed example

15

Class: laso
Shape: 3
Map fm2g:
vfex5
Eqn type:
Linear

Step #3: Construct a time stepper object ts

The time stepper class decides which numerical method to use for advancing along the integral
curve of the vector eld. Calling any of the time stepper constructors will return a time stepper
object with default coordinate and method. If the user prefers other coordinates or another
method, these can be changed through the functions setcoordinate and setmethod. To get an
overview of the dierent time steppers type dmhelp timestepper in MATLAB. In our example
we want to use an RKMK method:
>> ts =
ts =
Class:
Coord.:
Method:

tsrkmk
tsrkmk
exp
RK4

In case of @tsrkmk the default coordinate is exp and the default method is RK4. For a discussion
of possible choices of coordinates, see Section 6.1. For each time stepper class there are many
schemes to choose from. None of these schemes can be used for all the dierent time stepper
classes and DiMan will issue an error message if a wrong selection is made.
In our example we are not satis ed with only the standard 4th-order RK4 method we want the
more accurate answer supplied by the 6th-order Butcher method:
>> setmethod(ts,'butcher6')
>> ts
ts =
Class: tsrkmk
Coord.: exp
Method: butcher6

To get information about the dierent methods while running DiMan, type dmhelp setmethod.

Step #4: Construct a ow object f

The ow object is constructed from the vector eld object vf and the time stepper object ts
already created. Merely calling the @flow constructor will create an object with a default time
stepper. The default time stepper preset in the ow object f is only a matter of convenience, and
must not be confused with the time stepper object created in Step #3.
>> f = flow
f =
Class: flow
Timestepper class: tsrkmk
Coordinates:
exp
Method:
RK4

In our example we have created another time stepper object ts that we want to use instead of the
default time stepper object supplied by the @flow constructor. To change the time stepper of the
ow object f to ts, call the function settimestepper:

16

How to use DiMan

>> settimestepper(f,ts)

A ow is de ned as the ow of some vector eld. Hence, our ow object f must have information
about this vector eld.
>> setvectorfield(f,vf)
>> f
f =
Class: flow
Vector field information:
Domain:
hmnsphere
Equation type:
Linear
Map defining DE: vfex5
Timestepper class: tsrkmk
Coordinates:
exp
Method:
butcher6

Now the ow object has the necessary information and we can go on to the next, and nal step,
in the 5-step solution procedure.

Step #5: Solve the ODE

Solving equation (3.1) with the RKMK method is done by evaluating the ow object with four
arguments: initial domain object, start time, end time, and step size.
>> curve
curve =
y:
t:
rej:

= f(y,0,5,0.05)
1x61 hmnsphere]
1x61 double
]
1x61 double
]

The output curve is a MATLAB struct with the three elds: y, t, and rej. curve.y is a vector of
objects from the homogeneous space upon which the problem is modeled. curve.t is a vector of
scalars, the time points. curve.rej is a vector of integers indicating whether a step was rejected
or not. In our example curve.rej is the zero vector, since we did not use variable time stepping.
See Section 6.3 on how to do variable time stepping.
Calling getdata(curve.y) will access the actual data representations of all the @hmnsphere objects. In this case, this output will be a vector three times the length of the scalar vector curve.t.
To get the 3-vectors corresponding to each time point, the output from getdata(curve.y) must
be reshaped into a 3length(t) matrix where each column corresponds to a time point. To plot
the data we can do the following:
>>
>>
>>
>>

t = curve.t

a = getdata(curve.y)

a = reshape(a,3,length(t))

comet3(a(1,:),a(2,:),a(3,:))

In Figure 3.1 the solution of the problem is plotted on the Northern hemisphere of the unit ball.
This detailed example is found as example 5 in the DiMan toolbox and runs by typing:
>> dmex5

3.4 ODEs as innitesimal generators

17

Figure 3.1: Plot of the solution of (3.1)

What's next?: Solve the same problem with a dierent time stepper

To use another time stepper to solve equation (3.1) we must repeat steps #3 through #5. We
must create a new time stepper object, put this into the existing ow object, and evaluate the
ow again. To use the Crouch{Grossman method we do the following:
>> ts2 = tscg
ts2 =
Class: tscg
Coord.: exp
Method: CG3a
>> settimestepper(f,ts2)
>> f
f =
Class: flow
Vector field information:
Domain:
hmnsphere
Equation type:
Linear
Map defining DE: vfex5
Timestepper class: tscg
Coordinates:
exp
Method:
CG3a
>> curve = f(y,0,5,0.05)

To plot the solution we just repeat the above plotting commands. The solution is the same, except
from the fact that we have used a third-order method. This solution is not as accurate as the
solution obtained by the 6th-order Butcher method used in the RKMK time stepper.

3.4 ODEs as innitesimal generators

All the ODEs that we can solve in DiMan are assumed to be written in the form of an in nitesimal
generator. If you are given just any ODE, it might turn out to be an impossible feat to determine
the Lie-group action of which the given ODE can be written as the in nitesimal generator. The

18

How to use DiMan

choices can be many, and there is no known general procedure for doing this. Consult Appendix A
for necessary de nitions and notation.
But on the other hand, there are many well-known examples of ODEs evolving on homogeneous
spaces that are known to be able to be stated in the form of an in nitesimal generator. In the
rest of this section we will give you examples of such ODEs, in order to aid you in your hunt for
the group-action and the best setting for your particular ODE.
Recall that the ingredients of a homogeneous space is a Lie group G, a domain manifold M, and
a Lie-group action # : G  M ! M. The in nitesimal generator of the Lie-group action # with
respect to the element  2 g is de ned as

d
(3.2)
 (x) = dt  #exp(t) (x) 8x 2 M:
t=0
M

Example 3.4.1 (Classical ODEs in Rn)

Any classical ODE can be cast in the representation of an innitesimal generator by making the
choices M = Rn G = Rn, and #(g x) = g + x. Calculating the innitesimal generator of this
action (remember that in this case the exponential map is equal to the identity map) with respect
to the element  2 g = Rn gives us
 n (x) = :
(3.3)
Hence, any ODE
y = f(t y)
(3.4)
on Rn has the form of an innitesimal generator by just choosing the generator map  : R  Rn !
Rn equal to the function f in (3.4).

R
0

Example 3.4.2 (Dierential equations on matrix Lie groups)

In this example we choose the manifold equal to the Lie group that is M = G, and let the Lie
group act on itself by left multiplication, #(g h) = gh. In this case the exponential takes the form
of the matrix exponential and the innitesimal generator is
G (g) =   g:
(3.5)
Choosing  as the generator map f : R G ! g all ODEs on matrix Lie groups take on the general
form
y = f(t y)y:
0

Example 3.4.3 (Isospectral ows)

For isospectral
ows the domain manifold M is chosen as a subset of the set of n  n matrices. The
Lie group is the special orthogonal group SO(n) that acts upon M by the action #(g m) = gmg 1 .
The exponential map is in this case also equal to the matrix exponential, and the innitesimal
generator of this action with respect to the element  2 so(n) is
 (m) =  m]:
(3.6)
 ] is the matrix commutator. Now, choosing  as the generator map f : R  M ! so(n) all
ODEs for isospectral
ows take on the general form
y = f(t y)y ; yf(t y):
;

Example 3.4.4 (Lie-Poisson systems)

This example might seem very hard and abstract on a rst reading, but it is a very important
and interesting problem and deserves some attention. For notation and a detailed introduction
see 18, 6].

3.4 ODEs as innitesimal generators

19

A Lie-Poisson system is nothing else than a Hamiltonian problem. In this example the domain
manifold is the dual space of a Lie algebra g, that is M = g . The Hamiltonian function H : g ! R
is a conserved quantity for the
ow. The Lie group G acts on the dual Lie algebra g by the
coadjoint action: #(g ) = Ad g;1 (). The innitesimal generator of this action with respect to
 2 g is


g () = ad  ():

(3.7)

For this particular example it turns out that the generator map is expressible by the Hamiltonian.
Next, we will introduce the notion of the functional derivative, which classically is nothing else
than the gradient of a function. The functional derivative F
 of a function F : g ! R is the
element in the Lie algebra g that satises the relation
lim 1 (F( + ) ; F ()) = h F
(3.8)
 0
 i:
The functional derivative can be viewed as a function from g to g, and hence it serves the role as a
generator map for time-independent Hamiltonians. The Hamiltonian ODE on g with Hamiltonian
H takes the form


 = ad H
():

0

(3.9)

What does this equation look like in concrete examples? The rigid body and the Euler equations
pop up by considering the Hamiltonian H() = 21   I 1  modeled on the dual space of the Lie
algebra so(3). In this case (3.9) reduces to the Euler equations
d =   I 1 :
dt
;

Chapter 4

Domain
In DiMan 1.6 the following collections of domains are implemented:
hmanifold
liealgebra
liegroup

% Homogeneous spaces
% Lie algebras
% Lie groups

As a user you will work exclusively with homogeneous spaces. Thus, the collections of Lie algebras
and Lie groups are mere geometric building blocks for the homogeneous spaces.
Each of the collections of domains contains a virtual superclass of that collection. The purpose
of this superclass is that it serves as the parent of all the other classes, and all functions common
to all the classes in the collection are implemented once and for all in this superclass. Thus, all
the actual matrix class implementations contain far fewer functions than the number of functions
implemented in the virtual superclass. For an overview of the actual functions implemented in the
superclasses see Appendix C.
In MATLAB a class has to be pre xed by @ in order to be recognized as a class. The constructor
of the particular @myclass has to be an m- le with the name myclass.m. In the virtual superclass
of each collection of domains we have overloaded ordinary arithmetic operations in order to make
them work for the objects. Since the virtual superclass is the parent of all the implemented classes,
they inherit these operations. The advantage of this approach is that one saves a lot of coding if
a new class is to be added, and if changes has to be made these are only made one place. Do not
forget that these inherited functions can again be overloaded in each of the particular classes.
In the next three subsections, all the implemented classes in each of the domain collections are
listed.

4.1 Homogeneous spaces

The homogeneous space classes implemented in DiMan are the following:
@hmanifold
@hmisospec
@hmlie
@hmnsphere
@hmrigid
@hmrn

The virtual superclass

Isospectral flow: action of Lie algebra on M \in R^(nxn).
The action of any Lie group and algebra on itself.
The N-sphere with action of the orthogonal group.
The rigid body modeled as a homogenous space.
The action of any algebra on R^n.

22

Domain
@hmtop

- The heavy top modeled as a homogenous space.

The virtual superclass homogeneous space is named @hmanifold. All the other homogeneous
spaces are pre xed by @hm in order to emphasize that these are actual implementations of homogeneous spaces.

4.2 Lie algebras

The Lie algebra classes implemented in DiMan are the following:
@ladirprod
@lafree
@lagl
@larn
@lase
@lasl
@laso
@lasp
@liealgebra

The
The
The
The
The
The
The
The
The

direct product of Lie algebras.

free Lie algebra of q elements up to order s.
Lie algebra of the general linear group.
Lie algebra of R^n.
special Euclidean algebra.
Lie algebra of the special linear group.
Lie algebra of the special orthogonal group.
symplectic Lie algebra.
virtual superclass of all Lie algebras.

The virtual superclass Lie algebra is named @liealgebra. All the other algebras are pre xed by
@la in order to emphasize that these are actual implementations of Lie algebras.

4.2.1 The free Lie algebra

In this section we want to show you in a very rudimentary way how to use the free Lie algebra
class @lafree. See also Section 7.4.2 for other examples.
The commands given below reect the basic operations in the free Lie algebra class @lafree.
: : : ,wp]})

Generate a free Lie algebra from p symbols with grades w1,w2, : : : ,wp. All terms of total
grade greater than q are set to 0. If no grades are supplied, grades equal to 1 are used.

>> fla = lafree({p,q],w1,w2,

>> Xi = basis(fla,i)

Return the 'th Hall basis element in fla. If 1  i  p, return the i'th generator Xi .

>> X+Y
r*X
X,Y]

>>

Basic computations in the free Lie algebra.

Z = eval(E,{Y1,Y2, : : : ,Yp})

If E is an element of a free Lie algebra, and {Y1,Y2, : : : ,Yp} is a list of elements from any
DiMan Lie algebra, this will evaluate the expression E, using the data set Y1,Y2, : : : ,Yp
in place of the generating set.

Examples of use of these commands are:

>> fla = lafree({3,3]})
fla =
LieAlgebra class: lafree
Shape:
{3 3],1 1 1]}

4.3 Lie groups

23

Basis vectors:
1:1] 2:2] 3:3] 4:1,2] 5:1,3] 6:2,3] 7:1,1,2]]
8:1,1,3]] 9:2,1,2]] 10:2,1,3]] 11:2,2,3]] 12:3,1,2]]
13:3,1,3]] 14:3,2,3]]
>> x1 = basis(fla,1)
x1 =
LieAlgebra class: lafree
Data:
1]
>> x4 = basis(fla,4)
x4 =
LieAlgebra class: lafree
Data:
1,2]
>> x=random(lagl(2))
x =
Class: lagl
Shape: 2
Data:
992/1139
-166/925
1169/1402
1029/1307
>> y = random(x), z = random(x)
y =
Class: lagl
Shape: 2
Data:
-1367/1546
1527/2438
-1185/4027
-1342/1369
z =
Class: lagl
Shape: 2
Data:
-10067/13939 -1037/1721
-129/217
104/501
>> eval(x7,cat(1,x,y,z))
ans =
Class: lagl
Shape: 2
Data:
-76/989
-271/1666
-452/571
76/989

>> x7 = basis(fla,7)
x7 =
LieAlgebra class: lafree
Data:
1,1,2]]
>> x1 x4] - x7
ans =
LieAlgebra class: lafree
Data:
0

4.3 Lie groups

The Lie group classes implemented in DiMan are the following:
@lgdirprod
@lggl
@lgon
@lgrn
@lgse
@lgsl
@lgso
@lgsp

The
The
The
The
The
The
The
The

direct product of Lie groups.

general linear group.
orthogonal group.
Lie group R^n
special Euclidean group.
special linear group.
special orthogonal group.
symplectic group.

24

Domain
@liegroup

- The virtual superclass of all Lie groups.

The virtual superclass Lie group is named @liegroup. All the other groups are pre xed by @lg
in order to emphasize that these are actual implementations of Lie groups.

4.4 My domain is not implemented!?

Eventually, DiMan will contain all possible domain classes that you can think of. Since this is
just DiMan 1.6 you might encounter the fact that the homogeneous space or Lie group that you
want to use as a domain in your application, is not yet implemented.
If that is to happen you have at least two options: You can carefully read this guide { which is by
no means complete { and peek into the source code of the other classes and try to implement the
missing class yourself. If you do this we would appreciate obtaining a copy of your class so that
it can be included in the general distribution. We are more than willing to answer any of your
questions if you choose to do it this way.
A second option is to send us a request, and let us know about the classes that are missing, so
that we can possibly include them in a future version of DiMan.

Chapter 5

Field
In DiMan 1.6 the only eld implemented is vector elds over domains.

5.1 Vector eld

A vector eld F over a manifold M is a section of the tangent bundle of the manifold, F :
M ! TM. This means that at each point m 2 M, the vector eld computes a tangent vector
F(m) 2 TMm , or, equivalently, that   F = id , where  is the projection from TM to M.
A vector eld on a manifold de nes the ow, and integral curves of vector elds are solutions of
dierential equations.
DiMan 1.6 is based on domains that are homogeneous manifolds. As is described in Appendix A,
the function evaluating the vector eld should take t 2 R and y 2 M as arguments and return
an element in the Lie algebra of the Lie group which, together with the Lie-group action and the
manifold, de ne the homogeneous space.
The integral curves of a vector eld, or, in other words, the solution of the dierential equation
de ned by the vector eld, are computed numerically in DiMan. A vector eld over a domain
is constructed by the vectorfield operation. In the following example, we de ne an object y to
belong to the homogeneous space de ned by hmlie over the Lie group SO(3):
M

>> y=hmlie(lgso(3))

>> vf=vectorfield(y)
vf =
Class: vectorfield
Domain: hmlie
Shape-object information:
Class: lgso
Shape: 3
Eqn type:
General

The vector eld object is now de ned, but we have to assign to it a function which actually
computes the tangent vectors. Example 1 in DiMan gives an example of such a function (function
vfex1):
function la] = vfex1(t,y)
% VFEX1 - Generator map from RxM to the Lie algebra. Linear type.

26

Field

la = liealgebra(y)

dat = 0 t 1
-t 0 -t^2
-1 t^2 0]

setdata(la,dat)

return

The function should in general receive t and y as input arguments and return a Lie algebra
element. The Lie algebra is the one corresponding to the Lie group which de nes, together with
the Lie-group action and the manifold, the homogeneous space.
Using setfmg, the function is assigned to a vectorfield object:
>> setfm2g(vf,'vfex1')

and information about the current map is retrieved using getfm2g:

>> getfm2g(vf)
ans =
vfex1

When we initialized vf using vectorfield, the output

Eqn type:

General

appeared on the screen. General means that the vector eld is of general type, i.e. it depends
both on t and y. When the vector eld only depends on t, we say it is a linear vector eld. The
type of the vector eld can be changed using seteqntype:
>> seteqntype(vf,'L')

Type information about the current vector eld is retrieved using geteqntype:
>> geteqntype(vf)
ans =
Linear

If we want to change the domain of the vector eld, we may use the function setdomain. Information about current domain is retrieved using getdomain:
>> setdomain(vf,hmlie(lgso(4)))
>> getdomain(vf)
ans =
Class: hmlie
Shape-object information:
Class: lgso
Shape: 4

Chapter 6

Flow
The underlying assumption of the time-integrators in DiMan is the existence of a Lie group G
with Lie algebra g that is endowed with Lie bracket  ], a (left) Lie-group action # : G M ! M
and a function  : R M ! g such that the ordinary dierential equation describing the problem
can be written in the form (see Appendix A)
y =  (t y)
0

y(0) = p 2 M:

(6.1)

The ow operator of this dierential equation is the operator #exp(t) : M ! M, where M is the
in nitesimal generator of the action corresponding to  2 g,

d
 (q) = dt  #exp(t) (q) 8 q 2 M:
t=0
The classical solution of a dierential equation is an integral curve of the vector eld generating
the ow operator. This integral curve is found by evaluating the ow operator in the initial point
on the manifold.
In DiMan the ow is approximated numerically using a particular time stepper method. The
virtual superclass de ning the ow is
M

@flow

% The virtual flow superclass

A ow object is de ned by a vector eld object and a time stepper object. The default time stepper
object if from the class tsrkmk with coordinates exp and the classical fourth order Runge-Kutta
method RK4 as scheme. The ow constructor is used as follows:
>> fl=flow
fl =
Class: flow
Timestepper class: tsrkmk
Coordinates:
exp
Method:
RK4

When evaluated, the flow object approximates the integral curve of the ow through an initial
point from time tstart to tend using either constant or variable step size. The outer part of the time
stepping process is included in flow, while the computation of one single step is done using the
time stepper object. The advantage of this is that we write the outer part only once. The variable
step size control resides here, and so do the other control structures de ning the integration

28

Flow

process. When changing time stepper object, the environment and integration parameters remain
the same, and the eect of changing the time stepper object can be measured.
The flow object must be associated with a vector eld (see e.g. Section 5.1). This is done using
the setvectorfield routine. Let y be the object hmlie(lgso(3)). Then
>> vf=vectorfield(y)
vf =
Class: vectorfield
Domain: hmlie
Shape-object information:
Class: lgso
Shape: 3
Eqn type:
General

and this vector eld is given to the flow object through

>> setvectorfield(fl,vf)

The vector eld coupled to a flow object is retrieved using getvectorfield.

In the flow object a number of parameters are de ned. Most of these are used in the time stepper
routines. The getdefaults routine returns the default setting:
>> getdefaults(fl)
ans =
small: 0.5000
large: 2
...
disp: 1

The values are changed using setdefaults:

>> setdefaults(fl,'small',0.1)
>> getdefaults(fl)
ans =
small: 0.1000
large: 2
...
disp: 1

6.1 Time stepping

In DiMan 1.6 the following numerical time stepper algorithms are implemented:
@timestepper
@tscg
@tsfer
@tsmagnus
@tsqq
@tsrk
@tsrkmk

%
%
%
%
%
%
%

The virtual superclass timestepper

The Crouch-Grossman methods
The Fer expansion methods
The Magnus series methods
Quadrature methods for quadratic Lie groups
Classical Runge-Kutta methods
Runge-Kutta methods of Munthe-Kaas type

6.1 Time stepping

29

A detailed mathematical exposition of each of the methods is found in Appendix A. A future

release of DiMan will also contain various multistep methods.
Initialization of a time stepper of type tscg is done as follows:
>> ts=tscg
ts =
Class: tscg
Coord.: exp
Method: CG3a

The default coordinates are exp and the default scheme is CG3a. A list of the schemes available in
DiMan 1.6 is included in Appendix B. You can change time stepper scheme using setmethod:
>> setmethod(ts,'CG43')

and you can retrieve the parameter values of the scheme using getmethod:
>> getmethod(ts)
ans =
RKname: 'CG43'
RKa: 5x5 double]
RKb: 0.6756 0 -0.1756 -0.1756 0.6756]
RKc: 0 1.5000 1.3512 -0.3512 1]
RKns: 5
RKord: 4
RKtype: 'explicit'
RKbhat: 0.6756 0 -0.1756 -0.1756 0.6756]

Many of the methods are based on a certain choice of coordinate system. DiMan 1.6 provides
the following coordinates:
exp
expexp
cay
caycay
pade22

%
%
%
%
%
%
%
%
%
%

canonical coordinates of the first kind

defined by a single exponential map

canonical coordinates of the second kind

defined by a product of exponential maps

coordinates based on the Cayley map

defined by a single Cayley map

coordinates based on the Cayley map

defined by a product of Cayley maps

coordinates based on the (2,2) diagonal Pade map

defined by a single (2,2) diagonal Pade map

See e.g. 5] for a discussion of dierent choices of coordinates. The default coordinate choice is
the exponential mapping for most of the methods. You can change coordinates by using the
setcoordinate routine:
>> setcoordinate(ts,'cay')

The getcoordinate routine returns the current choice of coordinate system.

You may change time stepper in DiMan by using the settimestepper routine:

30

Flow
>> ts=tsmagnus
ts =
Class: tsmagnus
Coord.: exp
Method: M4a
>> settimestepper(fl,ts)

The gettimestepper routine retrieves information from the flow object:

>> gettimestepper(fl)
ans =
Class: tsmagnus
Coord.: exp
Method: M4a

6.1.1 My time stepper is not implemented!?

Eventually, DiMan will contain most of the time stepper classes described in the literature. In
DiMan 1.6 you might encounter the fact that the time stepper that you want to choose is not

yet implemented. If that is to happen you have at least two options: You can carefully read this
guide { which is by no means complete { and peek into the source code of the other classes and
try to implement the missing class yourself. If you do this, the DiMan development team would
appreciate receiving a copy of your class so that it can be included in the general distribution. We
are more than willing to answer any of your questions if you choose to do it this way.
A second option is to send us a request, and let us know about the classes that are missing. We
will then possibly include them in a future version of DiMan.

6.2 Implicit methods | Solution of nonlinear equations

In DiMan 1.6 the nonlinear systems of equations arising from the implicit time steppers are
solved using xed point iteration only. The iteration on the stage values continue until the error
is below max(10 12 hp =100), where p is the order of the method and h is the step size.
In future versions of DiMan, we will provide general nonlinear equation solvers, e.g. Newton
iteration as developed by Owren and Welfert 35]. These schemes reduce to the classical Newtoniteration scheme in Euclidean space with the standard basis.
;

6.3 Variable step sizing

Traditional step size control strategies rely on the local error of the method. At every step this
quantity is estimated, and a new step size is computed. It is natural to employ similar techniques
also in the case of integration on Lie groups or more general manifolds. Description of the strategy
may be found in most standard texts on integration methods for ordinary dierential equations,
but for completeness we include a brief overview of the procedure.
In order to attain the local error estimate rk+1 = " at time step k + 1, the next step size hk+1 is
chosen as a function of the previous step size, hk , as follows (see e.g. 36] or 10, 11]). Let p be the
order of the method. When using embedded pairs, as is usual in classical Runge-Kutta methods,
we let p be the order of the lower-order approximation scheme). Furthermore, rk = ek , the error

6.3 Variable step sizing

31

estimate, and pessimist is a pessimist factor which is heuristically determined (typical values are
0:8 or 0:9). We rst compute
bhk+1 = pessimist

 1=(p+1)
"

hk 
rk
A typical strategy to prevent rapid oscillations of the step size is to restrict the extent of step size
variation in any single step. This is obtained by letting
hk+1 = minfhmax  maxfsmall hk  minflargehk  bhk+1ggg
where hmax is the largest allowed step size, while small and large are two constants. If the local
error exceeds the tolerance by a factor more than accept, then we reject the step and retry with
a smaller step size computed as above but with hk equal to the step size we just tried. This
algorithm proceeds until the local error estimate satis es
ek+1  accept":
DiMan de nes default values for the constants used in variable step size integration. The names

are

pessimist
small
large
accept
"
hmax

$
$
$
$
$
$

pessimist
small
large
accept
tol
hmax

All the values can be changed by the user of DiMan (see description of the ow object). The
routine getdefaults returns the default setting of the constants:
>> fl=flow

>> getdefaults(fl)
ans =
small: 0.5000
large: 2
pessimist: 0.9000
...
disp: 1

The values are changed using setdefaults:

>> setdefaults(fl,'large',4)
>> getdefaults(fl)
ans =
small: 0.5000
large: 4
pessimist: 0.9000
...
disp: 1

The variable step size algorithm will be extended in future releases of DiMan.

Chapter 7

Auxiliary
7.1 Demos
Issuing the MATLAB command demo on the command line in DiMan will launch the MATLAB
Demos. Since this is done while DiMan is running you will be able to nd DiMan and its
demonstrations as one of the MATLAB toolboxes. The situation should look very similar to
Figure 7.1.

Figure 7.1: The MATLAB Demos.

The Demos feature in MATLAB is very simple to use. You just high-light what you want to
learn more about, and then push the button down to the right ('Run ...'-button) to go on to more
information about the speci c topic. For DiMan 1.6 there are two topics for further help: 'The
DiMan tutorials' and 'The Command Line Examples'.
Under 'DiMan tutorials' you will nd short and well-documented slide shows which guide you
through dierent aspects of how to use DiMan. Figure 7.2 shows you the 'Tutorial' window
as launched from the 'Demo' window. The two existing tutorials are on how to use DiMan to
solve ODEs on manifolds, and about the domains in DiMan. More tutorials will be tried added
in the future. If you have ideas for such tutorials please inform the DiMan development team:
[email protected].

34

Auxiliary

Figure 7.2: The DiMan tutorials.

'Command Line Examples' collects 10 of the examples found in the DiMan distribution. Accessing the CL-examples this way, the user simply has to push a button in order to run an example.
See Section 7.3 for more information.

7.2 Documentation
All the DiMan documentation is placed in the directory DiffMan/auxiliary/documentation.
The User's Guide, which you are reading now, is found as both a PDF and PS- le. There are
also other .doc and .m- les in this directory which are worth while looking at. However, in the
present distribution of DiMan they are not guaranteed to be nished.
When detailed technical notes for instance about new classes or speci c problems solved in DiMan
are released by the DiMan development team, these will also be placed in this directory as PDF
and/or PS- les.

7.3 Examples
In DiMan you can nd several examples of solved ODEs. In DiMan 1.6 these are:
dmex1
dmex1a
dmex1b

dmex2
dmex3
dmex4
dmex5
dmex6
dmex7
dmex8

This is an ODE evolving in SO(3)

This is an ODE evolving in SO(3)
PURPOSE: Integrate 'dmex1' with variable and constant step size.
This is an ODE evolving in SO(3)
PURPOSE: Integrate 'dmex1' with variable and constant step size
for time steppers: 'tscg' and 'tsrk'.
Solution of the Lorenz equations in R^3
This is a linear ODE evolving in SO(3)
Integration of the rigid body
This is an ODE evolving on the sphere S^2
Integration of an isospectral flow
Integration of the Airy equation
Integration of the van der Pol equation

7.3 Examples
dmex9
dmex10
dmex10a

35

PURPOSE:
WARNING:

exlafree PURPOSE:

extools1 PURPOSE:

extools2 PURPOSE:

Integration of the heavy top

This is an ODE evolving in SO(3)
This is an ODE evolving in SO(3)
Use "ftorder" to verify the order of the solution
of some fer schemes
This routine is very time consuming to run.
Using the Lie algebra @lafree.
Use the free Lie algebra to establish a
connection between the Magnus method and the RKMK
method.
Example of ODE evolving in SO(3).
Demonstrate the use of the flow tools routine
"ftorder", that computes order of approximation
of a given integrator and scheme.
Example of ODE evolving in SO(3).
Demonstrate the use of the flow tools routine
"fteff", that computes the efficiency of a given
integrator and scheme as global error versus
flops.

All these examples can be run directly in DiMan by just typing the name of the example. If
you are a beginner user of DiMan, it might also be worth-while to view the source code of the
examples with dmhelp. This gives you an idea of how things are done, and probably the best way
to learn is to take an already existing example, copy it, and modify it, and see what happens.
The examples dmex1 through dmex10 are the ones found among the 'Command Line Examples' in
the DiMan Demo, see Figure 7.3. In order to run the examples this way, you push the example
button. Make sure that the MATLAB window is visible, because output from the examples will
be displayed here and in plots.

Figure 7.3: The DiMan command line examples.

36

Auxiliary

7.4 Utilities
The root utilities directory contains some functions which are 'nice' to have. It is not vital to
know how to use all these functions, but it is very convenient to have an idea of where to look for
these types of functions, in case you are in need of one. The functions located in the root utilities
directory are:
addsubdir
array
dmargcheck
dmhelp
dmprogrep
iseven
iscellempty
iseven
repprogress
isinteger
skew

Add subdirectories to the path.

Create arrays of objects.
Turn on/off input checking in DiffMan.
The help facility in DiffMan.
Turn on/off progress report.
Function to test if a number is even.
Check if a cell tree consists of empty matrices.
Check if integer is even.
The progress report m-file.
Function to test if a number is integer.
Creates a skew matrix from a 3-vector.

There are also two subdirectories containing class speci c utilities functions:
flowtools
lafreeutil

- Functions for efficiency and order checks.

- Utility functions for the free Lie algebra.

For more information about the functions contained in these subdirectories see the next two
subsections.

7.4.1

flowtools

DiMan 1.6 provides the user with two special flow utility routines:

ftorder and fteff. ftorder

estimates both the local and global order of approximation of a timestepper. The user can provide
a \correct" (or \exact") integrator. If this is not supplied, the tsrkmk timestepper with the RK4
scheme is used. The rst time this routine is called, an \exact" reference solution is computed. This
is a rather time consuming operation, and can be avoided in the next call with the same setting.
The user should notify ftorder that the same \exact" solution should be used, by changing the
value of the ow parameter newexact:
>> setdefaults(fl,'newexact',0)

The example routine extools1 uses this tool:

...
flA = flow % The integrator to be estimated
ts = tsrkmk
setcoordinate(ts,'pade22')
setmethod(ts,'RKF34')
settimestepper(flA,ts)
...
flB = flow % "Reference" integrator - computes the "exact" solution
ts = tsrkmk
setcoordinate(ts,'exp')
setmethod(ts,'RK4')

7.4 Utilities

37

settimestepper(flB,ts)
...
out=ftorder(flA,flB,y)
...
% input exact solution to avoid computing it once more - example
setdefaults(flA,'newexact',0)
out2=ftorder(flA,flB,y,],],],out.exact)
...

The fteff utility routine estimates the eciency of a timestepper. The eciency measure is global
error as a function of number of ops used by the integrator. The MATLAB routine flops is used
to count the ops usage. The sample program extools2 demonstrates the use of the routine:
...
flA = flow % The integrator to be estimated
ts = tsrkmk
setcoordinate(ts,'pade22')
setmethod(ts,'RKF34')
settimestepper(flA,ts)
...
flB = flow % "Reference" integrator - computes the "exact" solution
ts = tsrkmk
setcoordinate(ts,'exp')
setmethod(ts,'RK4')
settimestepper(flB,ts)
...
out=fteff(flA,flB,y)
...
% input exact solution to avoid computing it once more - example
out2=fteff(flA,out.sol,y)
...

7.4.2

lafreeutil

This subdirectory collects some handy functions related to the free Lie algebra @lafree:
bch
bch2
cdopri5
divisors
killing
lafcount
lafdim
magnusdim
mobius
rkgl
rkmk4
rkmk4mod
slegendre

Computes the BCH formula of order q, and n flows.

Computes the BCH formula of order q, just 2 flows.
Classical dopri5 of order 5.
All the divisors of an integer.
Killing form on a Lie algebra.
Count commutators in a graded free Lie algebra.
Dimension of a graded free Lie algebra.
Magnus dimension.
Number theoretic mu function.
Runge-Kutta-Gauss-Legendre coefficients of n stages, order 2n.
Classical RKMK of order 4.
Modified classical RKMK of order 4.
Shifted Legendre polynomial of order n.

For instance, bch and bch2 can be used like this:

>> format rat
>> bch(3,3)
Fixpoint iteration, 3 steps:

38

Auxiliary
Done step: 1
Done step: 2
Done step: 3
Composing 3 flows:
ans =
computing commtab!
Done step: 3
ans =
LieAlgebra class: lafree
Data:
1] + 2] + 3] + 1/2*1,2] + 1/2*1,3] + 1/2*2,3] + 1/12*1,1,2]]
+ 1/12*1,1,3]] - 1/12*2,1,2]] + 1/6*2,1,3]] + 1/12*2,2,3]]
- 1/3*3,1,2]] - 1/12*3,1,3]] - 1/12*3,2,3]]
>> bch2(4)
ans =
LieAlgebra class: lafree
Data:
1] + 2] + 1/2*1,2] + 1/12*1,1,2]] - 1/12*2,1,2]] - 1/24*2,1,1,2]]]

7.5 Eciency and speed-up of DiMan

First, let us state the following fact: the object orientation in MATLAB is not fast. We have
tried to remedy this situation in DiMan by a couple of programming tricks. The rst 'trick'
is to use MEX- les, and the second 'trick' is to aid the most time-consuming computation by
precomputations in the free Lie algebra. In the present version of DiMan only the rst of these
two tricks is available for exploitation.

7.5.1 Speed-up through MEX- les

Following the standard DiMan 1.6 distribution there are three pre-programmed les in C that
the user can compile in order to speed up the execution of DiMan. A prerequisite for this to
work is that there is a C compiler installed on the platform which is running MATLAB. The les
are located in the directory DiffMan/domain/liealgebra/@liealgebra, and they are:
>> pwd
ans =
/../DiffMan/domain/liealgebra/@liealgebra
>> ls *.c
ans =
dexpinv.c
horzcat.c
mtimes.c

To compile the C les and make MEX- les you can issue the following commands in MATLAB:
>> mex -O dexpinv.c
>> mex -O horzcat.c
>> mex -O mtimes.c
>> ls *.mexsol
ans =
dexpinv.mexsol
horzcat.mexsol
mtimes.mexsol

7.5 Eciency and speed-up of DiMan

39

Note that the le extension of the MEX- les will vary depending on the platform on which you
are running MATLAB.
What happens now is that the next time you are running your DiMan application, MATLAB will
choose the MEX- les instead of the m- les for any of the three functions dexpinv.m, horzcat.m,
and mtimes.m. This is done automatically, and the only way that the user can control this is by
removing the MEX- les. The MEX- les are well tested on all the matrix groups, and they are
expected to fail seriously if used on any of the functorial classes. A word of advise is that if you run
into any kind of trouble using the MEX- les, remove them, issue the command clear functions
in MATLAB, and run your problem just using the m- les (which are known to work properly).
Please be warned that the ops count which MATLAB produces when running any of the above
MEX- les is not correct. The reason for this is that the ops counter is not being updated in
any of the MEX- les. Hence, the results yielded by the function fteff are erronous when used
together with these MEX- les.

7.5.2 Speed-up by use of the free Lie algebra

Unfortunately, this did not make it in time for the release of DiMan 1.6. At the time of release
of DiMan 1.6 this was something still on the test bed, but it will de nitely be included in the
next release of DiMan.
To give you an idea of this beautiful trick we will briey comment on it. The trick will probably
be implemented in DiMan as a new version of the time stepper class @tsrkmk. Hence, the user
will only notice the speed increase, and does not have to do anything special than choosing the
'right' RKMK time stepper class in order to take advantage of it. The trick itself constitutes of
aiding the most time-consuming computation by a precomputation in the free Lie algebra @lafree.
The object from the @lafree class represents the whole update of step size h that the numerical
method is supposed to perform on the initial data. The free Lie algebra object acts as an operator,
and once calculated the object is saved for the rest of the iteration, and whenever the time stepper
is called, the object in the free Lie algebra is evaluated on the data. Hence, you end up only with
an evaluation in each step, instead of a time-consuming calculation.
More on this in the next release of DiMan.

Bibliography
1] R. Abraham, J. E. Marsden, and T. Ratiu. Manifolds, Tensor Analysis, and Applications.
AMS 75. Springer-Verlag, Second edition, 1988.
2] R. L. Bryant. An introduction to Lie groups and symplectic geometry. In D. S. Freed and
K. K. Uhlenbeck, editors, Geometry and Quantum Field Theory, volume 1, Second Edition
of IAS/Park City Mathematics Series. American Mathematical Society, 1995.
3] E. Celledoni and A. Iserles. Approximating the exponential from a Lie algebra to a Lie group.
Technical Report 1998/NA3, Department of Applied Mathematics and Theoretical Physics,
University of Cambridge, England, 1998.
4] P. E. Crouch and R. Grossman. Numerical integration of ordinary dierential equations on
manifolds. J. Nonlinear Sci., 3:1{33, 1993.
5] K. Eng. On the construction of geometric integrators in the RKMK class. Technical Report
No. 158, Department of Informatics, University of Bergen, 1998.
6] K. Eng and S. Faltinsen. Integrating Lie{Poisson systems with the RKMK method. In
preparation. 1999.
7] K. Eng and A. Marthinsen. Modeling and solution of some mechanical problems on Lie
groups. Multibody System Dynamics, 2:71{88, 1998.
8] K. Eng, A. Marthinsen, and H. Z. Munthe-Kaas. Diman | an object oriented MATLAB
toolbox for solving dierential equations on manifolds. Technical Report No. 164, Department
of Informatics, University of Bergen, 1999.
9] F. Fer. R'esolution del l`equation matricielle U_ = pU par produit in ni d`exponentielles
matricielles. Bull. Classe des Sci. Acad. Royal Belg., 44:818{829, 1958.
10] K. Gustafsson. Control of Error and Convergence in ODE Solvers. PhD thesis, Department
of Automatic Control, Lund Institute of Technology, Sweden, 1992.
11] K. Gustafsson. Control-Theoretic Techniques for Stepsize Selection in Implicit Runge-Kutta
Methods. ACM TOMS, 20(4):496{517, 1994.
12] E. Hairer, S. P. Nrsett, and G. Wanner. Solving Ordinary Dierential Equations I, Nonsti
Problems. Springer-Verlag, Second revised edition, 1993.
13] M. Haveraaen, V. Madsen, and H. Munthe-Kaas. Algebraic programming technology for partial dierential equations. In Proceedings of Norsk Informatikk Konferanse (NIK), Trondheim,
Norway, 1992. Tapir.
14] A. Iserles. Solving linear ordinary dierential equations by exponentials of iterated commutators. Numer. Math., 45:183{199, 1984.

42

BIBLIOGRAPHY

15] A. Iserles, A. Marthinsen, and S. P. Nrsett. On the implementation of the method of Magnus
series for linear dierential equations. BIT, 39(2):281{304, 1999.
16] A. Iserles and S. P. Nrsett. On the solution of linear dierential equations in Lie groups.
Technical Report 1997/NA3, Department of Applied Mathematics and Theoretical Physics,
University of Cambridge, England, 1997. To appear in Philosophical Transactions of the
Royal Society.
17] W. Magnus. On the exponential solution of dierential equations for a linear operator. Comm.
Pure and Appl. Math., VII:649{673, 1954.
18] J. E. Marsden and T. S. Ratiu. Introduction to Mechanics and Symmetry. Springer-Verlag,
1994.
19] A. Marthinsen. Interpolation in Lie groups and homogeneous spaces. Technical Report 139,
Department of Mathematics, Arizona State University, Tempe, Arizona, 1998.
20] A. Marthinsen, H. Munthe-Kaas, and B. Owren. Simulation of ordinary dierential equations
on manifolds | some numerical experiments and veri cations. Modeling, Identi cation and
Control, 18:75{88, 1997.
21] A. Marthinsen and B. Owren. A note on the construction of Crouch{Grossman methods.
Technical Report Numerics No. 2/1998, The Norwegian University of Science and Technology,
Trondheim, Norway, 1998.
22] A. Marthinsen and B. Owren. Quadrature methods based on the Cayley transform. Technical Report Numerics No. 1/1999, The Norwegian University of Science and Technology,
Trondheim, Norway, 1999.
23] R. I. McLachlan. Explicit symplectic splitting methods applied to PDE's. In E. L. Allwoger,
K. Georg, and R. Miranda, editors, Lectures in Applied Mathematics: Exploiting Symmetry
in Applied and Numerical Analysis, pages 325{337. American Mathematical Society, 1993.
24] R. I. McLachlan. On the numerical integration of ordinary dierential equations by symmetric
composition methods. SIAM J. Sci. Comput., 16:151{168, 1995.
25] H. Munthe-Kaas. Lie{Butcher theory for Runge{Kutta methods. BIT, 35(4):572{587, 1995.
26] H. Munthe-Kaas. Runge{Kutta methods on Lie groups. BIT, 38(1):92{111, 1998.
27] H. Munthe-Kaas. High order Runge{Kutta methods on manifolds. Appl. Numer. Math.,
29:115{127, 1999.
28] H. Munthe-Kaas and M. Haveraaen. Coordinate free numerics | Part I: How to avoid index
wrestling in tensor computations. Technical Report No. 101, Department of Informatics,
University of Bergen, Norway, 1995.
29] H. Munthe-Kaas and M. Haveraaen. Coordinate free numerics | Closing the gap between
'Pure' and 'Applied' mathematics? In Proceedings of ICIAM{95, Zeitschrift fur Angewandte
Mathematik und Mechanik (ZAMM), Berlin, 1996. Akademie Verlag.
30] H. Munthe-Kaas and B. Owren. Computations in a free Lie algebra. Technical Report No. 148,
Department of Informatics, University of Bergen, Norway, 1998. To appear in Philosophical
Transactions of the Royal Society.
31] H. Munthe-Kaas and A. Zanna. Numerical integration of dierential equations on homogeneous manifolds. In F. Cucker and M. Shub, editors, Foundations of Computational Mathematics, pages 305{315. Springer Verlag, 1997.

BIBLIOGRAPHY

43

32] P. J. Olver. Applications of Lie Groups to Dierential Equations. GTM 107. Springer-Verlag,
Second edition, 1993.
33] B. Owren and A. Marthinsen. Integration methods based on canonical coordinates of the
second kind. Manuscript 1999.
34] B. Owren and A. Marthinsen. Runge{Kutta methods adapted to manifolds and based on
rigid frames. BIT, 39(1):116{142, 1999.
35] B. Owren and B. Welfert. The Newton iteration on Lie groups. Technical Report Numerics
No. 3/1996, Norwegian University of Science and Technology, Trondheim, Norway, 1996.
36] H. J. Stetter. Analysis of Discretization Methods for Ordinary Dierential Equations.
Springer-Verlag, Berlin, 1973.
37] V. S. Varadarajan. Lie Groups, Lie Algebras, and Their Representations. GTM 102. SpringerVerlag, 1984.
38] F. W. Warner. Foundations of Dierentiable Manifolds and Lie Groups. GTM 94. SpringerVerlag, 1983.
39] A. Zanna. Collocation and relaxed collocation for the Fer and the Magnus expansions. Technical Report 1997/NA17, Department of Applied Mathematics and Theoretical Physics, University of Cambridge, England, 1997. To appear in SIAM J. Num. Anal.
40] A. Zanna. On the Numerical Solution of Isospectral Flows. PhD thesis, University of Cambridge, England, 1998.
41] A. Zanna and H. Munthe-Kaas. Iterated commutators, Lie's reduction method and ordinary
dierential equations on matrix Lie groups. In F. Cucker and M. Shub, editors, Foundation
of Computational Mathematics, pages 434{441. Springer-Verlag, 1997.

Appendix A

The mathematical building blocks

of DiMan
In this chapter we briey describe the mathematical background of DiMan. To get a more
detailed exposition of the topics the reader is recommended to study some of the more established
references like 1, 2, 18, 32, 37, 38]

A.1 Homogeneous spaces

To really appreciate DiMan, the most important concept to understand is the notion of a homogeneous space. All the numerical algorithms for solving ordinary dierential equations have been
reformulated to solve problems evolving on homogeneous spaces. We believe this to be the most
general setting for solving ordinary dierential equations on manifolds. It should be noticed that
all the methods, when applied in the traditional setting of RN , reduce to the classical Runge{Kutta
schemes.
Before de ning homogeneous spaces, we need some mathematical building blocks.

Denition A.1.1 (Manifold)

A manifold is a topological space M equipped with continuous local coordinate charts i : Ui

M ! Rd such that all the overlap charts ij : Rd ! Rd are dieomorphisms. The overlap
charts (transition functions) ij are dened as j  i 1 ji(Ui Uj ) , where i 1ji (Ui Uj ) means the
restriction of i 1 to the set i (Ui \ Uj ).
;

While this is a quite abstract de nition, in DiMan we will mainly concentrate on a particular
class of dierentiable manifolds called Lie groups.

Denition A.1.2 (Lie group)

A Lie group (G ) is a dierential manifold G equipped with a binary operation  on G satisfying
the axioms of a group, such that the map : G  G ! G given by (q p) = q  p 1 is smooth.
;

In this report we will slightly abuse notation and just refer to the Lie group as G. The identity
element in the Lie group will be denoted by e.

Denition A.1.3 (Tangent space)

Given a point p 2 M, we denote by TMjp the tangent space of M at p. This space is the set of

46

The mathematical building blocks of DiMan

all linear derivations vp such that

vp (f1 + f2 ) = vp (f1 ) + vp (f2 ) and vp (f1 f2 ) = f1 (p)vp (f2 ) + f2 (p)vp (f1 )
for all functions f1  f2 : M ! R dened in a neighborhood of p, and all   2 R.
S

The tangent bundle of M is TM = p TMjp. A vector eld, X on M, is a section of TM,

i.e. to each point p 2 M it associates a vector X(p) 2 TMjp .
Since a Lie group, G, is a manifold, there exists a tangent space, TGjg , at each point g 2 G.
2M

Denition A.1.4 (Lie algebra)

A Lie algebra is a vector space, g, equipped with a bilinear, skew-symmetric form,  ] : g  g ! g,
satisfying the Jacobi identity,
u v w]] + v w u]]+ w u v]] = 0
when u v w 2 g. We call  ] the Lie bracket on g.
The Lie algebra of a Lie group is de ned as the tangent space at the identity, g = TGje. In this
case its Lie bracket is given by

@ 2 
1
u v] = @t@s
t=s=0 g(t)h(s)g (t)
where g(t) h(s) 2 G are two curves such that g(0) = h(0) = e, g (0) = u, and h (0) = v. In the
case of matrix Lie groups, the Lie bracket is the matrix commutator, u v] = u  v ; v  u, where 
denotes matrix multiplication.
;

Denition A.1.5 (Lie-group action)

A (left) Lie-group action of a Lie group G on a manifold M is a smooth mapping # : G M ! M,

which satises
#(e p) = p where e 2 G is the identity element,
and
#(g1  g2 p) = #(g1  #(g2 p)) for all g1 g2 2 G and p 2 M.
We say that a Lie-group action is eective if #(g p) = p for all p 2 M implies that g = e.
Furthermore, an action is transitive if, for arbitrary p q 2 M, there exists a g 2 G such that
#(g p)  q, i.e. the space M consists of just a single orbit.
Based on these de nitions we can now de ne the concept of homogeneous spaces.

Denition A.1.6 (Homogeneous space)

A homogeneous space is a manifold with a transitive Lie-group action.

Any  2 g speci es a tangent m 2 TMjm at any point m 2 M via

d
m = dt  #(g(t) m)
t=0
where g(t) 2 G is a curve such that g(0) = e and g (0) = . One may use g(t) = exp(t), where
exp : g ! G is the exponential map 27], or g(t) = (t) for any smooth function  : g ! G such
that (0) = e and  (0) = I. This gives an identi cation  7! m 2 TMjm , which depends on the
choice of action #, but not on the particular choice of .
0

A.2 Computing ows of vector elds

47

A.2 Computing ows of vector elds

We have chosen to view all the numerical methods implemented in DiMan as working on homogeneous spaces. Even the classical Runge{Kutta methods are expressed in this setting.
The numerical methods in DiMan assume that the dierential equation to be solved is presented
in the following canonical form
y = F(t y) =  (t y)
0

y(0) = y0 2 M

(A.1)

for some function  : R  M ! g (see 31, 27, 5]).

If (t y) = (t), the equation is of Lie type or linear type. Otherwise it is of general type. Equations
of Lie type can be handled more eciently than general type equations.

A.2.1 Classical Runge{Kutta methods

Classical Runge{Kutta methods have been thoroughly described in a large amount of papers
the last decades. These methods are implemented in DiMan, but based on a slightly dierent
understanding since we work on homogeneous spaces.
In the classical setting, the dierential equation (A.1) takes on the following form. Integrate
;

u =  t #(u y0) 
0

u(0) = 0

with y(t) = #(u(t) y0 ). We have here used that  is the identity mapping in Euclidean space.

Algorithm A.2.1 (Classical Runge{Kutta methods)

Let A = (aij ), b = (bj ) and c = (cj ) be the Butcher-coecients of an s-stage, qth order Runge{
Kutta method. The following algorithm integrates (A.1) from t = tn to t = tn + h:
Assume that yn  y(tn ) is given
for i = 1P
2 : : :  s
ui = h sj=1 aij kj
ki =  (tn + cih #(ui yn ))
end P
v = h sj=1 bj kj
yn+1 = #(v yn )
When #(u y) = u + y, this reduces to the well known classical setting:


P
ki =  tn + ci h yn + h sj=1 aij kj 

yn+1 = yn + h

s
X
j =1

i = 1 2 : : :  s

bj kj :

If # is a general group action, this method attains at most order 2 on an arbitrary manifold.

A.2.2 Munthe-Kaas methods

The Munthe-Kaas methods were rst described in 25]. In the succeeding paper 26], the methods
were re ned until their nal formulation appeared in 27].

48

The mathematical building blocks of DiMan

A large class of numerical algorithms are based on the assumption that the maps #(() m) can
be computed eciently. The Munthe-Kaas methods in 27] are based on the choice () = exp().
More general s are discussed in 5].
The following commutative diagram, which is thoroughly discussed in 5], illustrates the relations
used as a framework for these algorithms:
y0 T
Tg ;T
;;;;;
! TM


x
?
?F =M
M

du ;1  y0 ?

?
g

; ;;;!

y0 

Here y0 2 M is the initial point, u 2 g, #y0 (u) = #(u y0 ) and du 1 : g ! g is the right trivialized
tangent of . If  = exp, then du 1 = dexpu 1 can be expressed in terms of Lie brackets. For
more general  one needs an ecient algorithm for computing du 1, see 5, 33] for dierent
choices. This yields the following algorithm:
;

Algorithm A.2.2 (General Munthe-Kaas methods)

Given a dierential equation in the form (A.1), this algorithm produces a qth order approximation
to the solution, using step size h:
 Find an approximation u1  u(t0 +h) by integrating the following dierential equation on g

1; ;

u = du  t #((u) y0)  u(0) = 0

from t0 to t0 + h using one step with a qth order Runge{Kutta method.

 Advance the solution on M to y1 = #((u1) y0 )  y(t0 + h).
 Repeat with new initial values y0 := y1 , t0 := t0 + h.
0

When  = exp, this algorithm reduces to the Munthe-Kaas methods presented in 27].

Algorithm A.2.3 (Munthe-Kaas methods based on the exponential mapping)

Let A = (aij ), b = (bj ) and c = (cj ) be the coecients of an s-stage, qth order classical Runge{
Kutta method. The following algorithm integrates (A.1) from t = tn to t = tn + h:
Assume that yn  y(tn ) is available
for i = 1 2 : : :  s
P
ui = h; sj=1 aij k~j ;

ki =  tn + ci h # exp(ui ) yn
k~i = dexpinv(ui  ki q)
end
P
v = h sj=1
b k~
; j j

yn+1 = # exp(v) yn
Here, a qth order truncation of the dexpinv function is de ned by
k

qX1
z }| {
dexpinv(u v q) = v ; 21 u v] + Bk!k u u :: :  u v]]]
k=2
where  ] is the matrix commutator de ned by A B] = AB ; BA when A and B are matrices,
and Bk is the kth Bernoulli number.
This method has at least order q on any manifold. In Eucliden space this algorithm reduces to
the classical Runge{Kutta algorithm.
;

A.2 Computing ows of vector elds

49

A.2.3 Magnus series methods

The solution of Lie type ordinary dierential matrix equations,
y =  (t)
0

y(0) = p 2 M

(A.2)

where  : R+ ! g for every t  0, and M = G is a matrix Lie group, was recently studied by
Iserles and Nrsett 16]. These methods can be viewed as a particular case of the Munthe-Kaas
methods. The following commutative diagram shows the framework:
T y0 T exp
Tg ;;;;;;;!
TM


x
?
?F =M
M

dexpu;1  y0 exp?

?

;;;;;!
exp

y0 

Again, y0 2 M is the initial point, u 2 g, #y0 (exp(u)) = #(exp(u) y0) and dexpu 1 : g ! g is the
right trivialized tangent of exp. By applying an implicit Runge{Kutta method to the ordinary
dierential equation on g and, since  = (t), performing Picard iteration, an in nite sum of
integrals appears. Magnus 17] observed that u(t) can be expressed as an in nite sum of elements
in g:
;

u(t) =

Zt

()d +

1
2

Z t

()

()d d

0
 
Z t
Z 0 
Z 0

()
() ()d d d
+ 41
0
 Z

Z0 t  0Z
() ()d  ()d d +   
+ 121
0
0
0

(A.3)
:

Iserles and Nrsett analysed this sum and presented the devices necessary to make it a useful
numerical method { or rather a whole family of methods { named Magnus series methods. Implementation issues and error control of these numerical methods were discussed in 15].
When u is approximated by ue, say, the solution is advanced according to
yn+1 = #(exp(ue) yn):

Algorithm A.2.4 (A fourth-order Magnus series method)

Let c1 and c2 be the Gauss{Legendre points
c1 = 21 ;

3
6

and

c2 = 12 +

3
6 

and

2 = (tn + c2h):

and evaluate  at these abscissae values:

1 = (tn + c1 h)

A fourth-order approximation to u is then given as

u4] = 21 h(1 + 2 ) ;

3 2
12 h 1  2]:

The solution is advanced according to

yn+1 = #(exp(u4] ) yn ):

50

The mathematical building blocks of DiMan

Algorithm A.2.5 (A sixth-order Magnus series method)

Let c1 , c2 and c3 be the Gauss{Legendre points
c1 = 21 ;

15
10 

c2 = 21 

c3 = 21 +

and

and evaluate  at these abscissae values:

1 = (tn + c1 h) 2 = (tn + c2h)

and

15
10 

3 = (tn + c3 h):

A sixth-order approximation to u is then given by the following equations:

K1 = 18h (51 + 82 + 53 )
K2 = ; 10815 h2(212 + 13 + 223 )
h3 (1 ; 53  12] + 51 ; 3  23])
K3 = 432
15 h4 1 3 13]]
K4 = 2160
p

u6] = K1 + K2 + K3 + K4 
where ij = i j ]. The solution is advanced according to
yn+1 = (exp(u6] ) yn):
The generalized Magnus series methods that solve y = G (t y), y(0) = y0 2 G, are implemented
according to the algorithms presented in 39, 40]. These methods are based on the collocation
idea.
;

Assume that approximations i   tn + ci h y(tn + ci h) , i = 1 : : :  s, are known. Based in these
values we approximate the function , in the vector space g, around t = tn with its Lagrangian
interpolating polynomial at the abscissae values c1  : : :  cs :
0

(t y(t)) 

s
t ; t 
X
n 
L
i=1

where
Li (t) =

(A.4)

s t;c
Y
k:
c
;
c
k
k=1 i
k6=i

By inserting the interpolating polynomial into the Magnus series, a method solving the general
problem is obtained. As in the classical case, the collocation methods are necessarily implicit.
However, it is possible to derive relaxed collocation schemes that are explicit.
The two collocation based Magnus methods in DiMan 1.6 are MRC3 and MC4:

MRC3: (Magnus series method of order 3 based on relaxed collocation)

Y1 = yn ;
1 = (t
; n  Y1h)
h
Y2 = #(exp ; 2 1  yn )
2 =  ;tn + 2  Y2 
Y3 = #(exp h(;1 + 22)  yn) 3 =  tn + h Y3 
with

; ;

yn+1 = # exp h 61 1 + 23 2 + 61 3 ; h22 1 ; 3  152 2 + 301 3  yn :

A.2 Computing ows of vector elds

51

MC4: (Magnus series method of order 4 based on collocation)

Solve the following system

; ;

Y1 = # exp h 41 1 + 14 ; 63 2 + 725 ;

; ;;

;
Y2 = # exp h 14 + 63 1 + 14 2 + 725 +
p

3 2
24 h 12  yn 
p
3 2
24 h 12  yn 
p

where i = (tn + cih Yi ), i = 1 2, and 12 = 1 2]. Advance the solution by computing

;
yn+1 = # exp h2 (1 + 2 ) ;

3 2
12 h 1  2]  yn

A.2.4 Quadrature methods on quadratic Lie groups

The quadrature methods based on the Cayley transform are similar to the Magnus series methods.
They are discussed in 22]. We again consider the solution of Lie type ordinary dierential matrix
equations,
y =  (t)
0

y(0) = p 2 M

where  : R+ ! g for every t  0. For any matrix v 2 Rn n a subalgebra of gl(n) is



gv

= u 2 gl(n) : vu + uT v = 0 :

Such Lie algebras are called quadratic Lie algebras. Roughly speaking, the Lie groups, G, obtained
by exponentiation of these Lie algebras are called quadratic Lie groups. We immediately see that
by choosing v to be
In

or

0 In=2
;In=2 0

(when n is even)

we recover the Lie algebras so(n) and sp(n), respectively. It is well known that the computation of
matrix exponentials in general is a costly operation. When constructing numerical integrators for
dierential equations evolving on quadratic Lie groups, we exploit the fact that there exist other
mappings between the Lie algebra and the Lie group than the exponential mapping. Celledoni and
Iserles 3] showed that if  is any analytic function that satis es (z)  (;z) = 1, then (gv )
G.
There exist a large number of such functions, but we shall focus on the Cayley transform
cay(z) = (1 ; 2z ) 1(1 + z2 ):
;

The following commutative diagram shows the framework for the methods:
T

Tcay

y0
Tg ;;;;;;;!
TM

dcayu;1  y0 cay?

?
g

; ;;;;!
cay
y0 

x
?
?F =M
M

Again, y0 2 M is the initial point, u 2 g, #y0 (cay(u)) = #(cay(u) y0 ) and dcayu 1 : g ! g is the
right trivialized tangent of cay. By applying an implicit Runge{Kutta method to the ordinary
dierential equation on g and, since  = (t), performing Picard iteration, an in nite sum appears.
The numerical methods below are based on truncations of this sum.
The two timesteppers of the above kind implemented in DiMan 1.6 are qq4a and qq6a:
;

52

The mathematical building blocks of DiMan

qq4a: (quadrature method of order four on quadratic Lie groups)

Consider the Gauss-Legendre weights of order 4: c1 = 21 ;  and c2 = 21 +  with  = 63 .

Let in be the function  evaluated at the abscissae values, in = (tn + ci h), i = 1 2. The
resulting fourth order quadrature method based on the Cayley transform is then given by
un4 = 12 h(1n + 2n ) ; 4 1 3 h21n  2n] ; 961 h3 (1n + 2n )3
yn+1 = #(cay(un4 ) yn ):
p

qq6a: (quadrature method of order six on quadratic Lie groups)

1

Consider the Gauss-Legendre weights of order 6: c1 = 2 ; , c2 = 12 and c3 = 12 +  with

 = 1015 , and let again in = (tn + ci h), i = 1 : : :  3, be the function  evaluated at the
abscissae values. Let !1n , !2n and !3n be de ned as follows:
1n = !1n ; h!2n + (h)2!3n  2n = !1n and 3n = !1n + h!2n + (h)2 !3n :
The resulting sixth order quadrature method based on the Cayley transform is then given
by
un6 = h!1 + 121 h3(!3 ; !1 !2] ; !13 )

;
1 !2 !3] ; !2 !1 !2]] ; !2 !3 ; !3!2 + !1!2!1  !1]
+ h5 240
1
1
p

; 801 !1 !3!1 + 121 (!13 !2] + !15 )

yn+1 = #(cay(un6 ) yn):

A.2.5 Fer expansion methods

The Fer expansion was introduced by Fer 9] as a method of solving matrix dierential equations
in Euclidean space of the form
y = f(t)y
y(0) = y0 :
(A.5)
Iserles 14] proposed numerical methods based on a similar construction. They both showed that
the solution of (A.5) can be expressed as an in nite product of exponentials:
;
;

;

y(t) = nlim exp B0 (t) exp B1 (t)    exp Bn (t) y0 
(A.6)
0

!1

in a neighborhood of 0. The Bi are matrix valuedR functions, and they can be computed iteratively.
By letting A0 (t) = f(t), we obtain B0 (t) = 0t A0() d. Furthermore, we construct C0k as
C00(t) = A0 (t) and C0i+1(t) = C0i(t) B0 (t)], i = 0 1 : : :. Here,  ] denotes the matrix
commutator. Ak+1 (t) and Bk+1 (t) are now computed as follows:
Ak+1(t) =

i C (t)
ki
i=1 (i + 1)!
1

where Ck0(t) = Ak (t) and Cki+1(t) = Cki(t) Bk (t)], i = 0 1 : : :, with Bk+1 (t) = 0t Ak+1 () d.
In DiMan, we view the dierential equation in a generalized setting:
y =  (t) y(0) = y0 2 M:
(A.7)
The numerical procedure generates at each step an element gn 2 G which we use to advance the
numerical solution from yn to yn+1 :
yn+1 = #(gn  yn)
0

A.2 Computing ows of vector elds

53

This procedure is only valid when  is a function of t only. It is, however, possible to extend this
algorithm to also cope with y-dependent functions. This has been analysed in 39, 40].
The Fer expansion methods integrating problem (A.7) are implemented according to the algorithms
presented in 14]. The implementation of the algorithm is not straight-forward. We have, therefore,
only implemented in DiMan methods up to order 6 with n  2 in (A.6). The algorithm is as
follows (see also 14]):
Let A0(t) = (t). Assume we are given the coecients c(ij ) and wi(j ) , i = 1 : : :  s and
j = 1 : : :  m. Set c(2)
0 = 0 and B0 (t0 0) = 0. Evaluate, for every 1  i  s,
;

(2)
B0 t0  c(2)
i h = B0 t0 ci 1h
s


;
(2) h X w(1)A t + ;c(2) + (c(2) ; c(2) )c(1) h
+ c(2)
;
c
i
i 1
j 0 0
i 1
i
i 1 j
;

and

j =1

(2)
C00 t0 + c(2)
i h = A0 t0 + ci
;
; (2) 
;


(2)
C0k t0 + c(2)
i h = C0k 1 t0 + ci h  B0 t0 ci h 
;

1  k  p ; 1:

Then
pX1

A1 t0 + c(2)
i h =

k C ;t + c(2) h 
0k 0
i
k=1 (k + 1)!

and
B1 (t0  h) = h

s
X
;

wi(2) A1 t0 + c(2)
i h:
i=1

The generalized Fer expansion methods that solve y =  (t y), y(0) = y0 2 M, are implemented
according to the algorithms presented in 39, 40]. These methods are based on the collocation idea.
Again, the general implementation procedure is not straight-forward, so we have only implemented
a few particular methods.
;

Assume that approximations i   tn + ci h y(tn + ci h) , i = 1 : : :  s, are known. Based in these
values we approximate the function  around t = tn , with its Lagrangian interpolating polynomial
at the abscissae values c1 : : :  cs as in (A.4). By inserting the interpolating polynomial into the
Fer expansion, a method solving the general problem is obtained. As in the classical case, the
collocation methods are necessarily implicit. However, it is possible to derive relaxed collocation
schemes that are explicit.
The two collocation based Fer methods in DiMan 1.6 are FRC3 and FC4:
0

FRC3: (Fer expansion method of order 3 based on relaxed collocation)

Y1 = yn; ;
1 = (t
; n Y1h)
h
Y2 = #; exp ; 2 1  yn  2 =  ;tn + 2  Y2 
Y3 = # exp h(;1 + 22 )  yn  3 =  tn + h Y3 
with

; ;

yn+1 = # exp h 16 1 + 32 2 + 16 3 exp ; h22 1 ; 3  152 2 + 301 3  yn :

54

The mathematical building blocks of DiMan

FC4: (Fer expansion method of order 4 based on collocation)

Solve the following system

12 = 1 2 ] 13 = 1 3] 23 = 2 3]
Y1 = yn
11 12 + 1 13 ; 1 23
K1 = 245 1 + 31 2 ; 241 3  K2 = ; 240
240
240
; h2
Y2 = #(exp(hK1 ) exp 2 K2  yn)
K1 = 16 1 + 32 2 + 16 3  K2 = ; 152 12 ; 301 13 ; 152 23
;

Y3 = #(exp(hK1 ) exp h22 K2  yn)
where i = (tn + cih Yi ), i = 1 2 3. Advance the solution by computing
;

U1 = h 16 1 + 23 2 + 16 3
K12 = 1 2 ] K13 = 1 3] K23 = 2 3]
;

U2 = h22 ; 152 K12 ; 301 K13 ; 152 K23

and nally,

8 1 ; 17 2 ; 17 3 
Ye1 = ; 315
315
5670
1 1 ; 1 2 + 13 3 
eY2 = ; 168
45
5670
1  
Ye3 = ; 421 1 ; 635 2 ; 126
3
3
h
U3 = 3 (K1 + K2 + K3 )

K1 = K12 Ye1]
K2 = K13 Ye2]
K3 = K23 Ye3]

yn+1 = #(exp(U1 ) exp(U2 + U3 ) yn):

A.2.6 Crouch{Grossman methods

The Crouch{Grossman methods were rst described in 4], and a general theory describing the
order conditions was presented in 34].
Assume that there exists a frame on the manifold M, i.e. a set of vector elds E1 : : :  Ed on M,
which at each point p 2 M span the tangent space TMjp . A dierential equation on M can be
written in terms of this frame as
y = Fy (y) =
0

d
X
i=1

fi (y)Ei 

where fi : M ! R are smooth functions:

(A.8)

Let Fp denote the vector eld with coecients frozen at p relative to the frame:
Fp (y) =

d
X
i=1

fi (p)Ei:

Let g be the Lie algebra generated by the frame E1 : : :  Ed and let G
Di(M) be the collection
of ows on M generated by exponentiating g. Furthermore, let  : g  M ! M be the ow
operator, i.e. y(t) = (tF q) is the solution of y = F(y) with y(0) = q. Since

d  (tF  q) = F ;y(t)  = F (q)
y
y
y
t=0
dt t=0
it follows that (A.8) is an equation of the form (A.1).
0

A.2 Computing ows of vector elds

55

Algorithm A.2.6 (Crouch{Grossman methods)

Let A = (aij ), b = (bj ) and c = (cj ) be the coecients of an s-stage, qth order Crouch{Grossman
method (see e.g. 34]). The following algorithm integrates (A.8) from t = tn to t = tn + h:
Assume that yn  y(tn ) is available
for i = 1 2 : : :  s
Yi = yn
for j = 1 2 : : :  s
Yi = (haij FYj  Yi )
end
end
yn+1 = yn
for i = 1 2 : : :  s
yn+1 = (hbi FYi  yn+1)
end
;

The ow operator  is given as (v p) = # exp(v) p . In Eucliden space this algorithm reduces
to the classical Runge{Kutta algorithm.

Appendix B

Available time stepper schemes

The schemes available in DiMan 1.6 are
Number
1
2
3
4

String
'E1'
'ME2'
'heun2'
'ode23'

5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

'M4a'
'M6a'
'moan25'
'moan35'
'CG23'
'CG3a'
'CG43'
'CG34'
'RK4'
'rk45'
'RKF34'
'RKF43'
'RKF45a'
'RKF54a'
'RKF45b'
'RKF54b'
'dopri45'
'dopri54'
'dopri5'
'butcher6'
'RKF78'
'RKF87'
'dopri78'
'dopri87'
'fer2a'
'fer4G2'

31

'fer5GR'

Description of method
explicit Euler, order 1
modified Euler, order 2
Heun's method, order 2
the method implemented in the MATLAB
ode23 routine
a Magnus method, order 4
a Magnus method, order 6
Moan's method, order 2(5)
Moan's method, order 3(5)
Crouch-Grossman method, order 2(3)
Crouch-Grossman method, order 3
Crouch-Grossman method, order 4(3)
Crouch-Grossman method, order 3(4)
"The" Runge-Kutta method, order 4
Runge-Kutta method, order 4(5)
Fehlberg's method of order 3(4)
Fehlberg's method of order 4(3)
Fehlberg's method of order 4(5) (a)
Fehlberg's method of order 5(4) (a)
Fehlberg's method of order 4(5) (b)
Fehlberg's method of order 5(4) (b)
Dormand and Prince's method of order 4(5)
Dormand and Prince's method of order 5(4)
Dormand and Prince's method of order 5
Butcher's method, order 6
Fehlberg's method of order 7(8)
Fehlberg's method of order 8(7)
Dormand and Prince's method of order 7(8)
Dormand and Prince's method of order 8(7)
Fer method of order 2
Fer method of order 4 based on Gaussian
quadrature
Fer method of order 5 based on
Gauss-Radau quadrature

58

Available time stepper schemes

32

'fer6G3'

- Fer method of order 6 based on

Gaussian quadrature
'fer6GLR'
- Fer method of order 6 based on
Gauss-Legendre and Gauss-JacobiRadau quadrature
'FRC3'
- Fer method of order 3 based on
relaxed collocation
'MRC3'
- Magnus method of order 3 based on
relaxed collocation
'qq4a'
- Quadrature method for quadratic Lie
groups. Order 4.
'qq6a'
- Quadrature method for quadratic Lie
groups. Order 6.
'IE1'
- Implicit Euler, order 1
'GL2' 'IM2' - Gauss-Legendre/implicit midpoint, order 2
'GL4'
- Gauss-Legendre, order 4
'GL6'
- Gauss-Legendre, order 6
'FC4'
- Fer method of order 4 based on collocation
'MC4'
- Magnus method of order 4 based on collocation
'TRAP2'
- Trapozoidal rule of 2nd order.
'GL4S'
- Time symmetric GL method of order 4
'GL6S'
- Time symmetric GL method of order 6

33

34
35
36
37
38
39
40
41
42
43
44
45
46

You can refer to either the number of the method or to its abbreviated name. The following elds
are returned:
.RKname
.RKa
.RKb
.RKc

.RKns
.RKord
.RKtype
.RKbhat

name of the method

matrix A from the method's Butcher tableau
vector b from the method's Butcher tableau
vector c from the method's Butcher tableau or the
abscissae values in case of Magnus methods
number of stages in the method
order of the method
type of the method ('explicit', 'implicit', 'SDIRK')
vector bhat from the method's Butcher tableau
(used in error estimation)

You may add new schemes in the le:

DiffMan/flow/timestepper/@timestepper/setmethod.m

Appendix C

Summary of virtual superclass

functions
C.1 Functions in @liealgebra
basis(a,i)
Returns the i'th basis vector in the Lie algebra.
dcay(a,b,ord)
The differential of the Cayley transform.
dcaycay(x,z,ord)
The differential of the Cayley coordinates of the second kind.
dcaycayinv(x,z,ord)
Inverse of the differential of Cayley coord. of the second kind.
dcayinv(a,b,ord)
The inverse of the differential of the Cayley transform.
dexp(a,b,ord)
The ord'th order approximation of the differential of exp.
dexpexp(x,z,ord)
The differential of canonical coordinates of the second kind.
dexpexpinv(x,z,ord)
Inverse of differential of canonical coord. of the second kind.
dexpinv(a,b,ord)
The ord'th order approximation of the inverse differential of exp.
dexpinvtest(a,b,ord)
The ord'th order approximation of the inverse differential of exp.
dimension(a)
Returns the dimension of the Lie algebra vectorspace.
display(obj)
Display a LIEALGEBRA object, or objects from a daugther class.
dist(a,b)
Distance metric function on the Lie algebra.
dpade22(x,z,ord)
Differential of the (2,2) Pade' approximation of exponential map.
dpade22inv(x,z,ord)
Inverse differential of the (2,2) Pade' approximation.
eig(a)
Overloaded version of the MATLAB built-in eigenvalue function.
getdata(g)
Returns the data that represents the element g in the Lie algebra.

60

Summary of virtual superclass functions

getmatrix(g)
Returns the matrix representation of g in the Lie algebra.
getshape(g)
Returns shape information if the Lie algebra is dynamically subtyped.
getvector(g)
Returns a column vector representing g in the Lie algebra.
hasmatrix(g)
Checks if the Lie algebra has a matrix representation.
hasshape(g)
Checks if the Lie algebra has dynamic shape information.
horzcat(a,b)
Commutator in Lie algebra.
isabelian(a)
Checks whether or not a Lie algebra is Abelian.
isdata(a,m)
Checks if m could be data for an element in Lie algebra.
ismatrix(a,m)
Checks if m is a possible matrix representation in the Lie algebra.
liealgebra(varargin)
Constructor for virtual superclass of all liealgebras.
liegroup(a)
Picks out the liegroup corresponding to the liealgebra.
minus(u,v)
Vector subtraction in Lie algebra.
mtimes(u,v)
Scalar multiplication in Lie algebra.
norm(a,alt)
Overloaded version of the MATLAB built-in norm function.
plus(u,v)
Vector addition in Lie algebra.
project(a,m)
Returns a matrix v which is acceptable by the Lie algebra.
random(lalg)
Creates a random object in the Lie algebra.
sameshape(a,b)
Chechs if a and b belong to the same Lie algebra.
setdata(a,m)
Sets m to be the data of a.
setmatrix(a,m)
Sets m to be the matrix data of a.
setshape(a,sh)
Sets shape information in g.
setvector(a,v)
Sets v to be the vector data of a.
uminus(u)
Unary minus in Lie algebra.
zero(lalg)
Create the zero object in a Lie algebra.
zeros(obj,sz)
Creating an array of objects initalized to zero(obj).

C.2 Functions in @liegroup

C.2 Functions in @liegroup

cay(lgr,a)
Computes the Cayley transform from Lie algebra to Lie group.
caycay(lgr,a)
Computes Cayley coordinates of the second kind.
display(obj)
Display a LIEGROUP object, or objects from a daugther class.
dist(a,b)
Distance metric function on the Lie group.
eig(a)
Overloaded version of the MATLAB built-in eigenvalue function.
exp(lgr,a)
Computes the exponential from the Lie algebra to the Lie group.
expexp(lgr,a)
Computes canonical coordinates of the second kind.
getdata(g)
Returns data that represents the element g in the Lie group.
getmatrix(g)
Returns matrix data that represents the element in the Lie group.
getshape(g)
Returns shape information if the Lie group is dynamically subtyped.
hasmatrix(g)
Returns if the Lie group has a matrix representation.
hasshape(g)
Checks if the Lie group has dynamic shape information.
identity(a)
Returns the identity object in the Lie group of a.
inv(a)
The invers of an element in the Lie group.
invcay(a)
Computes the inverse Cayley coordinates of the first kind.
invcaycay(a)
Computes the inverse Cayley coordinates of the second kind.
invexpexp(a)
Computes inverse Canonical coordinates of the second kind.
invpade22(a)
The inverse (2,2) diagonal Pade' coordinates of first kind.
isabelian(a)
Returns if the Lie group is Abelian or not.
isdata(a,m)
Checks if m is data representation for the Lie group.
ismatrix(a,m)
Checks if m is a matrix representation for the Lie group.
liealgebra(a)
Picks out the liealgebra corresponding to the lie group.
liegroup(varargin)
Constructor for LIEGROUP objects.
log(a)
Computes the logarithm from the Lie group to the Lie algebra.
mtimes(a,b)
The binary operation of two elements in the Lie group.
norm(a,alt)
Overloaded version of the MATLAB built-in norm function.
pade22(lgr,a)
Computes the (2,2) Pade' approximation of the exponential.

61

62

Summary of virtual superclass functions

project(a,m)
Returns a matrix v acceptable by the Lie group.
random(a)
Creates a random object in the Lie group.
sameshape(a,b)
Chechs if a and b belong to the same Lie group.
setdata(a,m)
Sets m to be the data repr. of a.
setmatrix(a,m)
Sets m to be the matrix repr. of a.
setshape(a,sh)
Sets shape information in g.

C.3 Functions in @hmanifold

C.3 Functions in @hmanifold

display(obj)
Display a HMANIFOLD object, or objects from daugther classes.
dist(a,b)
Distance metric function on the homogeneous manifold.
getdata(g)
Returns data representation of element in homogeneous space.
getshape(g)
Returns shape information of the homogeneous space.
hasshape(g)
Checks if the homogeneous space has dynamic shape information.
hmanifold(varargin)
Constructor for HMANIFOLD-objects.
invlambda(p,q)
Returns an object v in the Lie algebra such that lambda(v,p) = q.
isdata(a,m)
Checks if m is a data representation for the homogeneous space.
lambda(a,m,coord)
The action of the Lie algebra on the manifold.
liealgebra(a)
Picks out the liealgebra of the homogeneous space.
origin(a)
Returns the origin in the homogeneous space.
project(a,m)
Projects to a matrix acceptable in the homogeneous space.
random(a)
Creates a random object in the homogeneous space.
sameshape(a,b)
Checks if input has the same shape information.
setdata(a,m)
Sets the data representation of a homogenous space object.
setshape(a,sh)
Sets the shape information in a homogeneous space object.
stabilizer(a)
Returns a matrix spanning the stabilizer subalgebra.
zeros(obj,sz)
Creates an array of objects initalized to the origin object.

63

64

Summary of virtual superclass functions

C.4 Functions in @vectorfield

display(obj)
Display a VECTORFIELD object.
getdomain(f)
Returns object in domain over which the vector field is defined.
geteqntype(f)
Returns the type of the equation.
getfm2g(f)
Returns the map describing the vector field.
setdomain(vf,dom)
Sets dom to be the domain of the vector field vf.
seteqntype(vf,type)
Sets the equation-type-field of vf equal to 'type'.
setfm2g(vf,map)
Sets the map describing the differential equation.
vectorfield(varargin)
Constructor for the vector field class.

C.5 Functions in @flow

C.5 Functions in @flow

display(obj)
Display a FLOW object.
flow(varargin)
Constructor for the flow class.
getdefaults(f)
Returns the default values of the flow object.
gettimestepper(f)
Returns the timestepper used by the flow.
getvectorfield(f)
Returns the vector field defining the flow.
newstepsize(fl,varargin)
Computes a new step size to be used by time stepper objects.
setdefaults(f,varargin)
Sets the defaults of the flow f to ts.
settimestepper(f,ts)
Sets the timestepper of the flow f to ts.
setvectorfield(f,vf)
Sets the vector field of the flow f to vf.
subsref(f,s)
Overloads the parenthesis for flow objects.

65

66

Summary of virtual superclass functions

C.6 Functions in @timestepper

display(obj)
Display a TIMESTEPPER object.
getcoordinate(ts)
Returns the coordinates used by the timestepper object.
getmethod(ts)
Returns the name of the integration scheme used.
setcoordinate(ts,coord)
Sets the coordinates to be used by the timestepper object.
setmethod(ts,method)
Assignes the numerical scheme to be used by the timestepper object.
subsref(ts,s)
This function overloads the parenthesis of a timestepper object.
timestepper(varargin)
Constructor TIMESTEPPER virtual superclass.

Index
DiMan examples, 34

,4

@
auxiliary
demo
dexpinv
dmhelp
dminit
getdata
horzcat
mtimes
shape
startup.m
struct

,5
, 33
, 39, 44
,8
, 11
, 16
, 39
, 39
,6
, 11
,4

action
coadjoint, 19
Lie group, 17, 18, 27, 42
C++, iii, 4
category, 4, 5
functor, 5
class, 3, 21
@, 4, 21
child, 5
functions, 4
functor, 6
private, 4
public, 4
tensor, 3
tensor eld, 5
collocation, 46, 49
relaxed, 46, 49
constructor, 4
coordinate
canonical, rst kind, 29
canonical, second kind, 29
Cayley, 29
Pad'e, 29
coordinate free, 3
algorithm, 3
numerics, iii, 3
documentation, 34
domain, 21
domain, 5

,6
, 26
,6
, 21
, 21
, 21
,6
, 26
, 6, 13
dynamic sybtyping, 6
getdata
getdomain
getshape
hmanifold
liealgebra
liegroup
setdata
setdomain
setshape

embedded pairs, 30
Euclidean space, 1
Euler equations, 19
exponential, 18, 42
Fer expansion, 48
generalized, 49
eld
@fm2g, 7
@vectorfield, 5
field, 5
getfm2g, 26
setdomain, 12
seteqntype, 12
setfm2g, 12, 14, 26
xed point iteration, 30
ops count, 39
ow, 7, 25, 27
@flow, 15
defaults, 8
flow, 5
getdefaults, 31
getvectorfield, 28
setdefaults, 8, 31
settimestepper, 12, 15
setvectorfield, 12, 28
timestepper, 8
vectorfield, 8
owtools, 36
fteff, 36
ftorder, 36
newexact, 36
frame, 50
function

68
private, 4
public, 4
functional derivative, 19
Gauss{Legendre, 45, 46, 48
generator map, 14
geometric integration, 1
Hamiltonian problem, 19
help
demo, 12, 33
dmhelp, 8, 12, 35
dmtutorial, 11
helpwin, 12
online, 8
tutorial, 33
homogeneous space, 4, 12, 13, 21, 25, 41, 42
@hmanifold, 22
@hmisospec, 22
@hmlie, 6, 22, 25
@hmnsphere, 13, 22
@hmrigid, 22
@hmrn, 22
@hmtop, 22
in nitesimal generator, 17, 18, 27
information hiding, 3
inheritance, 4
initial condition, 12
integral curve, 12, 25
interpolation
Lagrangian, 46
isospectral ows, 18
Jacobi identity, 42
lafreeutil, 36, 37
bch2, 37
bch, 37
cdopri5, 37
divisors, 37
killing, 37
lafcount, 37
lafdim, 37
magnusdim, 37
mobius, 37
rkgl, 37
rkmk4mod, 37
rkmk4, 37
slegendre, 37
left multiplication, 18
Lie algebra, 4, 22, 25, 42
@ladirprod, 6, 22
@lafree, 22, 37, 39
@lagl, 6, 22

INDEX
, 22
, 22
, 22
, 22
, 22

@larn
@lase
@lasl
@laso
@lasp
@liealgebra

, 22
Jacobi identity, 42
lafreeutil, 37
Lie bracket, 42
quadratic, 47
Lie bracket, 42
Lie group, 4, 23, 25, 41
@lgdirprod, 6, 24
@lggl, 24
@lgon, 24
@lgrn, 24
@lgse, 24
@lgsl, 24
@lgso, 24
@lgsp, 24
@liegroup, 24
matrix, 18
quadratic, 47
special orthogonal, 18
Lie-Poisson systems, 18
Magnus series method, 45
Magnus series methods
generalized, 46
manifold, 41
in nite dimensional, 1
MEX, 38
Munthe-Kaas methods, 43, 45
Newton iteration, 30
nonlinear systems, 30
object, 3
domain, 6
eld, 6
ow, 6
private, 3
public, 3
time stepper, 6
object orientation, 4
ODE
canonical form, 43
online help, 8
overloading, 5
partial dierential equations, 1, 7
Picard iteration, 45, 47
private, 3
public, 3

INDEX

69

quadrature, 47

, 36

rigid body, 19
Runge{Kutta, 1, 41, 43, 44, 47, 51
SOPHUS, iii
speci cation, 3
step size
variable, 12, 30
SYNODE, iii
tangent bundle, 42
tangent space, 41
tensor eld equations, iii
time stepper, 7, 27, 28
RK4, 15
@timestepper, 29
@tscg, 29
@tsfer, 29
@tsmagnus, 29
@tsqq, 29
@tsrkmk, 15, 29, 39
@tsrk, 29
coordinate, 7
getcoordinate, 29
getdefaults, 28
getmethod, 29
gettimestepper, 30
method, 7
setcoordinate, 12, 15, 29
setdefaults, 28
setmethod, 12, 15, 29
settimestepper, 29
timesteppers, 5
Butcher method, 15, 17
Cayley transform, 47
collocation, 46, 49
Crouch{Grossman method, 17, 50, 51
Fer expansion method, 48
generalized, 49
Gauss{Legendre, 45, 46, 48
Lie type, 43, 45, 47
Magnus series method, 45
RKMK, 17, 43
Runge{Kutta, 41, 43, 44, 47, 51
tutorial, 33
utilities

, 36

addsubdir
array
dmargcheck
dmhelp
dmprogrep
iscellempty

, 36

, 36

, 36

, 36
, 36

iseven
isinteger
repprogress
skew

, 36

, 36
, 36

vector eld, 14, 25, 42

@vectorfield, 7, 14
geteqntype, 26
seteqntype, 26
vectorfield, 25
virtual superclass, 4, 5, 21, 22, 24, 27
flow, 27