Modelica.Mechanics.MultiBody.Frames

Information

Package Frames contains type definitions and functions to transform rotational frame quantities. The basic idea is to hide the actual definition of an orientation in this package by providing essentially type Orientation together with functions operating on instances of this type.

Content

In the table below an example is given for every function definition. The used variables have the following declaration:

   Frames.Orientation R, R1, R2, R_rel, R_inv;
   Real[3,3]   T, T_inv;
   Real[3]     v1, v2, w1, w2, n_x, n_y, n_z, e, e_x, res_ori, phi;
   Real[6]     res_equal;
   Real        L, angle;

Package Content

Name	Description
Orientation	Orientation object defining rotation from a frame 1 into a frame 2
orientationConstraint	Return residues of orientation constraints (shall be zero)
angularVelocity1	Return angular velocity resolved in frame 1 from orientation object
angularVelocity2	Return angular velocity resolved in frame 2 from orientation object
resolve1	Transform vector from frame 2 to frame 1
resolve2	Transform vector from frame 1 to frame 2
resolveRelative	Transform vector from frame 1 to frame 2 using absolute orientation objects of frame 1 and of frame 2
resolveDyade1	Transform second order tensor from frame 2 to frame 1
resolveDyade2	Transform second order tensor from frame 1 to frame 2
nullRotation	Return orientation object that does not rotate a frame
inverseRotation	Return inverse orientation object
relativeRotation	Return relative orientation object
absoluteRotation	Return absolute orientation object from another absolute and a relative orientation object
planarRotation	Return orientation object of a planar rotation
planarRotationAngle	Return angle of a planar rotation, given the rotation axis and the representations of a vector in frame 1 and frame 2
axisRotation	Return rotation object to rotate around an angle along one frame axis
axesRotations	Return fixed rotation object to rotate in sequence around fixed angles along 3 axes
axesRotationsAngles	Return the 3 angles to rotate in sequence around 3 axes to construct the given orientation object
smallRotation	Return rotation angles valid for a small rotation and optionally residues that should be zero
from_nxy	Return fixed orientation object from n_x and n_y vectors
from_nxz	Return fixed orientation object from n_x and n_z vectors
from_T	Return orientation object R from transformation matrix T
from_T2	Return orientation object R from transformation matrix T and its derivative der(T)
from_T_inv	Return orientation object R from inverse transformation matrix T_inv
from_Q	Return orientation object R from quaternion orientation object Q
to_T	Return transformation matrix T from orientation object R
to_T_inv	Return inverse transformation matrix T_inv from orientation object R
to_Q	Return quaternion orientation object Q from orientation object R
to_vector	Map rotation object into vector
to_exy	Map rotation object into e_x and e_y vectors of frame 2, resolved in frame 1
axis	Return unit vector for x-, y-, or z-axis
Quaternions	Functions to transform rotational frame quantities based on quaternions (also called Euler parameters)
TransformationMatrices	Functions for transformation matrices

Modelica.Mechanics.MultiBody.Frames.Orientation

Information

This object describes the rotation from a frame 1 into a frame 2. An instance of this type should never be directly accessed but only with the access functions provided in package Modelica.Mechanics.MultiBody.Frames. As a consequence, it is not necessary to know the internal representation of this object as described in the next paragraphs.

"Orientation" is defined to be a record consisting of two elements: "Real T[3,3]", the transformation matrix to rotate frame 1 into frame 2 and "Real w[3]", the angular velocity of frame 2 with respect to frame 1, resolved in frame 2. Element "T" has the following interpretation:

   Orientation R;
   R.T = [ex, ey, ez];
       e.g., R.T = [1,0,0; 0,1,0; 0,0,1]

where e_x,e_y,e_z are unit vectors in the direction of the x-axis, y-axis, and z-axis of frame 1, resolved in frame 2, respectively. Therefore, if v₁ is vector v resolved in frame 1 and v₂ is vector v resolved in frame 2, the following relationship holds:

    v2 = R.T * v1

The inverse orientation R_inv.T = R.T^T describes the rotation from frame 2 into frame 1.

Since the orientation is described by 9 variables, there are 6 constraints between these variables. These constraints are defined in function Frames.orientationConstraint.

R.w is the angular velocity of frame 2 with respect to frame 1, resolved in frame 2. Formally, R.w is defined as:
skew(R.w) = R.T*der(transpose(R.T)) with

             |   0   -w[3]  w[2] |
   skew(w) = |  w[3]   0   -w[1] |
             | -w[2]  w[1]     0 |

Modelica.Mechanics.MultiBody.Frames.orientationConstraint

