MultiBondLib.Mechanics3D

A library for 3D-Mechanics based upon MultiBond graphs

MultiBondLib.Mechanics3D.World3D MultiBondLib.Mechanics3D.Interfaces MultiBondLib.Mechanics3D.AdditionalMBG MultiBondLib.Mechanics3D.Forces MultiBondLib.Mechanics3D.Joints MultiBondLib.Mechanics3D.Parts MultiBondLib.Mechanics3D.RollingObjects MultiBondLib.Mechanics3D.Types MultiBondLib.Mechanics3D.Utilities MultiBondLib.Mechanics3D.Examples

Information


  This is the package for 3D-mechanical models. 
  It is a partial reimplementation of the MultiBody library of Prof. Dr. Martin Otter.

This library offers an object-oriented solution for the modeling of 3D-mechanical systems. Mechanical systems can be composed out of single ideal elements. They are separated according to their nature into subpackages. These packages contain:

All the basic elements consist of multibond graphs.

Tutorial

The MultiBody library offers an excelent tutorial. The models of this library can be treated essentially the same way.

Wrapped MultiBond Graphs

A look into the mechanical models reveals the corresponding multibond graphs. There are separate multibonds for the translational and rotational domain, both of cardinality 3. The composition of them is illustrated in the next figure.

This separation is necessary because the corresponding bondgraphic variables are resolved in different coordinate systems. The translational variables are resolved with respect to the inertial system. The rotational variables are resolved with respect to the body system. The body system is defined by the signal R that contains the 3x3 orientation matrix. Again, the the positional variables are processed by acuasal signals and are of course resolved in the inertial system.

Two converter elements convert the bondgraphic variables to the variables of the main connectors and vice-versa. These elements create a shell for the multibond graph. The figure below presents such a typical shell. The multibond graph is indicated by 1-junctions.

Kinematic Loops

Kinematic loops are not problematic and can be modeled in a fully object-oriented way. The appearing redundant statements are removed automatically. Whenever loop structures occur, non-linear algebraic equations are present on "position level", but usually they are solved fast and robustly and cause no further problems.

Also an element for the manual closure of kinematic loops is provided. The application of this element is meaningful, if you want to "cut" the loop at a specific point. (This might lead to better equations)

Planar loops cannot be handled autoatically. To close such a strucute a special revolute joint is provided.

Efficency

The Mechanics3D library offers a comprehensive set of ideal elements for 3D-mechanics. Mechanical systems can be comfortably modeled and efficiently simulated.

The selection of the state variables is of major importance for the efficiency of the resulting simulation. This selection is automatically done by Dymola. The resulting state variables are then always the states of a joint's relative position and motion. So each joint is declaring state variables, unless there is a kinematic loop.

The state selection can be improved or fully determined by the advanced parameter "enforceStates" that is part of all joints. This helpful to avoid sets of dynamic state selection as they occur in kinematic loops.

The resulting systems of linear equations are usually small and can be solved fast and accurately. Kinematic loops lead to a systems non-linear equations.

Examples

A comprehensive set of examples demonstrate the usage of the Mechanics3D library. They are easy to understand and offer a good starting point to make yourself familiar with this library. Don't forget the examples of the PlanarMechanics library.

NameDescription
World3D world element of the 3D-mechanicsWorld coordinate system + gravity field + default animation definition
Interfaces Connector elements
AdditionalMBG Additional bondgraphic elements
Forces force elements
Joints joint elements
Parts parts
RollingObjects part and joint elements of ideal rolling wheels and marbles
Types additional type definitions specific for 3D-Mechanics
Utilities useful internal elements and functions to create models of 3D-Mechanics
Examples Examples


MultiBondLib.Mechanics3D.World3D MultiBondLib.Mechanics3D.World3D

world element of the 3D-mechanicsWorld coordinate system + gravity field + default animation definition

MultiBondLib.Mechanics3D.World3D

Information


This is the World3D model. 
This model is an extended copy of the Modelica.Mechanics.MultiBody.World model.

