Mambo and The Mambo Toolbox - Hints for usage
© Arne Nordmark, Department of Mechanics, Royal Institute of Technology, Sweden

General

Keep it simple.

The most obvious hint: Start simple, and expand as you get familiar with the program.

It there is a complicated mechanism to be modelled, start with another, very simple mechanism with one or two state variables. Try to make a geometry description with no fancies, but with the correct influence of the state variables. If you first do not want to come up with a differential equation, that's OK. By editing the current data point, you can still see the influence of state and parameter changes, and verify that you understand the construction. Then add differential equations.

When the simple mechanism works, you are much better prepared to treat a more complicated system. Still, it is better to try to do a subset first of the complicated system, which is often composed of several identical or similar parts. By bringing the subset to work, no time is wasted, more experience is gained, and it is now easy to extend the debugged code to treat more of these similar parts.

The worst thing to do is to try a full design, find a fatal flaw, change all code, find another design flaw, and so on.

There is no built in text editor

so you have to use your favorite external one, or perhaps even the lowly NotePad.

Dynamical quantities

How to use dynamical quantities

With so many dynamical quantities, state variables, parameters, insignals, and animated variables, how should these be used efficiently? There is no "right" answer here, since they (partly for historical reason) can be used very flexibly.

State variables: These are controlled by differential equations, which is why they are special. One thing to keep in mind is that the implementation of some constraints are made easier by introducing redundant state variables, for example if two vectors must be parallel and we can not come up with two other independent vectors to project onto, we can use the constraint that one vector is a scalar factor times the other, the factor being a redundant state variable.

Insignals: This is the obvious place to put time (or state) dependent control signals, but since thay are available in the expressions of the animated variables, ODEs and in the geometry file, they can often (despite the name) be used simply to calculate sub expressions used elsewhere.

Animated variables: These have the sole purpose of calculating quantities use in the geometry description.
 

Tricks with expressions

The expressions can contain logical operators that evaluate to 1 if true and 0 is false. This makes it possible to write expresions with discontinuites. Examples:

Square wave: u=amplityde*((sin(omega*t)>0)*1+(sin(omega*t)<0)*(-1));
Delayed ramp: u=(t>t0)*(t-t0)*slope;

There is no short circuit code, however, and everything is evaluated. Thus for example potential divisions by zero must be protected, like in sinc=(q==0)*1+(q!=0)*sin(q)/(q*(q!=0)+1*(q==0));

Differential equations

The ODE specification

Remember that a single mass expression in an ODE specification results in a semi explicit ODE system, and that entries in the mass matrix and rhs vector not mentioned default to zero. Thus if we do not specify as many equations as there are state variables, the system will silently add null equations, and we will only find this out when the simulation wont take a single time step due to the singularity.

Singularites

When using ODEs in semi-implicit form, there is always the risk of specifying a singular system, where the mass matrix is not invertible. For example, a kinematic constraint to move on a circle, x^2+y^2=1, combined with a constraint on fixed x velocity, could look like this in a .dyn file

states x=0,y=1;

parameters u=1;

ode {
  mass[x][x]=2*x;
  mass[x][y]=2*y;
  mass[y][x]=1;
  rhs[y]=u;
}

The determinant of the mass matrix is -2*y, so when y becomes 0 after 1 time unit, the simulation will be stuck, and the simulation is aborted. This is reported in the log window and can be inferred from the progress bar in the animation controller which takes a jump to the end. To be able to see what happens, it is convenient to use the 3D visualization window combined with a small time step, so we can see the movement of the mechanism and understand what happens when it gets stuck. Most often this is the result of something getting stretch out maximally, like the x coordinate in the example above.

If the simulation does not start at all or aborts immediately, we have either started in a stick point, like x=1, y=0 in the above example, or the mass matrix is always singular because we have specified redundant constraints. For example if we want x=y=z, and we divide this into three constraints: x-y=0, y-z=0, x-z=0,  implemented as

states x,y,z;

ode {
  mass[x][x]=1;
  mass[x][y]=-1;
  mass[y][y]=1;
  mass[y][z]=-1;
  mass[z][x]=1;
  mass[z][z]=-1;
}

we will have a singular system since the determinant of the mass matrix is 0. Instead we will have to replace one of the constraints with an independent one, like fixed x velocity. While this example is trivial, it may not be so easy to find the redundancy in a more complicated mechanism.

It is also possible that the simulation will proceed when encountering a singularity, but that strange numbers like near infinities will be produced. This may be spotted by studying the data set in the list view or from the disappearance of solids in the animation view.
 

Data sets

Complicated time histories, composed of several parts, may be constructed by running simulations with different control signals or constraints, saving them as data sets, and pasting data sets together in a text editor. Even though data sets are stored in the project file, it is wise to save them as separate files if you need them in the future. Observe that a data set assumes a specific ordering of the states variables and parameters, and any change of this ordering will cause Mambo to refuse to read the data set file or use the data sets in a project file.

3D graphics

Moving the mechanism by editing the current data point

The fact that we can make changes to the current data point in the state and parameter views, make it possible to verify that a mechanism is constructed as expected, since we can immediately study the effects in the animation view.

Checking the geometry description

The .geo file parser is quite forgiving, so if there is any doubt that the nesting of frames and solids is not what you intend, or you want to verify that default values are as you expect them, the geometry view gives a tree presentation of the geometry description with all default values visible.

Smooth animations

Speed and smoothness of the animation may be improved by changing rendering settings (polygon count, vertices/wireframe/solid), changing the playback speed (Animation->Playback Speed), or by using a different time step (Simulation->Solver Properties) in the simulation.

Default camera position

The default camera position can not be changed, but one can always add a new body surrounding the rest with a non-default position definition, thus causing the camera to be properly positioned relative to the rest of the contruction.

Simulation

Initial conditions

When starting a new simulation, the initial condition is taken from the current data point. If a data set present is already present, the current data point is chosen with the animation controller. The current data point can be modified in the state view. Only if there is no data set present is the current data point initialized from the simulation description. In the state view, there is also the possibility to give the initial time point.

The project file

The project file is not overly useful while developing your geometry and simulation decriptions, since a change of the number of state variables will make the data sets stored in the project file useless.  When the description files are stable, it is nice to store different data sets in the project file.
 

© Harry Dankowicz 2003-2006
Mechanical and Industrial Engineering
University of Illinois at Urbana-Champaign
Urbana, IL 61801
e-mail: danko@uiuc.edu