```{raw} latex \clearpage ``` (sec-item-objectcontactspheretorus)= # 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 - Nodes it takes: [](#sec-item-nodegenericdata) - Markers it acts on: those providing `Position` and `Orientation`: [](#sec-item-markerbodyrigid), [](#sec-item-markernoderigid), [](#sec-item-markersuperelementrigid), [](#sec-item-markerkinematictreerigid) ## 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, [](#sec-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!), [](#sec-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](#sec-drawing-objectsconnector); the sphere with `contact.showSpheres` and the center circle of the torus with `contact.showTori`. Settings beyond those of all connectors: [`contact.colorSpheres`](#sec-vsettingscontact), [`contact.colorTori`](#sec-vsettingscontact), [`contact.showSpheres`](#sec-vsettingscontact), [`contact.showTori`](#sec-vsettingscontact), [`contact.tilingSpheres`](#sec-vsettingscontact), [`general.circleTiling`](#sec-vsettingsgeneral). ## 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 | |---|---|---| | 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 | (description-objectcontactspheretorus)= ## 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 [](#sec-item-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). (miniexample-objectcontactspheretorus)= ## Mini example ```python #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`](https://github.com/jgerstmayr/EXUDYN/blob/master/python/TestModels/contactSphereTorusMomentumTest.py) (TM)