A Guide to the Integrator Library

MBSSIM
Version 1.00
Reinhold von Schwerin1
and
Michael Winckler 1
Interdisciplinary Center for Scientic Computing (IWR)
University of Heidelberg
Im Neuenheimer Feld 368
D{69120 Heidelberg, Germany
e-mail : Reinhold.vonSchwerin@IWR.Uni-Heidelberg.De
Michael.Winckler@IWR.Uni-Heidelberg.De

January 7, 1997

1 funded by the Deutsche Forschungsgemeinschaft within the Schwerpunktprogramm \Dy-

namik von Mehrkorpersystemen"
Contents
1 Introduction 2
2 The MBSSIM{les 3
3 Sample models 7
3.1 Available example models . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.2 Using the simulation examples . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.2.1 Makeles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.2.2 The option le . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.2.3 Screen output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
4 The Integrators 17
4.1 Available Discretizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.2 The Calling sequence of the integrators . . . . . . . . . . . . . . . . . . . . 18
4.3 Parameters: Rwork and Iwork . . . . . . . . . . . . . . . . . . . . . . . . . 21
4.3.1 Control parameters passed via rwork. . . . . . . . . . . . . . . . . . 21
4.3.2 Control parameters passed via iwork. . . . . . . . . . . . . . . . . . 23
5 User Dened Subroutines 26
5.1 Model Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
5.2 Output Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
5.2.1 The prompt ag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
5.2.2 The output modes of the integrators . . . . . . . . . . . . . . . . . 30
5.2.3 Output control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
5.2.4 Sample Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
5.3 Switching Point Localization Routine . . . . . . . . . . . . . . . . . . . . . 32
5.3.1 State{Event Finder (SEF) . . . . . . . . . . . . . . . . . . . . . . . 33
5.3.2 User routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
5.3.3 The prompt ag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
5.3.4 Coding your own mbsswt . . . . . . . . . . . . . . . . . . . . . . . 37
6 Coding new models 43

1
1 Introduction
The integrator library MBSSIM has been designed for the treatment of initial value prob-
lems in multibody system dynamics. The routines are written in standard FORTRAN 77
(except for IMPLICIT NONE statements) and use DOUBLE PRECISION arithmetic.
The models may be formulated either as an ODE or (preferably) as a DAE of index 3.
It is assumed that the equations of motion are derived via a multibody formalism like
NEWEUL (see [16]), so that all the parts needed for a treatment by index reduction to
index 1 are readily available. To be precise, we assume that the model can be formulated
in the following way:
M (p) p = f (t; p; p_) G(p)T 
g(p) = 0 ;
where
p = (generalized) positions
M (p) = mass matrix
G(p) := gp(p) = @p @ g(p) (constraint matrix)
f (t; p; v) = explicit force terms
After index reduction, this becomes
p_ = v ; v_ = a
! ! !
M GT a = f (t; p; v)
G 0  (p; v)
subject to
g(p) = 0 (position constraint)
G(p) v = 0 (velocity constraint)
Here
(p; v) := ddt (G(p)) v = vT Gp (p) v :
The index 3 condition (position constraint) along with the index 2 condition (velocity
constraint) and the part of the index 1 condition (acceleration constraint) must also be
specied in the subroutine mbsmod describing the multibody system model (see below).
The equations of motion are subsequently solved numerically, by means of structure-
exploiting linear algebra methods. Consistency of the position and velocity coordinates
is maintained by sequential projection in order to ensure physically meaningful solutions.
It is possible to process data during or after integration by using either a grid output or
a continuous output feature (or both). Also, the integrators provide a state{event nder
2
for the treatment of models with jumps or higher derivative discontinuities.
The integrators can also treat variables of external dynamics, which is essential for exten-
sions to mechatronical models.

2 The MBSSIM{les

The les reside in a (sub{)directory called
mbs sim :
This directory is further subdivided into the following subdirectories which fall into three
classes and contain the les described below. Apart from the les listed, there is also a
makefile in each one of the (sub{)directories.

 Class 1: Directories containing the implemetations of numerical methods of MBSSIM

There are four of these directories:
{ in mbs
Here, the integration routines are grouped together.
 mbshb3.f : MBS-Integrator based on a low order RK3(2) method
 mbsdp5.f : MBS-Integrator based on a medium order RK5(4) method
 mbsd85.f : MBS-Integrator based on a high order RK8 method
 mbsabm.f : MBS-Integrator based on an Adams PECE method
 mbsext.f : MBS-Integrator based on extrapolation
 mbserr.f : Error handling and error codes
 mbsuti.f : Utilities for the integrators
 mbssut.f : Utilities for the switching point localization
{ la mbs
This directory holds the linear algebra routines based on higher level blas and
the lapack (see [2]) collection of linear solvers.
 mbslal.f : Interface calling the decomposition and back{substitution rou-
tines according to a method- ag
 msdcnu.f : Decomposition using NSM
 msslnu.f : Back{substitution using NSM
 msdcrs.f : Decomposition using RSM
 msslrs.f : Back{substitution using RSM
 msdcgc.f : Decomposition (Gaussian) with column interchange
 msslgc.f : Back{substitution for column interchange
3
  msdcgr.f : Decomposition (Gaussian) with row interchange
 msslgr.f : Back{substitution for row interchange
 dgetz2.f : LAPACK-like routine for LU-factorization
where NSM means null{space method and RSM means range{space method (see
[4]).
{ li mbs
This directory holds the linear algebra routines based on blas level 1 and the
linpack collection of linear solvers.
 msfanu.f : Decomposition using NSM
 msawnu.f : Back{substitution using NSM
 msfars.f : Decomposition using RSM
 msawrs.f : Back{substitution using RSM
 msfagc.f : Decomposition (Gaussian) with column interchange
 msawgc.f : Back{substitution for column interchange
 msfagr.f : Decomposition (Gaussian) with row interchange
 msawgr.f : Back{substitution for row interchange
{ pr mbs
This directory holds the projection routines corresponding to the decomposition
routines above. Those routines that have the letters pr in the middle use higher
level blas, those that have mf use only level one.
 mbsprj.f : Interface calling the projection routines in accordance with the
linear algebra method
 msprgc.f : Projection using LU -decomposition of G (column interchange)
 msprgr.f : Projection using LU -decomposition of G (row interchange)
 msprch.f : Auxiliary routine for LU -projection
 msprrs.f : Projection using RSM-decomposition
 msmfgc.f : Projection using LU -decomposition of G (column interchange)
 msmfgr.f : Projection using LU -decomposition of G (row interchange)
 msmfch.f : Auxiliary routine for LU -projection
 msmfrs.f : Projection using RSM-decomposition
 Class 2: Directories containing sample simulation models
The examples which are available are described in the section on the sample models,
where we also give detailed hints on how to make use of them. The organization of
the directories containing the examples is as follows:
{ xxxyyy
The simulation models all have names consisting of six letters. They are also
used for some of the les in the directory (sometimes just the rst three of
these, namely, xxx)
4
  : initial values, model dimensions, etc.
xxxini

xxxlsg : reference solution

xxxrun : option le for simulation run

xxxmain.f : main program

xxxmod.f : model description

xxxsol.f : sample output routine

xxxswt.f : subroutine dening the switching functions

 Class 3: Directories with auxiliary routines.

{ sp mbs
This directory holds all the les that do not t into any of the four categories
of class 1, namely the les that the main programs need for input and output,
the core of the main programs (which is the same for all the examples) and the
timing routine for measuring the CPU time for the simulation runs.
 dumswt.f : template/dummy for mbsswt
 mbsint.f : Interface between the main program and the integrators
 mbsmai.f : The main subroutine used by all the sample programs
 mbsma2.f : Variation of the main subroutine (hmax set to 0:1)
 mbsout.f : File with subroutines for output of statistics, etc.
 mbstim.apo : Timing routine for APOLLO DOMAIN workstations
 mbstim.f : Dummy timing routine
 mbstim.o.ibm : Object le of a timing routine (in C for IBM RS6000)
 mbszus.f : File containing some subroutines used by mbsmai.f
{ dblas
Double Precision Basic Linear Algebra Subprograms necessary for MBSSIM.
These les were all obtained via electronic mail from netlib 1. The directory
contains the following two routines:
 xerbla.f : blas error handling
 lsame.f : blas auxiliary routine
This directory is further divided into three subdirectories according to the level
of the BLAS:
 blas1

daxpy.f : vector addition

dcopy.f : vector copy

ddot.f : Euclidean inner product
1 e-mail: netlib@ornl.gov . E{mail with send index on a line by itself will produce more
information.

5

dnrm2.f : Euclidean norm

dscal.f : scaling of vector

dswap.f : swapping of two vectors

idamax.f : index of maximal vector element
 blas2

dgemv.f : matrix{vector multiplication

dger.f : rank 1 update

dtrmv.f : triangular matrix{vector multiplication

dtrsv.f : triangular solve (matrix{vector)
 blas3

dgemm.f : matrix{matrix multiplication

dsyrk.f : symmetrical rank 1 update

dtrmm.f : triangular matrix{matrix multiplication

dtrsm.f : triangular solve (matrix{matrix)
Remark. On some computers it is possible to use a blas library, which usually
contains the blas in a form optimized for the particular computing environ-
ment they are used on. These are normally accessed by specifying some kind
of option (like, e.g. -lblas) when calling the linker. In this case it may make
more sense to use these routines rather than the ones described above.
{ linlap
LINPACK and LAPACK routines necessary for MBSSIM. All these les were
also obtained via electronic mail from netlib. The directory contains the
following routines:
 ilaenv.f : Auxiliary routine for optimal block size (LAPACK)
 dpotrf.f : Interface for Cholesky factorization (LAPACK)
 dpotf2.f : Actual Cholesky factorization (LAPACK)
 dpofa.f : Cholesky factorization (LINPACK)
 dposl.f : Back{substitution routine for dpofa.f (LINPACK)
 dtrsl.f : Triangular solve (LINPACK)
 This documentation can be found in
{ docu

 readme.ps : Documentation in PostScript format.

6
3 Sample models
The main programs, as well as the output and switching routines that come together with
MBSSIM, are intended to provide a useful introduction to the integrator library. They
are adequately commented and easy to use. In order to try out some of the options, all
that needs to be done is to change the respective parameters in the option le that is
read by the main program. This means that no recompilation is necessary, if only those
parameters are changed which are supplied via these option les. If, however, some of
the various other parameters that can in principle be set by the user are to be changed
as well, they are easy to access in the main program's source code itself.

3.1 Available example models

Together with MBSSIM, we supply several examples, that is, model subroutines sitting in
subdirectories complete with initial values, reference solutions, output routines and plot
les for gnuplot. The organization inside the subdirectories is described in detail in the
section on the les of MBSSIM. The examples have been chosen so as to highlight most
of the features of MBSSIM and are quite representative, as they usually correspond to
real technical models.
Here is a short description of the models:
 dummyy
A directory with templates for all the les needed to use our standard main subrou-
tine mbsmai. For more details, see the section on how to code one's own models.
 fvlink
This is the model of a ve{link wheel suspension ([8]) used in the automotive in-
dustry. The model comes with the road model of a pothole. This example is pro-
grammed in two ways: with real g{stopping, i.e. forcing the integrator to reinitialize
('model 1') and with event monitoring ('model 2'), to show the problems that occur
when a discontinuous the right hand side is not treated correctly ([17]).
50

α, β, γ spherical joints
ϕ1 , ψ1
vertical position of tire center - 278 [mm]

1
δ
2 0

ϕ,ψ
2 2
wheel
universal wheel carrier
joints 7 -50
6
z
ϕ,ψ
3 3
y
B
3
x

4
-100
ϕ , ψ4
4 5 street
ϕ5, ψ center of wheel
5 line of liftoff/contact
g-stops
-150

0 10 20 30 40 50 60
distance travelled [m]

model of ve-link suspension Plot of pot{hole Solution

7
 gelenk

This example models the well known

squeezer mechanism ([3], [16]), a me-
B chanical device found in small printers,
K3
etc., using relative coordinates (Eule-
rian angles). There are three closed
D
γ

kinematic loops to be considered. For a

K5
y

dierent model of the same mechanism

K4 K2
θ
φ

see below.
K1 β
δ ω O x
A K6

ε
K7

 kurbel
y This is a model of the planar slider{
Q=(p1 ,p2 ) crank mechanism ([1]), a standard
benchmark for MBS{integrators, since
O x it is one of the simplest examples with
P=(p3 ,0) a kinematic loop. The model uses nat-
ural coordinates ([18]).
 pendel

ali This directory holds the scalable mul-

tiple pendulum with initial values and
Si reference solutions for 1, 3, 5, 10 or 30
bodies.

 spielz
A model of a toy woodpecker (in Ger-
man Spielzeugspecht ) sliding down a
metal pole ([14]). Again switching
functions are used to make this model
work. Not only does it speed up the
simulation to make use of g{stops, but
in this case it is also unavoidable due
to jump discontinuities in the model.
A detailed description of the complete
model can be found in the section on
mbsswt.

8
  qckrtn
al5

al4

P5
P4

This is the model of the quick{return

Pi

mechanism , a description of which can

al2
ali al3
P2
P3 be found in ([19],[12]). Again, this is
al1 quite a popular benchmark for MBS{
P1 integrators.

 svnbod

This is a model for the same device as

gelenk, but the modelling is done in
B
K3 Cartesian coordinates instead of Eule-
D rian angles ([18],[1]). Although there
K5
Q3 ( p5 , p6 )
are more variables, the simulation is
much faster due to easier expressions
y
Q 1 ( p1 , p )
K4 2

without sin and cos functions.

K2

K1
O x
A K6
Q 4( p7 , p )
8

K7 Q (p ,p )
2 3 4

There is also a version of this model with on{line animation which is located in the
directory sqzani. To run this version you need to have the gl{library installed,
e.g. on Silicon Graphics workstations.
Remark. If you have an interesting application for which you have found MBSSIM
useful, or one where you thought it should have been useful, but was not particularly or if
you have any problems or unresolved errors, please do contact us either via email or using
good old 'snail mail'. We are always interested in improving our package and examining
new models.

3.2 Using the simulation examples

In order to run the examples, all you have to do is make them and afterwards you can try
out various options by changing parameters in the option le .
9
3.2.1 Makeles
Making executables. The easiest way to get an executable (in all example directories
at once) is to simply type
make

in the directory mbs sim. The Makefile will then access all the subdirectories and make
all the necessary object les. Finally, it will also link everything together and produce
executables called
xxxyyy

in the subdirectory that has the same name.

A second possibility is appropriate, when you just want to use one example. In this case
you prepare the package for use by saying
make preparation

in the directory mbs sim. After this you can switch to the appropriate subdirectory that
holds your example and just type
make

again, resulting in the actual program to be compiled and linked with the methods in the
package. If you want to test your own examples, follow the detailed description on how
to code your own examples or examine one of our models for reference. The examples
gelenk and spielz contain easy to read descriptions that nevertheless cover most of the
usual problems in implementation, including switching functions and g{stops.
Making other things. Typing
make rubbish

in either the main directory or one of the subdirectories purges unwanted les e.g. leftovers
of the editor emacs and backup les (i.e. les ending with .bak or ~).
To get rid of the object les and executables type
make clean

in either the main directory or one of the subdirectories. Again, typing this in the main
directory results in this command being carried out in all the subdirectories.
Having made all the executables, you can run them and control the simulation runs by
changing the option le described next.

10
3.2.2 The option le
For every example, there is a le called xxxrun (e.g. gelrun) in the respective directory
xxxyyy (e.g. gelenk; see below for more details). This is used to try out some of the
options the user has with MBSSIM without recompiling the main program. First, eight
global parameters that apply for all runs are read from the option le. After that, there
are seven local parameters in each of the subsequent blocks describing the combinations of
methods to be used by the integrator chosen. Finally, there is a single line with a negative
value to terminate the session. To be precise, the option le looks as follows:
#
0 ** Run-time statistics channel **
1 ** language **
3.d0 ** -log(least stringent tolerance) **
6.d0 ** -log( most stringent tolerance) **
1.d0 ** -log(tolerance factor) **
0 ** type of integrator output **
100 ** number of output points **
0 ** lswt: Switches ON or OFF **
#
0 ** Integrator **
0 ** LA-Method **
0 ** Mass matrix constant ? **
1 ** >> NO << projection ? **
0 ** Projection method **
9.d0 ** -log(projection accuracy) **
11.d0 ** -log(accuracy for SWT-point loc.) **
#
30 ** Integrator **
12 ** LA-Method **
0 ** Mass matrix constant ? **
0 ** >> NO << projection ? **
1 ** Projection method **
10.d0 ** -log(projection accuracy) **
12.d0 ** -log(accuracy for SWT-point loc.) **
#
-1 >>>>> terminate <<<<<<
#

The values in the various lines are to be interpreted as follows:

Global parameters. Runtime statistics can be output to the screen or to a le (which
will then be called xxxsta) by assigning a channel number dierent from 0 or 6. In
the present case, the statistics are being sent to the screen using the English language .
The default language, however, is German for any value other than 1. The simulation

11
is repeated over a range of tolerances from 10 3 to 10 6, where the requirement is made
stricter by a tolerance factor of 10 1 . The respective input values are the negative loga-
rithms thereof. No intermediate output is requested (i.e. iout = 0; for alternative choices
see the documentation on mbssol) so that the number of output points does not mean
anything in this case. There are no switching functions in the model, so the calls to the
switching routine are turned o.
Local parameters. Two dierent integrators are used for the simulations in connection
with dierent linear algebra and projection methods.
The rst time the model is simulated using the integrator mbshb3 (number 0). For the
solution of the linear systems , the null-space method (number 0, i.e. based on blas level
1 and linpack solvers) is chosen. This example does not have a constant mass matrix
(indicator is 0). Also, we only solve the index 1 system without projection (thus causing
substantial drift !!), denoted by setting the no{projection indicator to 1. The ag for
the projection method is then ignored. The projection accuracy is set to 10 9 while the
tolerance for locating switching points is set to 10 11 (again by giving the values of the
negative logarithms thereof ). Both these parameters, however, are ignored, since we have
requested no projection and there are no switching points in the model.
The second time, the integrator mbsabm (number 30) is called and, as the linear algebra
method, we choose the Gauss method with row interchanges (number 12, i.e. based on
blas levels 1,2, and 3 and lapack solvers). Also, we use projection in Euclidean-norm
in order to avoid drift (no-projection indicator is 0 and projection-method ag is 1).
The projection and switching point localization accuracies are set to 10 10 and 10 12
respectively, although the latter is again ignored.
Finally, we terminate execution of the main program by supplying a negative value for
the number of the integrator.
Remarks.
1. The numbers for the respective integrators are as follows:

integrator mbshb3 mbsdp5 mbsd85 mbsabm mbsext

number 0 10 20 30 40
2. The tolerances are always scalars itol = 0 and we set atol = rtol in mbsmai.
3.2.3 Screen output
When the above option le is used for simulating the squeezer mechanism (see [3],[16] for
details of the model) the output to the screen will look as follows:

12
<!>==========================================================================<!>

Example : 7-body Mechanism (angl.)

Problem Type : DAE 7--6
Time-Interval : [ .000, .060] (with 0 Outputpoints)
Range of Tols : 10^- 3.00 -- 10^- 6.00 (in steps of 10^-1.00)
Switches : 0

<!>==========================================================================<!>

Initial Values (at Time t= .00) :

Positions Velocities

pos( 1) = -.061713890014 vel( 1) = .000000000000

pos( 2) = .000000000000 vel( 2) = .000000000000
pos( 3) = .455279819163 vel( 3) = .000000000000
pos( 4) = .222668390166 vel( 4) = .000000000000
pos( 5) = .487364979544 vel( 5) = .000000000000
pos( 6) = -.222668390166 vel( 6) = .000000000000
pos( 7) = 1.230547444550 vel( 7) = .000000000000

Accelerations Constraint Forces

acc( 1) = 14220.635674458952 cfr( 1) = -.000670825158

acc( 2) = -10665.476755844213 cfr( 2) = -.000894433544
acc( 3) = .000000000000 cfr( 3) = 3.004204857213
acc( 4) = .000000000000 cfr( 4) = .000000000000
acc( 5) = .000000000000 cfr( 5) = .000000000000
acc( 6) = .000000000000 cfr( 6) = .000000000000
acc( 7) = .000000000000 cfr( 7) = .000000000000

<!>==========================================================================<!>
Integrator : MBShb3
==============================================================================
without switching-point search
==============================================================================
BLAS 1 : LR-Null-Space-Method
==============================================================================
without projection
==============================================================================

Runtime-Statistics :

-log -log -log -log

13
 (TOL) CPU OK STPS ACPT RJCT NMAT NRHS PRJP PRJV (ERR ) (ERRP) (ERRV)

3.0 .7 1 390 304 86 1172 1172 0 0 1.73 4.12 2.49

4.0 1.5 1 707 632 75 2123 2123 0 0 2.84 5.13 3.44
5.0 2.4 1 1380 1358 22 4142 4142 0 0 4.31 6.20 4.52
6.0 5.3 1 2959 2954 4 8879 8879 0 0 5.47 7.23 5.56

<!>==========================================================================<!>
Integrator : MBSabm
==============================================================================
without switching-point search
==============================================================================
BLAS 123 : GAUSS (swap columns)
==============================================================================
with Euclid-projection (accuracy : 10^-10.00)
==============================================================================

Runtime-Statistics :

-log -log -log -log

(TOL) CPU OK STPS ACPT RJCT NMAT NRHS PRJP PRJV (ERR ) (ERRP) (ERRV)

3.0 .9 1 386 386 0 778 778 379 383 3.35 - -

4.0 1.3 1 502 502 0 1010 1010 400 499 4.08 - -
5.0 1.5 1 614 614 0 1234 1234 207 609 4.89 - -
6.0 1.7 1 724 724 0 1454 1454 37 701 5.99 - -

<!>==========================================================================<!>

Final Values (at Time t= .06) :

Positions Velocities

pos( 1) = 44.734390343526 vel( 1) = 1058.440242744149

pos( 2) = -44.582942823108 vel( 2) = -801.432923946381
pos( 3) = .404740826697 vel( 3) = -123.584119956581
pos( 4) = .122585862271 vel( 4) = -240.280405027648
pos( 5) = .497825207290 vel( 5) = 23.316334900609
pos( 6) = -.122585862274 vel( 6) = 240.280405051226
pos( 7) = 1.193743619129 vel( 7) = -85.642163627360

Accelerations Constraint Forces

acc( 1) = -76799.926515613100 cfr( 1) = -.129270142928

acc( 2) = -77149.039134068647 cfr( 2) = .062450738260

14
 acc( 3) = -123430.010693342207 cfr( 3) = .876442010636
acc( 4) = -219953.868100964173 cfr( 4) = -.164888194195
acc( 5) = 12658.624725991922 cfr( 5) = .711344827112
acc( 6) = 219953.868115446850 cfr( 6) = .124134937707
acc( 7) = -64261.150144381187 cfr( 7) = -2.442214856808

<!>==========================================================================<!>

The output is divided up into sections by delimiting lines starting and ending with <!>.
Header section with global parameters. In the rst section information is given
about the task the integrator is to carry out. This corresponds to the block of global
parameters read from the option le.
Initial values. The next one gives the initial values. Here, only the values for the posi-
tions and velocities have been specied, whereas the corresponding values of accelerations
and constraint forces have been calculated by solving the system of equations (cf. the
introduction)
! ! !
M GT acc = f and cfr := GT
 :
G 0 
Local parameters. After this, the user is told which integrator is used to solve the
problem, whether event localization is performed, also which linear algebra method is
used (together with the level of blas involved) and whether or not projection is carried
out. If so, the user is also told which projection method and accuracy has been requested.
Runtime statistics Next, the actual statistics are given. These consist of 13 columns,
the rst of which reports the negative logarithm of the tolerance being used. The second
gives the CPU-time, and the third indicates whether integration was successful. Then
follow the number of steps attempted, after that the number of accepted steps and the
sixth column reports the number of rejected steps after at least one has been successful.
Thus, the dierence STPS - ACPT - RJCT is the number of unsuccessful attempts at
the start of the integration. Then follow the number of evaluations of both the model
matrix on the left hand side (NMAT) and the right hand side (NRHS). Then the number
of projection steps on position and on velocity level are given. Finally, the negative
logarithms of various errors are reported. The rst of these is the error of the solution
measured against a solution obtained by a very high precision calculation (usually in
quadruple precision), the second measures the size of the residual on position level, and
the third measures the residual on velocity level. In all these cases, a dash indicates that
the error is below the requested tolerance.

15
Repetition and nal values. These statistics are repeated for each new integrator
along with the information on the name of the integrator, the use of switching functions,
the linear algebra method and the use of projection, until no further integration is re-
quested. In this case, the nal values last obtained are written to the screen and the
program terminates.
Other choices of the parameters (especially a dierent channel for the runtime statistics)
will result in dierent screen output, but this output should be self-explanatory.

16
4 The Integrators
4.1 Available Discretizations
Currently the following discretization schemes have been implemented in MBSSIM:
 mbshb3
This integrator is based on a 3(2){pair of Runge{Kutta formulae. This means
that the orders are 3 and 2 respectively and that the code uses local extrapolation,
i.e. the integration is continued with the higher order result as the initial value for
the next step. Although four stages are needed for the second order result, the
eective number of function evaluations per step is three, since the last evaluation
is subsequently used as the initial function value for the next step 2. The integrator
has been especially designed for the needs of low accuracy computations (from 10 3
to 10 1, say) along with graphical output.
For a detailed description refer to the documentation in the code.
 mbsdp5
This integrator is based on a 5(4){pair of Runge{Kutta formulae due to Dor-
mand and Prince (see [15]). The code also uses local extrapolation and, again,
although it needs seven stages for the fourth order result, the eective number of
function evaluations per step is six (FSAL). The formulae have been shown to be
particularly eective for tolerances in the appropriate range (as a rule of thumb,
from 10 6 to 10 2 ). It is thus especially useful for medium accuracy computations,
possibly also with graphical output.
For a detailed description refer to the documentation in the code and [10].
 mbsd85
This integrator is based on a Runge{Kutta formula of order 8 due again to Dor-
mand and Prince. This formula along with the special type of error control and
dense output is described in detail in [10]. It needs 12 evaluations of the model
equations per step. This code is highly ecient over a wide range of tolerances and
can be used for higher precision calculations as well as lower precision.
For a detailed description refer to the documentation in the code.
Remark. It must be emphasized that, due to the xed orders of the Runge{Kutta
methods, it does not make sense to use the lower order ones ( mbshb3, mbsdp5) for
high precision calculations, since this will waste a lot of computer time. These methods,
however, generally perform better when only low accuracy is requested, since they need less
function evaluations per step. But, numerical experiments have shown that this is only
true for very loose accuracy requirements, since even for tolerances like 10 4 mbsd85 is
usually already more ecient.
2 This is called rst same as last (FSAL)

17
  mbsabm
This integrator is an implementation of an Adams{Bashforth{Moulton
predictor{corrector method. Such multistep methods generally need signicantly
less function evaluations in order to meet given tolerance requirements. Thus they
are very ecient and especially useful if the evaluation of the righthand side is ex-
pensive and time consuming. The method is fast and reliable over a wide range
of tolerances due to the fact that it varies both order and stepsize automatically.
Dense output can be provided in a natural way which also allows for an ecient
treatment of model discontinuities.
For a detailed description refer to the documentation in the code and to the forth-
coming paper [5].
 mbsext
This integrator is based on the explicit midpoint rule as it is implemented in the
ODE-solver ODEX by Hairer and Wanner ([10]). It is quite useful for reaching
higher precisions but is ill{suited for locating switching points. This is due to the fact
that extrapolation allows for very large stepsizes which in turn raises the probability
of missing the occurrence of an event described by zeroes of switching functions (see
the section on the user supplied subroutine mbsswt).

4.2 The Calling sequence of the integrators

All the integrators in MBSSIM have the same calling sequence, which is as follows:

C
C ----------------------------------------------------------
SUBROUTINE MBSXXX(MBSMOD,MBSSOL,MBSSWT,
@ t ,s ,p ,v ,rlam ,
@ tend ,ns ,npos ,nvel ,nlam ,
@ ngpos ,rpar ,ipar ,rtol ,atol ,
@ wk ,lwk ,iwk ,liwk ,mbsfl )
C ----------------------------------------------------------
C

The meaning of the parameters in the calling sequence is given in the following.

18
C
C ----------------------------------------------------------------
C
C a. USER DEFINED (EXTERNAL) SUBROUTINES
C --------------------------------------
C
C a1. MBSMOD U this subroutine supplies the
C parts of the MultiBody-System MODel
C (** see below **)
C
C a2. MBSSOL U this is the subroutine for processing
C the numerical solution during integration
C (** see below **)
C
C a3. MBSSWT U this is the subroutine for specifying switching
C functions for event localization
C (** see below **)
C
C b. MODEL VARIABLES
C ------------------
C
C t I REAL*8; starting time of integration
C s I REAL*8; initial values for external dynamics
C p I REAL*8; initial values for positions
C v I REAL*8; initial values for velocities
C rlam I REAL*8; initial values for LANGRANGE multipliers
C tend I REAL*8; final time of integration
C
C c. MODEL DIMENSIONS
C -------------------
C
C ns I INTEGER; # of external dynamical variables
C npos I INTEGER; # of position variables
C nvel I INTEGER; # of velocity variables
C nlam I INTEGER; # of LAGRANGE multipliers
C ngpos I INTEGER; # of position constraints
C
C d. USER DEFINED MODEL PARAMETERS
C --------------------------------
C
C rpar I REAL*8; array for user parameters
C ipar I INTEGER; array for user parameters
C
C
C

19
C e. REQUESTED ACCURACY
C ---------------------
C
C rtol I REAL*8; (array of) relative tolerance(s)
C atol I REAL*8; (array of) absolute tolerance(s)
C
C Their type depends on ** itol = iwk(7) **
C
C itol rtol atol
C ---------------------------------
C 0 scalar scalar
C 1 scalar vector
C 2 vector scalar
C 3 vector vector
C
C f. WORKSPACE
C ------------
C
C wk I REAL*8; real workspace
C lwk I INTEGER; length of real workspace
C iwk I INTEGER; integer workspace
C liwk I INTEGER; length of integer workspace
C
C OUTPUT PARAMETERS :
C -----------------
C
C t O REAL*8; endpoint reached during integration
C s O REAL*8; final values for external dynamics
C p O REAL*8; final values for positions
C v O REAL*8; final values for velocities
C rlam O REAL*8; final values for LANGRANGE multipliers
C lwk O INTEGER; real workspace required (optional)
C liwk O INTEGER; integer workspace required (optional)
C
C g. ERROR FLAG
C -------------
C
C mbsfl O INTEGER; error flag
C = 0 --> o.k.
C <> 0 --> error
C
C ----------------------------------------------------------------
C

20
4.3 Parameters: Rwork and Iwork
The arrays rwork and iwork serve two purposes:
 they provide workspace for the integrators, e.g. for storage of the mass matrix, the
constraint matrix and other quantities not communicated explicitly via the interface
 they contain parameters pertinent to the performance of the integrators
To guarantee a kind of standard integration mode, all these parameters have certain
default values that are used if the user does not want to make his own choice. In order
for these default values (which have been found to give a good average performance) to
be used, the user must initialize the relevant entries of the workspace arrays with zero
values in the routine calling the integrators (which will often be the main program).
In the following, we give a short description of the parameters that are passed through
rwork and iwork, so that the user can make his own adjustments as he deems suitable
(within limits, of course).
4.3.1 Control parameters passed via rwork.
A total of thirty elements of the array rwork are reserved for control parameters, only the
rst 14 of which are currently being used.
 rwork(1) = uround
This parameter represents the machine{dependent rounding unit for double pre-
cision variables and is used, e.g., to determine a limit for the minimum stepsize
allowed. This parameter must be in the range from 10 35 to 10 6 . The default
value for rwork(1) = 0.d0 is uround = 2.3d-16.
 rwork(2) = safe
This is the safety factor used when a new stepsize is calculated. The integrator mb-
sabm calculates a safety factor depending on the tolerances given. This parameter
must be in the range from 10 2 to 1. The default value for rwork(2) = 0.d0 is
safe = 0.9d0 for all integrators except mbshb3 where it is safe = 0.85d0.

 rwork(3) = fac1 and rwork(4) = fac2

These two parameters control the maximal decrease (fac1) and increase (fac2) in
stepsize. Thus, they must always satisfy 0 < fac1 < 1 < fac2, that is fac2 can
be made arbitrarily large and fac1 arbitrarily small. Changing these parameters
makes the stepsize prediction more conservative or more liberal. The default values
for rwork(3) = 0.d0 and rwork(4) = 0.d0 are as follows:
mbshb3 mbsdp5 mbsd85 mbsabm mbsext
fac1 0.2d0 0.333333d0 0.333333d0 0.5d0 0.02d0
fac2 10.d0 6.d0 6.d0 3.d0 4.d0

21
 rwork(5) = beta
beta is a further parameter for stabilization of the stepsize control in the Runge{
Kutta integrators. It is used for the so called Lund stabilization (see [11]). It
must not exceed the value of 0.2. The default value for rwork(5) = 0.d0 is beta
= 0.04d0. The user can turn o Lund stabilization by specifying a negative value
for rwork(5).
 rwork(6) = hmax
In setting
hmax the user can set an upper limit for the stepsize. A warning will be
printed if the stepsize is set greater than the length of the integration interval. By
default, i.e. for rwork(6) = 0.d0, hmax = ABS(tend-t).
 rwork(7) = hini
hini is a guess for the initial stepsize. If the user does not provide a value for hini
(i.e. a value of
0.d0 is passed in rwork(7)) the routine mbshin is used to produce a
rst stepsize guess automatically. However, sometimes this guess can be quite poor.
Thus, the user has the opportunity to provide a better guess, e.g. the value of hopt
(see below) from a previous run of that problem. Here, integration is halted if the
initial stepsize is set greater than the length of the integration interval.
 rwork(8) = hopt (output only)
The rst stepsize accepted by the integrator is stored in hopt and returned to the
user. Using this value for hini in a later run of the problem will ensure acceptance
of the rst integration step for the particular combination of tolerances given in
atol and rtol.

 special parameters for mbsext

{ rwork(9) = fac3 and rwork(10) = fac4
These parameters are used for order selection and must be less than or equal to
1. The default values for rwork(9) = 0.d0 and rwork(10) = 0.d0 are fac3
= 0.8d0 and fac4 = 0.9d0.
{ rwork(11) = safe1 and rwork(12) = safe2
These are safety factors for stepsize prediction which must be non{negative.
By default, i.e. for rwork(11) = 0.d0 and rwork(12) = 0.d0, these values
are safe1 = 0.6d0 and safe2 = 0.94d0.
 rwork(13) = protol
protol denotes the accuracy to which the user wants the constraints to be satised.
The integrators keep the norm of the position and velocity residuals below this
threshold by using projection, if necessary. The value of protol must be between
50*uround and 1. However, if 0.d0 is passed as the value for rwork(13), this is
interpreted as asking for as much accuracy as possible (internally set to 50*uround).

22
  rwork(14) = swttol
When using switching functions, swttol species the error tolerance for the local-
ization of event times. This value must again be greater than 50uround and a
value of rwork(14) = 0.d0 is interpreted as a request for this maximum possible
accuracy, so that swttol = 50*uround.
4.3.2 Control parameters passed via iwork.
A total of fty elements of the array iwork is reserved for control parameters, some of
which are currently unused. The latter are omitted in the following description.
 iwork(3) = nmax
With this parameter the user can specify the maximum number of steps that the
integrators are allowed to take. If nmax is exceeded, the integrators print an error
message and terminate. The default value for iwork(3) = 0 is nmax = 10000.
 iwork(4) = iprint
By means of the parameter iprint the user species the output channel. iwork(4)
should contain the le number of the error channel. The default value for iwork(4)
= 0 is iprint = 6, i.e. messages are output to the screen.

 iwork(5) = nstiff
A simple test for stiness of the model has been incorporated in the Runge{Kutta
integrators mbsdp5 and mbsd85. This test is invoked after every nstiff steps. If
nstiff is negative, the stiness test is never performed. The default value for
iwork(5) = 0 is nstiff = 1000.

 iwork(6) = iout
iout species the output mode that the integrator starts with. This parameter can
be changed after calls to mbssol, which is discussed in detail in a special section of
this documentation. The default value for iwork(6) = 0 is iout = 0, i.e. there is
no output during integration.
 iwork(7) = itol
For a description of itol, see the one on rtol and atol in the calling sequence of
the integrators above. The default for iwork 2= [0,1,2,3] is itol = 0, i.e. both
tolerances are assumed to be scalars.
 iwork(11) = lconmm
This parameter, if set to 1, indicates that the mass matrix of the model to be
simulated is constant over time. This fact can only be exploited by the range{space
method (methla = 1 or = 11, see below). For iwork(11) <> 1, we assume lconmm
= 0.

23
 iwork(12) = methla
MBSSIM provides a choice of four dierent linear algebra methods, each of which
has been implemented in two dierent ways. The rst implementation is for smaller
models and is based on blas (Basic Linear Algebra Subprograms) level 1 and
the linpack linear algebra solvers (browse netlib for more information on these
subroutines). The second implementation makes use of all three levels of the blas
and is based on lapack solvers, which makes them more ecient for larger problems
but, due to more overhead, less ecient for smaller ones. (Again, more information
on lapack can be found in netlib or in [2].) The possible choices are given in
following table:
iwork(12) = methla linpack lapack
null{space method 0 10
range{space method 1 11
rst Gauss method 2 12
second Gauss method 3 13
Any other choice will lead to termination of the simulation run and an error message
to that eect.
 iwork(13) = lnopro
If set to 1 this is the indicator for no projection. Normally, stabilization of the inte-
gration via projection is necessary to obtain physically meaningful results. Therefore
setting iwork(13) = 0, i.e. assigning lnopro the value zero, will result in better
performance. This indicator has been included for the purpose of numerical exper-
iments.
 iwork(14) = methpr
If so requested, the integrators will perform a sequential projection, rst on the
position level and then on the velocity level. This can be done using a least{squares
criterion formulated in the energy norm (methpr = 0) or in the usual Euclidean
metric (methpr = 1). For experimental purposes, it is also possible to choose a
mixture where on the position level the Euclidean norm is used, while the energy
norm is used on the velocity level (methpr = 2). Any other choice will again
terminate integration along with an appropriate error message.
 special parameters for mbsext
{ iwork(21) = maxcol
The maximum number of columns in the extrapolation tableau. The default
value for iwork(21) = 0 is maxcol = 9
{ iwork(22) = nseq
nseq species which stepsize sequence is to be used for the extrapolation. Not

24
 all the stepsize sequences can be combined with continuous output. Read
the section on mbssol for further details. The only possible values for nseq
are [1,..,5]. The default value for iwork(22) = 0 depends on whether the
interpolation formula will be needed (i.e. continuous output or switching point
localization has been requested by the user). If so, the default value is nseq =
4, if not, nseq = 1.
{ iwork(23) = mstab
This denes the maximum number of stability tests performed in one row of
the extrapolation tableau. The default for iwork(23) = 0 is mstab = 1.
{ iwork(24) = jstab
jstab species how many rows are tested for stability in the extrapolation
tableau. The default for iwork(24) = 0 is jstab = 1.
{ iwork(25) = dtest
dtest is a switch that turns the error control for the interpolation formula o
(dtest = 1), or on (
dtest = 0).
{ iwork(26) = mudiff
mudiffsets the degree of the interpolating polynomial. The default value for
iwork(26) = 0 is
mudiff = 4 . For further details see [9].
 integration statistics (output only)
Some entries in iwork are used to store various statistics accumulated during the
integration. Their meaning and location of storage is as follows:
{ iwork(31) = nstep # of steps
{ iwork(32) = naccpt # of accepted steps
{ iwork(33) = nrejct # of rejected steps
{ iwork(34) = nemat # of matrix evaluations
{ iwork(35) = nerhs # of righthand side evaluations
{ iwork(36) = nprp # of projections of positions
{ iwork(37) = nprv # of projections of velocities
{ iwork(38) = nswstp # of steps where switch occured
{ iwork(39) = nrduce # of reductions of uniform stepsize
The last one is used only in mbsabm, but all the others are updated in all integrators
in the package MBSSIM.
 iwork(41) = lswt
This is the indicator for the presence of switching functions, the zeroes of which are
to be localized during integration.
 iwork(42) = nswt
Ifiwork(41) = lswt is not 0, this denotes the number of switching functions to
be considered. For more information on these last two parameters, see the detailed
description of the user supplied subroutine mbsswt below.
25
5 User Dened Subroutines
5.1 Model Description
There is one subroutine that absolutely must be supplied by the user, namely mbsmod. In
this subroutine, the various parts needed to describe the model as given in the introduction
have to be programmed.
C -------------------------------------------------------------------
C
C CALLING SEQUENCE :
C ------------------
C
C SUBROUTINE MBSMOD(
C @ ns ,npos ,nvel ,nlam ,ngpos ,ldm ,ldg ,
C @ t ,s ,p ,v ,rlam ,
C @ MM ,GM ,f ,gam ,sdot ,pdot ,gpos ,
C @ gvel ,FM ,rpar ,ipar ,leqns ,mbsfl )
C
C INPUT PARAMETERS:
C -----------------
C
C ns I INTEGER; # of external dynamical variables
C npos I INTEGER; # of position variables
C nvel I INTEGER; # of velocity variables
C nlam I INTEGER; # of LAGRANGE multipliers
C ngpos I INTEGER; # of position constraints
C ldm I INTEGER; leading dimension of MM
C ldg I INTEGER; leading dimension of GM
C t I REAL*8; current time of integration
C s I REAL*8; current values of external
C dynamical variables
C p I REAL*8; current values of positions
C v I REAL*8; current values of velocities
C rlam I REAL*8; current values of LAGRANGE
C multipliers
C
C rpar I REAL*8; array for user parameters
C ipar I INTEGER; array for user parameters
C leqns I INTEGER; array of evaluation flags
C
C OUTPUT PARAMETERS:
C ------------------
C
C MM(ldm,*) O REAL*8; mass-matrix

26
C GM(ldg,*) O REAL*8; velocity constraint-matrix
C OR : position constraint Jacobian
C f(nvel) O REAL*8; forces f(t,p,v,lambda,s)
C gam(nlam) O REAL*8; right-hand-side of index 1 condition
C = -v^T*d/dt(G(t,p))-del^2/delt^2(g(t,p))
C sdot(ns) O REAL*8; derivative s'=h(t,p,v,lambda,s)
C pdot(npos) O REAL*8; derivative p'=T(t,p)*v
C gpos(ngpos) O REAL*8; position constraint residual g_p(t,p)
C gvel(nlam) O REAL*8; velocity constraint residual g_v(t,p)
C FM(ldm,*) O REAL*8; Jacobian matrix df/dlambda
C
C mbsfl O INTEGER; error flag
C = 0 --> o.k.
C <> 0 --> error
C
C ==============================================================
C === ACTION of MBSMOD according to flags <---> leqns(1..10) ===
C ==============================================================
C
C - leqns(1).NE.0 : mass matrix M(t,p)
C ===> MM
C - leqns(2).NE.0 : velocity constraint matrix G(t,p)
C ===> GM
C - leqns(3).NE.0 : forces f(t,p,v,lambda,s)
C ===> f
C - leqns(4).NE.0 : v^T*d/dt(G(t,p))+del^2/delt^2(g(t,p))
C ===> gam
C - leqns(5).NE.0 : derivative s'=h(t,p,v,lambda,s)
C ===> sdot
C - leqns(6).NE.0 : derivative p'=T(t,p)*v
C ===> pdot
C - leqns(7).NE.0 : position constraint residual g_p(t,p)
C ===> gpos
C - leqns(8).NE.0 : velocity constraint residual g_v(t,p)
C ===> gvel
C - leqns(9).NE.0 : position constraint Jacobian
C dg/dp(t,p) * T(t,p)
C ===> GM
C - leqns(10).NE.0 : Jacobian matrix df/dlambda
C ===> FM
C
C -------------------------------------------------------------------

27
 Remarks.
 It is essential to take the leading dimensions for the matrices MM,GM (and FM, if used)
into account when programming the model subroutine.
 The above interface has been chosen so as to allow more features in future versions
of MBSSIM. At the present time, the model is assumed to be in standard form ,
i.e. we assume that we have
{ npos = nvel
{ ngpos = nlam
{ T (t; p)  I , i.e. the identity matrix
{ g(t; p)  g(p)
{ f (t; p; v; ; s)  f (t; p; v)
 Presently, there are three types of calls to mbsmod:
1. index one call
In this call, the parts needed for the index one equations (together with
the external dynamical variables, if present) are requested by the integrator
(leqns(1,...,6) = 1, leqns(7,...,10) = 0). On occasion, this call may
be split , i.e. the system matrices and the force terms may be requested in two
separate calls.
2. position constraint call
Here only leqns(7) = 1, and the position constraint residual g(p) communi-
cated via gpos is requested.
3. velocity constraint call
In this case only leqns(8) = 1, and the velocity constraint residual G(p) v
communicated via gvel is requested.
!Warning! The user might wish to specify the velocity constraint by recalculating the
constraint matrix and multiplying it with the velocity values supplied by the integrator.
In this case, however, it is essential that extra storage be allocated for the constraint
matrix . Since the storage provided by the integrator contains decomposition information
that is still needed for the actual projection step, GM must not be overwritten in the
velocity constraint call. As an example, see the le qckmod.f providing the model for a
quick{return mechanism (for the mechanism's description see, e.g., [19],[12]).

5.2 Output Routine

An essential feature of modern integration routines, namely so called continuous (or dense)
output , is also included in MBSSIM. This can be used for both post{processing of data

28
generated in a simulation run as well as on{line animation. If the user does request
output during integration (by setting iwork(6) = iout = 1,2 or 3 (see above)), he has
to supply a subroutine of the following form:
C -------------------------------------------------------------------
C
C CALLING SEQUENCE :
C ------------------
C
C SUBROUTINE MBSSOL(
C @ naccpt,rpar ,ipar ,tout ,
C @ sout ,ns ,
C @ pout ,npos ,
C @ vout ,nvel ,iprmpt)
C
C INPUT PARAMETERS:
C -----------------
C
C naccpt I INTEGER; # of steps accepted so far
C rpar(*) I REAL*8; USER defined array
C ipar(*) I INTEGER; USER defined array
C tout I REAL*8; current (guess for) event time
C sout I REAL*8; s-value at tout
C ns I INTEGER; # of external dynamics variables
C pout I REAL*8; p-value at tout
C npos I INTEGER; # of position variables
C vout I REAL*8; v-value at tout
C nvel I INTEGER; # of velocity variables
C iprmpt I INTEGER; task indicator
C
C OUTPUT PARAMETERS:
C ------------------
C
C iprmpt O INTEGER; indicator for termination
C or change of output mode
C
C -------------------------------------------------------------------

!Warning! The solution variables sout, pout , and vout should be referenced only and
not changed during the call.
5.2.1 The prompt ag
To control the output supplied by the integrator, the prompt iprmpt is part of the interface
of the subroutine mbssol. It tells the user in each call for what purpose the integrator is
calling mbssol, thus helping him decide what to do with the information that is passed:
29
  iprmpt = 0 : initialization call
 iprmpt = 1 : communication point call
in this call the user has to supply a new communication point via tout!

 iprmpt = 2 : integration point call

 iprmpt = 3 : call before g{stop reinitialization

 iprmpt = 4 : call after g{stop reinitialization

 iprmpt = 5 : nal call (at t = tend)

On the other hand, the user can in uence the output of the integrator by changing the
value of iprmpt upon leaving the subroutine mbsswt:
 iprmpt < 0 : terminate integration
 iprmpt = 10 : cut o output entirely (iout = 0)
 iprmpt = 11 : switch to dense output (iout = 1)
 iprmpt = 12 : switch to step output (iout = 2)
 iprmpt = 13 : switch to mixed output (iout = 3)
For better understanding, the output modes of the integrators are described in greater
detail.
5.2.2 The output modes of the integrators
There are 4 output modes incorporated into MBSSIM (or 5, if you count a special mode
of the integrator mbsext). The variable iout is used to denote the output mode the
integrators are currently in.
1. iout = 0 : no output
In this mode there is no output at all. The integrator merely returns the nal values
to the calling program via the integrator interface.
2. iout = 1 : continuous output
In this mode the user can control output freely. When a communication point
(specied by the user on a previous call to mbssol) is reached, the integrator calls
mbssol with iprmpt = 1 and supplies the values of the dynamical variables at
this communication point. The user then species a new communication point via
tout. To obtain the rst communication point, the integrator calls the subroutine
mbssol before starting the actual integration. This call is marked by iprmpt = 0
(see below).
30
 3. iout = 2 : step output
In this mode the integrator calls mbssol after each successful step. The value of
iprmpt on these calls is 2 to distinguish them from the calls for continuous output.
The integrator passes the values of the dynamical variables at the current point
reached in integration.
4. iout = 3 : mixed output
The mixed output mode combines the modes iout = 1 and iout = 2 to form one
universal output mode. The calls are done with iprmpt =1 and iprmpt = 2 respec-
tively.
5. iout = 4 : step output only (solely for mbsext)
The need for this special mode is due to the fact that continuous output is only
possible with mbsext, if stepsize sequences with iwork(22) = nseq > 3 are used.
In choosing iout = 4 from the very beginning, the user restricts himself to demand
only step output and can thus choose freely amongst the stepsize sequences.

5.2.3 Output control

Initialization call. If the user has requested some kind of output during integration by
assigning iwork(6) = iout a value of either 1, 2 or 3, there will rst be an initialization
call for the routine mbssol. This call has two purposes:
 to signal the user the need to open output channels and (possibly) initialize graphics
 for iout = 1 or iout = 3, the user must provide the rst communication point
For example, it is possible to store the values for t and tend in rpar and a given number
of steps in ipar, pass them to mbssol and thus calculate the output points to be equally
distributed over the integration interval.
Switch of output mode. As long as the integrator is in one of the modes iout = 1,
2 or 3, it is possible to switch to another output mode or even to terminate integration
as described above. Note, however, that when switching to dense or mixed output, the
rst communication point must be specied via tout.
!Warning! Switching to iout = 0 turns the output o entirely and there will be no
further calls to mbssol. If the user decides to do so, all output les, etc. should be closed,
as there will be no nal call after the end of integration once the integrator is in output
mode 0 !

Sample output routines. Sample output routines are supplied along with the ex-
amples that show how the data supplied by the integrators during integration can be
processed. In these sample routines, output is into les which can subsequently be used

31
for visualization, e.g. with the public domain plotting tool gnuplot. A further example
(sqzani) is for on{line animation using GL (tested on Silicon Graphics and IBM RS6000).
Output in discontinuous models. If the model includes g{stops, i.e. model discon-
tinuities demanding reinitialization at possibly state{dependent time points described by
switching functions (see the section on mbsswt below), there are two more calls from the
integrators to the function mbssol. These calls will be made regardless of the output
mode chosen, as long as some output has been requested. This is to ensure that the last
integration value before the g{stop and the rst value after the reinitialization are given
to the output routine. Note, that in models with jump discontinuities, these points can
be dierent from each other. The calls to mbssol are made with iprmpt = 3 and iprmpt
= 4 respectively.

Final call. The nal call to mbssol with iprmpt = 5 signals the fact that the end of
the integration interval has been reached and the user can, e.g., close output les.
5.2.4 Sample Output
Using the continuous output facility and the plotting tool gnuplot, we have
plotted the trajectories for the example gelenk for a simulation time of 60 ms .
50 1.4
p(1) p(3)
40 p(2) 1.2 p(4)
p(5)
30 1 p(6)
p(7)
20 0.8

10 0.6

0 0.4

-10 0.2

-20 0

-30 -0.2

-40 -0.4

-50 -0.6
0 0.01 0.02 0.03 0.04 0.05 0.06 0 0.01 0.02 0.03 0.04 0.05 0.06

5.3 Switching Point Localization Routine

Specifying switching functions and detecting discontinuities in models by localizing the
zeroes of those switching functions presents a mathematically correct way of treating
those discontinuities numerically. This is because numerical integration methods only
work correctly if there is a certain degree of smoothness in the equations to be solved, at
least when taking one single step . This approach also oers the chance to obtain error-
controlled results, if the interpolation routines of the integrators are natural. Also, it is
usually much faster and more ecient than hoping for the integrators to stumble, but not
trip over discontinuities ([6],[17]). Furthermore, if there are jump discontinuities in the

32
model, model validation is impossible without localizing the exact time of occurrence of
the discontinuity.
5.3.1 State{Event Finder (SEF)
For these reasons, all the integrators in MBSSIM have a SEF built in. This is an imple-
mentation of the safeguarded root nding algorithm described in [6] and it will search for
the roots of the switching functions iteratively . The switching functions themselves are
assumed to be of the form
q(t; s; s_; p; p;_ v; v_ ) = 0 :
Although by evaluating the parts of the model equations and solving the resulting linear
system, one could equivalently consider
q(t; s; p; v) = 0 :
This would mean that the user would have to call the linear solvers himself. Also, the
integrator mbsabm not only provides an interpolated solution, but also an interpolation
for the derivatives, so that there is no need for an extra model evaluation in this case.
5.3.2 User routine
Thus, the subroutine for specifying the switching functions has the following form:
C -------------------------------------------------------------------
C
C CALLING SEQUENCE :
C ------------------
C
C SUBROUTINE MBSSWT(
C @ naccpt,rpar ,ipar ,tswt ,
C @ sswt ,dsswt ,ns ,
C @ pswt ,dpswt ,npos ,
C @ vswt ,dvswt ,nvel ,
C @ iswt ,swt ,nswt ,nswsta,iprmpt )
C
C INPUT PARAMETERS:
C -----------------
C
C naccpt I INTEGER; # of steps accepted so far
C rpar(*) I REAL*8; USER defined array
C ipar(*) I INTEGER; USER defined array
C tswt I REAL*8; current (guess for) event time
C sswt I REAL*8; s-value at tswt
C dsswt I REAL*8; sdot-value at tswt

33
C ns I INTEGER; # of external dynamics variables
C pswt I REAL*8; p-value at tswt
C dpswt I REAL*8; pdot-value at tswt
C npos I INTEGER; # of position variables
C vswt I REAL*8; v-value at tswt
C dvswt I REAL*8; vdot-value at tswt
C nvel I INTEGER; # of velocity variables
C iswt I INTEGER; index of switching function to be
C evaluated
C nswt I INTEGER; # of switching functions specified
C nswsta(*) I INTEGER; statistics for iteration of root finder
C
C * nswsta(1) = nbis : # of bisection steps
C * nswsta(2) = ncls : # of closeness steps
C * nswsta(3) = nfst : # of fast steps
C * nswsta(4) = nits : # of iterations
C
C iprmpt I INTEGER; task indicator
C
C OUTPUT PARAMETERS:
C ------------------
C
C swt O REAL*8; array of value(s) of the switching
C function(s)
C iprmpt O INTEGER; g-stop or termination indicator
C
C -------------------------------------------------------------------

5.3.3 The prompt ag

As in mbssol, the prompt iprmpt is used for communication between the integrator and
the user routine mbsswt.
As input to mbsswt.
In order to work properly in connection with the integrators in MBSSIM, the subroutine
mbsswt reacts on every call according to the values of the parameters iprmpt and iswt
in the following way:
 Initialization call (iprmpt=0).
As in the case of mbssol this call gives the user the opportunity to make prepara-
tions like opening output channels, reading parameters and so on. However, here
the integrators also expect a rst evaluation of all switching functions.
 Evaluation call (iprmpt<0).
The user has to supply the actual values for one or all of the switching functions
34
 and store them in the array swt. Communication about the switching functions to
be evaluated is via iswt:
{ iswt>nswt ! evaluate all switching functions
{ iswt<=nswt ! evaluate only switching function with index iswt
 Output call (iprmpt=1).
The user is given the switching point for one of the switching functions. The values
are again stored in tswt, sswt ,pswt and vswt, the number of the function where
the switch has occurred is given by the value of iswt. Now the user has to decide
whether or not he wants this point to be marked for reinitialization of the integrator.
Reinitialization is necessary if the root of the switching function signals a model
discontinuity (jump etc.), i.e. if a so called g{stop condition holds. To tell the
integrator this, the user must set iprmpt = 1 (see below). This way simulation of
discontinuous or non-dierentiable models with error control is possible.
If more than one g{stop occurs in a single step, the integrator reinitializes the
integration at the rst time instant marked as a g{stop.
 Reinitialization call (iprmpt=3).
If a g{stop has been marked, the integrator calls mbsswt again just before it restarts
the integration at the g{stop instant. At this point the user can change some of
the variables in order to incorporate jumps into the simulation. Furthermore, the
array swt might have to be reinitialized, as there is no further call to recalculate the
switching functions!
 Final call (iprmpt=5).
At the end of the prescribed integration interval, i.e. for t = tend, there is a nal
call to mbsswt, as in the case of mbssol, to give the user the chance to close output
les and to perform other clean{up tasks.
As output from mbsswt.
On some occasions, the integrator checks whether there is some special request by the
user, such as g{stops. The user should set iprmpt as follows to communicate his wishes
to the integrator:
 iprmpt = 0
This is the general case. If the user does not want to indicate a g{stop or a request
to terminate the integration, then, to be on the safe side, he should set iprmpt =
0 upon leaving mbsswt, lest unwanted eects happen.

 iprmpt = 7
Settingiprmpt = 7 only makes sense after a reinitialization call (where iprmpt =

35
 3 ) and indicates that the model equations have to be reevaluated upon reinitializa-
tion. This is always the case in the presence of jump discontinuities, but may be
necessary for non{dierentiable eects as well.
 iprmpt = -1
This indicates a possible g{stop and is only checked after an output call to mbsswt
with iprmpt = 1, i.e. after a root of a switching function has been successfully
localized.
 iprmpt = -2
This indicates the user's wish to terminate integration and is also only checked after
a call to mbsswt with iprmpt = 1.
Some nal advice:
 If your model does not include discontinuous eects and you do not want any other
events monitored either (i.e. if you do not want to use switching functions) use
the dummy routine dumswt for mbsswt supplied in the directory sp mbs as the
argument in the call to the integrator.
 Recall that the integrators will only call the SEF, if the iwork parameter iwork(41)
= lswt has been properly set:
{ lswt = 0: no switching functions
{ lswt = 1: with switching functions

Also take care to set the number of switching functions, i.e. iwork(42) = nswt,
correctly.
 Also recall that the rworkspace parameter rwork(14) = swttol is used to pass the
relative tolerance used to locate the event instances to the integrator.
 The statistics of the last switching point iteration can be read o the array nswsta
at the output call to mbsswt. The meaning of the various entries is described in
the subsection on the calling sequence of mbsswt.
 !Warning!: As with all other subroutines the user is strongly advised not to change
any of the variables except the ones he is told to recalculate. Such changes are
normally not checked by the integrators and errors in further calculation might be
caused by this.
 !Warning!: The large steps that mbsext takes mean that it is not well{suited for
models with switching points, since the large stepsize raises the probability of missing
sign changes in switching functions. That is, there may easily be two sign changes
in the same switching function rather close together, which might go unnoticed.

36
5.3.4 Coding your own mbsswt
Programming the subroutine mbsswt for the treatment of model discontinuities is not
as easy and \straightforward" as \handling" them by means of IF{statements in the
subroutine mbsmod alone. When using switching functions to distinguish between the
various models corresponding to the modes the system can possibly be in (described by the
sign of a switching function or combinations of signs of more than one switching function),
there must be a way of communicating the current mode from mbsswt to mbsmod, and
this also has to be programmed. However, although coding the subroutine mbsswt is
at rst quite a dicult task, it presents a way to cope with discontinuous eects in a
mathematically correct fashion which also allows for optimization problems to be treated.
Thus, this coding is well worth the eort. In order to (hopefully!) make things a little bit
easier, we will describe some basic rules as to how the task can be accomplished. This is
best done by looking in some detail at one of our examples, namely the toy woodpecker in
the directory spielz, and how we coded the corresponding subroutine spiswt.
Model description. The model spielz is of a toy woodpecker as described in [6]. This
model has jump discontinuities in the angular velocity due to non-elastic impact.
20
phase curve
15 switches

10

thd 0

-5

-10

-15

-20
-0.15 -0.1 -0.05 0 0.05 0.1 0.15 0.2 0.25 0.3 0.35
th

model of toy woodpecker Phase{Plot with switching points

As one can see from the picture, the spring is connected to a socket. The initial conditions
are such that the socket is blocked on the pole and thus can not slide down. The motion
can be divided into the following phases:
  > 1
The woodpecker swings clockwise, turns and swings back counterclockwise until it
reaches the critical angle 1.
 1 <  < 1
When it reaches this angle, the socket unblocks and starts sliding down the pole.
The woodpecker swings further to the left and blocks the socket again as it reaches
the opposite critical angle 1 on the other side.

37
  2 <  < 1
The spring swings a little more to the left until the beak hits the pole as the angle
reaches 2.
 2 <  < 1
After hitting the pole, the woodpecker swings back to the right. At the angle 1
the socket unblocks.
 1 <  < 1
The socket slides down the pole again as the woodpecker continues swinging to the
right. At the angle 1 the socket is blocked again.
As the socket is again blocked, the woodpecker starts another cycle, now sitting a little
lower than before.
For the blocked and unblocked phase two dierent sets of equations of motion are used,
model 1 and model 2. In the equations of motion,  denotes the angle of the spring while
z denotes the vertical positon of the socket on the pole.
Model 1: only one degree of freedom (), z = const:
 + I +cm b2 = I m 2 bg
2 2 2 + m2b2
z_ = 0
Model 2: two degrees of freedom
 + I + m b2(1c m2 )  = 0
2 2 m1 +m2
z + m2 b = g
m1 + m2
The impact of the socket and the beak at the pole are modelled as non{elastic impacts
causing jumps in the angular velocity _. These jumps are given by the following equations:
 Upper socket impact
_+ = (1 d3)(_ + I +mm 2 b z_ )
2 2 b2
 Lower socket impact
_+ = (1 d1)(_ + I +mm 2 b z_ )
2 2 b2
 Beak hitting the pole:
_+ = _
where _ and z_ are the velocities before the impact, _+ and z_+ are the velocities after
the impact and d1 and d3 are impact constants.
38
Transformation into code. To summarize the important points, there are two dier-
ent sets of equations of motion (or models) that are valid according to which mode the
system is currently in. This in turn depends on certain critical values of the model vari-
able , which can be conveniently monitored by checking the roots of certain switching
functions. Thus, we have to answer the following questions and turn the answers into
code:
 What are the modes in the model ?
According to the above description the motion of the woodpecker can be divided up
into ve phases, where imode indicates the mode the system is in and imodl stands
for one of the two dierent models (i.e. one of the two sets of equations of motion
depending on whether the socket is blocked or not):
1. imode = 1 , imodl = 1
The woodpecker swings to the right and turns back because of the force of the
spring. The socket is blocked.
2. imode = 2 , imodl = 2
The socket is unblocked. The woodpecker still swings to the left.
3. imode = 3 , imodl = 1
The socket is again blocked. The woodpecker swings towards the pole.
4. imode = 4 , imodl = 1
After hitting the pole, the woodpecker starts swinging to the right while the
socket is still blocked.
5. imode = 5 , imodl = 2
The socket is unblocked. The woodpecker continues swinging to the right.
 What are the switching functions?
It is essential to analyze in detail the kind of eects that will in uence the behavior
of the system to be simulated, in order to get the proper switching structure in
mbsswt. In the model spielz, we use 4 switching functions to distinguish between
the 5 modes.
1. swt(1) = p(1)-theta1
This switching function has a root as the rst position coordinate, denoting
the angle  passes the critical angle 1 where the socket blocks/unblocks. This
switching function separates the modes 1 and 2 and the modes 5 and 1.
2. swt(2) = p(1)+theta1
Here we have a root as  reaches the opposite critical angle 1 where the socket
blocks/unblocks on the left hand side. This switching function separates the
modes 2 and 3 and the modes 4 and 5.

39
 3. swt(3) = p(1)+theta2
This function changes sign as the woodpecker's beak hits the pole at the angle
2. This switching function separates the modes 3 and 4.
4. swt(4) = v(1)
This switching function only keeps track of the sign of the angular velocity
_. It is used to determine the right turning point of the woodpecker. It is an
example for an event where no g{stop takes place and thus no reinitialization
of integration is needed.
From the discussion of our model, we know that during simulation, only changes
from mode i to mode i + 1; i = 1; 2; 3; 4 and from mode 5 to mode 1 can occur.
This point must be kept in mind when coding the switching structure.
The switching functions have to be evaluated at a call with iprmpt <= 0. De-
pending on the value of iswt, spiswt has to reevaluate one or all of the switching
functions (see the previous chapter for details). Furthermore, at each g{stop the
switching functions have to be reevaluated. Because of this, we code them twice in
our subroutine.
 What actions are to be taken as the mode changes ?
The rst thing one has to consider is how to communicate which mode the model
is currently in to the relevant subroutines mbsswt and mbsmod. This is a typical
application for the user dened parameter array ipar.
In the present model, we use two entries in the array ipar to store the mode
(ipar(1)) and the model index (ipar(2)). The initialization depends on the initial
values. As stated before, our model starts in mode 1 with model 1, so we initialize
ipar accordingly via the subroutine spipar, which is called by the main program
mbsmai before the start of the integration. The subroutine spimod reads the value
of imode from the parameter array ipar and thus always uses the appropriate model.
After the initialization, all further changes in both the model and the mode have to
be prompted by spiswt.
{ As the mode changes from 1 to 2, the model index has to be changed, since
the socket is then no longer blocked (ipar(2) = imodl = 2).
{ As the mode changes from 2 to 3, the socket hits the pole. This causes a jump
in the velocity variables, which are changed according to the formulae given
above. The model index is also changed since the socket is now blocked again
(ipar(2) = imodl = 1).
{ As the mode changes from 3 to 4, the beak hits the pole and the sign of the
angular velocity has to be reversed.
{ As the mode changes from 4 to 5, the socket unblocks and the model changes
again (ipar(2) = imodl = 2).
40
 { Finally, as the mode changes from 5 back to 1, the conservation law of impulses
is used once again to calculate the jump in the velocities. The model changes
back as the socket blocks (ipar(2) = imodl = 1).
All these transitions must be checked and carried out in the call to spiswt with
iprmpt = 3. After that, the switching functions are reevaluated and the control goes
back to the integrator with iprmpt = 7, signalling for the integrator to reevaluate
the model equations at the beginning of the new integration interval.
 Marking switching points for g{stopping
The most crucial part in coding mbsswt is the reaction to an output{call (where
iprmpt = 1). Such a call indicates that the integrator has found a switching point.
To save the values of all switching points, we open the output le spielz.swt at
the initialization call (where iprmpt = 0) and write the switching points to this
le. It is a good idea to save the statistics of the iterations (passed in nswsta) too,
as they can be a valuable source of information if something goes wrong with the
switching functions.
After that, one has to decide whether one wants to reinitialize the integration (g{
stopping). This decision is made based on the switching structure described above,
which has to be appropriately coded. If the conditions for a g{stop are met, spiswt
indicates this to the integrator by setting iprmpt = -1.
Remark. It is very important for the coding of mbsswt to understand the dierence
between the output call and the reinitialization call. In the former a possible g{stop
is marked for stopping, while in the latter all actions at an actual g{stop are taken.
For the above example of the toy woodpecker, the le recording the g{stops local-
ized looks as follows (for a simulation time of 0:5s):

#
# g-stops found during simulation
#
# MODE ISWT TIME THETA THETADOT
#
1 1 .057971080 .100000000 -12.000000000
2 2 .072445952 -.100000000 -12.000000000
3 3 .073494911 -.106000000 -5.338675177
4 2 .074543870 -.100000000 6.097812826
5 1 .096775540 .100000000 6.097812826
1 1 .154746622 .100000000 -11.999991481
2 2 .169221503 -.100000000 -11.999991481
3 3 .170270463 -.106000000 -5.338662613
4 2 .171319424 -.100000000 6.097801826
5 1 .193551115 .100000000 6.097801826

41
 1 1 .251522197 .100000000 -11.999988782
2 2 .265997080 -.100000000 -11.999988782
3 3 .267046042 -.106000000 -5.338658633
4 2 .268095003 -.100000000 6.097798342
5 1 .290326700 .100000000 6.097798342
1 1 .348297783 .100000000 -11.999987927
2 2 .362772666 -.100000000 -11.999987927
3 3 .363821628 -.106000000 -5.338657372
4 2 .364870590 -.100000000 6.097797238
5 1 .387102289 .100000000 6.097797238
1 1 .445073371 .100000000 -11.999987656
2 2 .459548255 -.100000000 -11.999987656
3 3 .460597217 -.106000000 -5.338656973
4 2 .461646179 -.100000000 6.097796888
5 1 .483877878 .100000000 6.097796888

Note that the roots of the fourth switching function do not appear in this le, since
they do not indicate a g{stop. If requested, however, these roots could also be
recorded (and, in fact, we have done so in a second le not shown here).
 Questions and Answers
There are two questions arising from this description of how to code spiswt in
particular and mbsswt in general:
1. Why is there a separate reinitialization call at each g{stop ? Could this not be
replaced by the output call?
2. Where do the diculties in coding the switching structure come from?
The answers are the following:
1. The output call is done in a loop where all the switching functions are checked
for roots. If more than one switching function changes sign in the same in-
tegration step, the model changes at the g{stop event that occurs earliest.
Through this change, the integration process is altered, perhaps leading to a
completely dierent solution, that might not even reach the second g{stop. By
marking a sign change as a possible g{stop, the user allows the integrator to
search for other switching functions which change sign and thus localize the
rst such change. After checking all switching functions, the integrator chooses
amongst the switching points marked and stops at the rst one. After calling
mbssol for output, the integrator calls mbsswt again with iprmpt = 3 in
order to perform the actual g{stopping by asking it to provide the necessary
information.
2. The SEF in MBSSIM has been designed in a way that tries to ensure that
at a g{stop point, the sign change in the switching function in question has
42
 actually taken place. However, numerical diculties may result in an inexact
localization of the g{stop points, necessitating a remedy from the user. For
example, in the woodpecker model, mode 5 waits for swt(1) to switch. When
this happens, the mode is switched to 1 and after this the model again (!) waits
for swt(1) to transit to mode 2.
If the rst of these two g{stop events is not localized exactly, the function
swt(1) may not have changed sign at the g{stop point localized by the inte-
grator. The function value may be of magnitude 10 15 , but it has not actually
changed its sign. In the next integration step, the integrator again localizes
the same point, as it only reacts to a change of signs in the switching functions
between beginning and end of the integration interval. Such double localization
of the same g{stop can cause serious trouble in simulation.
In the example of the toy woodpecker, we solved this problem by also taking
into account the sign of the angular velocity: The switch from 1 to 2 is only
performed if the angular velocity _ in the woodpecker model is negative. Thus,
the two neighboring decisions that formerly depended on the sign of the same
switching function are now cleanly separated.
This sample coding of a switching structure together with the dummy switching{routine
dumswt in the directory dummyy (which can be completed in order to obtain a switching
routine corresponding to one's needs) should put the user in a position to make use of the
opportunities for a correct treatment of discontinuous in multibody models with the help
of MBSSIM.

6 Coding new models

In order to make the package useful for simulating one's own models, we have supplied a
variety of templates which can be lled in, thus providing a basis for the coding of new
models. This section gives an introduction on how to implement new models and how
to make use of said templates by describing the implementation of the model spielz as
it was done using the structure of the template model dummyy. In the following we
describe the necessary steps:
1. The rst step towards implementing a new model is to make a new directory to
store all the model-dependent information. The directory for spielz sits directly
below the main directory.
2. To this directory we copied the les dumrun, dumini and dumlsg and replaced
the rst three letters dum by spi.
 spirun can be left unchanged as the control le xxxrun is independent of the
model.

43
  spiini holds all information necessary for one simulation run. The parameters
such as dimensions and the time interval have to be changed to the appropri-
ate values for the model. The lines beginning with a '#' are skipped when the
main subroutine mbsmai reads this initial le. Nevertheless, mbsmai needs
them exactly as supplied in the templates in order to work properly. After the
headers for positions, etc., one has to supply the initial values for the problem,
one on each line. The initial values for the accelerations and Lagrange mul-
tipliers are not used for starting the integration { at least not in this version of
MBSSIM, which cannot yet treat phenomena such as dry friction. They have
to be supplied, though, if mbsmai is to be used, but dummy values will suce.
 spilsg holds reference values for all the variables together with relative errors
in much the same way as spiini holds initial values. Reference solution value
and error are grouped together in one line. Separation lines again must have
the structure of the template to be readable by mbsmai. If one doesn't have
reference values, supplying dummy values and tolerances is ne; note, however,
that in this case the accuracy of the solution cannot be calculated and hence the
corresponding values in the standard output will have absolutely no meaning.
3. The crucial part of the implementation is how to code the model. The user has
to supply the subroutine xxxmod which calculates the model parts such as mass
matrix and constraint residual. How this is done in detail can be seen from the
various models of the examples. The template dummod gives a rough structure
of how this subroutine can be organized. Note, however, that it may be useful to
combine some of the calculations in order to exploit common subexpressions in one
call to the subroutine. Most of the time in a simulation run is spent on evaluating
the model parts and solving the linear systems. Thus, coding the model subroutine
in an ecient way will help to save time during simulation.
4. Together with spimod, we program the subroutine spipar (also in the le spimod).
This subroutine is called to initialize parameters for the model prior to the start
of the integration. These parameters can be stored in the parameter vectors rpar
and ipar which are passed through all of the integrators untouched. We use these
parameters to set constants such as the gravitational constant, to communicate the
gridsize for continuous output (see spisol), to set the identication number for the
model (ipar(2)) and most importantly to change between dierent models in our
formulation due to g{stops localized in spiswt.
5. To have a short descriptive name of the model included in the output of mbsmai,
one can add a line to the subroutine proble located in the le mbszus in the
directory sp mbs. There it is assumed that the model number is stored in ipar(2)
and has been set in the subroutine xxxpar in the le xxxmod (see above).
We have already used model numbers 1 to 11 for our examples and given each model
a short title. If you only set the model number ipar(2) in the subroutine xxxpar,
44
 you will get '???' in the relevant line of the output from mbsmai, indicating that no
title is available for your model. However, if you have augmented proble properly
(and also recompiled it by typing make in sp mbs! ), your own title will appear in
the output.
6. The subroutine spiswt has to supply the values for the switching functions (if
any), handle the g{stops and store the events localized by the integrator. The exact
structure necessary has been described in the section on mbsswt, but again we
supply a template which can be lled in appropriately. For our model we copy
dumswt to our directory spielz, rename it to spiswt and code the switching
functions and the structure of the switching modes corresponding to our model.
7. The requirements for the subroutine spisol are also described in the section on the
user{dened subroutines. To make use of dumsol we copy it to the model directory,
rename it to spisol, rename the output lename in the code from DUMerg to SPIerg
and rewrite the write{ and format{statements according to the variables we want
to record in our output le.
8. All these changes aect the makefile and the driver le. We copy the driver le
dummain to our model directory, rename it to spimain and change all references
in the code made to dum... to spi.... The makefile has to be copied and adapted
as well. The variable lok obj has to be changed from the dum{les to spi{les
and we also change the name of the executable from dummyy to spielz. The same
modications take place in the clean section and in the variable mod obj.
9. Now we can nally compile our new model. The command make program makes
the executable called spielz.
Some troubleshooting now that our model should be ready to work:
 Remember to switch o the switching routine via the variable lswt in the xxxrun{
le if there are no switching functions in the model. Otherwise, you might experience
mysterious things with the integrator library MBSSIM.
 If you run into trouble because the makefile cannot nd some of the subroutines,
check to see if you renamed not only the les, but also the subroutines in them!
 If the program prints some warnings about wrong data formats, you should carefully
doublecheck the structure of the option le xxxrun and the data les xxxini and
xxxlsg. It is best to compare them to data les from one of our examples.
Some nal comments. The template main program mbsmai is by no means a general
purpose main program for all possible models. We do think, however, that together with
the examples, it presents a good introduction to what you can do with MBSSIM.
The introduction you are reading at the moment is not meant as an introduction to the
45
simulation of multibody systems (in index{reduced descriptor form). Its sole purpose
is to give a user, who is familiar with this modelling, easy access to using the package.
For further questions on modelling we recommend the standard literature on multibody
systems, e.g. [16], [12], or [7].
Acknowledgements. The authors would like to take the opportunity to thank Professor
Ernst Hairer for his kindness in answering various questions on numerical integration.
Also, his ODE-codes have provided a splendid basis for some of the integrators in MBSSIM
and many of his ideas (as described in [10] and [11]) have been incorporated within the
library.
Also, thanks are due to Dr. Bernd Simeon for supplying a FORTRAN routine with the
equations of motion for the ve{link suspension.
Furthermore, the authors are grateful to their colleague Ray Spiteri for proofreading
this guide.

References
[1] T. Alishenas. Zur numerischen Behandlung, Stabilisierung durch Projektion und
Modellierung mechanischer Systeme mit Nebenbedingungen und Invarianten, Dis-
sertation, Institut fur numerische Analysis und Informatik, Konigliche Technische
Hochschule, Stockholm, Schweden, 1992
[2] E. Anderson et al. LAPACK User's Guide, SIAM, Philadelphia, 1992
[3] G. C. Andrews. The vector-network model: A topological approach to mechanics,
Dissertation, University of Waterloo, Waterloo, Canada, 1971
[4] T. Andrzejewski, H. G. Bock, E. Eich, and R. von Schwerin. Recent Ad-
vances in the Numerical Integration of Multibody Systems. In W. Schiehlen, ed.:
Advanced Multibody System Dynamics { Simulation and Software Tools, pages 127{
151, Dordrecht, NL, 1993. Kluwer Academic Publishers.
[5] H. G. Bock and R. von Schwerin. An Adams Method for Complex Systems of
Nonlinear Dierential-Algebraic Equations with State Dependent Events, Preprint of
SFB 359, University of Heidelberg, 1994, in preparation
[6] E. Eich. Projizierende Mehrschrittverfahren zur numerischen Losung von Bewe-
gungsgleichungen technischer Mehrkorpersysteme mit Zwangsbedingungen und Un-
stetigkeiten, Dissertation, Universitat Augsburg, Augsburg, 1991.
[7] J. Garcia de Jalon and E. Bayo. Kinematic and Dynamic Simulation of Multi-
body Systems | The Real Time Challenge, Springer Verlag, New York, 1993

46
 [8] F. Grupp and B. Simeon. Description of the ve-link suspension benchmark prob-
lem, private communication, 1993
[9] E. Hairer and A. Ostermann. Dense output for extrapolation methods, Numer.
Math., Vol.58, p.419-439, 1990
[10] E. Hairer, S. P. Nrsett, G. Wanner. Solving Ordinary Dierential Equations
I, 2.ed, Springer Verlag, Heidelberg, 1993
[11] E. Hairer, G. Wanner. Solving Ordinary Dierential Equations II, Springer
Verlag, Heidelberg, 1991
[12] E. J. Haug. Computer Aided Kinematics and Dynamics of Mechanical Systems,
volume I: Basic Methods, Allyn and Bacon, 160 Gould Street, Needham Heights,
Massachusetts 02194, 1989.
[13] Ch. Lubich, U. Nowak, U. Pohle, Ch. Engstler. MEXX | Numerical Soft-
ware for the Integration of Constrained Mechanical Multibody Systems, Preprint SC
92{12, ZIB Berlin, 1992
 angen, Ingenieurarchiv 54,
[14] F. Pfeiffer. Mechanische Systeme mit unstetigen Uberg
p.232-240, 1984
[15] J. R. Dormand and P. J. Prince. A Family of Embedded Runge-Kutta Formulae,
Journal of Computational and Applied Mathematics, 6(1):19{26, 1980.
[16] W. Schiehlen. Multibody System Handbook, Springer-Verlag, 1990.
[17] R. von Schwerin and M. Winckler. A Mathematical Method for the Numerical
Solution of Initial Value Problems for Complex Systems of Nonlinear Dierential-
Algebraic Equations in Vehicle System Dynamics, submitted to Proceedings of the
8th ECMI conference, Kaiserslautern, 1994
[18] G. Vilalonga, J. Unda, J. Garcia de Jalon. Numerical Kinematic Analysis
of Three{Dimensional Mechanisms Using a 'Natural' System of Lagrangian Coordi-
nates, ASME Paper No. 84{DET{199, 1984
[19] J. Yen. Numerical methods for constrained equations of motion in mechanical system
dynamics, Dissertation, The University of Iowa, Iowa City , 1990

47