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

(sec-item-objectrotationalmass1d)=
# ObjectRotationalMass1D

A 1D rotational inertia (mass) which is attached to Node1D.

## Interface

- Python names: `ObjectRotationalMass1D` or `Rotor1D`, and `VRotor1D` for its visualization
- Nodes it takes: [](#sec-item-node1d), [](#sec-item-nodegenericode2), [](#sec-item-nodepointground)
- Body markers that can be placed on it: [](#sec-item-markerbodyposition), [](#sec-item-markerbodyrigid)

## Parameters

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

| name | type | size | default | description |
|---|---|---|---|---|
| **name** | String |  | '' | objects's unique name |
| **inertia** | UReal |  | 0. | (symbol: $J$) inertia components [SI:kgm$^2$] of rotor / rotational mass |
| **nodeNumber** | NodeIndex |  | invalid (-1) | (symbol: $n0$) node number (type NodeIndex) of Node1D, providing rotation coordinate $\psi_0 = c_0$ |
| **referencePosition** | Vector3D | 3 | [0.,0.,0.] | (symbol: $\LU{0}{\pRef_0}$) a constant reference position = reference point, used to assign joint constraints accordingly and for drawing |
| **referenceRotation** | Matrix3D | 9 | [[1,0,0], [0,1,0], [0,0,1]] | (symbol: $\LU{0i}{\Rot_{0}} \in \Rcal^{3 \times 3}$) an intermediate rotation matrix, which transforms the 1D coordinate into 3D, see description |
| **visualization** | VObjectRotationalMass1D |  |  | parameters for visualization of item |


Renamed parameters, still taken with a `DeprecationWarning`: `physicsInertia` (deprecated since 1.12.258, removed in 2031): use `inertia`.

## Visualization parameters

The parameters of `VObjectRotationalMass1D`, 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 |
| **graphicsData** | BodyGraphicsData |  |  | Structure contains data for body visualization; data is defined in special list / dictionary structure |

## Drawing

Drawn as [all bodies](#sec-drawing-objectsbody); its `graphicsData`, rotated about the axis of its reference rotation by the coordinate of its node.

## 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= \pRefG$ | global position vector; for interpretation see intermediate variables |
| Displacement | $\LU{0}{\uv}\cConfig$ | global displacement vector; for interpretation see intermediate variables |
| Velocity | $\LU{0}{\vv}\cConfig $ | global velocity vector; for interpretation see intermediate variables |
| RotationMatrix | $\LU{0b}{\Rot}$ | vector with 9 components of the rotation matrix (row-major format) |
| Rotation | $\theta$ | scalar rotation angle obtained from underlying node |
| AngularVelocity | $\LU{0}{\tomega}\cConfig$ | global 3D angular velocity vector of body |
| AngularVelocityLocal | $\LU{b}{\tomega}\cConfig$ | local (body-fixed) 3D angular velocity vector of body |
| KineticEnergy | $T = \frac{1}{2} J\, \dot \theta_0^2$ | kinetic energy of the rotor; localPosition must be $[0,0,0]$ |
| PotentialEnergy | $V = 0$ | the body has no elastic energy; gravity and other loads are not part of it (see exudyn.advancedUtilities.LoadPotentialEnergy) - the value stays the same when a body gets a built-in gravity; localPosition must be $[0,0,0]$ |

(description-objectrotationalmass1d)=
## Detailed description

### Definition of quantities

| intermediate variables | symbol | description |
|---|---|---|
| rotation | ${\theta_0}\cConfig = {c_0}\cConfig + {c_0}\cRef$ | the coordinate $c_0$ of the node plus its reference value |
| Position | $\LU{0}{\pv}\cConfig = \LU{0}{\pRef_0}$ | the constant `referencePosition` |
| RotationMatrix | $\LU{0b}{\Rot} = \LU{0i}{\Rot_{0}} \LU{ib}{\mr{\cos(\theta_0)}{-\sin(\theta_0)}{0} {\sin(\theta_0)}{\cos(\theta_0)}{0} {0}{0}{1}}$ | a rotation about the local $z$-axis of the frame given by `referenceRotation` $\LU{0i}{\Rot_{0}}$ |
| AngularVelocity | $\LU{0}{\tomega}\cConfig = \LU{0i}{\Rot_{0}} \LU{i}{\vr{0}{0}{\dot \theta_0}}$ | global angular velocity |
| applied torque | $\LU{0}{\ttau}_a$ | 3D torque from loads, connectors and joints |
| residual torque | $\tau$ | the component of the applied torques about the axis |

### Equations of motion

$$
J \cdot \ddot \theta_0 = \tau , \quad \tau = \LU{i}{[0,\,0,\,1]} \LU{i0}{\Rot_{0}} \LU{0}{\ttau}_a .
$$

### Marker interfaces

$$
\LU{0}{\Jm_{pos}} = \frac{\partial \LU{0}{\vv}}{\partial \dot \theta_0} = \LU{0b}{\Rot} \left( \LU{b}{\vr{0}{0}{1}} \times \LU{b}{\pv} \right) , \quad
\LU{0}{\Jm_{rot}} = \frac{\partial \LU{0}{\tomega}}{\partial \dot \theta_0} = \LU{0i}{\Rot_{0}} \LU{i}{\vr{0}{0}{1}} :
$$

a torque acts with its component about the axis, a force at the local position $\LU{b}{\pv}$ with its moment
about the axis - on the axis, $x = y = 0$, it has no effect; there is no mass-proportional load on it.

(miniexample-objectrotationalmass1d)=
## Mini example


```python
node = mbs.AddNode(Node1D(referenceCoordinates = [1], #\psi_0ref
                          initialCoordinates=[0.5],   #\psi_0ini
                          initialVelocities=[0.5]))   #\psi_t0ini
rotor = mbs.AddObject(Rotor1D(nodeNumber = node, inertia=1))

#assemble and solve system for default parameters
mbs.Assemble()
mbs.SolveDynamic()

#check result, get current rotor z-rotation at local position [0,0,0]
exu.sys['testResult'] = mbs.GetObjectOutputBody(rotor, exu.OutputVariableType.Rotation, [0,0,0])
#final z-angle of rotor shall be 2
```


Relevant Examples (Ex) and TestModels (TM) with weblink to github: [`accessFunctionsTest.py`](https://github.com/jgerstmayr/EXUDYN/blob/master/python/TestModels/accessFunctionsTest.py) (TM), [`distanceSensor.py`](https://github.com/jgerstmayr/EXUDYN/blob/master/python/TestModels/distanceSensor.py) (TM), [`energiesTest.py`](https://github.com/jgerstmayr/EXUDYN/blob/master/python/TestModels/energiesTest.py) (TM), [`coordinateSpringDamperExt.py`](https://github.com/jgerstmayr/EXUDYN/blob/master/python/TestModels/coordinateSpringDamperExt.py) (TM), [`driveTrainTest.py`](https://github.com/jgerstmayr/EXUDYN/blob/master/python/TestModels/driveTrainTest.py) (TM)