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

(sec-item-objectconnectorcoordinate)=
# ObjectConnectorCoordinate

A coordinate constraint which constrains two (scalar) coordinates of Marker[Node|Body]Coordinates attached to nodes or bodies. The constraint acts directly on coordinates, but does not include reference values, e.g., of nodal values. This constraint is computationally efficient and should be used to constrain nodal coordinates.

**Simpler**: [`mbs.CreateCoordinateConstraint`](#sec-mainsystemextensions-createcoordinateconstraint) adds this item, with what it needs, in one call.

## Interface

- Python names: `ObjectConnectorCoordinate` or `CoordinateConstraint`, and `VCoordinateConstraint` for its visualization
- Markers it acts on: those providing `Coordinate`: [](#sec-item-markernodecoordinate), [](#sec-item-markernodeode1coordinate), [](#sec-item-markernoderotationcoordinate), [](#sec-item-markerbodiesrelativetranslationcoordinate), [](#sec-item-markerbodiesrelativerotationcoordinate), [](#sec-item-markerbodycable2dshape), [](#sec-item-markerbodycable2dcoordinates)

## Parameters

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

| name | type | size | default | description |
|---|---|---|---|---|
| **name** | String |  | '' | constraints's unique name |
| **markerNumbers** | ArrayMarkerIndex |  | [ invalid (-1), invalid (-1) ] | (symbol: $[m0,m1]\tp$) list of markers used in connector |
| **offset** | Real |  | 0. | (symbol: $l_\mathrm{off}$) An offset between the two values |
| **factor1** | Real |  | 1. | (symbol: $k_{m1}$) An additional factor multiplied with value1 used in algebraic equation |
| **velocityLevel** | Bool |  | False | If true: connector constrains velocities (only works for {ref}`ODE2 <ODE2>` coordinates!); offset is used between velocities; in this case, the offsetUserFunction_t is considered and offsetUserFunction is ignored |
| **offsetUserFunction** | ObjectConnectorCoordinateOffsetUserFunction |  | 0 | (symbol: $\mathrm{UF} \in \Rcal$) A Python function which defines the time-dependent offset; see description below |
| **offsetUserFunction_t** | ObjectConnectorCoordinateOffsetUserFunction_t |  | 0 | (symbol: $\mathrm{UF}_t \in \Rcal$) time derivative of offsetUserFunction; needed for velocity level constraints; see description below |
| **activeConnector** | Bool |  | True | flag, which determines, if the connector is active; used to deactivate (temporarily) a connector or constraint |
| **visualization** | VObjectConnectorCoordinate |  |  | parameters for visualization of item |


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

## Visualization parameters

The parameters of `VObjectConnectorCoordinate`, 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 = link size; size == -1.f means that default connector size is used |
| **color** | Float4 | 4 | [-1.,-1.,-1.,-1.] | RGBA connector color; if R==-1, use default color |

## Drawing

Drawn as [all constraints](#sec-drawing-objectsconstraint); a circle of diameter `drawSize` at the position of each marker, the one of marker 0 red.

## 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 |
|---|---|---|
| Displacement | $\Delta q$ | relative scalar displacement of marker coordinates, not including factor1 |
| Velocity | $\Delta v$ | difference of scalar marker velocity coordinates, not including factor1 |
| ConstraintEquation | $\cv$ | (residuum of) constraint equation |
| Force | $\lambda_0$ | scalar constraint force (Lagrange multiplier) |

(description-objectconnectorcoordinate)=
## Detailed description

### Definition of quantities

| intermediate variables | symbol | description |
|---|---|---|
| marker m0 coordinate | $q_{m0}$ | current displacement coordinate which is provided by marker m0; does NOT include reference coordinate! |
| marker m1 coordinate | $q_{m1}$ |  |
| marker m0 velocity coordinate | $v_{m0}$ | current velocity coordinate which is provided by marker m0 |
| marker m1 velocity coordinate | $v_{m1}$ |  |
| difference of coordinates | $\Delta q = q_{m1} - q_{m0}$ | Displacement between marker m0 to marker m1 coordinates (does NOT include reference coordinates) |
| difference of velocity coordinates | $\Delta v= v_{m1} - v_{m0}$ |  |

### Connector constraint equations

If `activeConnector = True`, the index 3 algebraic equation reads

$$
\cv(q_{m0}, q_{m1}) = k_{m1} \cdot q_{m1} - q_{m0} - l_\mathrm{off} = 0
$$

If the offsetUserFunction $\mathrm{UF}$ is defined, $\cv$ instead becomes ($t$ is current time)

$$
\cv(q_{m0}, q_{m1}) = k_{m1} \cdot q_{m1} - q_{m0} -  \mathrm{UF}(mbs, t, i_N, l_\mathrm{off}) = 0
$$

The `activeConnector = True`, index 2 (velocity level) algebraic equation reads

$$
\dot \cv(\dot q_{m0}, \dot q_{m1}) = k_{m1} \cdot \dot q_{m1} - \dot q_{m0} - d = 0
$$

The factor $d$ in velocity level equations is zero, except if parameters.velocityLevel = True, then $d=l_\mathrm{off}$.
If velocity level constraints are active and the velocity level offsetUserFunction_t $\mathrm{UF}_t$ is defined, $\dot \cv$ instead becomes ($t$ is current time)

$$
\dot \cv(\dot q_{m0}, \dot q_{m1}) = k_{m1} \cdot \dot q_{m1} - \dot q_{m0} - \mathrm{UF}_t(mbs, t, i_N, l_\mathrm{off}) = 0
$$

and `iN` represents the itemNumber (=objectNumber).
Note that the index 2 equations are used, if the solver uses index 2 formulation OR if the flag parameters.velocityLevel = True (or both).
The user functions include dependency on time $t$, but this time dependency is not respected in the computation of initial accelerations. Therefore,
it is recommended that $\mathrm{UF}$ and $\mathrm{UF}_t$ does not include initial accelerations.

If `activeConnector = False`, the (index 1) algebraic equation reads for ALL cases:

$$
\cv(\lambda_0) = \lambda_0 = 0
$$

**Userfunction**: `offsetUserFunction(mbs, t, itemNumber, lOffset)`
A user function, which computes scalar offset for the coordinate constraint, e.g., in order to move a node on a prescribed trajectory.
It is NECESSARY to use sufficiently smooth functions, having **initial offsets** consistent with **initial configuration** of bodies,
either zero or compatible initial offset-velocity, and no initial accelerations.
The `offsetUserFunction` is **ONLY used** in case of static computation or index3 (generalizedAlpha) time integration.
In order to be on the safe side, provide both  `offsetUserFunction` and  `offsetUserFunction_t`.

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

The user function gets time and the offset parameter as an input and returns the computed offset:

| 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, ...) |
| `lOffset` | Real | $l_\mathrm{off}$ |
| **return value** | Real | computed offset for given time |

**Userfunction**: `offsetUserFunction_t(mbs, t, itemNumber, lOffset)`
A user function, which computes scalar offset **velocity** for the coordinate constraint.
It is NECESSARY to use sufficiently smooth functions, having **initial offset velocities** consistent with **initial velocities** of bodies.
The `offsetUserFunction_t` is used instead of `offsetUserFunction` in case of `velocityLevel = True`,
or for index2 time integration and needed for computation of initial accelerations in second order implicit time integrators.

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

The user function gets time and the offset parameter as an input and returns the computed offset velocity:

| 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 of the object in mbs, allowing easy access to all object data via mbs.GetObjectParameter(itemNumber, ...) |
| `lOffset` | Real | $l_\mathrm{off}$ |
| **return value** | Real | computed offset velocity for given time |

*Example*:

```python
#see also mini example!
from math import sin, cos, pi
def UFoffset(mbs, t, itemNumber, lOffset):
    return 0.5*lOffset*(1-cos(0.5*pi*t))

def UFoffset_t(mbs, t, itemNumber, lOffset): #time derivative of UFoffset
    return 0.5*lOffset*0.5*pi*sin(0.5*pi*t)

nMass=mbs.AddNode(Point(referenceCoordinates = [2,0,0]))
massPoint = mbs.AddObject(MassPoint(mass = 5, nodeNumber = nMass))

groundMarker=mbs.AddMarker(MarkerNodeCoordinate(nodeNumber= nGround, coordinate = 0))
nodeMarker  =mbs.AddMarker(MarkerNodeCoordinate(nodeNumber= nMass, coordinate = 0))

#Spring-Damper between two marker coordinates
mbs.AddObject(CoordinateConstraint(markerNumbers = [groundMarker, nodeMarker],
                                   offset = 0.1,
                                   offsetUserFunction = UFoffset,
                                   offsetUserFunction_t = UFoffset_t))
```

(miniexample-objectconnectorcoordinate)=
## Mini example


```python
def OffsetUF(mbs, t, itemNumber, lOffset): #gives 0.05 at t=1
    return 0.5*(1-np.cos(2*3.141592653589793*0.25*t))*lOffset

nMass=mbs.AddNode(Point(referenceCoordinates = [2,0,0]))
massPoint = mbs.AddObject(MassPoint(mass = 5, nodeNumber = nMass))

groundMarker=mbs.AddMarker(MarkerNodeCoordinate(nodeNumber= nGround, coordinate = 0))
nodeMarker  =mbs.AddMarker(MarkerNodeCoordinate(nodeNumber= nMass, coordinate = 0))

#Spring-Damper between two marker coordinates
mbs.AddObject(CoordinateConstraint(markerNumbers = [groundMarker, nodeMarker], 
                                   offset = 0.1, offsetUserFunction = OffsetUF)) 

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

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


Examples (Ex) and TestModels (TM) that show this item, with weblink to github: [`SliderCrank.py`](https://github.com/jgerstmayr/EXUDYN/blob/master/python/Examples/SliderCrank.py) (Ex), [`SpringDamperMassUserFunction.py`](https://github.com/jgerstmayr/EXUDYN/blob/master/python/Examples/SpringDamperMassUserFunction.py) (Ex), [`slidercrankWithMassSpring.py`](https://github.com/jgerstmayr/EXUDYN/blob/master/python/Examples/slidercrankWithMassSpring.py) (Ex), [`SwitchingConstraintsTest.py`](https://github.com/jgerstmayr/EXUDYN/blob/master/python/TestModels/SwitchingConstraintsTest.py) (TM)