ObjectContactSphereTorus

A simple contact connector between a sphere (marker0) and a torus (marker1). The sphere is assumed to be placed inside of the torus (outer contact of sphere with torus currently not implemented!).

Author: Gerstmayr Johannes

Interface

Parameters

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

name

type

size

default

description

name

String

‘’

constraints’s unique name

markerNumbers

ArrayMarkerIndex

2

[ invalid (-1), invalid (-1) ]

(symbol: \([m0,m1]\tp\)) list of markers representing centers of sphere (marker 0) and center of torus (marker 1)

nodeNumber

NodeIndex

invalid (-1)

(symbol: \(n_d\)) node number of a NodeGenericData with numberOfDataCoordinates = 4 dataCoordinates, needed for discontinuous iteration (friction and contact); data variables contain values from last PostNewton iteration: data[0] is the gap, data[1] is the norm of the tangential velocity (and thus contains information if it is stick or slip); data[2] is the impact velocity; data[3] is unused.

sphereRadius

PReal

0.

(symbol: \(r_S\)) radius of sphere [SI:m]; must be given: the default is only a placeholder

torusMajorRadius

PReal

0.

(symbol: \(r_{M}\)) major radius of torus [SI:m], representing center of rotated circle; must be given: the default is only a placeholder

torusMinorRadius

PReal

0.

(symbol: \(r_{m}\)) minor radius of torus [SI:m], representing radius of circle of ring; must be given: the default is only a placeholder

torusAxis

Vector3D

3

[0,0,0]

(symbol: \(\vv_{axis}\)) Vector containing rotation axis of torus; must be a unit vector.

dynamicFriction

UReal

0.

(symbol: \(\mu_d\)) dynamic friction coefficient for friction model, see StribeckFunction in exudyn.physics, Module: physics

frictionProportionalZone

UReal

0.001

(symbol: \(v_{reg}\)) limit velocity [m/s] up to which the friction is proportional to velocity (for regularization / avoid numerical oscillations), see StribeckFunction in exudyn.physics (named regVel there!), Module: physics

contactStiffness

UReal

0.

(symbol: \(k_c\)) normal contact stiffness [SI:N/m] (units in case that \(n_\mathrm{exp}=1\))

contactDamping

UReal

0.

(symbol: \(d_c\)) linear normal contact damping [SI:N/(m s)]; this damping should be used (!=0) if the restitution coefficient is < 1, as it changes its behavior.

contactStiffnessExponent

PReal

1.

(symbol: \(n_\mathrm{exp}\)) exponent in normal contact model [SI:1]

restitutionCoefficient

PReal

1.

(symbol: \(e_\mathrm{res}\)) coefficient of restitution [SI:1]; used in particular for impact mechanics; different models available within parameter impactModel; the coefficient must be > 0, but can become arbitrarily small to emulate plastic impact (however very small values may lead to numerical problems)

minimumImpactVelocity

UReal

0.

(symbol: \(\dot\delta_\mathrm{-,min}\)) minimal impact velocity for coefficient of restitution [SI:1]; this value adds a lower bound for impact velocities for calculation of viscous impact force; it can be used to apply a larger damping behavior for low impact velocities (or permanent contact)

impactModel

UInt

0

(symbol: \(m_\mathrm{impact}\)) number of impact model: 0) linear model (only linear damping is used); 1) Hunt-Crossley model; 2) Gonthier/EtAl-Carvalho/Martins mixed model; model 2 is much more accurate regarding the coefficient of restitution, in the full range [0,1] except for 0; NOTE: in all models, the linear contactDamping is added, if not set to zero!

activeConnector

Bool

True

flag, which determines, if the connector is active; used to deactivate (temporarily) a connector or constraint

visualization

VObjectContactSphereTorus

parameters for visualization of item

Renamed parameters, still taken with a DeprecationWarning: radiusSphere (deprecated since 1.12.258, removed in 2031): use sphereRadius.

Visualization parameters

The parameters of VObjectContactSphereTorus, given as visualization:

name

type

size

default

description

show

Bool

False

set true, if item is shown in visualization and false if it is not shown; draws spheres by given radii

color

Float4

4

[0.7,0.7,0.7,1.]

RGBA connector color; if R==-1, use default color

Drawing

Drawn as all connectors; the sphere with contact.showSpheres and the center circle of the torus with contact.showTori.

Settings beyond those of all connectors: contact.colorSpheres, contact.colorTori, contact.showSpheres, contact.showTori, contact.tilingSpheres, general.circleTiling.

Output variables

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

output variable

symbol

description

Position

contact center point (also given for positive gap, when no contact occurs)

Displacement

global vector from marker 0 (sphere center) to marker 1 (torus center)

DisplacementLocal

1D Vector, containing only gap

Director1

normalized vector from marker 0 to marker 1

Director2

normalized vector from marker 1 (torus center) to the projection of marker 0 into the plane of the major circle

Director3

normalized vector from the center of the minor circle next to the sphere to the sphere center (marker 0): the contact normal

Velocity

