MultiBondLib.PlanarMechanics

A library for planar mechanics based upon MultiBond graphs

Information


  This is the package for planar mechanical models. It is similar in its structure
  and way of usage to the MultiBody library. 

This library offers an object-oriented solution for the modeling of planar 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. The standard multibond for planar mechanical systems is of cardinality 3 and summarizes the translational and rotational domain. The first two bonds belong to the translational domain whereas the third one is of the rotational domain. A multibond's effort vector is then {fx, fy, t} and the corresponding flow vector: {vx,vy,w}. The composition is illustrated in the next figure.

The processing of the positional variables is done by acausal signals. All bondgraphic variables and the positional signals are 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)

Efficency

The PlanarMechanics library offers a comprehensive set of ideal elements for planar mechanics. Planar 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 usually lead to a system of 2 non-linear equations.

Examples

A small set of examples demonstrate the usage of the PlanarMechanics library. They are easy to understand and offer a good starting point to make yourself familiar with this library.

Package Content

NameDescription
MultiBondLib.PlanarMechanics.PlanarWorld PlanarWorld world model for planar mechanics.World coordinate system + gravity field + default animation definition
MultiBondLib.PlanarMechanics.Interfaces Interfaces connectors of the planar mechanic objects and converters to wrap the bond graphs
MultiBondLib.PlanarMechanics.AdditionalMBG AdditionalMBG Additional multibondgraphic elements specific for planar mechanics
MultiBondLib.PlanarMechanics.Forces Forces force elements
MultiBondLib.PlanarMechanics.Joints Joints joint elements
MultiBondLib.PlanarMechanics.Parts Parts parts
MultiBondLib.PlanarMechanics.Examples Examples examples for planar mechanics
MultiBondLib.PlanarMechanics.Types Types additional type definitions specific for 3D-Mechanics


MultiBondLib.PlanarMechanics.PlanarWorld MultiBondLib.PlanarMechanics.PlanarWorld

world model for planar mechanics.World coordinate system + gravity field + default animation definition

Information


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

    inner PlanarMechanics.PlanarWorld planarWorld

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


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
TempgravityTypeModelica.Mechanics.MultiBody...Type of gravity field
Accelerationg9.81 Constant gravity acceleration [m/s2]
Axisn[3]{0,-1,0} Direction of gravity resolved in world frame (gravity = g*n/length(n))
Realmue3.986e14 Gravity field constant (default = field constant of earth) [m3/s2]
Animation
if animateWorld = true
DistanceaxisLengthnominalLength/2 Length of world axes arrows [m]
DistanceaxisDiameteraxisLength/defaultFrameDiame... Diameter of world axes arrows [m]
BooleanaxisShowLabelstrue = true, if labels shall be shown
ColoraxisColor_x[3]Modelica.Mechanics.MultiBody... Color of x-arrow
ColoraxisColor_y[3]axisColor_x Color of y-arrow
ColoraxisColor_z[3]axisColor_x Color 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/2 Length of gravity arrow [m]
DiametergravityArrowDiametergravityArrowLength/defaultWi... Diameter of gravity arrow [m]
ColorgravityArrowColor[3]{0,230,0} Color of gravity arrow
if animateGravity = true and gravityType = PointGravity
DiametergravitySphereDiameter12742000 Diameter of sphere representing gravity center (default = mean diameter of earth) [m]
ColorgravitySphereColor[3]{0,230,0} Color of gravity sphere
Defaults
LengthnominalLength1 "Nominal" length of multi-body system [m]
LengthdefaultAxisLengthnominalLength/5 Default for length of a frame axis (but not world frame) [m]
LengthdefaultJointLengthnominalLength/10 Default for the fixed length of a shape representing a joint [m]
LengthdefaultJointWidthnominalLength/20 Default for the fixed width of a shape representing a joint [m]
LengthdefaultForceLengthnominalLength/10 Default for the fixed length of a shape representing a force (e.g. damper) [m]
LengthdefaultForceWidthnominalLength/20 Default for the fixed width of a shape represening a force (e.g. spring, bushing) [m]
LengthdefaultBodyDiameternominalLength/9 Default for diameter of sphere representing the center of mass of a body [m]
RealdefaultWidthFraction20 Default for shape width as a fraction of shape length (e.g., for Parts.FixedTranslation)
LengthdefaultArrowDiameternominalLength/40 Default for arrow diameter (e.g., of forces, torques, sensors) [m]
RealdefaultFrameDiameterFraction40 Default for arrow diameter of a coordinate system as a fraction of axis length
ColordefaultJointColor[3]{255,0,255} Default color of a joint element
ColordefaultBodyColor[3]{0,64,255} Default color of a body element
ColordefaultRodColor[3]{96,128,128} Default color of a rod element
ColordefaultForceElementColor[3]{0,64,255} Default color of a rod element

Modelica definition

model PlanarWorld 
  "world model for planar mechanics.World 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 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";
  
  /* 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 PlanarWorld;

MultiBondLib.PlanarMechanics.PlanarWorld.gravityAccelerationTypes MultiBondLib.PlanarMechanics.PlanarWorld.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 Aug 31 09:47:34 2006.