SimTK::CompliantContactSubsystem Class Reference

This is a force subsystem that implements a compliant contact model to respond to Contact objects as detected by a ContactTrackerSubsystem. More...

Inheritance diagram for SimTK::CompliantContactSubsystem:

Public Member Functions
	CompliantContactSubsystem ()
	Default constructor creates an empty handle. More...
	CompliantContactSubsystem (MultibodySystem &, const ContactTrackerSubsystem &)
	Add a new CompliantContactSubsystem to the indicated MultibodySystem, specifying the ContactTrackerSubsystem that we will use to obtain the list of ActiveContacts from which we will generate compliant forces. More...
Real	getTransitionVelocity () const
	Get the transition velocity (vt) of the friction model. More...
void	setTransitionVelocity (Real vt)
	Set the transition velocity (vt) of the friction model. More...
Real	getOOTransitionVelocity () const
	Get a precalculated 1/vt to avoid expensive runtime divisions. More...
void	setTrackDissipatedEnergy (bool shouldTrack)
	Specify whether to track energy dissipated by contacts. More...
bool	getTrackDissipatedEnergy () const
	Obtain the current setting of the "track dissipated energy" flag. More...
int	getNumContactForces (const State &state) const
	Determine how many of the active Contacts are currently generating contact forces. More...
const ContactForce &	getContactForce (const State &state, int n) const
	For each active Contact, get a reference to the most recently calculated force there; the ContactId that produced this force is available from the referenced ContactForce object. More...
const ContactForce &	getContactForceById (const State &state, ContactId id) const
	Get a reference to the ContactForce currently being produced by a particular ContactId; if that Contact is not currently producing forces then a reference to an invalid ContactForce is returned (you can check with isValid()). More...
bool	calcContactPatchDetailsById (const State &state, ContactId id, ContactPatch &patch) const
	Calculate detailed information about a particular active contact patch, including deformed geometric information, pressure and friction force distribution, and resultant forces and moments. More...
Real	getDissipatedEnergy (const State &state) const
	Obtain the total amount of energy dissipated by all the contact responses that were generated by this subsystem since some arbitrary starting point. More...
void	setDissipatedEnergy (State &state, Real energy) const
	Set the accumulated dissipated energy to an arbitrary value. More...
void	adoptForceGenerator (ContactForceGenerator *generator)
	Attach a new generator to this subsystem as the responder to be used when we see the kind of Contact type for which this generator is defined, replacing the previous generator for this Contact type if there was one. More...
void	adoptDefaultForceGenerator (ContactForceGenerator *generator)
	Attach a new generator to this subsystem as the responder to be used when we see a Contact type for which no suitable generator has been defined, replacing the previous default generator type if there was one. More...
bool	hasForceGenerator (ContactTypeId contact) const
	Return true if this subsystem has a force generator registered that can respond to this kind of Contact. More...
