The iFR Modelling Framework (iMF) shall help the user to model mechanic multi-body systems. It uses the formulation according to d’Alembert. The user defines generalized coordinates, coordinate systems with transformations (rotations and translations), symbolic system parameters, masses, frorces, moments and moments of inertia. The framework then computes the system's equations of motion in an symbolic form and generates MATLAB functions in mass-matrix form.
A huge part of the framework is adopted from the ACADO Toolkit which is licensed unter the GNU Lesser General Public License (GLPL).
The following classes are of particular interest for using the framework.
Model(interialSystem)inertialSystem: Pass an imf.CoordinateSystem, defining the inertial system in which the equations of motion will be expressed.
Add(external)external: Pass an imf.Force, imf.Moment or imf.Body which is then added to the model and automatically transformed into an expression in the inertial frame. If an imf.Body is added when gravity is defined, an equivalent imf.Force is automatically added.
Compilereturn value: Calculates the jacobians and derivatives needed for the formulation of the equations of motion and computes and returns them symbolically as an array of imf.Expression.
gravitySets the gravity for the model as an imf.Gravity.
Gravity(value, coordinateSystem)value: An vector or an imf.Vector - typically [0;0;9.81] given in coordinateSystem.
coordinateSystem: An imf.CoordinateSystem the value is given in.
Mass(name, value, positionVector, [inertia], [attitudeVector])name: A name for this external used by the visualize function.
value: A scalar value or an imf.Parameter defining the mass of a mass point.
positionVector: An imf.PositionVector defining the position vector of the force induced by the mass and the imf.Gravity.
inertia: (optional) An imf.Inertia giving the moment of inertia tensor.
angularVector: (optional) An imf.AttitudeVector describing the attitude of the system or an imf.AngularVelocity.
Force(name, value, positionVector)name: A name for this external used by the visualize function.
value: An imf.Vector defining the magnitude and the direction of a force.
positionVector: An imf.PositionVector describing the position vector of the force value.
Moment(name, value, attitudeVector, origin)name: A name for this external used by the visualize function.
value: An imf.Vector defining the magnitude and the axis of a moment.
attitudeVector: An imf.Vector describing the attitude of the system w.r.t. the generalized coordinates.
The class is the base for every symbolic formulation. It defines a lot of arithmetic functions like sin, cos, multiplication, etc. which will not be explained here.
matlabFunction(filename)Reduces the order of the differential function and generates two files filenameM and filenameF giving a first order differential equation in mass-matrix form M*xdot = F
symbolicReturns an vector of MATLAB's symbolic objects.
Transformation(from, to, [rotation], [rotation], [rotation], [rotation|translation]*)(*) You need to define at least one rotation or translation and not more than three roations and one translation. name: A name for this external used by the visualize function.
value: An imf.Vector defining the magnitude and the axis of a moment.
rotation: (optional) An imf.RotationMatrix describing rotation from from to to.
translation: (optional) An imf.Vector describing translational offset of both coordinate systems.
A vector is only rotated when transformed.
Vector(value, coordinateSystem)value: An vector or an imf.Vector defining the value in coordinateSystem. coordinateSystem: An imf.CoordinateSystem the value is given in.
A position vector is rotated and translated when transformed.
PositionVector(value, coordinateSystem)value: An vector or an imf.Vector defining the value in coordinateSystem. coordinateSystem: An imf.CoordinateSystem the value is given in.
An attitude vector can not be transformed at the moment. It is only used to derive the angular velocity.
AttitudeVector(value, coordinateSystem)value: An vector or an imf.Vector defining the value in coordinateSystem. coordinateSystem: An imf.CoordinateSystem the value is given in.
An angular velocity is transformed using the rotational sequences provided by the transformation.
AngularVelocity(value, coordinateSystem)value: An vector or an imf.Vector defining the value in coordinateSystem. coordinateSystem: An imf.CoordinateSystem the value is given in.
An matrix is transformed by rotation.
Matrix(value, coordinateSystem)value: An vector or an imf.Vector defining the value in coordinateSystem. coordinateSystem: An imf.CoordinateSystem the value is given in.
RotationMatrix(value, [axis], [generalizedCoordinate])value: A matrix or an imf.Expression defining the value. axis: (optional) A numeric scalar providing the axis which the turn is performed around. generalizedCoordinate: (optional) The imf.GeneralizedCoordinate giving the angle for the rotation.
CoordinateSystem(name)name: A name for the coordinate system.
visualize(model, variables, values, varargin)model: The imf.Model holding all masses, forces, etc. which will be displayed
variables: The variables which need to be substituded by numeric values. The variables need to be passed in a cell array.
values: The numeric values for variables in the same order as variables.
varargin:
- 'axis': Axis limits for x, y and z axis passed as a vector.
- 'view': View angles for azimuth and elevation as a vector.
- 'scale': A scalar scale value to adjust arrow lengths (not fully tested).
- 'revz': A switch to reverse the z and y axis.
% EXAMPLE USAGE:
visualize(m, {q1, q2, m1, m2, l}, [ysol(i,1), ysol(i,2), m1v, m2v, lv], 'axis', [-2 2 -2 2 -.5 4], 'view', [0 0], 'revz', 1)You find more complex and complete examples packaged with the framework. Those examples start with test_.
This is the recommended way of adding the framework to your PATH variable.
if ~exist('BEGIN_IMF','file'),
addpath( genpath([pwd filesep 'imf']) )
if ~exist('BEGIN_IMF','file'),
error('Unable to find the BEGIN_IMF function. Make sure to have' + ...
'the library as a sub folder of the current working directory.');
end
end
%%
BEGIN_IMF
%%
% >>> Your code goes here <<<
%%
END_IMFGeneralizedCoordinate q1
CoordinateSystem I
Parameter m1 l
m = imf.Model(I);
m.gravity = imf.Gravity(g, I);
m.Add(imf.Body('b1', m1, imf.PositionVector([sin(q1)*l,-cos(q1)*l,0]', I)));This is a simple model to show the functionality of rotational motion modelling.
GeneralizedCoordinate q1
CoordinateSystem I
Parameter m1 k Izz
m = imf.Model(I);
m.Add(imf.Body('b1', m1, imf.PositionVector([0;0;0]), imf.Inertia([0 0 0;0 0 0;0 0 Izz], I), imf.AttitudeVector([0 0 q1]', I)));
% Be aware of the sign of the Moment induced by the spring
m.Add(imf.Moment('M1', imf.Vector([0 0 -k*q1]', I), imf.AttitudeVector([0 0 q1]', I))); For this example we are going to model a two-mass pendulum and all steps will be explained. For an illustration of the coordinates chosen, see documents/two_mass_pendulum.ai.
For convenience, the Header will be skipped at this point.
- Define the generalized coordinates, coordinate systems and model parameters
GeneralizedCoordinate q1 q2
CoordinateSystem I c1
Parameter m1 m2 lCoordinate q1 describes the angle between the first pole and the inertial coordinate I system's z axis.
Coordinate q2 describes the angle between the second pole and the c1 coordinate system's z axis.
In this example the pendulum rotates around the y axis of each system and the right-hand rule applies. Therefore counter-clockwise rotation is positive.
The mass of the first pole is described by a point mass at the end of the pole with the free model parameter m1. The mass of the second pole is described by m2. The length of each pole is l.
- The transformation between coordinate system c1 and I must be defined if any vector is given in a non-inertial coordinate system. Otherwise, the framework would be unable to transform them into the inertial system. A transformation is defined as follows:
T21 = imf.Transformation(I, c1, imf.RotationMatrix.T2(q1), imf.Vector([0;0;-l], c1));It is not necessary to store this transformation into a workspace variable as the transformation is stored internally, too.
The above code defines a transformation from I to c1 by rotating around the 2-axis (y axis) with q1 (in radians). T1 and T3 are also available as predefined rotations.
Additionally, a translational offset between those two systems is defined by the fourth parameter. The offset can be described in the most convenient coordinate system.
3. The next step creates a model object which stores all relevant information concerning the dynamic system to be modelled:
m = imf.Model(I);- As we are going to add masses to the model, we need a gravitational acceleration to have forces acting on these masses.
g = [0;0;9.81];
m.gravity = imf.Gravity(g, I);- Now we are ready to define the masses of the poles (as point masses).
m.Add(imf.Body('b1', m1, imf.PositionVector([sin(q1)*l,0,cos(q1)*l]', I)));
m.Add(imf.Body('b2', m2, imf.PositionVector([sin(q2)*l,0,cos(q2)*l]', c1)));You just need to define a name (for visualization), the mass (either symbolic of numerical value) and the point of application of this mass in any coordinate system you like. 6. As a last step, you can now compile the model and export MATLAB functions to files named filenameM.m and filenameF.m resulting in equations in the form of M*x' = F.
model = m.Compile();
model.matlabFunction('filename');