Joints

Planar(; n = [0,0,1], n_x = [1,0,0], cylinderlength = 0.1, cylinderdiameter = 0.05, cylindercolor = [1, 0, 1, 1], boxwidth = 0.3*cylinderdiameter, boxheight = boxwidth, boxcolor = [0, 0, 1, 1])

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.

Structural parameters

• n: Axis orthogonal to unconstrained plane, resolved in frame_a (= same as in frame_b)
• n_x: Vector in direction of x-axis of plane, resolved in frame_a (n_x shall be orthogonal to n)

Connectors

• frame_a: Frame for the joint
• frame_b: Frame for the joint

Variables

• s_x: Relative distance along first prismatic joint starting at frame_a
• s_y: Relative distance along second prismatic joint starting at first prismatic joint
• phi: Relative rotation angle from frame_a to frame_b
• v_x: Relative velocity along first prismatic joint
• v_y: Relative velocity along second prismatic joint
• w: Relative angular velocity around revolute joint
• a_x: Relative acceleration along first prismatic joint
• a_y: Relative acceleration along second prismatic joint
• wd: Relative angular acceleration around revolute joint

Rendering parameters

• cylinderlength: Length of the revolute cylinder
• cylinderdiameter: Diameter of the revolute cylinder
• cylindercolor: (structural) Color of the revolute cylinder
• boxwidth: Width of the prismatic joint boxes
• boxheight: Height of the prismatic joint boxes
• boxcolor: (structural) Color of the prismatic joint boxes
• radius: (structural) Radius of the revolute cylinder
• render: Enable rendering of the joint in animations

FreeMotion(; name, state = true, sequence, isroot = true, w_rel_a_fixed = false, z_rel_a_fixed = false, phi = 0, phid = 0, phidd = 0, w_rel_b = 0, r_rel_a = 0, v_rel_a = 0, a_rel_a = 0)

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 state.

Note, that bodies such as Body, BodyShape, have potential state variables 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 state of the FreeMotion object consits of:

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 (= D(r_rel_a)).

Arguments

• state: Enforce this joint having state, this is often desired and is the default choice.
• sequence: Rotation sequence, defaults to [1, 2, 3]
• w_rel_a_fixed: = true, if w_rel_a_start are used as initial values, else as guess values
• z_rel_a_fixed: = true, if z_rel_a_start are used as initial values, else as guess values

Initial condition arguments:

• phi
• phid
• phidd
• w_rel_b
• r_rel_a
• v_rel_a
• a_rel_a

GearConstraint(; name, ratio, checkTotalPower = false, n_a, n_b, r_a, r_b)

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.

• ratio: Gear ratio
• n_a: Axis of rotation of frame_a
• n_b: Axis of rotation of frame_b
• r_a: Vector from frame bearing to frame_a resolved in bearing
• r_b: Vector from frame bearing to frame_b resolved in bearing

JointRRR(;
    name,
    n_a = [0,0,1],
    n_b = [0,0,1],
    rRod1_ia = [1,0,0],
    rRod2_ib = [-1,0,0],
    phi_offset = 0, 
    phi_guess = 0,

)

This component consists of 3 revolute joints with parallel axes of rotation that are connected together by two rods.

This joint aggregation introduces neither constraints nor state variables and should therefore be used in kinematic loops whenever possible to avoid non-linear systems of equations. It is only meaningful to use this component in planar loops. Basically, the position and orientation of the 3 revolute joints as well as of frame_ia, frame_ib, and frame_im are calculated by solving analytically a non-linear equation, given the position and orientation at frame_a and at frame_b.

Connector frame_a is the "left" side of the first revolute joint whereas frame_ia is the "right side of this revolute joint, fixed in rod 1. Connector frame_b is the "right" side of the third revolute joint whereas frame_ib is the "left" side of this revolute joint, fixed in rod 2. Finally, connector frame_im is the connector at the "right" side of the revolute joint in the middle, fixed in rod 2.

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 each other (alternatively, at least frame_a, frame_ia, frame_im, frame_ib, frame_b of the JointRRR joint should be parallel to each other when defining an instance of this component).

Basically, the JointRRR model internally consists of a universal-spherical-revolute joint aggregation (= JointUSR). In a planar loop this will behave as if 3 revolute joints with parallel axes are connected by rigid rods.