This world 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 World3D needs to be present in every model on the top level. The basic declaration needs to be:

    inner Mechanics3D.World3D world3D

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

To use the the gravity pool, set the parameter gravityPoolSize to the number of bodies you'd like to have in your pool. Then give each body in the pool a different index number from 1 to gravityPoolSize. The index number can be set by the parameter GPindex of the body element.


Parameters

NameDefaultDescription
enableAnimationtrue= true, if animation of all components is enabled
animateWorldtrue= true, if world coordinate system shall be visualized
animateGravitytrue= true, if gravity field shall be visualized (acceleration vector or field center)
label1"x"Label of horizontal axis in icon
label2"y"Label of vertical axis in icon
gravityTypeModelica.Mechanics.MultiBody...Type of gravity field
g9.81 Constant gravity acceleration [m/s2]
n{0,-1,0} Direction of gravity resolved in world frame (gravity = g*n/length(n))
mue3.986e14 Gravity field constant (default = field constant of earth) [m3/s2]
gravityPoolSize0size of gravity pool
Animation
if animateWorld = true
axisLengthnominalLength/2 Length of world axes arrows [m]
axisDiameteraxisLength/defaultFrameDiame... Diameter of world axes arrows [m]
axisShowLabelstrue = true, if labels shall be shown
axisColor_xModelica.Mechanics.MultiBody... Color of x-arrow
axisColor_yaxisColor_x Color of y-arrow
axisColor_zaxisColor_x Color of z-arrow
if animateGravity = true and gravityType = UniformGravity
gravityArrowTail[3]{0,0,0} Position vector from origin of world frame to arrow tail, resolved in world frame [m]
gravityArrowLengthaxisLength/2 Length of gravity arrow [m]
gravityArrowDiametergravityArrowLength/defaultWi... Diameter of gravity arrow [m]
gravityArrowColor{0,230,0} Color of gravity arrow
if animateGravity = true and gravityType = PointGravity
gravitySphereDiameter12742000 Diameter of sphere representing gravity center (default = mean diameter of earth) [m]
gravitySphereColor{0,230,0} Color of gravity sphere
Defaults
nominalLength1 "Nominal" length of multi-body system [m]
defaultAxisLengthnominalLength/5 Default for length of a frame axis (but not world frame) [m]
defaultJointLengthnominalLength/10 Default for the fixed length of a shape representing a joint [m]
defaultJointWidthnominalLength/20 Default for the fixed width of a shape representing a joint [m]
defaultForceLengthnominalLength/10 Default for the fixed length of a shape representing a force (e.g. damper) [m]
defaultForceWidthnominalLength/20 Default for the fixed width of a shape represening a force (e.g. spring, bushing) [m]
defaultBodyDiameternominalLength/9 Default for diameter of sphere representing the center of mass of a body [m]
defaultWidthFraction20 Default for shape width as a fraction of shape length (e.g., for Parts.FixedTranslation)
defaultArrowDiameternominalLength/40 Default for arrow diameter (e.g., of forces, torques, sensors) [m]
defaultFrameDiameterFraction40 Default for arrow diameter of a coordinate system as a fraction of axis length
defaultJointColor{255,0,255} Default color of a joint element
defaultBodyColor{0,64,255} Default color of a body element
defaultRodColor{96,128,128} Default color of a rod element
defaultForceElementColor{0,64,255} Default color of a rod element

Modelica definition

