ObjectConnectorLinearSpringDamper

An linear spring-damper element acting on relative translations along given axis of local joint0 coordinate system. It connects to position and orientation-based markers; the linear spring-damper is intended to act within prismatic joints or in situations where only one translational axis is free; if the two markers rotate relative to each other, the spring-damper will always act in the local joint0 coordinate system.

Interface

Python names: ObjectConnectorLinearSpringDamper or LinearSpringDamper, and VLinearSpringDamper for its visualization
Markers it acts on: those providing Position and Orientation: MarkerBodyRigid, MarkerNodeRigid, MarkerSuperElementRigid, MarkerKinematicTreeRigid

Parameters

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

name	type	size	default	description
name	String		‘’	connector’s unique name
markerNumbers	ArrayMarkerIndex		[ invalid (-1), invalid (-1) ]	(symbol: \([m0,\, m1]\)) list of markers used in connector
stiffness	Real		0.	(symbol: \(k\)) torsional stiffness [SI:Nm/rad] against relative rotation
damping	Real		0.	(symbol: \(d\)) torsional damping [SI:Nm/(rad/s)]
axisMarker0	Vector3D	3	[1,0,0]	(symbol: \(\LU{m0}{\dv}\)) local axis of spring-damper in marker 0 coordinates; this axis will co-move with marker \(m0\); if marker m0 is attached to ground, the spring-damper represents linear equations
offset	Real		0.	(symbol: \(x_\mathrm{off}\)) translational offset considered in the spring force calculation (this can be used as position control input!)
velocityOffset	Real		0.	(symbol: \(v_\mathrm{off}\)) velocity offset considered in the damper force calculation (this can be used as velocity control input!)
force	Real		0.	(symbol: \(f_c\)) additional constant force [SI:Nm] added to spring-damper; this can be used to prescribe a force between the two attached bodies (e.g., for actuation and control)
activeConnector	Bool		True	flag, which determines, if the connector is active; used to deactivate (temporarily) a connector or constraint
springForceUserFunction	ObjectConnectorLinearSpringDamperSpringForceUserFunction		0	(symbol: \(\mathrm{UF} \in \Rcal\)) A Python function which computes the scalar force between the two rigid body markers along axisMarker0 in \(m0\) coordinates, if activeConnector=True; see description below
visualization	VObjectConnectorLinearSpringDamper			parameters for visualization of item

Visualization parameters

The parameters of VObjectConnectorLinearSpringDamper, 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 = diameter of spring; size == -1.f means that default connector size is used
drawAsCylinder	Bool		False	if this flag is True, the spring-damper is represented as cylinder; this may fit better if the spring-damper represents an actuator
color	Float4	4	[-1.,-1.,-1.,-1.]	RGBA connector color; if R==-1, use default color

Drawing

Drawn as all connectors; a cylinder of diameter drawSize between the markers if drawAsCylinder, otherwise the spring of ObjectConnectorSpringDamper, with spheres at the markers.

Settings beyond those of all connectors: connectors.curveTiling, connectors.drawSimplified, connectors.springNumberOfWindings, general.cylinderTiling, general.sphereTiling.

Output variables

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

output variable	symbol	description
DisplacementLocal	\(\Delta x\)	(scalar) relative displacement of the spring-damper
Displacement	\(\LU{0}{\pv}_{m1} - \LU{0}{\pv}_{m0}\)	global vector from marker m0 to marker m1
HomogeneousTransformationLocal	\(\LU{0}{\Hm}_{m0}^{-1}\,\LU{0}{\Hm}_{m1}\)	the frame of marker m1 relative to the frame of marker m0: the relative rotation matrix \(\LU{0}{\Rot}_{m0}\tp\LU{0}{\Rot}_{m1}\) and the relative position in the frame of marker m0; returned and stored as HomogeneousTransformation
VelocityLocal	\(\Delta v\)	(scalar) relative velocity of spring-damper
ForceLocal	\(f_{SD}\)	(scalar) spring-damper force
PotentialEnergy	\(V = \frac{1}{2} k\, (u - u_\mathrm{off})^2 + f_c\, u\)	elastic energy of the spring and the potential of the constant force; zero if the connector is not active; raises for a springForceUserFunction

Detailed description

Definition of quantities

