<!-- GENERATED by tools/generators/itemDocsEmitter.py from definitions/ - do not edit -->
```{raw} latex
\clearpage
```

(sec-item-noderigidbodyep)=
# NodeRigidBodyEP

A 3D rigid body node based on Euler parameters for rigid bodies or beams. The node has 3 displacement coordinates (representing displacement of reference point $\LU{0}{\rv}$) and four rotation coordinates (Euler parameters = unit quaternions).

## Interface

- Python names: `NodeRigidBodyEP` or `RigidEP`, and `VRigidEP` for its visualization
- Provides: `Position`, `Orientation`, `RigidBody`, `RotationEulerParameters`
- Node markers that can be attached: [](#sec-item-markernodeposition), [](#sec-item-markernoderigid), [](#sec-item-markernoderotationcoordinate)
- Objects that take this node: [](#sec-item-objectmasspoint), [](#sec-item-objectrigidbody), [](#sec-item-objectbeamgeometricallyexact)

## Parameters

The parameters of the item; in a dictionary, its type is 'RigidBodyEP':

| name | type | size | default | description |
|---|---|---|---|---|
| **name** | String |  | '' | node's unique name |
| **referenceCoordinates** | Vector7D | 7 | [0.,0.,0., 0.,0.,0.,0.] | (symbol: $\qv\cRef = [q_0,\,q_1,\,q_2,\,\psi_0,\,\psi_1,\,\psi_2,\,\psi_3]\tp\cRef = [\pv\tp\cRef,\,\tpsi\tp\cRef]\tp$) reference coordinates (3 position coordinates and 4 Euler parameters) of node ==> e.g. ref. coordinates for finite elements or reference position of rigid body (e.g. for definition of joints) |
| **initialCoordinates** | Vector7D | 7 | [0.,0.,0., 0.,0.,0.,0.] | (symbol: $\qv\cIni = [q_0,\,q_1,\,q_2,\,\psi_0,\,\psi_1,\,\psi_2,\,\psi_3]\tp\cIni = [\uv\tp\cIni,\,\tpsi\tp\cIni]\tp$) initial displacement coordinates and 4 Euler parameters relative to reference coordinates |
| **initialVelocities** | Vector7D | 7 | [0.,0.,0., 0.,0.,0.,0.] | (symbol: $\dot \qv\cIni = [\dot q_0,\,\dot q_1,\,\dot q_2,\,\dot \psi_0,\,\dot \psi_1,\,\dot \psi_2,\,\dot \psi_3]\tp\cIni = [\dot \uv\tp\cIni,\,\dot \tpsi\tp\cIni]\tp$) initial velocity coordinates: time derivatives of initial displacements and Euler parameters |
| **addConstraintEquation** | Bool |  | True | True: automatically add Euler parameter constraint for node; False: Euler parameter constraint is not added, must be done manually (e.g., with CoordinateVectorConstraint) |
| **visualization** | VNodeRigidBodyEP |  |  | parameters for visualization of item |

## Visualization parameters

The parameters of `VNodeRigidBodyEP`, given as `visualization`:

| name | type | size | default | description |
|---|---|---|---|---|
| **show** | Bool |  | True | set true, if item is shown in visualization and false if it is not shown |
| **drawSize** | float |  | -1. | drawing size (diameter, dimensions of underlying cube, etc.) for item; size == -1.f means that default size is used |
| **color** | Float4 | 4 | [-1.,-1.,-1.,-1.] | Default RGBA color for nodes; 4th value is alpha-transparency; R=-1.f means, that default color is used |

## Drawing

Drawn as [all nodes](#sec-drawing-nodes); with `nodes.showBasis`, also its frame, of length `nodes.basisSize`.

Settings beyond those of all nodes: [`general.axesTiling`](#sec-vsettingsgeneral), [`nodes.basisSize`](#sec-vsettingsnodes), [`nodes.showBasis`](#sec-vsettingsnodes).

## Output variables

Available as `OutputVariableType` in sensors, `Get...Output()` and other functions:

```{tabularcolumns} \Y{0.25}\Y{0.25}\Y{0.5}
```

| output variable | symbol | description |
|---|---|---|
| Position | $\LU{0}{\pv}\cConfig = \LU{0}{[p_0,\,p_1,\,p_2]}\cConfig\tp= \LU{0}{\uv}\cConfig + \LU{0}{\pv}\cRef$ | global 3D position vector of node; $\uv\cRef=0$ |
| Displacement | $\LU{0}{\uv}\cConfig = [q_0,\,q_1,\,q_2]\cConfig\tp$ | global 3D displacement vector of node |
| Velocity | $\LU{0}{\vv}\cConfig = [\dot q_0,\,\dot q_1,\,\dot q_2]\cConfig\tp$ | global 3D velocity vector of node |
| Acceleration | $\LU{0}{\av}\cConfig = [\ddot q_0,\,\ddot q_1,\,\ddot q_2]\cConfig\tp$ | global 3D acceleration vector of node |
| CoordinatesTotal |  | displacement/rotation coordinates of node including reference configuration |
| Coordinates | $\cv\cConfig = [q_0,\,q_1,\,q_2, \,\psi_0,\,\psi_1,\,\psi_2,\,\psi_3]\tp\cConfig$ | coordinate vector of node, having 3 displacement coordinates and 4 Euler parameters |
| Coordinates_t | $\dot\cv\cConfig = [\dot q_0,\,\dot q_1,\,\dot q_2, \,\dot \psi_0,\,\dot \psi_1,\,\dot \psi_2,\,\dot \psi_3]\tp\cConfig$ | velocity coordinates vector of node |
| Coordinates_tt | $\ddot\cv\cConfig = [\ddot q_0,\,\ddot q_1,\,\ddot q_2, \,\ddot \psi_0,\,\ddot \psi_1,\,\ddot \psi_2,\,\ddot \psi_3]\tp\cConfig$ | acceleration coordinates vector of node |
| RotationMatrix | $[A_{00},\,A_{01},\,A_{02},\,A_{10},\,\ldots,\,A_{21},\,A_{22}]\cConfig\tp$ | vector with 9 components of the rotation matrix $\LU{0b}{\Rot}\cConfig$ in row-major format, in any configuration; the rotation matrix transforms local ($b$) to global (0) coordinates |
| Rotation | $[\varphi_0,\,\varphi_1,\,\varphi_2]\tp\cConfig$ | vector with 3 components of the Euler/Tait-Bryan angles in xyz-sequence ($\LU{0b}{\Rot}\cConfig=:\Rot_0(\varphi_0) \cdot \Rot_1(\varphi_1) \cdot \Rot_2(\varphi_2)$), recomputed from rotation matrix |
| AngularVelocity | $\LU{0}{\tomega}\cConfig = \LU{0}{[\omega_0,\,\omega_1,\,\omega_2]}\cConfig\tp$ | global 3D angular velocity vector of node |
| AngularVelocityLocal | $\LU{b}{\tomega}\cConfig = \LU{b}{[\omega_0,\,\omega_1,\,\omega_2]}\cConfig\tp$ | local (body-fixed) 3D angular velocity vector of node |
| AngularAcceleration | $\LU{0}{\talpha}\cConfig = \LU{0}{[\alpha_0,\,\alpha_1,\,\alpha_2]}\cConfig\tp$ | global 3D angular acceleration vector of node |

(description-noderigidbodyep)=
## Detailed description

### Coordinates

| index | symbol | kind | meaning | frame |
|---|---|---|---|---|
| 0, 1, 2 | $q_0,\,q_1,\,q_2$ | {ref}`ODE2 <ODE2>` | displacement of the reference point of the body | global |
| 3, 4, 5, 6 | $\psi_0,\,\psi_1,\,\psi_2,\,\psi_3$ | {ref}`ODE2 <ODE2>` | change of the four Euler parameters (unit quaternion) against their reference values | - |
| - | $\lambda_\theta$ | {ref}`AE <AE>` | the Lagrange multiplier of the Euler parameter constraint, if `addConstraintEquation = True` | - |

### Configuration

The position of the reference point and the Euler parameters $\ttheta$ are the sums of reference and
current coordinates,

$$
\pv\cConfig = \pv\cRef + \uv\cConfig, \quad \ttheta\cConfig = \tpsi\cRef + \tpsi\cConfig .
$$

The reference Euler parameters must be a unit quaternion - $[1,\,0,\,0,\,0]$ for no rotation; the
default of zeros is not one, which `CreateRigidBody` takes care of. The rotation matrix, as a
function of $\ttheta=[\theta_0,\,\theta_1,\,\theta_2,\,\theta_3]\tp$, transforms a local
(body-fixed) position $\pLocB = \LU{b}{[b_0,\,b_1,\,b_2]}\tp$ into the global frame,
$\LU{0}{\pLoc}\cConfig = \LU{0b}{\Rot}\cConfig \LU{b}{\pLoc}$, with

$$
\LU{0b}{\Rot} = \mr{-2\theta_3^2 - 2\theta_2^2+1}{-2\theta_3\theta_0+2\theta_2\theta_1}{2\theta_3\theta_1+2\theta_2\theta_0}
{2\theta_3\theta_0+2\theta_2\theta_1}{-2\theta_3^2-2\theta_1^2+1}{2\theta_3\theta_2-2\theta_1\theta_0}
{-2\theta_2\theta_0+2\theta_3\theta_1}{2\theta_3\theta_2+2\theta_1\theta_0}{-2\theta_2^2-2\theta_1^2+1}
$$

### Frame and interpretation

The displacement is given in the global frame, and the Euler parameters describe the rotation of the
body frame $b$ against the global frame. Every object using the node reads it this way.

### Action on the equations of motion

The velocity transformation relates the time derivatives of the Euler parameters to the angular
velocity, in the global or in the body frame,

$$
\begin{aligned}
\LU{0}{\tomega} &= \LU{0}{\Gm} \dot \ttheta, \\
\LU{b}{\tomega} &= \LU{b}{\Gm} \dot \ttheta.
\end{aligned}
$$ (eq-noderigidbodyep-gm)

All seven coordinates lead to {ref}`ODE2 <ODE2>` equations, which the object provides. The first three are
the residuals of the forces in the global frame. The last four are the torque equations projected
with the transposed velocity transformation: a torque $\LU{b}{\ttau}$ in the body frame enters
them as $\LU{b}{\Gm\tp} \LU{b}{\ttau}$, a torque $\LU{0}{\ttau}$ in the global frame as
$\LU{0}{\Gm\tp} \LU{0}{\ttau}$, see {eq}`eq-noderigidbodyep-gm` and the equations of motion of
[](#sec-item-objectrigidbody).

### Constraint of the Euler parameters

Four parameters for three rotations need one constraint. With `addConstraintEquation = True` the
node adds it itself, as one algebraic equation with the multiplier $\lambda_\theta$: on the position
level (index 3)

$$
\ttheta\tp \ttheta - 1 = 0,
$$

or on the velocity level (index 2) $2\,\ttheta\tp \dot\ttheta = 0$. With
`addConstraintEquation = False` it is left to the model, e.g. a `CoordinateVectorConstraint`.

For creating a `NodeRigidBodyEP` together with a rigid body, use `CreateRigidBody`, see
[](#sec-mainsystemextensions-createrigidbody).

(miniexample-noderigidbodyep)=
## Mini example


```python
#a rigid body spinning about its z-axis; the velocity coordinates are the time derivatives of the Euler parameters
omega = [0,0,0.5*np.pi]
ep0 = eulerParameters0
node = mbs.AddNode(NodeRigidBodyEP(referenceCoordinates=[0.5,0.2,0.1]+ep0,
                                   initialVelocities=[0,0,0]+list(AngularVelocity2EulerParameters_t(omega, ep0))))
inertia = InertiaCuboid(density=1000, sideLengths=[0.4,0.2,0.1])
mbs.AddObject(ObjectRigidBody(nodeNumber=node, mass=inertia.Mass(),
                              inertia=inertia.GetInertia6D()))

mbs.Assemble()
mbs.SolveDynamic()

#the node adds the constraint of the Euler parameters itself; the angle about z after 1 second:
exu.sys['testResult'] = mbs.GetNodeOutput(node, exu.OutputVariableType.Rotation)[2] #pi/2, to the accuracy of the time integration
```


Examples (Ex) and TestModels (TM) that show this item, with weblink to github: [`tutorialRigidBody.py`](https://github.com/jgerstmayr/EXUDYN/blob/master/python/Examples/notebooks/tutorialRigidBody.py) (Ex), [`tutorialRigidBodyCreate.py`](https://github.com/jgerstmayr/EXUDYN/blob/master/python/Examples/notebooks/tutorialRigidBodyCreate.py) (Ex), [`fourBarMechanism3D.py`](https://github.com/jgerstmayr/EXUDYN/blob/master/python/Examples/fourBarMechanism3D.py) (Ex)