Modelica.Mechanics.MultiBody.Joints

Components that constrain the motion between two frames

Information

This package contains joint components, that is, idealized, massless elements that constrain the motion between frames. In subpackage Assemblies aggregation joint components are provided to handle kinematic loops analytically (this means that non-linear systems of equations occurring in these joint aggregations are analytically solved, i.e., robustly and efficiently).

Content

Model	Description
Prismatic	Prismatic joint and actuated prismatic joint (1 translational degree-of-freedom, 2 potential states)
Revolute	Revolute and actuated revolute joint (1 rotational degree-of-freedom, 2 potential states)
Cylindrical	Cylindrical joint (2 degrees-of-freedom, 4 potential states)
Universal	Universal joint (2 degrees-of-freedom, 4 potential states)
Planar	Planar joint (3 degrees-of-freedom, 6 potential states)
Spherical	Spherical joint (3 constraints and no potential states, or 3 degrees-of-freedom and 3 states)
FreeMotion	Free motion joint (6 degrees-of-freedom, 12 potential states)
SphericalSpherical	Spherical - spherical joint aggregation (1 constraint, no potential states) with an optional point mass in the middle
UniversalSpherical	Universal - spherical joint aggregation (1 constraint, no potential states)
GearConstraint	Ideal 3-dim. gearbox (arbitrary shaft directions)
MultiBody.Joints.Assemblies	Package of joint aggregations for analytic loop handling.
MultiBody.Joints.Constraints	Package of components that define joints by constraints

Extends from Modelica.Icons.Package (Icon for standard packages).

Package Content

Name	Description
Prismatic	Prismatic joint (1 translational degree-of-freedom, 2 potential states, optional axis flange)
Revolute	Revolute joint (1 rotational degree-of-freedom, 2 potential states, optional axis flange)
RevolutePlanarLoopConstraint	Revolute joint that is described by 2 positional constraints for usage in a planar loop (the ambiguous cut-force perpendicular to the loop and the ambiguous cut-torques are set arbitrarily to zero)
Cylindrical	Cylindrical joint (2 degrees-of-freedom, 4 potential states)
Universal	Universal joint (2 degrees-of-freedom, 4 potential states)
Planar	Planar joint (3 degrees-of-freedom, 6 potential states)
Spherical	Spherical joint (3 constraints and no potential states, or 3 degrees-of-freedom and 3 states)
FreeMotion	Free motion joint (6 degrees-of-freedom, 12 potential states)
FreeMotionScalarInit	Free motion joint with scalar initialization and state selection (6 degrees-of-freedom, 12 potential states)
SphericalSpherical	Spherical - spherical joint aggregation (1 constraint, no potential states) with an optional point mass in the middle
UniversalSpherical	Universal - spherical joint aggregation (1 constraint, no potential states)
GearConstraint	Ideal 3-dim. gearbox (arbitrary shaft directions)
RollingWheel	Joint (no mass, no inertia) that describes an ideal rolling wheel (rolling on the plane z=0)
RollingWheelSet	Joint (no mass, no inertia) that describes an ideal rolling wheel set (two ideal rolling wheels connected together by an axis)
Assemblies	Components that aggregate several joints for analytic loop handling
Constraints	Components that define joints by constraints
Internal	Components used for analytic solution of kinematic loops (use only if you know what you are doing)

Modelica.Mechanics.MultiBody.Joints.Prismatic

Prismatic joint (1 translational degree-of-freedom, 2 potential states, optional axis flange)

Information

Joint where frame_b is translated along axis n which is fixed in frame_a. The two frames coincide when the relative distance "s = 0".

Optionally, two additional 1-dimensional mechanical flanges (flange "axis" represents the driving flange and flange "support" represents the bearing) can be enabled via parameter useAxisFlange. The enabled axis flange can be driven with elements of the Modelica.Mechanics.Translational library.

In the "Advanced" menu it can be defined via parameter stateSelect that the relative distance "s" and its derivative shall be definitely used as states by setting stateSelect=StateSelect.always. Default is StateSelect.prefer to use the relative distance and its derivative as preferred states. The states are usually selected automatically. In certain situations, especially when closed kinematic loops are present, it might be slightly more efficient, when using the StateSelect.always setting.

