Mambo 1.0 Reference Manual

2003-02-19

Introduction

Mambo provides an environment for simulation of systems of ordinary differential equations (ODEs) and visualization of the motion of a set of rigid bodies.

With Mambo, data representing time histories can be produced, imported, exported, and visualized. Mambo also contains an expression evaluator, so functions of the primary time dependent data may be visualized. Data is produced by solving a coupled set of ODEs. The ODEs are either in explicit: d/dt(state)=rhs, or semi-implicit: mass*d/dt(state) = rhs form. The ODEs are solved numerically, and the process of solving ODEs is referred to as simulation.

There are three kinds of files that Mambo uses to define the particular system studied. A simulation description tells the system everything that is needed to run a simulation, including variable names, expressions to be computed at each time point, and differential equations. Time dependent data can be loaded from or saved to a data file, so the ODE simulation need not be run each time. The result of a simulation or the data from a data file can be visualized as moving 3D solids, where the interpretation of the data in terms of solid motion is provided in a geometry description.

The terminology used in Mambo and its file formats does reflect a bit of the history and not yet implemented goals of the project. Thus the terminology and syntax may seem to be not fully relevant to its present use.

Mambo is developed at the Department of Mechanics, KTH, Sweden and at Virginia Polytechnic Institute and State University, USA.

Data flow concepts

During simulation and visualization, Mambo handles time dependent data and computes different kind of expressions. It is important to understand this process to be able to use the program. It is also important to keep in mind that there are two separate processes involved: In a simulation, the goal is to produce a data set representing a time history of data points by solving ODEs numerically. In a visualization, the goal is to present the data in a data point or data set. In both of these processes, expressions may be computed from the primary data in a data point. The expressions are written using the variable names representing time, parameters, state variables, insignals, and animated variables. The data flow is summarized in this figure.


Here the fine dashed lines indicate the data flow during visualization and the coarse dash-dotted lines indicate the data flow during simulation. The primary source of data is the data point.

During visualization, the current data point is used to compute insignals and animated variables, and all the resulting variables are available for the different visulization tools in Mambo. In an animation, the current data point is continuously updated from the sequence of data points in a data set.

During simulation, the current data point is used to provide initial conditions for the numerical ODE solver. The solver then produces data points as needed by the numerical algorithm, and these are used to compute insignals and the ODE expressions that describes the time evolution. Selected data points are also added to a data set. When the simulation is finished, the new data set becomes the current, and the first data point in that set becomes the current data point.

The different concepts are briefly explained below.

Time

A named variable that represents the time in the simulation. Time runs forwards during a simulation.

Parameters

Named variables that stay constant during a simulation.

State variables

Named variables whose time evolution is controlled by initial conditions and ODEs.

Data point

Together, a time value and the corresponding parameter values and state variable values make up a data point.

Insignals

Named variables defined by expressions. May be used to implement control laws, or for convenience to compute subexpressions used in animated and ode
expressions.

Animated variables

Named variables defined by expressions. They are only computed and used during visualization.

ODE

Expressions that determine the time derivatives of the state variables. They are only computed and used during simulation.

Data set

Mambo represents time histories of dynamical quantities by data sets. A data set consist of a list of data points. Data set can be produced by simulation or read from files.

Simulation

The process of producing a data set from parameters values, initial conditions for state variables, insignal definitions, and ODE definitions. Initial conditions are taken from the current data point.

Visualization

The process of presenting time, parameter, state, insignal, and animated variable data.

Dialog boxes

State and Parameter view dialogs can be used to set values for the current data point independent of a data set.

Data file

A data set can be loaded from or saved to a disk file.

The different variable types can be used as one find best suited for the problem at hand. For example, if the time history is known as explicit functions of time, there is no need to use any state variables, and consequntly there are no ODEs. Insignals and animated variables differ only in that the former is used in both simulation and visualization, and the latter only in visualization.

Simulation description

The information about dynamical quantities are entered into Mambo by reading an external file. This is referred to in Mambo loading a Simulation. Currently there are two supported file formats: A text based form stored in a file with the extension .dyn, and a compiled format in the form of a DLL with the extension .dll.

Text (.dyn) file format

General

Comments are like in C++: The token // introduces a comment extending to the end of the line, and the pairs of tokens /* */ forms a block comment. Block comments do not nest.

White space are comments and characters for which the C function isspace() returns non zero.

White space may be inserted anywhere except in names, keywords, and numerical constants.

Names begins with a letter and contains alphanumerical characters and the characters '.' and '_'. Case is significant.

