(Experimental – API will change – use at your own risk) A unilateral contact constraint uses a single holonomic (position) constraint equation to prevent motion in one direction while leaving it unrestricted in the other direction. More...

Inheritance diagram for SimTK::UnilateralContact:

Public Member Functions
	UnilateralContact (int sign=1)
	The base class constructor allows specification of the sign convention to be used with this constraint. More...

virtual	~UnilateralContact ()

Real	getSignConvention () const
	Report the sign convention (1 or -1) supplied at construction. More...

virtual bool	disable (State &state) const =0
	Disable the normal and friction constraints if they were enabled. More...

virtual bool	enable (State &state) const =0
	Enable the normal and friction constraints if they were disabled. More...

virtual bool	isEnabled (const State &state) const =0
	Return true if this contact is enabled. More...

virtual Vec3	whereToDisplay (const State &state) const =0
	This returns a point in the ground frame at which you might want to say the constraint is "located", for purposes of display only. More...

virtual Real	calcEffectiveCOR (const State &state, Real defaultCaptureSpeed, Real defaultMinCORSpeed, Real impactSpeed) const =0
	Returns the effective coefficient of restitution (COR) for this contact, given an impact speed (a nonnegative scalar). More...

virtual Real	getPerr (const State &state) const =0
	Return the position error for the contact constraint (usually a signed distance function). More...

virtual Real	getVerr (const State &state) const =0
	Return the time derivative of the contact constraint position error. More...

virtual Real	getAerr (const State &state) const =0
	Return the time derivative of the contact constraint velocity error. More...

virtual bool	isProximal (const State &state, Real ptol) const
	Given the position constraint tolerance currently in use, is this contact close enough to contacting that we should treat it as though it is in contact? Normally we just see if sign*perr <= tol, but individual contacts can override this if they want to do some scaling. More...

virtual MultiplierIndex	getContactMultiplierIndex (const State &state) const =0
	Return the multiplier index Simbody assigned for the unilateral contact constraint (for contact, this is the normal constraint). More...

virtual bool	hasFriction (const State &state) const
	Returns `true` if there is a friction constraint associated with this contact constraint. More...

virtual Real	calcEffectiveCOF (const State &state, Real defaultTransitionSpeed, Real slipSpeed) const
	Returns the effective coefficient of friction mu for this contact, given a relative slip speed (a nonnegative scalar). More...

virtual Vec2	getSlipVelocity (const State &state) const

virtual void	getFrictionMultiplierIndices (const State &state, MultiplierIndex &ix_x, MultiplierIndex &ix_y) const
	If hasFriction(), this method returns the multipliers used for the x- and y-direction friction constraints. More...

virtual Vec3	getPositionInfo (const State &state) const
	TODO: kludge needed because we're misusing existing constraints. More...

virtual void	setInstanceParameter (State &state, const Vec3 &pos) const
	TODO: kludge to set instance parameters on internal constraints; this should be the same Vec3 you got from getPositionInfo(). More...

void	setMyIndex (UnilateralContactIndex cx)

UnilateralContactIndex	getMyIndex () const

Detailed Description

(Experimental – API will change – use at your own risk) A unilateral contact constraint uses a single holonomic (position) constraint equation to prevent motion in one direction while leaving it unrestricted in the other direction.

Examples are surface-surface contact, joint stops, and inextensible ropes. These constraints are subject to violent impacts that are treated with a coefficient of restitution that may be state dependent.

Some unilateral contacts may be associated with one or more friction elements that are dependent on the normal force generated by the contact. Whenever the unilateral contact is inactive (meaning its associated multiplier is zero), its associated friction elements are also inactive.

There are two possible sign conventions, depending on the underlying Constraint element definition. The default (sign=1) is to consider the constraint position error (perr) to be a signed distance function, meaning that perr>=0 is valid and perr<0 is a violation. Similarly verr>=0 is separation while verr<0 is approach or penetration velocity, and aerr>=0 is separation acceleration. The corresponding force should also be >= 0, but since constraint multipliers have the opposite sign from applied forces that means the inequality restricting the multiplier is lambda<=0; lambda>0 would produce an attractive force. That would suck, so is not allowed. In the opposite sign convention (sign=-1), the inequalities that must be satisfied are perr,verr,aerr<=0 and lambda>=0. So the constraints to be enforced are:

    sign*perr >= 0 (always)
    sign*verr >= 0 (if perr==0)
    if perr==verr==0 then:
        sign*aerr >= 0 && -sign*lambda >= 0 && aerr*lambda==0

In practice we enforce constraints up to a tolerance, so the zeroes above are not enforced exactly.

Constructor & Destructor Documentation

◆ UnilateralContact()

SimTK::UnilateralContact::UnilateralContact ( int sign = 1 )

