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

(sec-item-objectconnectorgravity)=
# ObjectConnectorGravity

A connector for additing forces due to gravitational fields beween two bodies, which can be used for aerospace and small-scale astronomical problems. NOTE: DO NOT USE this connector for adding gravitational forces (loads), which should be using LoadMassProportional, which is acting global and always in the same direction.

## Interface

- Python names: `ObjectConnectorGravity` or `ConnectorGravity`, and `VConnectorGravity` for its visualization
- Markers it acts on: those providing `Position`: [](#sec-item-markerbodyposition), [](#sec-item-markerbodyrigid), [](#sec-item-markernodeposition), [](#sec-item-markernoderigid), [](#sec-item-markersuperelementposition), [](#sec-item-markersuperelementrigid), [](#sec-item-markerkinematictreerigid)

## Parameters

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

| name | type | size | default | description |
|---|---|---|---|---|
| **name** | String |  | '' | connector's unique name |
| **markerNumbers** | ArrayMarkerIndex |  | [ invalid (-1), invalid (-1) ] | (symbol: $[m0,m1]\tp$) list of markers used in connector |
| **gravitationalConstant** | Real |  | 6.6743e-11 | (symbol: $G$) gravitational constant [SI:m$^3$kg$^{-1}$s$^{-2}$)]; while not recommended, a negative constant gan represent a repulsive force |
| **mass0** | UReal |  | 0. | (symbol: $mass_0$) mass [SI:kg] of object attached to marker $m0$ |
| **mass1** | UReal |  | 0. | (symbol: $mass_1$) mass [SI:kg] of object attached to marker $m1$ |
| **minDistanceRegularization** | UReal |  | 0. | (symbol: $d_{min}$) distance [SI:m] at which a regularization is added in order to avoid singularities, if objects come close |
| **activeConnector** | Bool |  | True | flag, which determines, if the connector is active; used to deactivate (temporarily) a connector or constraint |
| **visualization** | VObjectConnectorGravity |  |  | parameters for visualization of item |

## Visualization parameters

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

| name | type | size | default | description |
|---|---|---|---|---|
| **show** | Bool |  | False | set true to draw a line between the two markers, e.g. to see which bodies attract each other |
| **color** | Float4 | 4 | [-1.,-1.,-1.,-1.] | RGBA connector color; if R==-1, use default color |

## Drawing

