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

(sec-item-objectconnectorlinearspringdamper)=
# ObjectConnectorLinearSpringDamper

An linear spring-damper element acting on relative translations along given axis of local joint0 coordinate system. It connects to position and orientation-based markers; the linear spring-damper is intended to act within prismatic joints or in situations where only one translational axis is free; if the two markers rotate relative to each other, the spring-damper will always act in the local joint0 coordinate system.

## Interface

- Python names: `ObjectConnectorLinearSpringDamper` or `LinearSpringDamper`, and `VLinearSpringDamper` for its visualization
- Markers it acts on: those providing `Position` and `Orientation`: [](#sec-item-markerbodyrigid), [](#sec-item-markernoderigid), [](#sec-item-markersuperelementrigid), [](#sec-item-markerkinematictreerigid)

## Parameters

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

| name | type | size | default | description |
|---|---|---|---|---|
| **name** | String |  | '' | connector's unique name |
| **markerNumbers** | ArrayMarkerIndex |  | [ invalid (-1), invalid (-1) ] | (symbol: $[m0,\, m1]$) list of markers used in connector |
| **stiffness** | Real |  | 0. | (symbol: $k$) torsional stiffness [SI:Nm/rad] against relative rotation |
| **damping** | Real |  | 0. | (symbol: $d$) torsional damping [SI:Nm/(rad/s)] |
| **axisMarker0** | Vector3D | 3 | [1,0,0] | (symbol: $\LU{m0}{\dv}$) local axis of spring-damper in marker 0 coordinates; this axis will co-move with marker $m0$; if marker m0 is attached to ground, the spring-damper represents linear equations |
| **offset** | Real |  | 0. | (symbol: $x_\mathrm{off}$) translational offset considered in the spring force calculation (this can be used as position control input!) |
| **velocityOffset** | Real |  | 0. | (symbol: $v_\mathrm{off}$) velocity offset considered in the damper force calculation (this can be used as velocity control input!) |
| **force** | Real |  | 0. | (symbol: $f_c$) additional constant force [SI:Nm] added to spring-damper; this can be used to prescribe a force between the two attached bodies (e.g., for actuation and control) |
| **activeConnector** | Bool |  | True | flag, which determines, if the connector is active; used to deactivate (temporarily) a connector or constraint |
| **springForceUserFunction** | ObjectConnectorLinearSpringDamperSpringForceUserFunction |  | 0 | (symbol: $\mathrm{UF} \in \Rcal$) A Python function which computes the scalar force between the two rigid body markers along axisMarker0 in $m0$ coordinates, if activeConnector=True; see description below |
| **visualization** | VObjectConnectorLinearSpringDamper |  |  | parameters for visualization of item |

## Visualization parameters

The parameters of `VObjectConnectorLinearSpringDamper`, 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 of spring; size == -1.f means that default connector size is used |
| **drawAsCylinder** | Bool |  | False | if this flag is True, the spring-damper is represented as cylinder; this may fit better if the spring-damper represents an actuator |
| **color** | Float4 | 4 | [-1.,-1.,-1.,-1.] | RGBA connector color; if R==-1, use default color |

## Drawing

Drawn as [all connectors](#sec-drawing-objectsconnector); a cylinder of diameter `drawSize` between the markers if `drawAsCylinder`, otherwise the spring of ObjectConnectorSpringDamper, with spheres at the markers.

Settings beyond those of all connectors: [`connectors.curveTiling`](#sec-vsettingsconnectors), [`connectors.drawSimplified`](#sec-vsettingsconnectors), [`connectors.springNumberOfWindings`](#sec-vsettingsconnectors), [`general.cylinderTiling`](#sec-vsettingsgeneral), [`general.sphereTiling`](#sec-vsettingsgeneral).

## 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 |
|---|---|---|
| DisplacementLocal | $\Delta x$ | (scalar) relative displacement of the spring-damper |
| Displacement | $\LU{0}{\pv}_{m1} - \LU{0}{\pv}_{m0}$ | global vector from marker m0 to marker m1 |
| HomogeneousTransformationLocal | $\LU{0}{\Hm}_{m0}^{-1}\,\LU{0}{\Hm}_{m1}$ | the frame of marker m1 relative to the frame of marker m0: the relative rotation matrix $\LU{0}{\Rot}_{m0}\tp\LU{0}{\Rot}_{m1}$ and the relative position in the frame of marker m0; returned and stored as HomogeneousTransformation |
| VelocityLocal | $\Delta v$ | (scalar) relative velocity of spring-damper |
| ForceLocal | $f_{SD}$ | (scalar) spring-damper force |
| PotentialEnergy | $V = \frac{1}{2} k\, (u - u_\mathrm{off})^2 + f_c\, u$ | elastic energy of the spring and the potential of the constant force; zero if the connector is not active; raises for a springForceUserFunction |

(description-objectconnectorlinearspringdamper)=
## Detailed description

### Definition of quantities

| input parameter | symbol | description |
|---|---|---|
| markerNumbers[0] | $m0$ | global marker number m0 |
| markerNumbers[1] | $m1$ | global marker number m1 |

| intermediate variables | symbol | description |
|---|---|---|
| marker m0 orientation | $\LU{0,m0}{\Rot}$ | current rotation matrix provided by marker m0 |
| marker m0 position | $\LU{0}{\pv_{m0}}$ | current position matrix provided by marker m0 |
| marker m1 position | $\LU{0}{\pv_{m1}}$ | current position matrix provided by marker m1 |
| marker m0 velocity | $\LU{0}{\vv}_{m0}$ | current global velocity vector provided by marker m0 |
| marker m1 velocity | $\LU{0}{\vv}_{m1}$ | current global velocity vector provided by marker m1 |
| relative displacement | $\Delta x = (\LU{0,m0}{\Rot} \LU{m0}{\dv})\tp (\LU{0}{\pv_{m1}} - \LU{0}{\pv_{m0}})$ | scalar relative displacement |
| relative velocity | $\Delta v = (\LU{0,m0}{\Rot} \LU{m0}{\dv})\tp (\LU{0}{\vv_{m1}} - \LU{0}{\vv_{m0}})$ | scalar relative velocity; note that this only corresponds to the time derivative of $\Delta x$ if the markers only move along the axis (in a prismatic joint) |

### Connector forces

If `activeConnector = True`, the vector spring force is computed as

$$
f_{SD} = k \left(\Delta x - x_\mathrm{off} \right) + d \left(\Delta v - v_\mathrm{off} \right) + f_c
$$

if `activeConnector = False`, $f_{SD}$ is set zero.

If the springForceUserFunction $\mathrm{UF}$ is defined and `activeConnector = True`,
$f_{SD}$ instead becomes ($t$ is current time)

$$
f_{SD} = \mathrm{UF}(mbs, t, i_N, \Delta x, \Delta v, \mathrm{stiffness}, \mathrm{damping}, \mathrm{offset})
$$

and `iN` represents the itemNumber (=objectNumber).

**Userfunction**: `springForceUserFunction(mbs, t, itemNumber, displacement, velocity, stiffness, damping, offset)`
A user function, which computes the scalar torque depending on mbs, time, local quantities
(relative displacement, relative velocity), which are evaluated at current time.
Furthermore, the user function contains object parameters (stiffness, damping, offset).
Note that itemNumber represents the index of the object in mbs, which can be used to retrieve additional data from the object through
`mbs.GetObjectParameter(itemNumber, ...)`, see the according description of `GetObjectParameter`.

Detailed description of the arguments and local quantities:

| arguments / return | type or size | description |
|---|---|---|
| `mbs` | MainSystem | provides MainSystem mbs in which underlying item is defined |
| `t` | Real | current time in mbs |
| `itemNumber` | Index | integer number $i_N$ of the object in mbs, allowing easy access to all object data via mbs.GetObjectParameter(itemNumber, ...) |
| `displacement` | Real | $\Delta x$ |
| `velocity` | Real | $\Delta v$ |
| `stiffness` | Real | copied from object |
| `damping` | Real | copied from object |
| `offset` | Real | copied from object |
| **return value** | Real | computed force |

*Example*:

```python
#define simple cubic force for spring-damper:
def UFforce(mbs, t, itemNumber, displacement, velocity, stiffness, damping, offset):
    k = stiffness #passed as list
    return k*displacement + 0.1*k* displacement**3

#markerNumbers and parameters taken from mini example
mbs.AddObject(LinearSpringDamper(markerNumbers = [mGround, mBody],
                                 stiffness = k,
                                 damping = k*0.01,
                                 offset = 0,
                                 springForceUserFunction = UFforce))
```

(miniexample-objectconnectorlinearspringdamper)=
## Mini example


```python
#example with rigid body at [0,0,0], with torsional load
k=2e3
nBody = mbs.AddNode(RigidRxyz())
oBody = mbs.AddObject(RigidBody(mass=1, inertia=[1,1,1,0,0,0], 
                                nodeNumber=nBody))

mBody = mbs.AddMarker(MarkerNodeRigid(nodeNumber=nBody))
mGround = mbs.AddMarker(MarkerBodyRigid(bodyNumber=oGround, 
                                        localPosition = [0,0,0]))
mbs.AddObject(PrismaticJointX(markerNumbers = [mGround, mBody])) #motion along ground X-axis
mbs.AddObject(LinearSpringDamper(markerNumbers = [mGround, mBody], axisMarker0=[1,0,0],
                                 stiffness = k, damping = k*0.01, offset = 0))

#force along x-axis; expect approx. Delta x = 1/k=0.0005
mbs.AddLoad(Force(markerNumber = mBody, loadVector=[1,0,0])) 

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

#check result at default integration time
exu.sys['testResult'] = mbs.GetNodeOutput(nBody, exu.OutputVariableType.Displacement)[0]
```


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