In the following figure the animation of a prismatic joint is shown. The light blue coordinate system is frame_a and the dark blue coordinate system is frame_b of the joint. The black arrow is parameter vector "n" defining the translation axis (here: n = {1,1,0}).

Extends from Modelica.Mechanics.MultiBody.Interfaces.PartialElementaryJoint (Base model for elementary joints (has two frames + outer world + assert to guarantee that the joint is connected)).

Parameters

Connectors

Modelica.Mechanics.MultiBody.Joints.Revolute

Revolute joint (1 rotational degree-of-freedom, 2 potential states, optional axis flange)

Information

Joint where frame_b rotates around axis n which is fixed in frame_a. The two frames coincide when the rotation angle "phi = 0".

Optionally, two additional 1-dimensional mechanical flanges (flange "axis" represents the driving flange and flange "support" represents the bearing) can be enabled via parameter useAxisFlange. The enabled axis flange can be driven with elements of the Modelica.Mechanics.Rotational library.

In the "Advanced" menu it can be defined via parameter stateSelect that the rotation angle "phi" and its derivative shall be definitely used as states by setting stateSelect=StateSelect.always. Default is StateSelect.prefer to use the joint angle and its derivative as preferred states. The states are usually selected automatically. In certain situations, especially when closed kinematic loops are present, it might be slightly more efficient, when using the StateSelect.always setting.

If a planar loop is present, e.g., consisting of 4 revolute joints where the joint axes are all parallel to each other, then there is no longer a unique mathematical solution and the symbolic algorithms will fail. Usually, an error message will be printed pointing out this situation. In this case, one revolute joint of the loop has to be replaced by a Joints.RevolutePlanarLoopConstraint joint. The effect is that from the 5 constraints of a usual revolute joint, 3 constraints are removed and replaced by appropriate known variables (e.g., the force in the direction of the axis of rotation is treated as known with value equal to zero; for standard revolute joints, this force is an unknown quantity).

In the following figure the animation of a revolute joint is shown. The light blue coordinate system is frame_a and the dark blue coordinate system is frame_b of the joint. The black arrow is parameter vector "n" defining the translation axis (here: n = {0,0,1}, phi.start = 45^o).

Parameters

Connectors

Modelica.Mechanics.MultiBody.Joints.RevolutePlanarLoopConstraint

Revolute joint that is described by 2 positional constraints for usage in a planar loop (the ambiguous cut-force perpendicular to the loop and the ambiguous cut-torques are set arbitrarily to zero)

Information

Joint where frame_b rotates around axis n which is fixed in frame_a and where this joint is used in a planar loop providing 2 constraint equations on position level.

If a planar loop is present, e.g., consisting of 4 revolute joints where the joint axes are all parallel to each other, then there is no unique mathematical solution if all revolute joints are modelled with Joints.Revolute and the symbolic algorithms will fail. The reason is that, e.g., the cut-forces in the revolute joints perpendicular to the planar loop are not uniquely defined when 3-dim. descriptions of revolute joints are used. Usually, an error message will be printed pointing out this situation. In this case, one revolute joint in the loop has to be replaced by model Joints.RevolutePlanarLoopCutJoint. The effect is that from the 5 constraints of a 3-dim. revolute joint, 3 constraints are removed and replaced by appropriate known variables (e.g., the force in the direction of the axis of rotation is treated as known with value equal to zero; for standard revolute joints, this force is an unknown quantity).

Parameters

Connectors

Modelica.Mechanics.MultiBody.Joints.Cylindrical

Cylindrical joint (2 degrees-of-freedom, 4 potential states)

Information

Joint where frame_b rotates around and translates along axis n which is fixed in frame_a. The two frames coincide when "phi=revolute.phi=0" and "s=prismatic.s=0". This joint has the following potential states;

• The relative angle phi [rad] around axis n,
• the relative distance s [m] along axis n,
• the relative angular velocity w [rad/s] (= der(phi)) and
• the relative velocity v [m/s] (= der(s)).

They are used as candidates for automatic selection of states from the tool. This may be enforced by setting "stateSelect=StateSelect.always" in the Advanced menu. The states are usually selected automatically. In certain situations, especially when closed kinematic loops are present, it might be slightly more efficient, when using the "StateSelect.always" setting.