The keywords of the language are time, parameters, states, insignals, anims, ode, rhs, and mass. Keywords may be given in any case combination, and keywords are not reserved, that is they may be used as variable names, although this use is discouraged.

Expressions are C-like. The following constants are defined: pi, and e. They cannot be used as names in any case combination. The following operators are defined: +, -, *, /, % (modulus), ^ (power), <, <=, >, >=, != (not equal), !& (bitwise xor), == (equality), & (bitwise and), && (logical and), | (bitwise or), || (logical or), ~ (bitwise complement), and ! (logical not). The following single argument functions are defined: ln, log, exp, abs, sqrt, neg, rand, sin, cos, tan, sec, csc, cot, asin, acos, atan, asec, acsc, acot, sinh, cosh, tanh, sech, csch, coth, ceil, and floor. The resulting type of an expression and the type of all variables is double precision floating point.

Definitions

The file consists of a sequence of time, parameters, state variables, insignals, animated variables, and ode definitions. None of the definitions are required. Definitions may come in any order, subject to the requirement that all names must be declared before their use. In general, definitions of the same kind adds to the list of variables of that kind. Exceptions are time and ode definitions, see below. All variable names are in the same name space. No name redeclarations are allowed.
Time definition
Syntax: time name ;

Meaning: Sets name as the current time name. Must be issued before name can be used in expressions. Subsequent time definitions define alternative time names. The last time definition sets the time name used for visualization. If there are no time definitions, the name t is used for visualization.

Parameters definition
Syntax: parameters name1 , name2 = constant, ... lastname ;

Meaning: Sets name1, name2, ... , lastname as parameter names, and initializes name2 to constant, and the others to 0. The initialized values are used to set the current data point. Subsequent definitions define further parameter names. The parameter ordering used by Mambo is the same as the declaration ordering.

State variables definition
Syntax: states name1 , name2 = constant, ... lastname ;

Meaning: Sets name1, name2, ... , lastname as state variable names, and initializes name2 to constant, and the others to 0. The initialized values are used to set the current data point. Subsequent definitions define further state variable names. The state variable ordering used by Mambo is the same as the declaration ordering.

Insignals definition
Syntax: insignals { name1 = expression1 ; name2=expression2; ... lastname = lastexpression ; }

Meaning: Sets name1, name2, ... , lastname as insignal names, and binds the names to the corresponding expressions. Names used in the expressions can be time, parameter, state variable, and insignal names already declared. Thus this is OK, insignals { u=1; v=-u; } but these are not: insignals {u=-u;}, insignals { u=v; v=-1e-4; }. Subsequent definitions define further insignal names.

Animated variables definition
Syntax: anims { name1 = expression1 ; name2 =expression2; ... lastname = lastexpression ; }

Meaning: Sets name1, name2, ... , lastname as animated variable names, and binds the names to the corresponding expressions. Names used in the expressions can be time, parameter, state variable, insignal, and animated variable names already declared. Subsequent definitions define further animated variable names.

ODE definition
Syntax: ode { rhs [ state_name1 ] = expression1 ; mass [ state_name2 ] [state_name3 ] = expression2 ;  ... rhs [ state_name] = lastexpression ; }

Meaning: Defines a set of ODEs. Names used in the expressions can be time, parameter, state variable, and insignal names. If there are no ODE definitions that contains mass, the ODE system is in explicit form. Then rhs[state_name1]=expression1 means that the time derivative of state_name1 is equal to expression1. To put it in another way, state_name1 is a row index in a rhs vector and the ODE system is d/dt(state)=rhs. If mass is found in any ODE definition, the ODE system is in semi implicit form. This means that state_name2 and state_name3 in mass[state_name2][state_name3]=expression2 are row and column indices in a square mass matrix and the ODE system is mass*d/dt(state) = rhs. In this case the row numbering in immaterial, that is we may perform the same permutation of the first index in the mass matrix and the rhs vector without changing the meaning of the system. The second index of the mass matrix is always coupled to a specific state variable. If a set of indices are found more than once in a for some rhs or mass, the later expression overrides the first. Entries in the rhs vector or mass matrix that are not
explicitly mentioned are set to 0. In particular, this means that a .dyn file without an ODE definition defines an explicit ODE with rhs as the zero vector.

Examples.

Start_of_file
End_of_file

An empty .dyn file is OK. It defines t as the time name for visualization and nothing more.

Start_of_file
/***************************************
 * A more ambitious example.           *
 * Differential equation for           *
 * a damped, driven linear oscillator. *
 ***************************************/

time t; // The time name

parameters delta=0.3 /* damping factor */, omega=2 /* driving frequency */;

states x=0.5, xdot=-1; // Position and velocity

