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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Meaning: The radius of a sphere or cylinder. Defaults to 1. This definition overrides all previous radius definitions for this solid.
Meaning: The length of the axis of a cylinder. Defaults to 1. This definition overrides all previous length definitions for this solid.
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.
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.
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
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.
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.
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.
© Harry Dankowicz 2003-2006
Mechanical and Industrial Engineering
University of Illinois at Urbana-Champaign
Urbana, IL 61801
e-mail: danko@uiuc.edu