Information

Inputs

Name	Description
R	Orientation object to rotate frame 1 into frame 2

Outputs

Name	Description
residue[6]	Residues of constraints between elements of orientation object (shall be zero)

Modelica.Mechanics.MultiBody.Frames.angularVelocity1

Information

Inputs

Name	Description
R	Orientation object to rotate frame 1 into frame 2

Outputs

Name	Description
w[3]	Angular velocity of frame 2 with respect to frame 1 resolved in frame 1 [rad/s]

Modelica.Mechanics.MultiBody.Frames.angularVelocity2

Information

Inputs

Name	Description
R	Orientation object to rotate frame 1 into frame 2

Outputs

Name	Description
w[3]	Angular velocity of frame 2 with respect to frame 1 resolved in frame 2 [rad/s]

Modelica.Mechanics.MultiBody.Frames.resolve1

Information

Inputs

Name	Description
R	Orientation object to rotate frame 1 into frame 2
v2[3]	Vector in frame 2

Outputs

Name	Description
v1[3]	Vector in frame 1

Modelica.Mechanics.MultiBody.Frames.resolve2

Information

Inputs

Name	Description
R	Orientation object to rotate frame 1 into frame 2
v1[3]	Vector in frame 1

Outputs

Name	Description
v2[3]	Vector in frame 2

Modelica.Mechanics.MultiBody.Frames.resolveRelative

Information

Inputs

Name	Description
v1[3]	Vector in frame 1
R1	Orientation object to rotate frame 0 into frame 1
R2	Orientation object to rotate frame 0 into frame 2

Outputs

Name	Description
v2[3]	Vector in frame 2

Modelica.Mechanics.MultiBody.Frames.resolveDyade1

Information

Inputs

Name	Description
R	Orientation object to rotate frame 1 into frame 2
D2[3, 3]	Second order tensor resolved in frame 2

Outputs

Name	Description
D1[3, 3]	Second order tensor resolved in frame 1

Modelica.Mechanics.MultiBody.Frames.resolveDyade2

Information

Inputs

Name	Description
R	Orientation object to rotate frame 1 into frame 2
D1[3, 3]	Second order tensor resolved in frame 1

Outputs

Name	Description
D2[3, 3]	Second order tensor resolved in frame 2

Modelica.Mechanics.MultiBody.Frames.nullRotation

Information

Outputs

Name	Description
R	Orientation object such that frame 1 and frame 2 are identical

Modelica.Mechanics.MultiBody.Frames.inverseRotation

Information

Inputs

Name	Description
R	Orientation object to rotate frame 1 into frame 2

Outputs

Name	Description
R_inv	Orientation object to rotate frame 2 into frame 1

Modelica.Mechanics.MultiBody.Frames.relativeRotation

Information

Inputs

Name	Description
R1	Orientation object to rotate frame 0 into frame 1
R2	Orientation object to rotate frame 0 into frame 2

Outputs

Name	Description
R_rel	Orientation object to rotate frame 1 into frame 2

Modelica.Mechanics.MultiBody.Frames.absoluteRotation

Information

Inputs

Name	Description
R1	Orientation object to rotate frame 0 into frame 1
R_rel	Orientation object to rotate frame 1 into frame 2

Outputs

Name	Description
R2	Orientation object to rotate frame 0 into frame 2

Modelica.Mechanics.MultiBody.Frames.planarRotation

Information

Inputs

Name	Description
e[3]	Normalized axis of rotation (must have length=1) [1]
angle	Rotation angle to rotate frame 1 into frame 2 along axis e [rad]
der_angle	= der(angle) [rad/s]

Outputs

Name	Description
R	Orientation object to rotate frame 1 into frame 2

Modelica.Mechanics.MultiBody.Frames.planarRotationAngle

Information

A call to this function of the form

    Real[3]                e, v1, v2;
    Modelica.SIunits.Angle angle;
  equation
    angle = planarRotationAngle(e, v1, v2);

computes the rotation angle "angle" of a planar rotation along unit vector e, rotating frame 1 into frame 2, given the coordinate representations of a vector "v" in frame 1 (v1) and in frame 2 (v2). Therefore, the result of this function fulfills the following equation:

    v2 = resolve2(planarRotation(e,angle), v1)

The rotation angle is returned in the range

    -p <= angle <= p

This function makes the following assumptions on the input arguments

• Vector e has length 1, i.e., length(e) = 1
• Vector "v" is not parallel to e, i.e., length(cross(e,v1)) ≠ 0

The function does not check the above assumptions. If these assumptions are violated, a wrong result will be returned and/or a division by zero will occur.

