Modelica.Mechanics.MultiBody

Library to model 3-dimensional mechanical systems

Information


Library MultiBody is a free Modelica package providing 3-dimensional mechanical components to model in a convenient way mechanical systems, such as robots, mechanisms, vehicles. Typical animations generated with this library are shown in the next figure:

For an introduction, have especially a look at:

Copyright © 1998-2009, Modelica Association and DLR.

This Modelica package is free software; it can be redistributed and/or modified under the terms of the Modelica license, see the license conditions and the accompanying disclaimer here.


Extends from Modelica.Icons.Library (Icon for library).

Package Content

NameDescription
Modelica.Mechanics.MultiBody.UsersGuide UsersGuide User's Guide of MultiBody Library
Modelica.Mechanics.MultiBody.World World World coordinate system + gravity field + default animation definition
Modelica.Mechanics.MultiBody.Examples Examples Examples that demonstrate the usage of the MultiBody library
Modelica.Mechanics.MultiBody.Forces Forces Components that exert forces and/or torques between frames
Modelica.Mechanics.MultiBody.Frames Frames Functions to transform rotational frame quantities
Modelica.Mechanics.MultiBody.Interfaces Interfaces Connectors and partial models for 3-dim. mechanical components
Modelica.Mechanics.MultiBody.Joints Joints Components that constrain the motion between two frames
Modelica.Mechanics.MultiBody.Parts Parts Rigid components such as bodies with mass and inertia and massless rods
Modelica.Mechanics.MultiBody.Sensors Sensors Sensors to measure variables
Modelica.Mechanics.MultiBody.Types Types Constants and types with choices, especially to build menus
Modelica.Mechanics.MultiBody.Visualizers Visualizers 3-dimensional visual objects used for animation


Modelica.Mechanics.MultiBody.World Modelica.Mechanics.MultiBody.World

World coordinate system + gravity field + default animation definition

Modelica.Mechanics.MultiBody.World

Information


Model World represents a global coordinate system fixed in ground. This model serves several purposes:

Since the gravity field function is required from all bodies with mass and the default settings of animation properties are required from nearly every component, exactly one instance of model World needs to be present in every model on the top level. The basic declaration needs to be:

    inner Modelica.Mechanics.MultiBody.World world

Note, it must be an inner declaration with instance name world in order that this world object can be accessed from all objects in the model. When dragging the "World" object from the package browser into the diagram layer, this declaration is automatically generated (this is defined via annotations in model World).

All vectors and tensors of a mechanical system are resolved in a frame that is local to the corresponding component. Usually, if all relative joint coordinates vanish, the local frames of all components are parallel to each other, as well as to the world frame (this holds as long as a Parts.FixedRotation, component is not used). In this "reference configuration" it is therefore alternatively possible to resolve all vectors in the world frame, since all frames are parallel to each other. This is often very convenient. In order to give some visual support in such a situation, in the icon of a World instance two axes of the world frame are shown and the labels of these axes can be set via parameters.

Parameters