In the following figure the animation of a cylindrical joint is shown. The light blue coordinate system is frame_a and the dark blue coordinate system is frame_b of the joint. The black arrow is parameter vector "n" defining the cylinder axis (here: n = {0,0,1}).

Extends from Modelica.Mechanics.MultiBody.Interfaces.PartialTwoFrames (Base model for components providing two frame connectors + outer world + assert to guarantee that the component is connected).

Parameters

Connectors

Modelica.Mechanics.MultiBody.Joints.Universal

Universal joint (2 degrees-of-freedom, 4 potential states)

Information

Joint where frame_a rotates around axis n_a which is fixed in frame_a and frame_b rotates around axis n_b which is fixed in frame_b. The two frames coincide when "revolute_a.phi=0" and "revolute_b.phi=0". This joint has the following potential states;

• The relative angle phi_a = revolute_a.phi [rad] around axis n_a,
• the relative angle phi_b = revolute_b.phi [rad] around axis n_b,
• the relative angular velocity w_a (= der(phi_a)) and
• the relative angular velocity w_b (= der(phi_b)).

They are used as candidates for automatic selection of states from the tool. This may be enforced by setting "stateSelect=StateSelect.always" in the Advanced menu. The states are usually selected automatically. In certain situations, especially when closed kinematic loops are present, it might be slightly more efficient, when using the "StateSelect.always" setting.

In the following figure the animation of a universal joint is shown. The light blue coordinate system is frame_a and the dark blue coordinate system is frame_b of the joint (here: n_a = {0,0,1}, n_b = {0,1,0}, phi_a.start = 90^o, phi_b.start = 45^o).

Extends from Modelica.Mechanics.MultiBody.Interfaces.PartialTwoFrames (Base model for components providing two frame connectors + outer world + assert to guarantee that the component is connected).

Parameters

Connectors

Modelica.Mechanics.MultiBody.Joints.Planar

Planar joint (3 degrees-of-freedom, 6 potential states)

Information

Joint where frame_b can move in a plane and can rotate around an axis orthogonal to the plane. The plane is defined by vector n which is perpendicular to the plane and by vector n_x, which points in the direction of the x-axis of the plane. frame_a and frame_b coincide when s_x=prismatic_x.s=0, s_y=prismatic_y.s=0 and phi=revolute.phi=0. This joint has the following potential states:

• the relative distance s_x = prismatic_x.s [m] along axis n_x,
• the relative distance s_y = prismatic_y.s [m] along axis n_y = cross(n,n_x),
• the relative angle phi = revolute.phi [rad] around axis n,
• the relative velocity v_x (= der(s_x)).
• the relative velocity v_y (= der(s_y)).
• the relative angular velocity w (= der(phi))

They are used as candidates for automatic selection of states from the tool. This may be enforced by setting "stateSelect=StateSelect.always" in the Advanced menu. The states are usually selected automatically. In certain situations, especially when closed kinematic loops are present, it might be slightly more efficient, when using the "StateSelect.always" setting.

In the following figure the animation of a planar joint is shown. The light blue coordinate system is frame_a and the dark blue coordinate system is frame_b of the joint. The black arrows are parameter vectors "n" and "n_x" (here: n = {0,1,0}, n_x = {0,0,1}, s_x.start = 0.5, s_y.start = 0.5, phi.start = 45^o).

Extends from Modelica.Mechanics.MultiBody.Interfaces.PartialTwoFrames (Base model for components providing two frame connectors + outer world + assert to guarantee that the component is connected).

Parameters

Connectors

Modelica.Mechanics.MultiBody.Joints.Spherical

Spherical joint (3 constraints and no potential states, or 3 degrees-of-freedom and 3 states)

Information

Joint with 3 constraints that define that the origin of frame_a and the origin of frame_b coincide. By default this joint defines only the 3 constraints without any potential states. If parameter enforceStates is set to true in the "Advanced" menu, three states are introduced. Depending on parameter useQuaternions these are either quaternions and the relative angular velocity or 3 angles and the angle derivatives. In the latter case the orientation of frame_b is computed by rotating frame_a along the axes defined in parameter vector "sequence_angleStates" (default = {1,2,3}, i.e., the Cardan angle sequence) around the angles used as states. For example, the default is to rotate the x-axis of frame_a around angles[1], the new y-axis around angles[2] and the new z-axis around angles[3], arriving at frame_b. If angles are used as states there is the slight disadvantage that a singular configuration is present leading to a division by zero.