insignals {
  driving=cos(omega*t);
}

anims {
  energy  = (xdot^2+x^2)/2;
}

// Explicit form of ODEs
ode {
  rhs[x]=xdot; // Kinematic equation
  rhs[xdot]=-2*delta*xdot-x+driving; // Dynamic equation
}
End_of_file

ODE in explicit form

Start_of_file
time t;
parameters delta=0.3,omega=2;
states x=0.5,xdot=-1;
insignals{driving=cos(omega*t);}

// This is the same set of ODEs, but in semi implicit form with rows switched.
ode {
  mass[x][xdot]=1;
  rhs[x]=-2*delta*xdot-x+driving;
  mass[xdot][x]=1;
  rhs[xdot]=xdot;
}
End_of_file

ODE in semi implicit form.

Compiled (.dll) format.

This format is not covered in this manual.

Data sets

Data set (.sds) file format

Data sets can be written to or read from data files. These are text files using the extension .sds. Each line of the file has a special meaning.

Line 1 should consist of a white space separated list of parameter names, in the same order as those defined by the Simulation file.

Line 2 should give a white space separated list of parameter values, in the same order as line 1.

Line 3 should consist of a white space separated list of time and state variable names. The time name should come first, followed by state variable names in the same order as those defined by the Simulation file.

Line 4 and subsequent lines should consist of values for time and state variables, in the same order as line 3. Time should increase with increasing line number.

Example.

Start_of_file
delta       omega
0.3         2
t           x          xdot
0           0.5        -1
0.1         0.43       -0.99
0.2         0.39       -0.95
End_of_file

Geometry description

One way of visualizing data is to let data represent properties of 3D solids. This allows for visualization of 3D mechanisms. The specification on how solids are shaped, colored, and placed in space in Mambo is called a Geometry description. The primary concepts dealt with are solids (graphics objects) and reference frames (observers).

Solid (graphics object)

A 3D rigid body, defined by its surfaces. Some solids are built-in in Mambo. Solids have a number of properties that can be set by the geometry description.

Reference frame (observer)

An affine coordinate system. Each solid has its own reference frame, and there is a world reference frame for the graphics in Mambo. Additional reference frames are introduce by the geometry description, with a description on how they relate. The result is a rooted tree of related reference frames, with the world frame at the root, and solid frames at leaves. The third (z) axis in the world reference frame is used as one of the rotation axes for camera movement in Mambo, and interactive camera rotation is most intuitive if the geometry is modeled such that the third world axis corresponds to "up".

The geometry description is read from an external geometry description file. There is currently a text file format for geometry descriptions, with an .geo file extension.

Geometry (.geo) text file format

The file format is extensively described in Dankowicz. The rules for comments, white space, names, and expressions are the same as for a .dyn file.

Keywords are module, body, point, orient, sphere, cylinder, block, color, radius, length, xlength, ylength, zlength, scale, file, and color. Keywords may be given in any case combination, and keywords may be used as variable names.

Definitions

A .geo file consists of a single module definition, containing a sequence of body definitions. Each body definition can contain a sequence of body, solid, and position definitions. Each solid definition can contain a sequence of property and position definitions. Body and solid definitions define additional bodies and solids, whereas position and property definitions override previous definitions of the same type in the same surrounding definition. All sequences referred to above may be empty.
Module definition
Syntax: module name { definitions }

Meaning: A single module definition must be found at the outermost level. It also defines the world reference frame. The name is is a label that has no further meaning, but may be used for commentary purposes and will show up in the Geometry view in Mambo. Definitions is a sequence of body and solid definitions.

Body definition
Syntax: body name { definitions }
           body name (variable_list ){definitions }

Meaning: Adds a reference frame. The name is a label. The variable_list is a comma separated list of local variable names. A local variable name sets up a mapping from this name to a global name constructed by concatenating all surrounding body names, starting from the outmost level, with a '.' character in between, and finally concatenating the local name with a '.' character in front. This mapping persist until the end of the body definition, and will be temporarily overridden if an interior body specifies the same name as local. The name space for variables in a body definition thus consists of the local variables declared in this and surrounding bodies, and  global names, subject to lexical scope rules. Definitions is a sequence of body, axis, solid, and position definitions.

Axis definition
Syntax: showaxis expression

Meaning: Makes a set of three arrows appear with directions corresponding to the triad directions and emmanating from the reference point. The x, y, and z directions are colored in red, green, and blue respectively.

Solid definitions

Defines a solid and its reference frame.
Sphere definition
Syntax: sphere { definitions }

Meaning: Adds a sphere solid with and a reference frame. The origin of the reference frame is in the center of the sphere. Definitions is a sequence is property and position definitions. Properties that can be used are radius and color.