Arguments

• n_a Axis of revolute joints resolved in frame_a (all axes are parallel to each other)
• n_b Axis of revolute joint fixed and resolved in frame_b
• rRod1_ia Vector from origin of frame_a to revolute joint in the middle, resolved in frame_ia
• rRod2_ib Vector from origin of frame_ib to revolute joint in the middle, resolved in frame_ib
• phi_offset Relative angle offset of revolute joint at frame_b (angle = phi(t) + phi_offset)

Connectors

• frame_a: Coordinate system fixed to the component with one cut-force and cut-torque
• frame_b: Coordinate system fixed to the component with one cut-force and cut-torque
• frame_ia: Coordinate system at origin of frame_a fixed at connecting rod of left and middle revolute joint
• frame_ib: Coordinate system at origin of frame_ib fixed at connecting rod of middle and right revolute joint
• frame_im: Coordinate system at origin of revolute joint in the middle fixed at connecting rod of middle and right revolute joint
• axis: 1-dim. rotational flange that drives the right revolute joint at frame_b
• bearing: 1-dim. rotational flange of the drive bearing of the right revolute joint at frame_b

JointUSR(;
    name,
    n1_a = [0, 0, 1],
    n_b = [0, 0, 1],
    rRod1_ia = [1, 0, 0],
    rRod1_ib = [-1, 0, 0],
    phi_offset = 0,
    phi_guess = 0,
)

This component consists of a universal joint at frame_a, a revolute joint at frame_b and a spherical joint which is connected via rod1 to the universal and via rod2 to the revolute joint.

This joint aggregation has no mass and no inertia and introduces neither constraints nor potential state variables. It should be used in kinematic loops whenever possible since the non-linear system of equations introduced by this joint aggregation is solved analytically (i.e., a solution is always computed, if a unique solution exists).

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 (= rod 1).

The definition of axis 2 of the universal joint is performed according to the most often occurring case for the sake of simplicity. Otherwise, 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 each other. Therefore, if possible n1_a should be selected in such a way that it is perpendicular to rRod1_ia in the initial configuration (i.e., the distance to the singularity is as large as possible).

The rest of this joint aggregation is defined by the following parameters:

• positive_branch: The positive branch of the revolute joint is selected (cf. elbow up vs. elbow down).
• The position of the spherical joint with respect to the universal joint is defined by vector rRod1_ia. This vector is directed from frame_a to the spherical joint and is resolved in frame_ia (it is most simple to select frame_ia such that it is parallel to frame_a in the reference or initial configuration).
• The position of the spherical joint with respect to the revolute joint is defined by vector rRod2_ib. This vector is directed from the inner frame of the revolute joint (frame_ib or revolute.frame_a) to the spherical joint and is resolved in frame_ib (note, that frame_ib and frame_b are parallel to each other).
• The axis of rotation of the revolute joint is defined by axis vector n_b. It is fixed and resolved in frame_b.
• When specifying this joint aggregation with the definitions above, two different configurations are possible. Via parameter phi_guess a guess value for revolute.phi(t0) at the initial time t0 is given. The configuration is selected that is closest to phi_guess (|revolute.phi - phi_guess| is minimal).

Connectors

• frame_a: Frame for the universal joint
• frame_b: Frame for the revolute joint
• An additional frame_ia is present. It is fixed in the rod connecting the universal and the spherical joint 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 rRod1ia, the position vector from the origin of `frameato the spherical joint, resolved inframe_ia`.
• An additional frame_ib is present. It is fixed in the rod connecting the revolute and the spherical joint at the side of the revolute joint that is connected to this rod (= rod2.frame_a = revolute.frame_a).
• An additional frame_im is present. It is fixed in the rod connecting the revolute and the spherical joint at the side of the spherical joint that is connected to this rod (= rod2.frame_b). It is always parallel to frame_ib.

Prismatic(; name, n = [0, 0, 1], axisflange = false)

Prismatic joint with 1 translational degree-of-freedom

• n: The axis of motion (unit vector)
• axisflange: If true, the joint will have two additional frames from Mechanical.Translational, axis and support, between which translational components such as springs and dampers can be connected.

If axisflange, flange connectors for ModelicaStandardLibrary.Mechanics.TranslationalModelica are also available:

• axis: 1-dim. translational flange that drives the joint
• support: 1-dim. translational flange of the drive support (assumed to be fixed in the world frame, NOT in the joint)

The function returns an ODESystem representing the prismatic joint.

PrismaticConstraint(; name, color, radius = 0.05, x_locked = true, y_locked = true, z_locked = true, render = true)

This model does not use explicit variables e.g. state variables in order to describe the relative motion of frame_b with respect to frame_a, but defines kinematic constraints between the frame_a and frame_b. The forces and torques at both frames are then evaluated in such a way that the constraints are satisfied. Sometimes this type of formulation is called an implicit joint in literature.

As a consequence of the formulation, the relative kinematics between frame_a and frame_b cannot be initialized.

In complex multibody systems with closed loops this may help to simplify the system of non-linear equations. Compare the simplification result using the classical joint formulation and this alternative formulation to check which one is more efficient for the particular system under consideration.

In systems without closed loops the use of this implicit joint does not make sense or may even be disadvantageous.

Parameters

• color: Color of the joint in animations (RGBA)
• radius: Radius of the joint in animations
• x_locked: Set to false if the translational motion in x-direction shall be free
• y_locked: Set to false if the translational motion in y-direction shall be free
• z_locked: Set to false if the translational motion in z-direction shall be free
• render: Whether or not the joint is rendered in animations

Revolute(; name, phi0 = 0, w0 = 0, n, axisflange = false)

Revolute joint with 1 rotational degree-of-freedom

• phi0: Initial angle
• w0: Iniitial angular velocity
• n: The axis of rotation
• axisflange: If true, the joint will have two additional frames from Mechanical.Rotational, axis and support, between which rotational components such as springs and dampers can be connected.

If axisflange, flange connectors for ModelicaStandardLibrary.Mechanics.Rotational are also available:

• axis: 1-dim. rotational flange that drives the joint
• support: 1-dim. rotational flange of the drive support (assumed to be fixed in the world frame, NOT in the joint)

Rendering options

• radius = 0.05: Radius of the joint in animations
• length = radius: Length of the joint in animations
• color: Color of the joint in animations, a vector of length 4 with values between [0, 1] providing RGBA values

RevolutePlanarLoopConstraint(; name, n)

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)

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 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. In this case, one revolute joint in the loop has to be replaced by model RevolutePlanarLoopConstraint. 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).

Spherical(; name, state = false, isroot = true, w_rel_a_fixed = false, z_rel_a_fixed = false, sequence, phi = 0, phid = 0, phidd = 0, d = 0)

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 state variables. If parameter state is set to true, three states are introduced. The orientation of frame_b is computed by rotating frame_a along the axes defined in parameter vector sequence (default = [1,2,3], i.e., the Cardan angle sequence) around the angles used as state. If angles are used as state there is the slight disadvantage that a singular configuration is present leading to a division by zero.

• isroot: Indicate that frame_a is the root, otherwise frame_b is the root. Only relevant if state = true.
• sequence: Rotation sequence
• d: Viscous damping constant. If d > 0. the joint dissipates energy due to viscous damping according to $τ ~ -d*ω$.

Rendering options

• radius = 0.1: Radius of the joint in animations
• color = [1,1,0,1]: Color of the joint in animations, a vector of length 4 with values between [0, 1] providing RGBA values
• render = true: Render the joint in animations

SphericalConstraint(; name, color = [1, 1, 0, 1], radius = 0.1, x_locked = true, y_locked = true, z_locked = true)

Spherical cut joint and translational directions may be constrained or released

This model does not use explicit variables e.g. state variables in order to describe the relative motion of frame_b with to respect to frame_a, but defines kinematic constraints between the frame_a and frame_b. The forces and torques at both frames are then evaluated in such a way that the constraints are satisfied. Sometimes this type of formulation is also called an implicit joint in literature.

As a consequence of the formulation the relative kinematics between frame_a and frame_b cannot be initialized.

In complex multibody systems with closed loops this may help to simplify the system of non-linear equations. Please compare state realization chosen by structural_simplify using the classical joint formulation and the alternative formulation used here in order to check whether this fact applies to the particular system under consideration. In systems without closed loops the use of this implicit joint is not recommended.

Arguments