model World3D 
  "world element of the 3D-mechanicsWorld coordinate system + gravity field + default animation definition" 
  
  import SI = Modelica.SIunits;
  
  
  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 Modelica.Mechanics.MultiBody.Types.AxisLabel label1="x" 
    "Label of horizontal axis in icon";
  parameter Modelica.Mechanics.MultiBody.Types.AxisLabel label2="y" 
    "Label of vertical axis in icon";
  parameter Modelica.Mechanics.MultiBody.Types.GravityTypes.Temp gravityType=
      Modelica.Mechanics.MultiBody.Types.GravityTypes.UniformGravity 
    "Type of gravity field";
  parameter SI.Acceleration g=9.81 " Constant gravity acceleration";
  parameter Modelica.Mechanics.MultiBody.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 Integer gravityPoolSize=0 "size of gravity pool";
  parameter SI.Distance axisLength=nominalLength/2 
    "|Animation|if animateWorld = true| Length of world axes arrows";
  parameter SI.Distance axisDiameter=axisLength/defaultFrameDiameterFraction 
    "|Animation|if animateWorld = true| Diameter of world axes arrows";
  parameter Boolean axisShowLabels=true 
    "|Animation|if animateWorld = true| = true, if labels shall be shown";
  parameter Modelica.Mechanics.MultiBody.Types.Color axisColor_x=Modelica.Mechanics.MultiBody.Types.Defaults.
      FrameColor "|Animation|if animateWorld = true| Color of x-arrow";
  parameter Modelica.Mechanics.MultiBody.Types.Color axisColor_y=axisColor_x 
    "|Animation|if animateWorld = true| Color of y-arrow";
  parameter Modelica.Mechanics.MultiBody.Types.Color axisColor_z=axisColor_x 
    "|Animation|if animateWorld = true| Color of z-arrow";
  
  parameter SI.Position gravityArrowTail[3]={0,0,0} 
    "|Animation|if animateGravity = true and gravityType = UniformGravity| Position vector from origin of world frame to arrow tail, resolved in world frame";
  parameter SI.Length gravityArrowLength=axisLength/2 
    "|Animation|if animateGravity = true and gravityType = UniformGravity| Length of gravity arrow";
  parameter SI.Diameter gravityArrowDiameter=gravityArrowLength/
      defaultWidthFraction 
    "|Animation|if animateGravity = true and gravityType = UniformGravity| Diameter of gravity arrow";
  parameter Modelica.Mechanics.MultiBody.Types.Color gravityArrowColor={0,230,0} 
    "|Animation|if animateGravity = true and gravityType = UniformGravity| Color of gravity arrow";
  parameter SI.Diameter gravitySphereDiameter=12742000 
    "|Animation|if animateGravity = true and gravityType = PointGravity| Diameter of sphere representing gravity center (default = mean diameter of earth)";
  parameter Modelica.Mechanics.MultiBody.Types.Color gravitySphereColor={0,230,0} 
    "|Animation|if animateGravity = true and gravityType = PointGravity| Color of gravity sphere";
  
  parameter SI.Length nominalLength=1 
    "|Defaults|| \"Nominal\" length of multi-body system";
  parameter SI.Length defaultAxisLength=nominalLength/5 
    "|Defaults|| Default for length of a frame axis (but not world frame)";
  parameter SI.Length defaultJointLength=nominalLength/10 
    "|Defaults|| Default for the fixed length of a shape representing a joint";
  parameter SI.Length defaultJointWidth=nominalLength/20 
    "|Defaults|| Default for the fixed width of a shape representing a joint";
  parameter SI.Length defaultForceLength=nominalLength/10 
    "|Defaults|| Default for the fixed length of a shape representing a force (e.g. damper)";
  parameter SI.Length defaultForceWidth=nominalLength/20 
    "|Defaults|| Default for the fixed width of a shape represening a force (e.g. spring, bushing)";
  parameter SI.Length defaultBodyDiameter=nominalLength/9 
    "|Defaults|| Default for diameter of sphere representing the center of mass of a body";
  parameter Real defaultWidthFraction=20 
    "|Defaults|| Default for shape width as a fraction of shape length (e.g., for Parts.FixedTranslation)";
  parameter SI.Length defaultArrowDiameter=nominalLength/40 
    "|Defaults|| Default for arrow diameter (e.g., of forces, torques, sensors)";
  parameter Real defaultFrameDiameterFraction=40 
    "|Defaults|| Default for arrow diameter of a coordinate system as a fraction of axis length";
  
  parameter Modelica.Mechanics.MultiBody.Types.Color defaultJointColor={255,0,255} 
    "|Defaults|| Default color of a joint element";
  parameter Modelica.Mechanics.MultiBody.Types.Color defaultBodyColor={0,64,255} 
    "|Defaults|| Default color of a body element";
  parameter Modelica.Mechanics.MultiBody.Types.Color defaultRodColor={96,128,128} 
    "|Defaults|| Default color of a rod element";
  parameter Modelica.Mechanics.MultiBody.Types.Color defaultForceElementColor={0,64,255} 
    "|Defaults|| Default color of a rod element";
  
  Utilities.GravityPool gravityPool(poolSize=gravityPoolSize);
  
  /* 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*Modelica.
      Mechanics.MultiBody.Types.Defaults.FrameHeadLengthFraction);
  parameter SI.Length headWidth=axisDiameter*Modelica.Mechanics.MultiBody.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[ndim](
    each shapeType="cylinder",
    each length=lineLength,
    each width=lineWidth,
    each height=lineWidth,
    each lengthDirection={1,0,0},
    each widthDirection={0,1,0},
    each color=axisColor_x,
    each specularCoefficient=0);
  Modelica.Mechanics.MultiBody.Visualizers.Advanced.Shape x_arrowHead[ndim](
    each shapeType="cone",
    each length=headLength,
    each width=headWidth,
    each height=headWidth,
    each lengthDirection={1,0,0},
    each widthDirection={0,1,0},
    each color=axisColor_x,
    each r={lineLength,0,0},
    each specularCoefficient=0);
  Modelica.Mechanics.MultiBody.Visualizers.Internal.Lines x_label[ndim2](
    each lines=scaledLabel*{[0, 0; 1, 1],[0, 1; 1, 0]},
    each diameter=axisDiameter,
    each color=axisColor_x,
    each r_lines={labelStart,0,0},
    each n_x={1,0,0},
    each n_y={0,1,0},
    each specularCoefficient=0);
  
  // y-axis
  Modelica.Mechanics.MultiBody.Visualizers.Advanced.Shape y_arrowLine[ndim](
    each shapeType="cylinder",
    each length=lineLength,
    each width=lineWidth,
    each height=lineWidth,
    each lengthDirection={0,1,0},
    each widthDirection={1,0,0},
    each color=axisColor_y,
    each specularCoefficient=0);
  Modelica.Mechanics.MultiBody.Visualizers.Advanced.Shape y_arrowHead[ndim](
    each shapeType="cone",
    each length=headLength,
    each width=headWidth,
    each height=headWidth,
    each lengthDirection={0,1,0},
    each widthDirection={1,0,0},
    each color=axisColor_y,
    each r={0,lineLength,0},
    each specularCoefficient=0);
  Modelica.Mechanics.MultiBody.Visualizers.Internal.Lines y_label[ndim2](
    each lines=scaledLabel*{[0, 0; 1, 1.5],[0, 1.5; 0.5, 0.75]},
    each diameter=axisDiameter,
    each color=axisColor_y,
    each r_lines={0,labelStart,0},
    each n_x={0,1,0},
    each n_y={-1,0,0},
    each specularCoefficient=0);
  
  // z-axis
  Modelica.Mechanics.MultiBody.Visualizers.Advanced.Shape z_arrowLine[ndim](
    each shapeType="cylinder",
    each length=lineLength,
    each width=lineWidth,
    each height=lineWidth,
    each lengthDirection={0,0,1},
    each widthDirection={0,1,0},
    each color=axisColor_z,
    each specularCoefficient=0);
  Modelica.Mechanics.MultiBody.Visualizers.Advanced.Shape z_arrowHead[ndim](
    each shapeType="cone",
    each length=headLength,
    each width=headWidth,
    each height=headWidth,
    each lengthDirection={0,0,1},
    each widthDirection={0,1,0},
    each color=axisColor_z,
    each r={0,0,lineLength},
    each specularCoefficient=0);
  Modelica.Mechanics.MultiBody.Visualizers.Internal.Lines z_label[ndim2](
    each lines=scaledLabel*{[0, 0; 1, 0],[0, 1; 1, 1],[0, 1; 1, 0]},
    each diameter=axisDiameter,
    each color=axisColor_z,
    each r_lines={0,0,labelStart},
    each n_x={0,0,1},
    each n_y={0,1,0},
    each specularCoefficient=0);
  
  // Uniform gravity visualization
  parameter Integer ndim_uniformGravity=if enableAnimation and animateGravity
       and gravityType == 1 then 1 else 0;
  parameter SI.Length gravityHeadLength=min(gravityArrowLength,
      gravityArrowDiameter*Modelica.Mechanics.MultiBody.Types.Defaults.
      ArrowHeadLengthFraction);
  parameter SI.Length gravityHeadWidth=gravityArrowDiameter*Modelica.Mechanics.
      MultiBody.Types.Defaults.ArrowHeadWidthFraction;
  parameter SI.Length gravityLineLength=max(0, gravityArrowLength -
      gravityHeadLength);
  Modelica.Mechanics.MultiBody.Visualizers.Advanced.Shape gravityArrowLine[ndim_uniformGravity](
    each shapeType="cylinder",
    each length=gravityLineLength,
    each width=gravityArrowDiameter,
    each height=gravityArrowDiameter,
    each lengthDirection=n,
    each widthDirection={0,1,0},
    each color=gravityArrowColor,
    each r_shape=gravityArrowTail,
    each specularCoefficient=0);
  Modelica.Mechanics.MultiBody.Visualizers.Advanced.Shape gravityArrowHead[ndim_uniformGravity](
    each shapeType="cone",
    each length=gravityHeadLength,
    each width=gravityHeadWidth,
    each height=gravityHeadWidth,
    each lengthDirection=n,
    each widthDirection={0,1,0},
    each color=gravityArrowColor,
    each r_shape=gravityArrowTail + Modelica.Mechanics.MultiBody.Frames.normalize(
                                                     n)*gravityLineLength,
    each specularCoefficient=0);
  
  // 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[ndim_pointGravity](
    each shapeType="sphere",
    each r_shape={-gravitySphereDiameter/2,0,0},
    each lengthDirection={1,0,0},
    each length=gravitySphereDiameter,
    each width=gravitySphereDiameter,
    each height=gravitySphereDiameter,
    each color=gravitySphereColor,
    each specularCoefficient=0);
  
  function gravityAcceleration = gravityAccelerationTypes (
      gravityType=gravityType,
      g=g*Modelica.Mechanics.MultiBody.Frames.normalize(
                                     n),
      mue=mue);
  
protected 
  function gravityAccelerationTypes 
    "Gravity field acceleration depending on field type and position" 
    
    extends Modelica.Icons.Function;
    input SI.Position r[3] 
      "Position vector from world frame to actual point, resolved in world frame";
    input Integer 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 == 1 then g else if gravityType == 2 then -(mue/(
      r*r))*(r/Modelica.Mechanics.MultiBody.Frames.length(r)) else zeros(3);
  end gravityAccelerationTypes;
equation 
  
  assert(Modelica.Mechanics.MultiBody.Frames.length(n) > 1.e-10,
    "Parameter n of World object is wrong (lenght(n) > 0 required)");
end World3D;

MultiBondLib.Mechanics3D.World3D.gravityAccelerationTypes MultiBondLib.Mechanics3D.World3D.gravityAccelerationTypes

Gravity field acceleration depending on field type and position

Modelica definition

function gravityAccelerationTypes 
  "Gravity field acceleration depending on field type and position" 
  
  extends Modelica.Icons.Function;
  input SI.Position r[3] 
    "Position vector from world frame to actual point, resolved in world frame";
  input Integer 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 == 1 then g else if gravityType == 2 then -(mue/(
    r*r))*(r/Modelica.Mechanics.MultiBody.Frames.length(r)) else zeros(3);
end gravityAccelerationTypes;

HTML-documentation generated by Dymola Thu Feb 23 12:19:32 2006.