If this joint is used in a chain structure, a Modelica translator has to select orientation coordinates of a body as states, if the default setting is used. It is usually better to use relative coordinates in the spherical joint as states, and therefore in this situation parameter enforceStates might be set to true.

If this joint is used in a loop structure, the default setting results in a cut-joint that breaks the loop in independent kinematic pieces, hold together by the constraints of this joint. As a result, a Modelica translator will first try to select 3 generalized coordinates in the joints of the remaining parts of the loop and their first derivative as states and if this is not possible, e.g., because there are only spherical joints in the loop, will select coordinates from a body of the loop as states.

In the following figure the animation of a spherical joint is shown. The light blue coordinate system is frame_a and the dark blue coordinate system is frame_b of the joint. (here: angles_start = {45, 45, 45}^o).

Extends from Modelica.Mechanics.MultiBody.Interfaces.PartialTwoFrames (Base model for components providing two frame connectors + outer world + assert to guarantee that the component is connected).

Parameters

Connectors

Modelica.Mechanics.MultiBody.Joints.FreeMotion

Free motion joint (6 degrees-of-freedom, 12 potential states)

Information

Joint which does not constrain the motion between frame_a and frame_b. Such a joint is only meaningful if the relative distance and orientation between frame_a and frame_b, and their derivatives, shall be used as states.

Note, that bodies such as Parts.Body, Parts.BodyShape, have potential states describing the distance and orientation, and their derivatives, between the world frame and a body fixed frame. Therefore, if these potential state variables are suited, a FreeMotion joint is not needed.

The states of the FreeMotion object are:

• The relative position vector r_rel_a from the origin of frame_a to the origin of frame_b, resolved in frame_a and the relative velocity v_rel_a of the origin of frame_b with respect to the origin of frame_a, resolved in frame_a (= der(r_rel_a)).
• If parameter useQuaternions in the "Advanced" menu is true (this is the default), then 4 quaternions are states. Additionally, the coordinates of the relative angular velocity vector are 3 potential states.
  If useQuaternions in the "Advanced" menu is false, then 3 angles and the derivatives of these angles are potential states. The orientation of frame_b is computed by rotating frame_a along the axes defined in parameter vector "sequence_angleStates" (default = {1,2,3}, i.e., the Cardan angle sequence) around the angles used as states. For example, the default is to rotate the x-axis of frame_a around angles[1], the new y-axis around angles[2] and the new z-axis around angles[3], arriving at frame_b.

The quaternions have the slight disadvantage that there is a non-linear constraint equation between the 4 quaternions. Therefore, at least one non-linear equation has to be solved during simulation. A tool might, however, analytically solve this simple constraint equation. Using the 3 angles as states has the disadvantage that there is a singular configuration in which a division by zero will occur. If it is possible to determine in advance for an application class that this singular configuration is outside of the operating region, the 3 angles might be used as states by setting useQuaternions = false.

In text books about 3-dimensional mechanics often 3 angles and the angular velocity are used as states. This is not the case here, since 3 angles and their derivatives are used as states (if useQuaternions = false). The reason is that for real-time simulation the discretization formula of the integrator might be "inlined" and solved together with the model equations. By appropriate symbolic transformation the performance is drastically increased if angles and their derivatives are used as states, instead of angles and the angular velocity.

If parameter enforceStates is set to true (= the default) in the "Advanced" menu, then FreeMotion variables are forced to be used as states according to the setting of parameters "useQuaternions" and "sequence_angleStates".

In the following figure the animation of a FreeMotion joint is shown. The light blue coordinate system is frame_a and the dark blue coordinate system is frame_b of the joint. (here: r_rel_a_start = {0.5, 0, 0.5}, angles_start = {45, 45, 45}^o).

Extends from Modelica.Mechanics.MultiBody.Interfaces.PartialTwoFrames (Base model for components providing two frame connectors + outer world + assert to guarantee that the component is connected).

Parameters

Connectors

Modelica.Mechanics.MultiBody.Joints.FreeMotionScalarInit

Free motion joint with scalar initialization and state selection (6 degrees-of-freedom, 12 potential states)

Information

