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: MarkerBodyPosition, MarkerBodyRigid, MarkerNodePosition, MarkerNodeRigid, MarkerSuperElementPosition, MarkerSuperElementRigid, MarkerKinematicTreeRigid

Parameters

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

name	type	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; if shown - show is False by default -, a line between the markers.

Output variables

Available as OutputVariableType in sensors, Get...Output() and other functions:

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

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}\).

Mini example

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 (TM), energiesTest.py (TM), inactiveConnectorForceTest.py (TM)