TypeNameDefaultDescription
BooleanenableAnimationtrue= true, if animation of all components is enabled
BooleananimateWorldtrue= true, if world coordinate system shall be visualized
BooleananimateGravitytrue= true, if gravity field shall be visualized (acceleration vector or field center)
AxisLabellabel1"x"Label of horizontal axis in icon
AxisLabellabel2"y"Label of vertical axis in icon
GravityTypesgravityTypeGravityTypes.UniformGravityType of gravity field
Accelerationg9.81Constant gravity acceleration [m/s2]
Axisn{0,-1,0}Direction of gravity resolved in world frame (gravity = g*n/length(n)) [1]
Realmue3.986e14Gravity field constant (default = field constant of earth) [m3/s2]
BooleandriveTrainMechanics3Dtrue= true, if 3-dim. mechanical effects of Parts.Mounting1D/Rotor1D/BevelGear1D shall be taken into account
Animation
if animateWorld = true
DistanceaxisLengthnominalLength/2Length of world axes arrows [m]
DistanceaxisDiameteraxisLength/defaultFrameDiame...Diameter of world axes arrows [m]
BooleanaxisShowLabelstrue= true, if labels shall be shown
ColoraxisColor_xModelica.Mechanics.MultiBody...Color of x-arrow
ColoraxisColor_yaxisColor_x 
ColoraxisColor_zaxisColor_xColor of z-arrow
if animateGravity = true and gravityType = UniformGravity
PositiongravityArrowTail[3]{0,0,0}Position vector from origin of world frame to arrow tail, resolved in world frame [m]
LengthgravityArrowLengthaxisLength/2Length of gravity arrow [m]
DiametergravityArrowDiametergravityArrowLength/defaultWi...Diameter of gravity arrow [m]
ColorgravityArrowColor{0,230,0}Color of gravity arrow
if animateGravity = true and gravityType = PointGravity
DiametergravitySphereDiameter12742000Diameter of sphere representing gravity center (default = mean diameter of earth) [m]
ColorgravitySphereColor{0,230,0}Color of gravity sphere
Defaults
LengthnominalLength1"Nominal" length of multi-body system [m]
LengthdefaultAxisLengthnominalLength/5Default for length of a frame axis (but not world frame) [m]
LengthdefaultJointLengthnominalLength/10Default for the fixed length of a shape representing a joint [m]
LengthdefaultJointWidthnominalLength/20Default for the fixed width of a shape representing a joint [m]
LengthdefaultForceLengthnominalLength/10Default for the fixed length of a shape representing a force (e.g. damper) [m]
LengthdefaultForceWidthnominalLength/20Default for the fixed width of a shape represening a force (e.g. spring, bushing) [m]
LengthdefaultBodyDiameternominalLength/9Default for diameter of sphere representing the center of mass of a body [m]
RealdefaultWidthFraction20Default for shape width as a fraction of shape length (e.g., for Parts.FixedTranslation)
LengthdefaultArrowDiameternominalLength/40Default for arrow diameter (e.g., of forces, torques, sensors) [m]
RealdefaultFrameDiameterFraction40Default for arrow diameter of a coordinate system as a fraction of axis length
RealdefaultSpecularCoefficient0.7Default reflection of ambient light (= 0: light is completely absorbed)
RealdefaultN_to_m1000Default scaling of force arrows (length = force/defaultN_to_m) [N/m]
RealdefaultNm_to_m1000Default scaling of torque arrows (length = torque/defaultNm_to_m) [N.m/m]

Connectors

TypeNameDescription
Frame_bframe_bCoordinate system fixed in the origin of the world frame

Modelica definition