Joint which does not constrain the motion between frame_a and frame_b. Such a joint is meaningful if the relative distance and orientation between frame_a and frame_b, and their derivatives, shall be used as states or shall be used for non-standard initialization. This joint allows to initialize every scalar element of the relative quantities, as well as to define StateSelect attributes for every scalar element separately.

In the following figure the animation of a FreeMotionScalarInit joint is shown. The light blue coordinate system is frame_a and the dark blue coordinate system is frame_b of the joint. (here: r_rel_a_1(start = 0.5), r_rel_a_2(start = 0), r_rel_a_3(start = 0.5), angle_1(start = 45^o), angle_2(start = 45^o), angle_3(start = 45^o)).

A example to use this joint for the initialization of a planar double pendulum by providing its tip position, is shown in Examples.Elementary.DoublePendulumInitTip.

Extends from Modelica.Mechanics.MultiBody.Interfaces.PartialTwoFrames (Base model for components providing two frame connectors + outer world + assert to guarantee that the component is connected).

Parameters

Connectors

Modelica.Mechanics.MultiBody.Joints.SphericalSpherical

Spherical - spherical joint aggregation (1 constraint, no potential states) with an optional point mass in the middle

Information

Joint that has a spherical joint on each of its two ends. The rod connecting the two spherical joints is approximated by a point mass that is located in the middle of the rod. When the mass is set to zero (default), special code for a massless body is generated. In the following default animation figure, the two spherical joints are represented by two red spheres, the connecting rod by a grey cylinder and the point mass in the middle of the rod by a light blue sphere:

This joint introduces one constraint defining that the distance between the origin of frame_a and the origin of frame_b is constant (= rodLength). It is highly recommended to use this joint in loops whenever possible, because this enhances the efficiency considerably due to smaller systems of non-linear algebraic equations.

It is sometimes desirable to compute the rodLength of the connecting rod during initialization. For this, parameter computeLength has to be set to true and instead one other, easier to determine, position variable in the same loop needs to have a fixed attribute of true. For example, if a loop consists of one Revolute joint, one Prismatic joint and a SphericalSpherical joint, one may fix the start values of the revolute joint angle and of the relative distance of the prismatic joint in order to compute the rodLength of the rod.

It is not possible to connect other components, such as a body with mass properties or a special visual shape object to the rod connecting the two spherical joints. If this is needed, use instead joint Joints.UniversalSpherical that has this property.

Extends from Interfaces.PartialTwoFrames (Base model for components providing two frame connectors + outer world + assert to guarantee that the component is connected).

Parameters

Connectors

Modelica.Mechanics.MultiBody.Joints.UniversalSpherical

Universal - spherical joint aggregation (1 constraint, no potential states)

Information

This component consists of a universal joint at frame_a and a spherical joint at frame_b that are connected together with a rigid rod, see default animation figure (the arrows are not part of the default animation):

This joint aggregation has no mass and no inertia and introduces the constraint that the distance between the origin of frame_a and the origin of frame_b is constant (= Frames.length(rRod_ia)). The universal joint is defined in the following way:

• The rotation axis of revolute joint 1 is along parameter vector n1_a which is fixed in frame_a.
• The rotation axis of revolute joint 2 is perpendicular to axis 1 and to the line connecting the universal and the spherical joint.

The definition of axis 2 of the universal joint is performed according to the most often occurring case. In a future release, axis 2 might be explicitly definable via a parameter. However, the treatment is much more complicated and the number of operations is considerably higher, if axis 2 is not orthogonal to axis 1 and to the connecting rod.

Note, there is a singularity when axis 1 and the connecting rod are parallel to other. Therefore, if possible n1_a should be selected in such a way that it is perpendicular to rRod_ia in the initial configuration (i.e., the distance to the singularity is as large as possible).

An additional frame_ia is present. It is fixed in the connecting rod at the origin of frame_a. The placement of frame_ia on the rod is implicitly defined by the universal joint (frame_a and frame_ia coincide when the angles of the two revolute joints of the universal joint are zero) and by parameter vector rRod_ia, the position vector from the origin of frame_a to the origin of frame_b, resolved in frame_ia.

The easiest way to define the parameters of this joint is by moving the MultiBody system in a reference configuration where all frames of all components are parallel to other (alternatively, at least frame_a and frame_ia of the UniversalSpherical joint should be parallel to other when defining an instance of this component). Since frame_a and frame_ia are parallel to other, vector rRod_ia from frame_a to frame_b resolved in frame_ia can be resolved in frame_a (or the world frame, if all frames are parallel to other).