inlineexplicit

The base class constructor allows specification of the sign convention to be used with this constraint.

The sign convention cannot be changed later. See the class documentation for more information.

◆ ~UnilateralContact()

virtual SimTK::UnilateralContact::~UnilateralContact ( )

inlinevirtual

Member Function Documentation

◆ getSignConvention()

Real SimTK::UnilateralContact::getSignConvention ( ) const

inline

Report the sign convention (1 or -1) supplied at construction.

◆ disable()

virtual bool SimTK::UnilateralContact::disable ( State & state ) const

pure virtual

Disable the normal and friction constraints if they were enabled.

Return true if we actually had to disable something.

Implemented in SimTK::EdgeEdgeContact, SimTK::SphereSphereContact, SimTK::SpherePlaneContact, SimTK::PointPlaneContact, SimTK::PointPlaneFrictionlessContact, SimTK::Rope, SimTK::HardStopLower, and SimTK::HardStopUpper.

◆ enable()

virtual bool SimTK::UnilateralContact::enable ( State & state ) const

pure virtual

Enable the normal and friction constraints if they were disabled.

Return true if we actually had to enable something.

Implemented in SimTK::EdgeEdgeContact, SimTK::SphereSphereContact, SimTK::SpherePlaneContact, SimTK::PointPlaneContact, SimTK::PointPlaneFrictionlessContact, SimTK::Rope, SimTK::HardStopLower, and SimTK::HardStopUpper.

◆ isEnabled()

virtual bool SimTK::UnilateralContact::isEnabled ( const State & state ) const

pure virtual

Return true if this contact is enabled.

Implemented in SimTK::EdgeEdgeContact, SimTK::SphereSphereContact, SimTK::SpherePlaneContact, SimTK::PointPlaneContact, SimTK::PointPlaneFrictionlessContact, SimTK::Rope, SimTK::HardStopLower, and SimTK::HardStopUpper.

◆ whereToDisplay()

virtual Vec3 SimTK::UnilateralContact::whereToDisplay ( const State & state ) const

pure virtual

This returns a point in the ground frame at which you might want to say the constraint is "located", for purposes of display only.

Implemented in SimTK::EdgeEdgeContact, SimTK::SphereSphereContact, SimTK::SpherePlaneContact, SimTK::PointPlaneContact, SimTK::PointPlaneFrictionlessContact, SimTK::Rope, SimTK::HardStopLower, and SimTK::HardStopUpper.

◆ calcEffectiveCOR()

virtual Real SimTK::UnilateralContact::calcEffectiveCOR	(	const State &	state,
		Real	defaultCaptureSpeed,
		Real	defaultMinCORSpeed,
		Real	impactSpeed
	)		const

pure virtual

Returns the effective coefficient of restitution (COR) for this contact, given an impact speed (a nonnegative scalar).

For a given pair of contacting materials this is typically a function of just the impact speed, but it could also depend on the time and configuration in state, which should be realized through Stage::Position. The given default impact speed thresholds (also nonnegative) are used to calculate the COR unless this Contact overrides those.

Implemented in SimTK::EdgeEdgeContact, SimTK::SphereSphereContact, SimTK::SpherePlaneContact, SimTK::PointPlaneContact, SimTK::PointPlaneFrictionlessContact, SimTK::Rope, SimTK::HardStopLower, and SimTK::HardStopUpper.

◆ getPerr()

virtual Real SimTK::UnilateralContact::getPerr ( const State & state ) const

pure virtual

Return the position error for the contact constraint (usually a signed distance function).

You have to apply the sign convention to interpret this properly.

Implemented in SimTK::EdgeEdgeContact, SimTK::SphereSphereContact, SimTK::SpherePlaneContact, SimTK::PointPlaneContact, SimTK::PointPlaneFrictionlessContact, SimTK::Rope, SimTK::HardStopLower, and SimTK::HardStopUpper.

◆ getVerr()

virtual Real SimTK::UnilateralContact::getVerr ( const State & state ) const

pure virtual

Return the time derivative of the contact constraint position error.

You have to apply the sign convention to interpret this properly.

Implemented in SimTK::EdgeEdgeContact, SimTK::SphereSphereContact, SimTK::SpherePlaneContact, SimTK::PointPlaneContact, SimTK::PointPlaneFrictionlessContact, SimTK::Rope, SimTK::HardStopLower, and SimTK::HardStopUpper.

◆ getAerr()

virtual Real SimTK::UnilateralContact::getAerr ( const State & state ) const

pure virtual

Return the time derivative of the contact constraint velocity error.

You have to apply the sign convention to interpret this properly.