velocity of the contact point on the torus relative to the one on the sphere, with the rotations of both

Force

global contact force vector

Torque

global torque due to friction on marker 0

Detailed description

Definition of quantities

intermediate variables

symbol

description

marker m0 position

\(\LU{0}{\pv}_{m0}\)

center of the sphere, provided by marker m0

marker m1 position

\(\LU{0}{\pv}_{m1}\)

center of the torus, provided by marker m1

marker m1 orientation

\(\LU{0,m1}{\Rot}\)

rotation of the torus, provided by marker m1

marker velocities

\(\LU{0}{\vv}_{m0}\), \(\LU{0}{\vv}_{m1}\)

global velocities of the two centers

marker angular velocities

\(\LU{0}{\tomega}_{m0}\), \(\LU{0}{\tomega}_{m1}\)

global angular velocities of sphere and torus

torus axis

\(\LU{0}{\av} = \LU{0,m1}{\Rot}\, \vv_{axis}\)

the axis torusAxis in the global frame

data coordinates

\(\xv=[x_0,\,x_1,\,x_2,\,x_3]\tp\)

the gap (0), the norm of the tangential velocity (1), the impact velocity (2); (3) is unused

Geometric relations

The sphere lies inside the torus - in its tube -, which is the case of a ball in the groove of a bearing ring; outer contact is not implemented. The sphere center is projected into the plane of the torus through \(\LU{0}{\pv}_{m1}\) normal to \(\LU{0}{\av}\), and the center of the tube circle next to it is

\[ \LU{0}{\pv}_{c} = \LU{0}{\pv}_{m1} + r_M \frac{\pv_{proj} - \LU{0}{\pv}_{m1}}{\Vert \pv_{proj} - \LU{0}{\pv}_{m1} \Vert} , \]

which fails if the sphere center is on the axis. With \(\Delta\pv = \LU{0}{\pv}_{m0} - \LU{0}{\pv}_{c}\), the gap and the normal are

\[ g = r_m - r_S - \Vert \Delta\pv \Vert , \quad \LU{0}{\nv} = \frac{\Delta\pv}{\Vert \Delta\pv \Vert} , \]

with the minor radius \(r_m\) and the sphere radius \(r_S\); the contact point is at \(\LU{0}{\pv}_{m0} + (r_S + g/2)\LU{0}{\nv}\), and the relative velocity there includes the rotations of both bodies.

Connector forces

The normal force - from the penetration \(\delta = -g\), with contactStiffness \(k_c\), the exponent \(n_\mathrm{exp}\), contactDamping \(d_c\) and the impact model impactModel with the restitution coefficient - and the regularized dry friction with \(\mu_d\) and frictionProportionalZone are computed exactly as for ObjectContactSphereSphere, see ObjectContactSphereSphere, with the normal \(\LU{0}{\nv}\) and the relative velocity at the contact point of this contact. The force on marker 1 is \(\LU{0}{\fv}\), the force on marker 0 is \(-\LU{0}{\fv}\); the friction force also gives a torque about the centers. The data coordinates hold the gap, the tangential velocity and the impact velocity of the last post Newton step, which decide on contact and on the friction regime during the Newton iterations (active set).

Mini example

#a ball in the groove of a torus, as in a ball bearing: pushed radially into the groove by a spring
inertia = InertiaSphere(mass=0.1, radius=0.01)
node = mbs.AddNode(NodeRigidBodyEP(referenceCoordinates=[0.1,0,0]+eulerParameters0))
ball = mbs.AddObject(ObjectRigidBody(nodeNumber=node, mass=inertia.Mass(), inertia=inertia.GetInertia6D()))
mRing = mbs.AddMarker(MarkerBodyRigid(bodyNumber=oGround, localPosition=[0,0,0]))
mBall = mbs.AddMarker(MarkerBodyRigid(bodyNumber=ball, localPosition=[0,0,0]))
nData = mbs.AddNode(NodeGenericData(numberOfDataCoordinates=4, initialCoordinates=[0,0,0,0]))
#groove of an outer ring: torus about z with major radius 0.1 and groove radius 0.011
mbs.AddObject(ObjectContactSphereTorus(markerNumbers=[mBall, mRing], nodeNumber=nData, sphereRadius=0.01,
                                       torusMajorRadius=0.1, torusMinorRadius=0.011, torusAxis=[0,0,1],
                                       contactStiffness=1e6, contactDamping=1e3))
mbs.AddLoad(LoadForceVector(markerNumber=mBall, loadVector=[10,0,0])) #pushes outwards

mbs.Assemble()
simulationSettings = exu.SimulationSettings()
simulationSettings.timeIntegration.numberOfSteps = 1000
mbs.SolveDynamic(simulationSettings)

#the ball rests in the groove: outwards by the play 0.001 and F/k
exu.sys['testResult'] = mbs.GetNodeOutput(node, exu.OutputVariableType.Position)[0] #0.10101

Relevant Examples (Ex) and TestModels (TM) with weblink to github: contactSphereTorusMomentumTest.py (TM)