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

(sec-item-markersuperelementposition)=
# MarkerSuperElementPosition

A position marker attached to a SuperElement, such as ObjectFFRF, ObjectGenericODE2 and ObjectFFRFreducedOrder (for which it is in its current implementation inefficient for large number of meshNodeNumbers). The marker acts on the mesh (interface) nodes, not on the underlying nodes of the object.

## Interface

- Provides: `Position`
- Bodies it can be placed on: [](#sec-item-objectgenericode2), [](#sec-item-objectffrf), [](#sec-item-objectffrfreducedorder)
- Connectors, constraints and loads that can use it: [](#sec-item-objectconnectorspringdamper), [](#sec-item-objectconnectorcartesianspringdamper), [](#sec-item-objectconnectorgravity), [](#sec-item-objectconnectorhydraulicactuatorsimple), [](#sec-item-objectconnectordistance), [](#sec-item-objectcontactspheresphere), [](#sec-item-objectcontactspheretriangle), [](#sec-item-objectjointspherical), [](#sec-item-objectjointrevolute2d), [](#sec-item-loadforcevector)

## Parameters

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

| name | type | size | default | description |
|---|---|---|---|---|
| **name** | String |  | '' | marker's unique name |
| **bodyNumber** | ObjectIndex |  | invalid (-1) | (symbol: $n_b$) body number to which marker is attached to |
| **meshNodeNumbers** | ArrayIndex |  | [] | (symbol: $[k_0,\,\ldots,\,k_{n_m-1}]\tp$) a list of $n_m$ mesh node numbers of superelement (=interface nodes) which are used to compute the body-fixed marker position; the related nodes must provide 3D position information, such as NodePoint, NodePoint2D, NodeRigidBody[..]; in order to retrieve the global node number, the generic body needs to convert local into global node numbers |
| **weightingFactors** | Vector |  | [] | (symbol: $[w_{0},\,\ldots,\,w_{n_m-1}]\tp$) a list of $n_m$ weighting factors per node to compute the final local position; the sum of these weights shall be 1, such that a summation of all nodal positions times weights gives the average position of the marker |
| **visualization** | VMarkerSuperElementPosition |  |  | parameters for visualization of item |

## Visualization parameters

The parameters of `VMarkerSuperElementPosition`, 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 |
| **showMarkerNodes** | Bool |  | True | set true, if all nodes are shown (similar to marker, but with less intensity) |

## Drawing

Drawn as [all markers](#sec-drawing-markers); at the weighted position of its mesh nodes, deformed with `bodies.deformationScaleFactor`.

Settings beyond those of all markers: [`bodies.deformationScaleFactor`](#sec-vsettingsbodies).
(description-markersuperelementposition)=
## Detailed description

**Definition of marker quantities**:

| intermediate variables | symbol | description |
|---|---|---|
| number of mesh nodes | $n_m$ | size of `meshNodeNumbers` and `weightingFactors` which are marked; this must not be the number of mesh nodes in the marked object |
| mesh node number | $i = k_i$ | abbreviation |
| mesh node points | $\LU{0}{\pv}_{i}$ | position of mesh node $k_i$ in object $n_b$ |
| mesh node velocities | $\LU{0}{\vv}_{i}$ | velocity of mesh node $i$ in object $n_b$ |
| marker position | $\LU{0}{\pv}_{m} = \sum_i w_i \cdot \LU{0}{\pv_i}$ | current global position which is provided by marker |
| marker velocity | $\LU{0}{\vv}_{m} = \sum_i w_i \cdot \LU{0}{\vv_i}$ | current global velocity which is provided by marker |

### Marker quantities

The marker provides a 'position' jacobian, which is the derivative of the marker velocity w.r.t. the
object velocity coordinates $\dot \qv_{n_b}$,

$$
\Jm_{m,pos} = \frac{\partial \LU{0}{\vv}_{m}}{\partial \dot \qv_{n_b}}
= \sum_i w_i \cdot \Jm_{i,pos}
$$

in which $\Jm_{i,pos}$ denotes the position jacobian of mesh node $i$,

$$
\Jm_{i,pos} = \frac{\partial \LU{0}{\vv}_{i}}{\partial \dot \qv_{n_b}}
$$

The jacobian $\Jm_{i,pos}$ usually contains mostly zeros for `ObjectGenericODE2`, because the jacobian only affects one single node.
In `ObjectFFRFreducedOrder`, the jacobian may affect all reduced coordinates.

Note that $\Jm_{m,pos}$ is actually computed by the
`ObjectSuperElement` within the function `GetAccessFunctionSuperElement`.

(miniexample-markersuperelementposition)=
## Mini example


```python
#set up a mechanical system with two nodes; it has the structure: |~~M0~~M1
#==>further examples see objectGenericODE2Test.py, objectFFRFTest2.py, etc.
nMass0 = mbs.AddNode(NodePoint(referenceCoordinates=[0,0,0]))
nMass1 = mbs.AddNode(NodePoint(referenceCoordinates=[1,0,0]))
mGround = mbs.AddMarker(MarkerBodyPosition(bodyNumber=oGround, localPosition = [1,0,0]))

mass = 0.5 * np.eye(3)      #mass of nodes
stif = 5000 * np.eye(3)     #stiffness of nodes
damp = 50 * np.eye(3)      #damping of nodes
Z = 0. * np.eye(3)          #matrix with zeros
#build mass, stiffness and damping matrices (:
M = np.block([[mass,         0.*np.eye(3)],
              [0.*np.eye(3), mass        ] ])
K = np.block([[2*stif, -stif],
              [ -stif,  stif] ])
D = np.block([[2*damp, -damp],
              [ -damp,  damp] ])

oGenericODE2 = mbs.AddObject(ObjectGenericODE2(nodeNumbers=[nMass0,nMass1], 
                                               massMatrix=M, 
                                               stiffnessMatrix=K,
                                               dampingMatrix=D))

#EXAMPLE for single node marker on super element body, mesh node 1; compare results to ObjectGenericODE2 example!!! 
mSuperElement = mbs.AddMarker(MarkerSuperElementPosition(bodyNumber=oGenericODE2, meshNodeNumbers=[1], weightingFactors=[1]))
mbs.AddLoad(Force(markerNumber = mSuperElement, loadVector = [10, 0, 0])) 

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

mbs.SolveDynamic(solverType = exu.DynamicSolverType.TrapezoidalIndex2)

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


Relevant Examples (Ex) and TestModels (TM) with weblink to github: [`NGsolvePistonEngine.py`](https://github.com/jgerstmayr/EXUDYN/blob/master/python/Examples/NGsolvePistonEngine.py) (Ex), [`NGsolvePostProcessingStresses.py`](https://github.com/jgerstmayr/EXUDYN/blob/master/python/Examples/NGsolvePostProcessingStresses.py) (Ex), [`objectFFRFreducedOrderNetgen.py`](https://github.com/jgerstmayr/EXUDYN/blob/master/python/Examples/objectFFRFreducedOrderNetgen.py) (Ex), [`objectFFRFreducedOrderAccelerations.py`](https://github.com/jgerstmayr/EXUDYN/blob/master/python/TestModels/objectFFRFreducedOrderAccelerations.py) (TM), [`objectFFRFreducedOrderStressModesTest.py`](https://github.com/jgerstmayr/EXUDYN/blob/master/python/TestModels/objectFFRFreducedOrderStressModesTest.py) (TM), [`objectFFRFreducedOrderTest.py`](https://github.com/jgerstmayr/EXUDYN/blob/master/python/TestModels/objectFFRFreducedOrderTest.py) (TM), [`objectFFRFTest.py`](https://github.com/jgerstmayr/EXUDYN/blob/master/python/TestModels/objectFFRFTest.py) (TM), [`objectFFRFTest2.py`](https://github.com/jgerstmayr/EXUDYN/blob/master/python/TestModels/objectFFRFTest2.py) (TM), [`objectGenericODE2Test.py`](https://github.com/jgerstmayr/EXUDYN/blob/master/python/TestModels/objectGenericODE2Test.py) (TM), [`superElementRigidJointTest.py`](https://github.com/jgerstmayr/EXUDYN/blob/master/python/TestModels/superElementRigidJointTest.py) (TM)