Cylinder definition
Syntax: cylinder { definitions }

Meaning: Adds a circular cylinder solid with and a reference frame. The origin of the reference frame is in the center of the cylinder. The cylinder axis is parallel to the third (z) axis. Definitions is a sequence is property and position definitions. Properties that can be used are radius, length, and color.

Block definition
Syntax: block { definitions }

Meaning: Adds a rectangular block solid with and a reference frame. The origin of the reference frame is in the center of the block. The edges are parallel to the frame axes. Definitions is a sequence is property and position definitions. Properties that can be used are xlength, ylength, zlength, and color.

Position definitions

These define the relation between the reference frame of this body or solid and the reference frame of the surrounding body or module.
Point definition
Syntax: point { expression1 , expression2 , expression3 }

Meaning: Shifts the origin of the reference frame of this body or solid to the point given by coordinates expression1, expression2, expression3 in the surrounding body or module frame. Defaults to no shift ({0,0,0}) if not specified. This definition overrides all previous point definitions for this body or solid.

Orientation definition
Syntax: orient { expression11 , expression12 , expression13,expression21, expression22 , expression23,expression31,expression32 , expression33}

Meaning: Uses the matrix given in column major form by expression11 to expression33 as a rotation matrix from the reference triad of the surrounding body or module to the reference triad of this body or solid. Defaults to no rotation ({1,0,0,0,1,0,0,0,1}) if not specified. There is no requirement that the matrix is orthogonal. If it is not, then scalings and shears may be specified by this property. This definition overrides all previous orientation definitions for this body or solid.

If x1 is a column vector of coordinates in this body or solid's reference frame, p is the column vector given by the last point definition, and R is the matrix given by the last orientation definition, the column vector x2 of coordinates in the surrounding body or module's reference frame is x2=R*x1+p.

Property definitions

These define properties of solids.
Radius property
Syntax: radius expression

Meaning: The radius of a sphere or cylinder. Defaults to 1. This definition overrides all previous radius definitions for this solid.

Length property
Syntax: length expression

Meaning: The length of the axis of a cylinder. Defaults to 1. This definition overrides all previous length definitions for this solid.

Xlength property
Syntax: xlength expression

Meaning: The length of the edge parallel to the first (x) axis of a block. Defaults to 1. This definition overrides all previous xlength definitions for this solid.

Ylength property
Syntax: ylength expression

Meaning: The length of the edge parallel to the second (y) axis of a block. Defaults to 1. This definition overrides all previous ylength definitions for this solid.

Zlength property
Syntax: zlength expression

Meaning: The length of the edge parallel to the third (z) axis of a block. Defaults to 1. This definition overrides all previous zlength definitions for this solid

Color property
Syntax: color { red_expression , green_expression , blue_expression }

Meaning: The color of a sphere, cylinder, or block. The color is given as three number in the range 0 to 1 representing RGB components. Defaults to white ({1,1,1}). This definition overrides all previous color definitions for this solid.

Examples

Start_of_file
Module world {}
End_of_file

The simplest geometry file. Nothing is shown on screen, and no time, parameters, state variables, or animated variables need be defined by the simulation file.

Start_of_file
Module world {
  Body outer { // Body with a block and body.
               // Displaced by (x,y,z)
    Block { // A white block with dimensions (1,1,a)
      Zlength a
    }
    Body inner(b) { // Body with a cylinder.
                    // Rotated by phi around the third axis.
      Cylinder { // A red cylinder with radius 1
                 // and length outer.inner.b, displaced by (3,0,0).
        Length b
        Point {3,0,0}
      }
      Orient {cos(phi), -sin(phi), 0, sin(phi), cos(phi), 0, 0, 0, 1}
    }
    Point {x,y,z}
  }
}
End_of_file

A geometry file with two nested bodies. A cylinder and a block is shown on screen. The names a, outer.inner.b, phi, x, y, and z must be declared as time, parameters, state variables, or animated variables by the simulation description.

Visualization

Data can be visualized in several ways in Mambo.

Parameter view

Parameters from the current data point can be shown or set. The values may be changed.

State view

Time and state variables from the current data point can be shown or set. The values may be changed.

List view

The time and state variable values from the current data set is shown.

Graph view

The time history of a state variable from the current data set is shown in a graph.

Geometry view

The contents of a Geometry description is shown in a tree from.

Animation view

The Geometry description is rendered as 3D solids for the current data point.

In an animation, the current data point is picked by cycling through the data set. When not animating, a current data point can be selected from the data set by means of a playback controller.
 

Graphical user interface