This joint aggregation can be used in cases where in reality a rod with spherical joints at end are present. Such a system has an additional degree of freedom to rotate the rod along its axis. In practice this rotation is usually of no interest and is mathematically removed by replacing one of the spherical joints by a universal joint. Still, in most cases the Joints.SphericalSpherical joint aggregation can be used instead of the UniversalSpherical joint since the rod is animated and its mass properties are approximated by a point mass in the middle of the rod. The SphericalSpherical joint has the advantage that it does not have a singular configuration.

In the public interface of the UniversalSpherical joint, the following (final) parameters are provided:

  parameter Real rodLength(unit="m")  "Length of rod";
  parameter Real eRod_ia[3] "Unit vector along rod, resolved in frame_ia";
  parameter Real e2_ia  [3] "Unit vector along axis 2, resolved in frame_ia";

This allows a more convenient definition of data which is related to the rod. For example, if a box shall be connected at frame_ia directing from the origin of frame_a to the middle of the rod, this might be defined as:

    Modelica.Mechanics.MultiBody.Joints.UniversalSpherical jointUS(rRod_ia={1.2, 1, 0.2});
    Modelica.Mechanics.MultiBody.Visualizers.FixedShape    shape(shapeType       = "box",
                                              lengthDirection = jointUS.eRod_ia,
                                              widthDirection  = jointUS.e2_ia,
                                              length          = jointUS.rodLength/2,
                                              width           = jointUS.rodLength/10);
  equation
    connect(jointUS.frame_ia, shape.frame_a);

Extends from Interfaces.PartialTwoFrames (Base model for components providing two frame connectors + outer world + assert to guarantee that the component is connected).

Parameters

Connectors

Modelica.Mechanics.MultiBody.Joints.GearConstraint

Ideal 3-dim. gearbox (arbitrary shaft directions)

Information

This ideal massless joint provides a gear constraint between frames frame_a and frame_b. The axes of rotation of frame_a and frame_b may be arbitrary.

Reference
Schweiger, Christian ; Otter, Martin: Modelling 3D Mechanical Effects of 1-dim. Powertrains. In: Proceedings of the 3rd International Modelica Conference. Linköping : The Modelica Association and Linköping University, November 3-4, 2003, pp. 149-158

Extends from Modelica.Mechanics.MultiBody.Interfaces.PartialTwoFrames (Base model for components providing two frame connectors + outer world + assert to guarantee that the component is connected).

Parameters

Connectors

Modelica.Mechanics.MultiBody.Joints.RollingWheel

Joint (no mass, no inertia) that describes an ideal rolling wheel (rolling on the plane z=0)

Information

A joint for a wheel rolling on the x-y plane of the world frame. The rolling contact is considered being ideal, i.e. there is no slip between the wheel and the ground. This is simply gained by two non-holonomic constraint equations on velocity level defined for both longitudinal and lateral direction of the wheel. There is also a holonomic constraint equation on position level granting a permanent contact of the wheel to the ground, i.e. the wheel can not take off.

The origin of the frame frame_a is placed in the intersection of the wheel spin axis with the wheel middle plane and rotates with the wheel itself. The y-axis of frame_a is identical with the wheel spin axis, i.e. the wheel rotates about y-axis of frame_a. A wheel body collecting the mass and inertia should be connected to this frame.

Note

To work properly, the gravity acceleration vector g of the world must point in the negative z-axis, i.e.

inner Modelica.Mechanics.MultiBody.World world(n={0,0,-1});

Parameters

Connectors

Modelica.Mechanics.MultiBody.Joints.RollingWheelSet

Joint (no mass, no inertia) that describes an ideal rolling wheel set (two ideal rolling wheels connected together by an axis)

Information

An assembly joint for a wheelset rolling on the x-y plane of the world frame. The frames frame1 and frame2 are connected to rotating wheels; the frameMiddle moves in a plane parallel to the x-y plane of the world and should be connected to the vehicle body.

Note

To work properly, the gravity acceleration vector g of the world must point in the negative z-axis, i.e.

inner Modelica.Mechanics.MultiBody.World world(n={0,0,-1});

Parameters

Connectors