model World 
  "World coordinate system + gravity field + default animation definition"

  import SI = Modelica.SIunits;
  import Modelica.Mechanics.MultiBody.Types.GravityTypes;
  import Modelica.Mechanics.MultiBody.Types;

    Interfaces.Frame_b frame_b 
    "Coordinate system fixed in the origin of the world frame";

  parameter Boolean enableAnimation=true 
    "= true, if animation of all components is enabled";
  parameter Boolean animateWorld=true 
    "= true, if world coordinate system shall be visualized";
  parameter Boolean animateGravity=true 
    "= true, if gravity field shall be visualized (acceleration vector or field center)";
  parameter Types.AxisLabel label1="x" "Label of horizontal axis in icon";
  parameter Types.AxisLabel label2="y" "Label of vertical axis in icon";
  parameter Types.GravityTypes gravityType=GravityTypes.UniformGravity 
    "Type of gravity field";
  parameter SI.Acceleration g=9.81 "Constant gravity acceleration";
  parameter Types.Axis n={0,-1,0} 
    "Direction of gravity resolved in world frame (gravity = g*n/length(n))";
  parameter Real mue(
    unit="m3/s2",
    min=0) = 3.986e14 
    "Gravity field constant (default = field constant of earth)";
  parameter Boolean driveTrainMechanics3D=true 
    "= true, if 3-dim. mechanical effects of Parts.Mounting1D/Rotor1D/BevelGear1D shall be taken into account";

  parameter SI.Distance axisLength=nominalLength/2 
    "Length of world axes arrows";
  parameter SI.Distance axisDiameter=axisLength/defaultFrameDiameterFraction 
    "Diameter of world axes arrows";
  parameter Boolean axisShowLabels=true "= true, if labels shall be shown";
  input Types.Color axisColor_x=Modelica.Mechanics.MultiBody.Types.Defaults.FrameColor 
    "Color of x-arrow";
  input Types.Color axisColor_y=axisColor_x;
  input Types.Color axisColor_z=axisColor_x "Color of z-arrow";

  parameter SI.Position gravityArrowTail[3]={0,0,0} 
    "Position vector from origin of world frame to arrow tail, resolved in world frame";
  parameter SI.Length gravityArrowLength=axisLength/2 "Length of gravity arrow";
  parameter SI.Diameter gravityArrowDiameter=gravityArrowLength/
      defaultWidthFraction "Diameter of gravity arrow";
  input Types.Color gravityArrowColor={0,230,0} "Color of gravity arrow";
  parameter SI.Diameter gravitySphereDiameter=12742000 
    "Diameter of sphere representing gravity center (default = mean diameter of earth)";
  input Types.Color gravitySphereColor={0,230,0} "Color of gravity sphere";

  parameter SI.Length nominalLength=1 "\"Nominal\" length of multi-body system";
  parameter SI.Length defaultAxisLength=nominalLength/5 
    "Default for length of a frame axis (but not world frame)";
  parameter SI.Length defaultJointLength=nominalLength/10 
    "Default for the fixed length of a shape representing a joint";
  parameter SI.Length defaultJointWidth=nominalLength/20 
    "Default for the fixed width of a shape representing a joint";
  parameter SI.Length defaultForceLength=nominalLength/10 
    "Default for the fixed length of a shape representing a force (e.g. damper)";
  parameter SI.Length defaultForceWidth=nominalLength/20 
    "Default for the fixed width of a shape represening a force (e.g. spring, bushing)";
  parameter SI.Length defaultBodyDiameter=nominalLength/9 
    "Default for diameter of sphere representing the center of mass of a body";
  parameter Real defaultWidthFraction=20 
    "Default for shape width as a fraction of shape length (e.g., for Parts.FixedTranslation)";
  parameter SI.Length defaultArrowDiameter=nominalLength/40 
    "Default for arrow diameter (e.g., of forces, torques, sensors)";
  parameter Real defaultFrameDiameterFraction=40 
    "Default for arrow diameter of a coordinate system as a fraction of axis length";
  parameter Real defaultSpecularCoefficient(min=0) = 0.7 
    "Default reflection of ambient light (= 0: light is completely absorbed)";
  parameter Real defaultN_to_m(unit="N/m", min=0) = 1000 
    "Default scaling of force arrows (length = force/defaultN_to_m)";
  parameter Real defaultNm_to_m(unit="N.m/m", min=0) = 1000 
    "Default scaling of torque arrows (length = torque/defaultNm_to_m)";

  /* The World object can only use the Modelica.Mechanics.MultiBody.Visualizers.Advanced.Shape model, but no
     other models in package Modelica.Mechanics.MultiBody.Visualizers, since the other models access
     data of the "outer Modelica.Mechanics.MultiBody.World world" object, i.e., there are
     mutually dependent classes. For this reason, the higher level visualization
     objects cannot be used.
  */