Drawn as [all connectors](#sec-drawing-objectsconnector); if shown - `show` is False by default -, a line between the markers.

## 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 |
|---|---|---|
| Distance | $L$ | distance between both points |
| Displacement | $\Delta\! \LU{0}{\pv}$ | relative displacement between both points |
| Force | $\fv$ | gravity force vector, pointing from marker $m0$ to marker $m1$ |
| PotentialEnergy | $V = -\frac{G m_0 m_1}{L}$ | gravitational potential, zero at infinite distance; below minDistanceRegularization $r$ the potential of the regularized force, $V = -\frac{G m_0 m_1}{r}\left(1 + \frac{\pi}{4} - \arctan\frac{2L - r}{r}\right)$; zero if the connector is not active |

(description-objectconnectorgravity)=
## Detailed description

### Definition of quantities

| intermediate variables | symbol | description |
|---|---|---|
| marker m0 position | $\LU{0}{\pv}_{m0}$ | current global position which is provided by marker m0 |
| marker m1 position | $\LU{0}{\pv}_{m1}$ |  |
| marker m0 velocity | $\LU{0}{\vv}_{m0}$ | current global velocity which is provided by marker m0 |
| marker m1 velocity | $\LU{0}{\vv}_{m1}$ |  |

| output variables | symbol | formula |
|---|---|---|
| Displacement | $\Delta\! \LU{0}{\pv}$ | $\LU{0}{\pv}_{m1} - \LU{0}{\pv}_{m0}$ |
| Velocity | $\Delta\! \LU{0}{\vv}$ | $\LU{0}{\vv}_{m1} - \LU{0}{\vv}_{m0}$ |
| Distance | $L$ | $\vert\Delta\! \LU{0}{\pv}\vert$ |
| Force | $\fv$ | see below |

### Connector forces

The unit vector in force direction reads (if $L=0$, singularity can be avoided using regularization),

$$
\vv_{f} = \frac{1}{L} \Delta\! \LU{0}{\pv}
$$

If `activeConnector = True`, and $L>=d_{min}$ the gravitational force is computed as

$$
f_G = - G \frac{mass_0 \cdot mass_1}{L^2}
$$

If `activeConnector = True`, and $L<d_{min}$ the gravitational force is computed as

$$
f_G = - G \frac{mass_0 \cdot mass_1}{L^2+(L-d_{min})^2}
$$

which results in a regularization for small distances, which is helpful if there are no restrictions in objects to keep apart.
If $d_{min}=0$ and $L=0$, there a system error is raised.

The vector of the gravitational force applied at both markers, pointing from marker $m0$ to marker $m1$, finally reads

$$
\fv = f_G \vv_{f}
$$

The virtual work of the connector force is computed from the virtual displacement

$$
\delta \Delta\! \LU{0}{\pv} = \delta \LU{0}{\pv}_{m1} - \delta \LU{0}{\pv}_{m0} \, ,
$$

and the virtual work (not the transposed version here, because the resulting generalized forces shall be a column vector,

$$
\delta W_G = \fv \delta \Delta\! \LU{0}{\pv}
= -\left( - G \frac{mass_0 \cdot mass_1}{L^2} \right) \left(\delta \LU{0}{\pv}_{m1} - \delta \LU{0}{\pv}_{m0} \right)\tp \vv_{f}
\, .
$$

The generalized (elastic) forces thus result from

$$
\Qm_G = \frac{\partial \LU{0}{\pv}}{\partial \qv_G\tp} \fv
\, ,
$$

and read for the markers $m0$ and $m1$,

$$
\Qm_{G, m0}
= -\left( - G \frac{mass_0 \cdot mass_1}{L^2} \right) \Jm_{pos,m0}\tp \vv_{f} , \quad
\Qm_{G, m1}
= \left( - G \frac{mass_0 \cdot mass_1}{L^2} \right) \Jm_{pos,m1}\tp \vv_{f}
\, ,
$$

where $\Jm_{pos,m1}$ represents the derivative of marker $m1$ w.r.t. its associated coordinates $\qv_{m1}$, analogously $\Jm_{pos,m0}$.

(miniexample-objectconnectorgravity)=
## Mini example


```python
mass0 = 1e25
mass1 = 1e3
r = 1e5
G = 6.6743e-11
vInit = np.sqrt(G*mass0/r)
tEnd = (r*0.5*np.pi)/vInit #quarter period
node0 = mbs.AddNode(NodePoint(referenceCoordinates = [0,0,0])) #star
node1 = mbs.AddNode(NodePoint(referenceCoordinates = [r,0,0], 
                              initialVelocities=[0,vInit,0])) #satellite
oMassPoint0 = mbs.AddObject(MassPoint(nodeNumber = node0, mass=mass0))
oMassPoint1 = mbs.AddObject(MassPoint(nodeNumber = node1, mass=mass1))

m0 = mbs.AddMarker(MarkerNodePosition(nodeNumber=node0))
m1 = mbs.AddMarker(MarkerNodePosition(nodeNumber=node1))

mbs.AddObject(ObjectConnectorGravity(markerNumbers=[m0,m1],
                                     mass0 = mass0, mass1=mass1))

#assemble and solve system for default parameters
mbs.Assemble()
sims = exu.SimulationSettings()
sims.timeIntegration.endTime = tEnd
mbs.SolveDynamic(sims, solverType=exu.DynamicSolverType.RK67)

#check result at default integration time
#expect y=x after one period of orbiting (got: 100000.00000000479)
exu.sys['testResult'] = mbs.GetNodeOutput(node1, exu.OutputVariableType.Position)[1]/100000
```


Relevant Examples (Ex) and TestModels (TM) with weblink to github: [`connectorGravityTest.py`](https://github.com/jgerstmayr/EXUDYN/blob/master/python/TestModels/connectorGravityTest.py) (TM), [`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)