Implemented in SimTK::EdgeEdgeContact, SimTK::SphereSphereContact, SimTK::SpherePlaneContact, SimTK::PointPlaneContact, SimTK::PointPlaneFrictionlessContact, SimTK::Rope, SimTK::HardStopLower, and SimTK::HardStopUpper.

◆ isProximal()

virtual bool SimTK::UnilateralContact::isProximal	(	const State &	state,
		Real	ptol
	)		const

inlinevirtual

Given the position constraint tolerance currently in use, is this contact close enough to contacting that we should treat it as though it is in contact? Normally we just see if sign*perr <= tol, but individual contacts can override this if they want to do some scaling.

◆ getContactMultiplierIndex()

virtual MultiplierIndex SimTK::UnilateralContact::getContactMultiplierIndex ( const State & state ) const

pure virtual

Return the multiplier index Simbody assigned for the unilateral contact constraint (for contact, this is the normal constraint).

If the constraint is not enabled, there is no multiplier and the returned index will be invalid.

Implemented in SimTK::EdgeEdgeContact, SimTK::SphereSphereContact, SimTK::SpherePlaneContact, SimTK::PointPlaneContact, SimTK::PointPlaneFrictionlessContact, SimTK::Rope, SimTK::HardStopLower, and SimTK::HardStopUpper.

◆ hasFriction()

virtual bool SimTK::UnilateralContact::hasFriction ( const State & state ) const

inlinevirtual

Returns true if there is a friction constraint associated with this contact constraint.

If so, calcEffectiveCOF() must be overridden.

Reimplemented in SimTK::EdgeEdgeContact, SimTK::SphereSphereContact, SimTK::SpherePlaneContact, and SimTK::PointPlaneContact.

◆ calcEffectiveCOF()

virtual Real SimTK::UnilateralContact::calcEffectiveCOF	(	const State &	state,
		Real	defaultTransitionSpeed,
		Real	slipSpeed
	)		const

inlinevirtual

Returns the effective coefficient of friction mu for this contact, given a relative slip speed (a nonnegative scalar).

For a given pair of contacting materials this is typically a function of just the slip speed, but it could also depend on the time and configuration in state, which should be realized through Stage::Position. The given default slip-to-roll transition speed threshold (also nonnegative) is used to calculate mu unless this Contact overrides it with its own transition speed.

Reimplemented in SimTK::EdgeEdgeContact, SimTK::SphereSphereContact, SimTK::SpherePlaneContact, and SimTK::PointPlaneContact.

◆ getSlipVelocity()

virtual Vec2 SimTK::UnilateralContact::getSlipVelocity ( const State & state ) const

inlinevirtual

Reimplemented in SimTK::EdgeEdgeContact, SimTK::SphereSphereContact, SimTK::SpherePlaneContact, and SimTK::PointPlaneContact.

◆ getFrictionMultiplierIndices()

virtual void SimTK::UnilateralContact::getFrictionMultiplierIndices	(	const State &	state,
		MultiplierIndex &	ix_x,
		MultiplierIndex &	ix_y
	)		const

inlinevirtual

If hasFriction(), this method returns the multipliers used for the x- and y-direction friction constraints.

If no friction, or if this constraint is disabled, the returned values are invalid.

Reimplemented in SimTK::EdgeEdgeContact, SimTK::SphereSphereContact, SimTK::SpherePlaneContact, and SimTK::PointPlaneContact.

◆ getPositionInfo()

virtual Vec3 SimTK::UnilateralContact::getPositionInfo ( const State & state ) const

inlinevirtual

TODO: kludge needed because we're misusing existing constraints.

This must be called while Stage::Position is valid.

◆ setInstanceParameter()

virtual void SimTK::UnilateralContact::setInstanceParameter	(	State &	state,
		const Vec3 &	pos
	)		const

inlinevirtual

TODO: kludge to set instance parameters on internal constraints; this should be the same Vec3 you got from getPositionInfo().

◆ setMyIndex()

void SimTK::UnilateralContact::setMyIndex ( UnilateralContactIndex cx )

inline

◆ getMyIndex()

UnilateralContactIndex SimTK::UnilateralContact::getMyIndex ( ) const

inline

The documentation for this class was generated from the following file:

ConditionalConstraint.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ UnilateralContact()

◆ ~UnilateralContact()

Member Function Documentation

◆ getSignConvention()

◆ disable()

◆ enable()

◆ isEnabled()

◆ whereToDisplay()

◆ calcEffectiveCOR()

◆ getPerr()

◆ getVerr()

◆ getAerr()

◆ isProximal()

◆ getContactMultiplierIndex()

◆ hasFriction()

◆ calcEffectiveCOF()

◆ getSlipVelocity()

◆ getFrictionMultiplierIndices()

◆ getPositionInfo()

◆ setInstanceParameter()

◆ setMyIndex()

◆ getMyIndex()