Inputs

Name	Description
e[3]	Normalized axis of rotation to rotate frame 1 around e into frame 2 (must have length=1) [1]
v1[3]	A vector v resolved in frame 1 (shall not be parallel to e)
v2[3]	Vector v resolved in frame 2, i.e., v2 = resolve2(planarRotation(e,angle),v1)

Outputs

Name	Description
angle	Rotation angle to rotate frame 1 into frame 2 along axis e in the range: -pi <= angle <= pi [rad]

Modelica.Mechanics.MultiBody.Frames.axisRotation

Information

Inputs

Name	Description
axis	Rotate around 'axis' of frame 1
angle	Rotation angle to rotate frame 1 into frame 2 along 'axis' of frame 1 [rad]
der_angle	= der(angle) [rad/s]

Outputs

Name	Description
R	Orientation object to rotate frame 1 into frame 2

Modelica.Mechanics.MultiBody.Frames.axesRotations

Information

Inputs

Name	Description
sequence[3]	Sequence of rotations from frame 1 to frame 2 along axis sequence[i]
angles[3]	Rotation angles around the axes defined in 'sequence' [rad]
der_angles[3]	= der(angles) [rad/s]

Outputs

Name	Description
R	Orientation object to rotate frame 1 into frame 2

Modelica.Mechanics.MultiBody.Frames.axesRotationsAngles

Information

A call to this function of the form

    Frames.Orientation     R;
    parameter Integer      sequence[3] = {1,2,3};
    Modelica.SIunits.Angle angles[3];
  equation
    angle = axesRotationAngles(R, sequence);

computes the rotation angles "angles[1:3]" to rotate frame 1 into frame 2 along axes sequence[1:3], given the orientation object R from frame 1 to frame 2. Therefore, the result of this function fulfills the following equation:

    R = axesRotation(sequence, angles)

The rotation angles are returned in the range

    -p <= angles[i] <= p

There are two solutions for "angles[1]" in this range. Via the third argument guessAngle1 (default = 0) the returned solution is selected such that |angles[1] - guessAngle1| is minimal. The orientation object R may be in a singular configuration, i.e., there is an infinite number of angle values leading to the same R. The returned solution is selected by setting angles[1] = guessAngle1. Then angles[2] and angles[3] can be uniquely determined in the above range.

Note, that input argument sequence has the restriction that only values 1,2,3 can be used and that sequence[1] ≠ sequence[2] and sequence[2] ≠ sequence[3]. Often used values are:

  sequence = {1,2,3}  // Cardan angle sequence
           = {3,1,3}  // Euler angle sequence
           = {3,2,1}  // Tait-Bryan angle sequence

Inputs

Name	Description
R	Orientation object to rotate frame 1 into frame 2
sequence[3]	Sequence of rotations from frame 1 to frame 2 along axis sequence[i]
guessAngle1	Select angles[1] such that |angles[1] - guessAngle1| is a minimum [rad]

Outputs

Name	Description
angles[3]	Rotation angles around the axes defined in 'sequence' such that R=Frames.axesRotation(sequence,angles); -pi < angles[i] <= pi [rad]

Modelica.Mechanics.MultiBody.Frames.smallRotation

Information

Inputs

Name	Description
R	Orientation object to rotate frame 1 into frame 2
withResidues	= false/true, if 'angles'/'angles and residues' are returned in phi

Outputs

Name	Description
phi[if withResidues then 6 else 3]	The rotation angles around x-, y-, and z-axis of frame 1 to rotate frame 1 into frame 2 for a small rotation + optionally 3 residues that should be zero [rad]

Modelica.Mechanics.MultiBody.Frames.from_nxy

Information

It is assumed that the two input vectors n_x and n_y are resolved in frame 1 and are directed along the x and y axis of frame 2 (i.e., n_x and n_y are orthogonal to each other) The function returns the orientation object R to rotate from frame 1 to frame 2.

The function is robust in the sense that it returns always an orientation object R, even if n_y is not orthogonal to n_x. This is performed in the following way:

If n_x and n_y are not orthogonal to each other, first a unit vector e_y is determined that is orthogonal to n_x and is lying in the plane spanned by n_x and n_y. If n_x and n_y are parallel or nearly parallel to each other, a vector e_y is selected arbitrarily such that e_x and e_y are orthogonal to each other.

Inputs

Name	Description
n_x[3]	Vector in direction of x-axis of frame 2, resolved in frame 1 [1]
n_y[3]	Vector in direction of y-axis of frame 2, resolved in frame 1 [1]

Outputs

Name	Description
R	Orientation object to rotate frame 1 into frame 2