protected 
  parameter Integer ndim=if enableAnimation and animateWorld then 1 else 0;
  parameter Integer ndim2=if enableAnimation and animateWorld and 
      axisShowLabels then 1 else 0;

  // Parameters to define axes
  parameter SI.Length headLength=min(axisLength, axisDiameter*Types.Defaults.
      FrameHeadLengthFraction);
  parameter SI.Length headWidth=axisDiameter*Types.Defaults.
      FrameHeadWidthFraction;
  parameter SI.Length lineLength=max(0, axisLength - headLength);
  parameter SI.Length lineWidth=axisDiameter;

  // Parameters to define axes labels
  parameter SI.Length scaledLabel=Modelica.Mechanics.MultiBody.Types.Defaults.FrameLabelHeightFraction*
      axisDiameter;
  parameter SI.Length labelStart=1.05*axisLength;

  // x-axis
  Modelica.Mechanics.MultiBody.Visualizers.Advanced.Shape x_arrowLine(
    shapeType="cylinder",
    length=lineLength,
    width=lineWidth,
    height=lineWidth,
    lengthDirection={1,0,0},
    widthDirection={0,1,0},
    color=axisColor_x,
    specularCoefficient=0) if enableAnimation and animateWorld;
  Modelica.Mechanics.MultiBody.Visualizers.Advanced.Shape x_arrowHead(
    shapeType="cone",
    length=headLength,
    width=headWidth,
    height=headWidth,
    lengthDirection={1,0,0},
    widthDirection={0,1,0},
    color=axisColor_x,
    r={lineLength,0,0},
    specularCoefficient=0) if enableAnimation and animateWorld;
  Modelica.Mechanics.MultiBody.Visualizers.Internal.Lines x_label(
    lines=scaledLabel*{[0, 0; 1, 1],[0, 1; 1, 0]},
    diameter=axisDiameter,
    color=axisColor_x,
    r_lines={labelStart,0,0},
    n_x={1,0,0},
    n_y={0,1,0},
    specularCoefficient=0) if enableAnimation and animateWorld and axisShowLabels;

  // y-axis
  Modelica.Mechanics.MultiBody.Visualizers.Advanced.Shape y_arrowLine(
    shapeType="cylinder",
    length=lineLength,
    width=lineWidth,
    height=lineWidth,
    lengthDirection={0,1,0},
    widthDirection={1,0,0},
    color=axisColor_y,
    specularCoefficient=0) if enableAnimation and animateWorld;
  Modelica.Mechanics.MultiBody.Visualizers.Advanced.Shape y_arrowHead(
    shapeType="cone",
    length=headLength,
    width=headWidth,
    height=headWidth,
    lengthDirection={0,1,0},
    widthDirection={1,0,0},
    color=axisColor_y,
    r={0,lineLength,0},
    specularCoefficient=0) if enableAnimation and animateWorld;
  Modelica.Mechanics.MultiBody.Visualizers.Internal.Lines y_label(
    lines=scaledLabel*{[0, 0; 1, 1.5],[0, 1.5; 0.5, 0.75]},
    diameter=axisDiameter,
    color=axisColor_y,
    r_lines={0,labelStart,0},
    n_x={0,1,0},
    n_y={-1,0,0},
    specularCoefficient=0) if enableAnimation and animateWorld and axisShowLabels;

  // z-axis
  Modelica.Mechanics.MultiBody.Visualizers.Advanced.Shape z_arrowLine(
    shapeType="cylinder",
    length=lineLength,
    width=lineWidth,
    height=lineWidth,
    lengthDirection={0,0,1},
    widthDirection={0,1,0},
    color=axisColor_z,
    specularCoefficient=0) if enableAnimation and animateWorld;
  Modelica.Mechanics.MultiBody.Visualizers.Advanced.Shape z_arrowHead(
    shapeType="cone",
    length=headLength,
    width=headWidth,
    height=headWidth,
    lengthDirection={0,0,1},
    widthDirection={0,1,0},
    color=axisColor_z,
    r={0,0,lineLength},
    specularCoefficient=0) if enableAnimation and animateWorld;
  Modelica.Mechanics.MultiBody.Visualizers.Internal.Lines z_label(
    lines=scaledLabel*{[0, 0; 1, 0],[0, 1; 1, 1],[0, 1; 1, 0]},
    diameter=axisDiameter,
    color=axisColor_z,
    r_lines={0,0,labelStart},
    n_x={0,0,1},
    n_y={0,1,0},
    specularCoefficient=0) if enableAnimation and animateWorld and axisShowLabels;

  // Uniform gravity visualization
  parameter SI.Length gravityHeadLength=min(gravityArrowLength,
      gravityArrowDiameter*Types.Defaults.ArrowHeadLengthFraction);
  parameter SI.Length gravityHeadWidth=gravityArrowDiameter*Types.Defaults.ArrowHeadWidthFraction;
  parameter SI.Length gravityLineLength=max(0, gravityArrowLength - gravityHeadLength);
  Modelica.Mechanics.MultiBody.Visualizers.Advanced.Shape gravityArrowLine(
    shapeType="cylinder",
    length=gravityLineLength,
    width=gravityArrowDiameter,
    height=gravityArrowDiameter,
    lengthDirection=n,
    widthDirection={0,1,0},
    color=gravityArrowColor,
    r_shape=gravityArrowTail,
    specularCoefficient=0) if enableAnimation and animateGravity and gravityType == GravityTypes.UniformGravity;
  Modelica.Mechanics.MultiBody.Visualizers.Advanced.Shape gravityArrowHead(
    shapeType="cone",
    length=gravityHeadLength,
    width=gravityHeadWidth,
    height=gravityHeadWidth,
    lengthDirection=n,
    widthDirection={0,1,0},
    color=gravityArrowColor,
    r_shape=gravityArrowTail + Modelica.Math.Vectors.normalize(
                                                n)*gravityLineLength,
    specularCoefficient=0) if enableAnimation and animateGravity and gravityType == GravityTypes.UniformGravity;

  // Point gravity visualization
  parameter Integer ndim_pointGravity=if enableAnimation and animateGravity
       and gravityType == 2 then 1 else 0;
  Modelica.Mechanics.MultiBody.Visualizers.Advanced.Shape gravitySphere(
    shapeType="sphere",
    r_shape={-gravitySphereDiameter/2,0,0},
    lengthDirection={1,0,0},
    length=gravitySphereDiameter,
    width=gravitySphereDiameter,
    height=gravitySphereDiameter,
    color=gravitySphereColor,
    specularCoefficient=0) if enableAnimation and animateGravity and gravityType == GravityTypes.PointGravity;

  function gravityAcceleration = gravityAccelerationTypes (
      gravityType=gravityType,
      g=g*Modelica.Math.Vectors.normalize(
                                     n),
      mue=mue);

