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 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: MarkerNodeCoordinate, MarkerNodeODE1Coordinate, MarkerNodeRotationCoordinate, MarkerBodiesRelativeTranslationCoordinate, MarkerBodiesRelativeRotationCoordinate, MarkerBodyCable2DShape, MarkerBodyCable2DCoordinates

Parameters

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

name	type	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 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; 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:

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)

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:

#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))

Mini example

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 (Ex), SpringDamperMassUserFunction.py (Ex), slidercrankWithMassSpring.py (Ex), SwitchingConstraintsTest.py (TM)