bool	hasDefaultForceGenerator () const
	Return true if this subsystem has a force generator registered that can be used for response to an unrecognized type of Contact (typically this will be a "do nothing" or "throw an error" generator. More...
const ContactForceGenerator &	getContactForceGenerator (ContactTypeId contact) const
	Return the force generator to be used for a Contact of the indicated type. More...
const ContactForceGenerator &	getDefaultForceGenerator () const
	Return the force generator to be used for a Contact type for which no suitable force generator has been registered. More...
const ContactTrackerSubsystem &	getContactTrackerSubsystem () const
	Get a read-only reference to the ContactTrackerSubsystem associated with this CompliantContactSubsystem. More...
const MultibodySystem &	getMultibodySystem () const
	Every Subsystem is owned by a System; a CompliantContactSubsystem expects to be owned by a MultibodySystem. More...
Public Member Functions inherited from SimTK::ForceSubsystem
	ForceSubsystem ()
	SimTK_PIMPL_DOWNCAST (ForceSubsystem, Subsystem)
Guts &	updRep ()
const Guts &	getRep () const
Public Member Functions inherited from SimTK::Subsystem
	Subsystem ()
	Default constructor creates and empty handle with a null Subsystem::Guts pointer. More...
	Subsystem (const Subsystem &)
	Copy constructor clones the Subsystem::Guts object if there is one and makes this the owner handle of the new clone. More...
Subsystem &	operator= (const Subsystem &)
	Copy assignment deletes the Subsystem::Guts object if there is one and then behaves like the copy constructor. More...
	~Subsystem ()
	Destructor deletes the referenced Subsystem::Guts object if this is the owner handle of that object, otherwise does nothing. More...
QIndex	allocateQ (State &s, const Vector &qInit) const
UIndex	allocateU (State &s, const Vector &uInit) const
ZIndex	allocateZ (State &s, const Vector &zInit) const
DiscreteVariableIndex	allocateDiscreteVariable (State &s, Stage g, AbstractValue *v) const
DiscreteVariableIndex	allocateAutoUpdateDiscreteVariable (State &s, Stage invalidates, AbstractValue *v, Stage updateDependsOn) const
CacheEntryIndex	allocateCacheEntry (const State &s, Stage dependsOn, Stage computedBy, AbstractValue *v) const
CacheEntryIndex	allocateCacheEntry (const State &state, Stage g, AbstractValue *v) const
CacheEntryIndex	allocateLazyCacheEntry (const State &state, Stage earliest, AbstractValue *v) const
QErrIndex	allocateQErr (const State &s, int nqerr) const
UErrIndex	allocateUErr (const State &s, int nuerr) const
UDotErrIndex	allocateUDotErr (const State &s, int nudoterr) const
EventTriggerByStageIndex	allocateEventTriggersByStage (const State &s, Stage g, int ntriggers) const
const Vector &	getQ (const State &s) const
const Vector &	getU (const State &s) const
const Vector &	getZ (const State &s) const
const Vector &	getUWeights (const State &s) const
const Vector &	getZWeights (const State &s) const
Vector &	updQ (State &s) const
Vector &	updU (State &s) const
Vector &	updZ (State &s) const
const Vector &	getQDot (const State &s) const
const Vector &	getUDot (const State &s) const
const Vector &	getZDot (const State &s) const
const Vector &	getQDotDot (const State &s) const
Vector &	updQDot (const State &s) const
Vector &	updUDot (const State &s) const
Vector &	updZDot (const State &s) const
Vector &	updQDotDot (const State &s) const
const Vector &	getQErr (const State &s) const
const Vector &	getUErr (const State &s) const
const Vector &	getQErrWeights (const State &s) const
const Vector &	getUErrWeights (const State &s) const
const Vector &	getUDotErr (const State &s) const
const Vector &	getMultipliers (const State &s) const
const Vector &	getEventTriggersByStage (const State &s, Stage g) const
Vector &	updQErr (const State &s) const
Vector &	updUErr (const State &s) const
Vector &	updUDotErr (const State &s) const
Vector &	updMultipliers (const State &s) const
Vector &	updEventTriggersByStage (const State &s, Stage g) const
SystemQIndex	getQStart (const State &s) const
int	getNQ (const State &s) const
SystemUIndex	getUStart (const State &s) const
int	getNU (const State &s) const
SystemZIndex	getZStart (const State &s) const
int	getNZ (const State &s) const
SystemQErrIndex	getQErrStart (const State &s) const
int	getNQErr (const State &s) const
SystemUErrIndex	getUErrStart (const State &s) const
int	getNUErr (const State &s) const
SystemUDotErrIndex	getUDotErrStart (const State &s) const
int	getNUDotErr (const State &s) const
SystemMultiplierIndex	getMultipliersStart (const State &s) const
int	getNMultipliers (const State &s) const
SystemEventTriggerByStageIndex	getEventTriggerStartByStage (const State &s, Stage g) const
int	getNEventTriggersByStage (const State &s, Stage g) const
void	setQ (State &s, const Vector &q) const
void	setU (State &s, const Vector &u) const
void	setZ (State &s, const Vector &z) const
Stage	getStage (const State &s) const
void	advanceToStage (const State &s, Stage g) const
const AbstractValue &	getDiscreteVariable (const State &s, DiscreteVariableIndex index) const
AbstractValue &	updDiscreteVariable (State &s, DiscreteVariableIndex index) const
const AbstractValue &	getCacheEntry (const State &s, CacheEntryIndex index) const
AbstractValue &	updCacheEntry (const State &s, CacheEntryIndex index) const
Real	getDiscreteVarLastUpdateTime (const State &s, DiscreteVariableIndex dx) const
CacheEntryIndex	getDiscreteVarUpdateIndex (const State &s, DiscreteVariableIndex dx) const
const AbstractValue &	getDiscreteVarUpdateValue (const State &s, DiscreteVariableIndex dx) const
AbstractValue &	updDiscreteVarUpdateValue (const State &s, DiscreteVariableIndex dx) const
bool	isDiscreteVarUpdateValueRealized (const State &s, DiscreteVariableIndex dx) const
void	markDiscreteVarUpdateValueRealized (const State &s, DiscreteVariableIndex dx) const
bool	isCacheValueRealized (const State &s, CacheEntryIndex cx) const
void	markCacheValueRealized (const State &s, CacheEntryIndex cx) const
void	markCacheValueNotRealized (const State &s, CacheEntryIndex cx) const
const String &	getName () const
	Obtain the Subsystem name if one was given on construction of the concrete Subsystem. More...
const String &	getVersion () const
	Obtain the Subsystem version string if one was given on construction. More...
bool	isInSystem () const
	Return true if this Subsystem is contained in a System. More...
bool	isInSameSystem (const Subsystem &otherSubsystem) const
	Return true if this Subsystem is contained in the same System as contains the given otherSubsystem. More...
const System &	getSystem () const
	Return a const reference to the System that contains this Subsystem. More...
System &	updSystem ()
	Return a writable reference to the System that contains this Subsystem. More...
void	setSystem (System &system, SubsystemIndex subx)
	Inform this Subsystem of the System that contains it, as well as the SubsystemIndex which the System has assigned to it. More...
SubsystemIndex	getMySubsystemIndex () const
	Return the SubsystemIndex within the containing System. More...
bool	isEmptyHandle () const
	Return true if this handle has a null Subsystem::Guts pointer. More...
bool	isSameSubsystem (const Subsystem &otherSubsystem) const
	Determine if this Subsystem handle refers to the same Subsystem::Guts object as handle otherSubsystem. More...
bool	isOwnerHandle () const
	Is this Subsystem handle the owner of the Subsystem::Guts object it points to? This is true if the handle is empty or if its Guts object points back to this handle. More...
bool	subsystemTopologyHasBeenRealized () const
	Returns true if this Subsystem's realizeTopology() method has been called since the last topological change or call to invalidateSubsystemTopologyCache(). More...
void	invalidateSubsystemTopologyCache () const
	Always call this method when a topological change is made to this Subsystem to indicate that any Stage::Topology cache values may need recomputation. More...
MeasureIndex	adoptMeasure (AbstractMeasure &)
	Obtain the Subsystem name if one was given on construction of the concrete Subsystem. More...
AbstractMeasure	getMeasure (MeasureIndex) const
	Obtain the Subsystem name if one was given on construction of the concrete Subsystem. More...
template<class T >
Measure_< T >	getMeasure_ (MeasureIndex mx) const
	Obtain the Subsystem name if one was given on construction of the concrete Subsystem. More...
const Subsystem::Guts &	getSubsystemGuts () const
	Obtain the Subsystem name if one was given on construction of the concrete Subsystem. More...
Subsystem::Guts &	updSubsystemGuts ()
	Obtain the Subsystem name if one was given on construction of the concrete Subsystem. More...
void	adoptSubsystemGuts (Subsystem::Guts *g)
	Obtain the Subsystem name if one was given on construction of the concrete Subsystem. More...
	Subsystem (Subsystem::Guts *g)
	Obtain the Subsystem name if one was given on construction of the concrete Subsystem. More...
bool	hasGuts () const
	Obtain the Subsystem name if one was given on construction of the concrete Subsystem. More...

Detailed Description

This is a force subsystem that implements a compliant contact model to respond to Contact objects as detected by a ContactTrackerSubsystem.

The subsystem contains an extendable collection of ContactForceGenerator objects, one per type of Contact. For example, a point contact would be handled by a different force generator than would a mesh contact.

Constructor & Destructor Documentation

CompliantContactSubsystem() [1/2]

SimTK::CompliantContactSubsystem::CompliantContactSubsystem ( )

inline

Default constructor creates an empty handle.

CompliantContactSubsystem() [2/2]

SimTK::CompliantContactSubsystem::CompliantContactSubsystem	(	MultibodySystem &	,
		const ContactTrackerSubsystem &
	)

Add a new CompliantContactSubsystem to the indicated MultibodySystem, specifying the ContactTrackerSubsystem that we will use to obtain the list of ActiveContacts from which we will generate compliant forces.

The MultibodySystem takes over ownership of the new subsystem object, but the handle we construct here retains a reference to it.

Member Function Documentation

getTransitionVelocity()

Real SimTK::CompliantContactSubsystem::getTransitionVelocity

(

)

const

Get the transition velocity (vt) of the friction model.

setTransitionVelocity()

void SimTK::CompliantContactSubsystem::setTransitionVelocity

(

Real

vt

)

Set the transition velocity (vt) of the friction model.

getOOTransitionVelocity()

Real SimTK::CompliantContactSubsystem::getOOTransitionVelocity

(

)

const

Get a precalculated 1/vt to avoid expensive runtime divisions.

setTrackDissipatedEnergy()

void SimTK::CompliantContactSubsystem::setTrackDissipatedEnergy

(

bool

shouldTrack

)

Specify whether to track energy dissipated by contacts.

This permits conservation of energy tests to be performed in the presence of dissipative contact elements. If you enable this, a state variable (z) will be allocated to integrate instantaneous dissipated power. By default energy dissipation is not tracked and an exception is thrown if it is requested. This is a topological change, meaning you'll have to call realizeTopology() and get a new State if you change the setting.

See also

getDissipatedEnergy(),setDissipatedEnergy(),getTrackDissipatedEnergy()

getTrackDissipatedEnergy()

bool SimTK::CompliantContactSubsystem::getTrackDissipatedEnergy

(

)

const

Obtain the current setting of the "track dissipated energy" flag.

You must not call getDissipatedEnergy() or setDissipatedEnergy() if this flag has not been set.

See also

getDissipatedEnergy(),setDissipatedEnergy(),setTrackDissipatedEnergy()

getNumContactForces()

int SimTK::CompliantContactSubsystem::getNumContactForces

(

const State &

state

)

const

Determine how many of the active Contacts are currently generating contact forces.

You can call this at Velocity stage or later; the contact forces will be realized first if necessary before we report how many there are.

getContactForce()

const ContactForce& SimTK::CompliantContactSubsystem::getContactForce	(	const State &	state,
		int	n
	)		const

For each active Contact, get a reference to the most recently calculated force there; the ContactId that produced this force is available from the referenced ContactForce object.

The ContactForce object is measured and expressed in the Ground frame. You can request this response at Velocity stage or later; the contact forces will be realized first if necessary.

See also

getContactForceById()

getContactForceById()

const ContactForce& SimTK::CompliantContactSubsystem::getContactForceById	(	const State &	state,
		ContactId	id
	)		const

Get a reference to the ContactForce currently being produced by a particular ContactId; if that Contact is not currently producing forces then a reference to an invalid ContactForce is returned (you can check with isValid()).

The ContactForce object is measured and expressed in the Ground frame. You can call this at Velocity stage or later; the contact forces (not just this one) will be realized first if necessary.

See also

getContactForce(), calcContactPatchDetailsById()

calcContactPatchDetailsById()

bool SimTK::CompliantContactSubsystem::calcContactPatchDetailsById	(	const State &	state,
		ContactId	id,
		ContactPatch &	patch
	)		const

Calculate detailed information about a particular active contact patch, including deformed geometric information, pressure and friction force distribution, and resultant forces and moments.

This detailed information is only calculated when requested because it may be expensive for some ContactForceGenerators; for simulation purposes only the resultants are needed. Resultant forces may be obtained cheaply by calling getContactForceById(); don't call this method unless you really need these details. The returned information will overwrite anything that is already in the supplied ContactPatch object; the contact point and vectors are expressed in Ground. You can call this operator at Velocity stage or higher. The result is calculated here and not saved internally.

Precondition

state realized to Stage::Velocity

Parameters

[in]	state	The state from whose active contacts we are selecting.
[in]	id	The ContactId of the Contact whose patch details are to be returned. This refers to a Contact within the ContactTrackerSubsystem associated with this ContactForceSubsystem.
[out]	patch	The object that will be overwritten with the result or set invalid if the given ContactId is not currently producing a patch. Results are returned in the Ground frame.

Returns

True if the indicated Contact is currently generating contact forces; false otherwise (in which case patch is also marked invalid).

See also

getContactForceById()

getDissipatedEnergy()

Real SimTK::CompliantContactSubsystem::getDissipatedEnergy

(

const State &

state

)

const

Obtain the total amount of energy dissipated by all the contact responses that were generated by this subsystem since some arbitrary starting point.

This information is available only if you have requested tracking by calling setTrackDissipatedEnergy().

This is the time integral of all the power dissipated during any of the contacts by material dissipative and friction forces. For a system whose only non-conservative forces are contacts, the sum of potential, kinetic, and dissipated energies should be conserved with an exception noted below. This is particularly useful for debugging new ContactForceGenerators. This is a State variable so you can obtain its value any time after it is allocated.

Precondition

state realized to Stage::Model

Parameters

[in]

state

The State from which to obtain the current value of the dissipated energy.

Returns

The total dissipated energy (a nonnegative scalar).

An error message will be thrown if you call this method without having turned on energy tracking via setTrackDissipatedEnergy().

Note

The Hunt and Crossley dissipation model used by many contact force generators can occasionally detect that a body is being "yanked" out of a contact (this is more likely with very large dissipation coefficients). To track all the energy in that case we would have to allow the surfaces to stick together, which is unreasonable. Instead, some of the energy will be lost to unmodeled effects because the surface is unable to transfer energy back to the bodies and will instead vibrate or ring until the energy is dissipated.

See also

setTrackDissipatedEnergy(), setDissipatedEnergy()

setDissipatedEnergy()

void SimTK::CompliantContactSubsystem::setDissipatedEnergy	(	State &	state,
		Real	energy
	)		const

Set the accumulated dissipated energy to an arbitrary value.

This is only permitted if you have requested tracking of dissipated energy by calling setTrackDissipatedEnergy().

Typically this method is used only to reset the dissipated energy to zero, but non-zero values can be useful if you are trying to match some existing data or continuing a simulation. This is a State variable so you can set its value any time after it is allocated.

Precondition

state realized to Stage::Model

Parameters

[in,out]	state	The State whose dissipated energy variable for this subsystem is to be modified.
[in]	energy	The new value for the accumulated dissipated energy (must be a nonnegative scalar).

An error message will be thrown if you call this method without having turned on energy tracking via setTrackDissipatedEnergy().

See also

getDissipatedEnergy(), setTrackDissipatedEnergy()

adoptForceGenerator()

void SimTK::CompliantContactSubsystem::adoptForceGenerator

(

ContactForceGenerator *

generator

)

Attach a new generator to this subsystem as the responder to be used when we see the kind of Contact type for which this generator is defined, replacing the previous generator for this Contact type if there was one.

The subsystem takes over ownership of the generator; don't delete it yourself.

adoptDefaultForceGenerator()

void SimTK::CompliantContactSubsystem::adoptDefaultForceGenerator

(

ContactForceGenerator *

generator

)

Attach a new generator to this subsystem as the responder to be used when we see a Contact type for which no suitable generator has been defined, replacing the previous default generator type if there was one.

The subsystem takes over ownership of the generator; don't delete it yourself.

hasForceGenerator()

bool SimTK::CompliantContactSubsystem::hasForceGenerator

(

ContactTypeId

contact

)

const

Return true if this subsystem has a force generator registered that can respond to this kind of Contact.

hasDefaultForceGenerator()

bool SimTK::CompliantContactSubsystem::hasDefaultForceGenerator

(

)

const

Return true if this subsystem has a force generator registered that can be used for response to an unrecognized type of Contact (typically this will be a "do nothing" or "throw an error" generator.

getContactForceGenerator()

const ContactForceGenerator& SimTK::CompliantContactSubsystem::getContactForceGenerator

(

ContactTypeId

contact

)

const

Return the force generator to be used for a Contact of the indicated type.

If no generator was registered for this type of contact, this will be the default generator.

getDefaultForceGenerator()

const ContactForceGenerator& SimTK::CompliantContactSubsystem::getDefaultForceGenerator

(

)

const

Return the force generator to be used for a Contact type for which no suitable force generator has been registered.

getContactTrackerSubsystem()

const ContactTrackerSubsystem& SimTK::CompliantContactSubsystem::getContactTrackerSubsystem

(

)

const

Get a read-only reference to the ContactTrackerSubsystem associated with this CompliantContactSubsystem.

This is the contact tracker that is maintaining the list of contacts for which this subsystem will be providing the response forces.

getMultibodySystem()

const MultibodySystem& SimTK::CompliantContactSubsystem::getMultibodySystem

(

)

const

Every Subsystem is owned by a System; a CompliantContactSubsystem expects to be owned by a MultibodySystem.

This method returns a const reference to the containing MultibodySystem and will throw an exception if there is no containing System or it is not a MultibodySystem.

---

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

• CompliantContactSubsystem.h