protected 
  function gravityAccelerationTypes 
    "Gravity field acceleration depending on field type and position"
    import Modelica.Mechanics.MultiBody.Types.GravityTypes;
    extends Modelica.Icons.Function;
    input SI.Position r[3] 
      "Position vector from world frame to actual point, resolved in world frame";
    input GravityTypes gravityType "Type of gravity field";
    input SI.Acceleration g[3] 
      "Constant gravity acceleration, resolved in world frame, if gravityType=1";
    input Real mue(unit="m3/s2") 
      "Field constant of point gravity field, if gravityType=2";
    output SI.Acceleration gravity[3] 
      "Gravity acceleration at point r, resolved in world frame";
  algorithm 
    gravity := if gravityType == GravityTypes.UniformGravity then g else 
               if gravityType == GravityTypes.PointGravity then 
                  -(mue/(r*r))*(r/Modelica.Math.Vectors.length(
                                                r)) else 
                    zeros(3);
  end gravityAccelerationTypes;
equation 
  Connections.root(frame_b.R);

  assert(Modelica.Math.Vectors.length(
                       n) > 1.e-10,
    "Parameter n of World object is wrong (lenght(n) > 0 required)");
  frame_b.r_0 = zeros(3);
  frame_b.R = Frames.nullRotation();
end World;

Modelica.Mechanics.MultiBody.World.gravityAccelerationTypes Modelica.Mechanics.MultiBody.World.gravityAccelerationTypes

Gravity field acceleration depending on field type and position

Information

Extends from Modelica.Icons.Function (Icon for a function).

Inputs

TypeNameDefaultDescription
Positionr[3] Position vector from world frame to actual point, resolved in world frame [m]
GravityTypesgravityType Type of gravity field
Accelerationg[3] Constant gravity acceleration, resolved in world frame, if gravityType=1 [m/s2]
Realmue Field constant of point gravity field, if gravityType=2 [m3/s2]

Outputs

TypeNameDescription
Accelerationgravity[3]Gravity acceleration at point r, resolved in world frame [m/s2]

Modelica definition

function gravityAccelerationTypes 
  "Gravity field acceleration depending on field type and position"
  import Modelica.Mechanics.MultiBody.Types.GravityTypes;
  extends Modelica.Icons.Function;
  input SI.Position r[3] 
    "Position vector from world frame to actual point, resolved in world frame";
  input GravityTypes gravityType "Type of gravity field";
  input SI.Acceleration g[3] 
    "Constant gravity acceleration, resolved in world frame, if gravityType=1";
  input Real mue(unit="m3/s2") 
    "Field constant of point gravity field, if gravityType=2";
  output SI.Acceleration gravity[3] 
    "Gravity acceleration at point r, resolved in world frame";
algorithm 
  gravity := if gravityType == GravityTypes.UniformGravity then g else 
             if gravityType == GravityTypes.PointGravity then 
                -(mue/(r*r))*(r/Modelica.Math.Vectors.length(
                                              r)) else 
                  zeros(3);
end gravityAccelerationTypes;

HTML-documentation generated by Dymola Sun Jan 17 21:11:07 2010.