Modelica.Mechanics.MultiBody.Frames.from_nxz

Information

It is assumed that the two input vectors n_x and n_z are resolved in frame 1 and are directed along the x and z axis of frame 2 (i.e., n_x and n_z are orthogonal to each other) The function returns the orientation object R to rotate from frame 1 to frame 2.

The function is robust in the sense that it returns always an orientation object R, even if n_z is not orthogonal to n_x. This is performed in the following way:

If n_x and n_z are not orthogonal to each other, first a unit vector e_z is determined that is orthogonal to n_x and is lying in the plane spanned by n_x and n_z. If n_x and n_z are parallel or nearly parallel to each other, a vector e_z is selected arbitrarily such that n_x and e_z are orthogonal to each other.

Inputs

Name	Description
n_x[3]	Vector in direction of x-axis of frame 2, resolved in frame 1 [1]
n_z[3]	Vector in direction of z-axis of frame 2, resolved in frame 1 [1]

Outputs

Name	Description
R	Orientation object to rotate frame 1 into frame 2

Modelica.Mechanics.MultiBody.Frames.from_T

Information

Inputs

Name	Description
T[3, 3]	Transformation matrix to transform vector from frame 1 to frame 2 (v2=T*v1)
w[3]	Angular velocity from frame 2 with respect to frame 1, resolved in frame 2 (skew(w)=T*der(transpose(T))) [rad/s]

Outputs

Name	Description
R	Orientation object to rotate frame 1 into frame 2

Modelica.Mechanics.MultiBody.Frames.from_T2

Information

Computes the orientation object from a transformation matrix T and the derivative der(T) of the transformation matrix. Usually, it is more efficient to use function "from_T" instead, where the angular velocity has to be given as input argument. Only if this is not possible or too difficult to compute, use function from_T2(..).

Inputs

Name	Description
T[3, 3]	Transformation matrix to transform vector from frame 1 to frame 2 (v2=T*v1)
der_T[3, 3]	= der(T)

Outputs

Name	Description
R	Orientation object to rotate frame 1 into frame 2

Modelica.Mechanics.MultiBody.Frames.from_T_inv

Information

Inputs

Name	Description
T_inv[3, 3]	Inverse transformation matrix to transform vector from frame 2 to frame 1 (v1=T_inv*v2)
w[3]	Angular velocity from frame 1 with respect to frame 2, resolved in frame 1 (skew(w)=T_inv*der(transpose(T_inv))) [rad/s]

Outputs

Name	Description
R	Orientation object to rotate frame 1 into frame 2

Modelica.Mechanics.MultiBody.Frames.from_Q

Information

Inputs

Name	Description
Q	Quaternions orientation object to rotate frame 1 into frame 2
w[3]	Angular velocity from frame 2 with respect to frame 1, resolved in frame 2 [rad/s]

Outputs

Name	Description
R	Orientation object to rotate frame 1 into frame 2

Modelica.Mechanics.MultiBody.Frames.to_T

Information

Inputs

Name	Description
R	Orientation object to rotate frame 1 into frame 2

Outputs

Name	Description
T[3, 3]	Transformation matrix to transform vector from frame 1 to frame 2 (v2=T*v1)

Modelica.Mechanics.MultiBody.Frames.to_T_inv

Information

Inputs

Name	Description
R	Orientation object to rotate frame 1 into frame 2

Outputs

Name	Description
T_inv[3, 3]	Inverse transformation matrix to transform vector from frame 2 into frame 1 (v1=T_inv*v2)

Modelica.Mechanics.MultiBody.Frames.to_Q

Information

Inputs

Name	Description
R	Orientation object to rotate frame 1 into frame 2
Q_guess	Guess value for output Q (there are 2 solutions; the one closer to Q_guess is used

Outputs

Name	Description
Q	Quaternions orientation object to rotate frame 1 into frame 2

Modelica.Mechanics.MultiBody.Frames.to_vector

Information

Inputs

Name	Description
R	Orientation object to rotate frame 1 into frame 2

Outputs

Name	Description
vec[9]	Elements of R in one vector

Modelica.Mechanics.MultiBody.Frames.to_exy

Information

Inputs

Name	Description
R	Orientation object to rotate frame 1 into frame 2

Outputs

Name	Description
exy[3, 2]	= [e_x, e_y] where e_x and e_y are axes unit vectors of frame 2, resolved in frame 1

Modelica.Mechanics.MultiBody.Frames.axis

Information

Inputs

Name	Description
axis	Axis vector to be returned

Outputs

Name	Description
e[3]	Unit axis vector [1]