Project handling

A Mambo project contains program settings, the locations of the simulation and geometry files, and data sets. Project handling functions are located under the File menu. Projects may be opened, closed, and saved to disk, or a new empty project can be generated. When opening a project, Mambo automatically tries to load simulation and geometry files from their last known locations. Two or more projects cannot be simultaneously active. When a project is active, simulation and geometry files can be loaded or reloaded. The Notepad program can be started to edit either of these files, but the files need to be reloaded after saving. There is really nothing that can be done in a project if no simulation file is loaded. When a simulation file is loaded, all functions of the program are possible to use, but the 3D solid rendering window will stay black and without visible change, since there are no solids to render. By File->Preferences, some parameters relating to 3D rendering can be set, and there is also an entry for changing the number of decimal part digits in the state, parameter, and list views, and in the data set files.

Documentation

In the help menu is a HTML viewer to see this documentation, and and about box. The HTML viewer is currently only available while a project is active.

Visual appearance

It is possible to hide some GUI components through functions found under the View menu.

Data set generation and handling

These functions are collected under the Simulation menu. Data sets are entered by reading data set files or by running a simulation.

Reading and writing a data set

The menu item Simulation->Load Dataset reads a data set from a file and makes it current . The menu item Simulation->Save Dataset writes the current data set to a file.

Running a simulation

A simulation starts with a data point as initial condition and runs for a fixed time interval. The time interval, the time spacing between data points in the data set, a minimum integrator time step safeguard against hanging simulations, and the ODE integrator algorithm and tolerances can be set by Simulation->Solver Properties. The simulation runs independently from the rest of the program and outputs data points to the growing current data set as they are computed. A simulation is started by Simulation->Start begins a new data set with the current data point as initial condition. A running simulation may be stopped by Simulation->Stop. Simulation->Continue appends to the current data set using the last data point as initial condition. A hung (for example due to singularities) or runaway simulation may be killed by Simulation->Kill. The progress of the simulation can be monitored by the progress bar in the animation controller.

Handling data sets

Mambo can keep track of several data sets. Simulation->DataSets are used to select the data set to be made current.

Data point handling (animation)

The functions for selecting the current data point are found under the Animation menu and in the animation controller on the utility bar. Animation (continuous cycling through the data points in the data set) can be turned on and off. When not animating, single stepping forwards or backwards, jumping to the first or last data point, or scrolling by moving the slider is supported. If a simulation is running, the number of data point will be increasing, and the functions above works within the part of the data set currently available. The real time interval between data points in an animation is controlled by Animation->Playback Speed.

Visualization

The functions for visualizing data sets and data point are found under the Window->New menu and on the utility bar.

Parameter view

A data point parameter window is brought up by Window->New->Parameter view. The value fields can be edited.

State view

A data point state window is brought up by Window->New->State view. The value fields can be edited. The window will as a last state name show disc.state with the value 0. This can be ignored and is not written to data set files.

List view

A data set window is brought up by Window->New->List view. The window will as a last state name show disc.state with the value 0. This can be ignored and is not written to data set files.

Graph view

A state variable graph window is brought up by selecting a state variable name from the Select variable list box on the utility bar, and then pressing the Display new graph button. By pressing the Graph settings button, the horizontal extent of the graph can be adjusted. The graph is always horizontally centered on the current data point, so the animation controller can be used for horizontal panning.

Geometry view

A geometry description tree window is brought up by Window->New->Geometry view.

Animation view

A 3D solid rendering window is brought up by Window->New->Animation view. The camera position may be controlled by the buttons in the camera portion of the utility bar. In the default position, which is set every time a geometry description is loaded or when the Reset camera button is pressed, the first (x) axis of  the world module reference frame points to the left of the screen, the second (y) axis points to the bottom of the screen, and the third (z) axis points out of the screen. If the Rotate and zoom button is active (default), mouse movements with the left mouse button pressed causes the camera to move and rotate on a sphere about the current view point. The horizontal camera axis is always parallel to the world x-y plane, and thus the geometry description should use the world z axis as "up". Vertical mouse movements with the right mouse button pressed and the Rotate and zoom button active causes the camera to move along the line through the current line of sight. If the Move look at button is active, mouse movements with the left mouse button pressed causes the view point to move horizontally, and vertical movements with the right mouse button pressed causes the view point to move along the line of sight. The Save view as image and Save view as avi buttons can be used to export the contents of the 3D solid rendering window. There is also a set controllers for the amount of graphics details. The Polygon count slider is used to control the number of patches of the solids. The Verticies only, Wireframe, and Solid polygons buttons controls the rendering type that is used.
 



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