• x_locked: Set to false if the translational motion in x-direction shall be free
• y_locked: Set to false if the translational motion in y-direction shall be free
• z_locked: Set to false if the translational motion in z-direction shall be free

Rendering parameters

• color: Color of the joint in animations (RGBA)
• radius: Radius of the joint in animations

SphericalSpherical(; name, state = false, isroot = true, iscut=false, w_rel_a_fixed = false, r_0 = [0,0,0], color = [1, 1, 0, 1], m = 0, radius = 0.1, kinematic_constraint=true)

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.

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 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 UniversalSpherical that has the additional frame frame_ia for this.

Connectors:

• frame_a: Frame for the first spherical joint
• frame_b: Frame for the second spherical joint

Rendering parameters:

• radius: Radius of the joint in animations
• color: Color of the joint in animations (RGBA)

Universal(; name, n_a, n_b, phi_a = 0, phi_b = 0, w_a = 0, w_b = 0, a_a = 0, a_b = 0, state_priority=10)

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 = D(phi_a)
• the relative angular velocity w_b = D(phi_b)

UniversalSpherical(; name, n1_a, rRod_ia, sphere_diameter = 0.1, sphere_color, rod_width = 0.1, rod_height = 0.1, rod_color, cylinder_length = 0.1, cylinder_diameter = 0.1, cylinder_color, kinematic_constraint = true)

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

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.

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 (= 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.

Note, there is a singularity when axis 1 and the connecting rod are parallel to each 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.

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 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.

Arguments

• n1_a Axis 1 of universal joint resolved in frame_a (axis 2 is orthogonal to axis 1 and to rod)
• rRod_ia Vector from origin of framea to origin of frameb, resolved in frame_ia (if computeRodLength=true, rRod_ia is only an axis vector along the connecting rod)
• kinematic_constraint = true Set to false if no constraint shall be defined, due to analytically solving a kinematic loop
• constraint_residue If set to :external, an equation in the parent system is expected to define this variable, e.g., rod.constraint_residue ~ rod.f_rod - f_rod where rod is the name of the UniversalSpherical joint. If unspecified, the length constraint rRod_0'rRod_0 - rodLength'rodLength is used

Connectors

• frame_a: Frame for the universal joint
• frame_b: Frame for the spherical joint
• frame_ia: Frame fixed in the rod at the origin of frame_a

Rendering parameters

• sphere_diameter: Diameter of spheres representing the universal and the spherical joint
• sphere_color: Color of spheres representing the universal and the spherical joint (RGBA)
• rod_width: Width of rod shape in direction of axis 2 of universal joint
• rod_height: Height of rod shape in direction that is orthogonal to rod and to axis 2
• rod_color: Color of rod shape connecting the universal and the spherical joints (RGBA)
• cylinder_length: Length of cylinders representing the two universal joint axes
• cylinder_diameter: Diameter of cylinders representing the two universal joint axes
• cylinder_color: Color of cylinders representing the two universal joint axes (RGBA)

Prismatic(; name, f, s = 0, axisflange = false)

A prismatic joint

Parameters

• r: [m, m] x,y-direction of the rod wrt. body system at phi=0
• axisflange=false: If true, a force flange is enabled, otherwise implicitly grounded"
• render: Render the joint in animations
• radius: Radius of the body in animations
• color: Color of the body in animations

Variables

• s(t): [m] Elongation of the joint
• v(t): [m/s] Velocity of elongation
• a(t): [m/s²] Acceleration of elongation
• f(t): [N] Force in direction of elongation

Connectors

• frame_a Frame
• frame_b Frame
• fixed Fixed if axisflange == false
• flange_a Flange if axisflange == true
• support Support if axisflange == true

Revolute(; name, phi = 0.0, tau = 0.0, axisflange = false)

A revolute joint

Parameters:

• axisflange=false: If true, a force flange is enabled, otherwise implicitly grounded"
• phi: [rad] Initial angular position for the flange
• tau: [Nm] Initial Cut torque in the flange

Variables:

• phi(t): [rad] angular position
• w(t): [rad/s] angular velocity
• α(t): [rad/s²] angular acceleration
• tau(t): [Nm] torque

Connectors

• frame_a Frame
• frame_b Frame
• fixed Fixed if axisflange == false
• flange_a Flange if axisflange == true
• support Support if axisflange == true