input parameter	symbol	description
markerNumbers[0]	\(m0\)	global marker number m0
markerNumbers[1]	\(m1\)	global marker number m1

intermediate variables	symbol	description
marker m0 orientation	\(\LU{0,m0}{\Rot}\)	current rotation matrix provided by marker m0
marker m0 position	\(\LU{0}{\pv_{m0}}\)	current position matrix provided by marker m0
marker m1 position	\(\LU{0}{\pv_{m1}}\)	current position matrix provided by marker m1
marker m0 velocity	\(\LU{0}{\vv}_{m0}\)	current global velocity vector provided by marker m0
marker m1 velocity	\(\LU{0}{\vv}_{m1}\)	current global velocity vector provided by marker m1
relative displacement	\(\Delta x = (\LU{0,m0}{\Rot} \LU{m0}{\dv})\tp (\LU{0}{\pv_{m1}} - \LU{0}{\pv_{m0}})\)	scalar relative displacement
relative velocity	\(\Delta v = (\LU{0,m0}{\Rot} \LU{m0}{\dv})\tp (\LU{0}{\vv_{m1}} - \LU{0}{\vv_{m0}})\)	scalar relative velocity; note that this only corresponds to the time derivative of \(\Delta x\) if the markers only move along the axis (in a prismatic joint)

Connector forces

If activeConnector = True, the vector spring force is computed as

\[ f_{SD} = k \left(\Delta x - x_\mathrm{off} \right) + d \left(\Delta v - v_\mathrm{off} \right) + f_c \]

if activeConnector = False, \(f_{SD}\) is set zero.

If the springForceUserFunction \(\mathrm{UF}\) is defined and activeConnector = True, \(f_{SD}\) instead becomes (\(t\) is current time)

\[ f_{SD} = \mathrm{UF}(mbs, t, i_N, \Delta x, \Delta v, \mathrm{stiffness}, \mathrm{damping}, \mathrm{offset}) \]

and iN represents the itemNumber (=objectNumber).

Userfunction: springForceUserFunction(mbs, t, itemNumber, displacement, velocity, stiffness, damping, offset) A user function, which computes the scalar torque depending on mbs, time, local quantities (relative displacement, relative velocity), which are evaluated at current time. Furthermore, the user function contains object parameters (stiffness, damping, offset). 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.

Detailed description of the arguments and local quantities:

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, …)
`displacement`	Real	\(\Delta x\)
`velocity`	Real	\(\Delta v\)
`stiffness`	Real	copied from object
`damping`	Real	copied from object
`offset`	Real	copied from object
return value	Real	computed force

Example:

#define simple cubic force for spring-damper:
def UFforce(mbs, t, itemNumber, displacement, velocity, stiffness, damping, offset):
    k = stiffness #passed as list
    return k*displacement + 0.1*k* displacement**3

#markerNumbers and parameters taken from mini example
mbs.AddObject(LinearSpringDamper(markerNumbers = [mGround, mBody],
                                 stiffness = k,
                                 damping = k*0.01,
                                 offset = 0,
                                 springForceUserFunction = UFforce))

Mini example

#example with rigid body at [0,0,0], with torsional load
k=2e3
nBody = mbs.AddNode(RigidRxyz())
oBody = mbs.AddObject(RigidBody(mass=1, inertia=[1,1,1,0,0,0], 
                                nodeNumber=nBody))

mBody = mbs.AddMarker(MarkerNodeRigid(nodeNumber=nBody))
mGround = mbs.AddMarker(MarkerBodyRigid(bodyNumber=oGround, 
                                        localPosition = [0,0,0]))
mbs.AddObject(PrismaticJointX(markerNumbers = [mGround, mBody])) #motion along ground X-axis
mbs.AddObject(LinearSpringDamper(markerNumbers = [mGround, mBody], axisMarker0=[1,0,0],
                                 stiffness = k, damping = k*0.01, offset = 0))

#force along x-axis; expect approx. Delta x = 1/k=0.0005
mbs.AddLoad(Force(markerNumber = mBody, loadVector=[1,0,0])) 

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

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

Relevant Examples (Ex) and TestModels (TM) with weblink to github: chainDriveExample.py (Ex), energiesTest.py (TM), inactiveConnectorForceTest.py (TM)