Class ExponentialSpringForce uses an "exponential spring" as a means of modeling contact of a specified point on a MobilizedBody with a contact plane that is fixed to Ground. More...

Inheritance diagram for SimTK::ExponentialSpringForce:

Public Member Functions
	ExponentialSpringForce (GeneralForceSubsystem &forces, const Transform &X_GP, const MobilizedBody &body_B, const Vec3 &station_B, ExponentialSpringParameters params=ExponentialSpringParameters())
	Construct an exponential spring force object with customized parameters. More...

const Transform &	getContactPlaneTransform () const
	Get the Transform specifying the location and orientation of the Contact Plane with respect to the Ground frame. More...

const MobilizedBody &	getBody () const
	Get the body (i.e., the MobilizedBody) to which the resultant contact force is applied and for which this exponential spring was instantiated. More...

const Vec3 &	getStation () const
	Get the point (body station) that interacts with the contact plane and at which the resulting contact force is applied. More...

void	setParameters (const ExponentialSpringParameters &params)
	Set the customizable Topology-stage parameters on this exponential spring instance. More...

const ExponentialSpringParameters &	getParameters () const
	Get a const reference to the parameters object owned by this exponential spring. More...

void	setMuStatic (State &state, Real mus)
	Set the static coefficient of friction (μₛ) for this exponential spring. More...

Real	getMuStatic (const State &state) const
	Get the static coefficient of friction (μₛ) held by the specified state for this exponential spring. More...

void	setMuKinetic (State &state, Real muk)
	Set the kinetic coefficient of friction (μₖ) for this exponential spring. More...

Real	getMuKinetic (const State &state) const
	Get the kinetic coefficient of friction (μₖ) held by the specified state for this exponential spring. More...

Real	getSliding (const State &state) const
	Get the Sliding state of this exponential spring after it has been updated to be consistent with the System State. More...

Vec3	getAnchorPointPosition (const State &state, bool inGround=true) const
	Get the position of the elastic anchor point (p₀), which will always lie in the Contact Plane. More...

void	resetAnchorPoint (State &state) const
	Reset the elastic anchor point (friction spring zero) so that it coincides with the projection of the body station onto the contact plane. More...

Vec3	getNormalForceElasticPart (const State &state, bool inGround=true) const
	Get the elastic part of the normal force. More...

Vec3	getNormalForceDampingPart (const State &state, bool inGround=true) const
	Get the damping part of the normal force. More...

Vec3	getNormalForce (const State &state, bool inGround=true) const
	Get the normal force. More...

Real	getMu (const State &state) const
	Get the instantaneous coefficient of friction (μ). More...

Real	getFrictionForceLimit (const State &state) const
	Get the friction limit. More...

Vec3	getFrictionForceElasticPart (const State &state, bool inGround=true) const
	Get the elastic part of the friction force. More...

Vec3	getFrictionForceDampingPart (const State &state, bool inGround=true) const
	Get the damping part of the friction force. More...

Vec3	getFrictionForce (const State &state, bool inGround=true) const
	Get the total friction force. More...

Vec3	getForce (const State &state, bool inGround=true) const
	Get the total force applied to the body by this ExponentialSpringForce instance. More...

Vec3	getStationPosition (const State &state, bool inGround=true) const
	Get the position of the body station (i.e., the point on the body at which the force generated by this ExponentialSpringForce is applied). More...

Vec3	getStationVelocity (const State &state, bool inGround=true) const
	Get the velocity of the body station (i.e., the point on the body at which the force generated by this ExponentialSpringForce is applied). More...

State Indices (Advanced)
If the State index of a discrete variable is known, the value of the variable can be accessed in a generic way by calling Subsystem::getDiscreteVariable() or Subsystem::updDiscreteVariable(). Such access is typically used by modeling frameworks, written on top of Simbody, to get and set State values in bulk (e.g., during serialization and deserialization). To support this functionality, a 'get' method for the State index of each discrete variable possessed by an ExponentialSpringForce instance is provided.
DiscreteVariableIndex	getMuStaticStateIndex () const
	Get the State index of the static coefficient of friction (μₛ) for this exponential spring. More...

DiscreteVariableIndex	getMuKineticStateIndex () const
	Get the State index of the kinetic coefficient of friction (μₖ) for this exponential spring. More...

DiscreteVariableIndex	getSlidingStateIndex () const
	Get the State index of the sliding state (K) for this exponential spring. More...

DiscreteVariableIndex	getAnchorPointStateIndex () const
	Get the State index of the elastic anchor point (p₀) for this exponential spring. More...

Public Member Functions inherited from SimTK::Force
void	disable (State &) const
	Disable this force element, effectively removing it from the System for computational purposes (it is still using its ForceIndex, however). More...

void	enable (State &) const
	Enable this force element if it was previously disabled. More...

bool	isDisabled (const State &) const
	Test whether this force element is currently disabled in the supplied State. More...

void	setDisabledByDefault (bool shouldBeDisabled)
	Normally force elements are enabled when defined and can be disabled later. More...

bool	isDisabledByDefault () const
	Test whether this force element is disabled by default in which case it must be explicitly enabled before it will take effect. More...

void	calcForceContribution (const State &state, Vector_< SpatialVec > &bodyForces, Vector_< Vec3 > &particleForces, Vector &mobilityForces) const
	Calculate the force that would be applied by this force element if the given state were realized to Dynamics stage. More...

Real	calcPotentialEnergyContribution (const State &state) const
	Calculate the potential energy contribution that is made by this force element at the given state. More...

	Force ()
	Default constructor for Force handle base class does nothing. More...

	operator ForceIndex () const
	Implicit conversion to ForceIndex when needed. More...

const GeneralForceSubsystem &	getForceSubsystem () const
	Get the GeneralForceSubsystem of which this Force is an element. More...

ForceIndex	getForceIndex () const
	Get the index of this force element within its parent force subsystem. More...

Public Member Functions inherited from SimTK::PIMPLHandle< Force, ForceImpl, true >
bool	isEmptyHandle () const
	Returns true if this handle is empty, that is, does not refer to any implementation object. More...

bool	isOwnerHandle () const
	Returns true if this handle is the owner of the implementation object to which it refers. More...

bool	isSameHandle (const Force &other) const
	Determine whether the supplied handle is the same object as "this" PIMPLHandle. More...

void	disown (Force &newOwner)
	Give up ownership of the implementation to an empty handle. More...

PIMPLHandle &	referenceAssign (const Force &source)
	"Copy" assignment but with shallow (pointer) semantics. More...

PIMPLHandle &	copyAssign (const Force &source)
	This is real copy assignment, with ordinary C++ object ("value") semantics. More...

void	clearHandle ()
	Make this an empty handle, deleting the implementation object if this handle is the owner of it. More...

const ForceImpl &	getImpl () const
	Get a const reference to the implementation associated with this Handle. More...

ForceImpl &	updImpl ()
	Get a writable reference to the implementation associated with this Handle. More...

int	getImplHandleCount () const
	Return the number of handles the implementation believes are referencing it. More...

Additional Inherited Members
Public Types inherited from SimTK::PIMPLHandle< Force, ForceImpl, true >
typedef PIMPLHandle< Force, ForceImpl, PTR >	HandleBase

typedef HandleBase	ParentHandle

Protected Member Functions inherited from SimTK::Force
	Force (ForceImpl *r)
	Use this in a derived Force handle class constructor to supply the concrete implementation object to be stored in the handle base. More...

Protected Member Functions inherited from SimTK::PIMPLHandle< Force, ForceImpl, true >
	PIMPLHandle ()
	The default constructor makes this an empty handle. More...

	PIMPLHandle (ForceImpl *p)
	This provides consruction of a handle referencing an existing implementation object. More...

	PIMPLHandle (const PIMPLHandle &source)
	The copy constructor makes either a deep (value) or shallow (reference) copy of the supplied source PIMPL object, based on whether this is a "pointer semantics" (PTR=true) or "object (value) semantics" (PTR=false, default) class. More...

	~PIMPLHandle ()
	Note that the destructor is non-virtual. More...

PIMPLHandle &	operator= (const PIMPLHandle &source)
	Copy assignment makes the current handle either a deep (value) or shallow (reference) copy of the supplied source PIMPL object, based on whether this is a "pointer sematics" (PTR=true) or "object (value) semantics" (PTR=false, default) class. More...

void	setImpl (ForceImpl *p)
	Set the implementation for this empty handle. More...

bool	hasSameImplementation (const Force &other) const
	Determine whether the supplied handle is a reference to the same implementation object as is referenced by "this" PIMPLHandle. More...

Detailed Description

Class ExponentialSpringForce uses an "exponential spring" as a means of modeling contact of a specified point on a MobilizedBody with a contact plane that is fixed to Ground.

In this documentation, this specified point is referred to as the "body station". Each ExponentialSpringForce instance acts at only one body station. In practice, you should choose a number of body stations strategically located across the surface of a MobilizedBody, and construct an ExponentialSpringForce for each of those body stations. For example, if the body were a cube, you would likely choose the body stations to be the corners of the cube and construct an ExponentialSpringForce instance for each corner of the cube (so a total of 8 instances). The contact plane is typically used to model interactions with a floor, but need not be limited to this use case. The contact plane can be rotated and displaced relative to the Ground frame and so can be used to model a wall, ramp, or some other planar structure.

A distinguishing feature of the exponential spring, relative to traditional contact models, is that it ALWAYS applies a force to the body; there is never a time in a simulation when the spring force is not applied. This seemingly non-physical feature works because (assuming default parameters are in use) the force becomes small (less than 0.01 N) as soon as the body station is more than 1.0 cm above the contact plane and extremely small (less than 0.000001 N) as soon as the body station is more than 2.0 cm above the contact plane. The sizes of these forces are likely small compared to the errors made in neglecting air resistance, assuming a uniform gravitational field, or estimating inertial parameters.

As a side note, electrostatic forces, which are the fundamental force from which all conventional contact forces arise, are never actually zero either. They obey Coulomb's Law (Fₑ = kₑq₁q₂/r²) which states that an electrostatic force only approaches zero as the distance between two charges (r) approaches infinity. It is certainly not the case that exponential springs accurately model contact force at the level of electrostatic forces; we only suggest that the use of a contact force field that acts over a great distance is reasonable as long as the force gets sufficiently small sufficiently quickly.

Introducing any additional modeling approximation into a simulation is hard to justify, however, unless there are significant benefits. In the case of exponential springs there are two: simplicity and speed. With exponential springs, there is no need to search for body intersections (the number of active springs does not change during a simulation) and there is no need to find the precise time of contact. In addition, because the function describing the contact force is smooth, the integration step sizes taken by variable-step explicit integrators are often well-behaved.

One of the challenges in modeling friction is handling the static case. When the net force applied to a body in a direction tangent to a contact plane is less than the limiting value of the static friction force (μₛ Fₙ), the body should not drift but remain fixed in place. One approach to handling this case is to apply conditional constraints that enforce zero acceleration of the body in the contact plane. Unfortunately, implementation of this approach is complex, particularly if there are multiple contact points on the body. Another approach is to apply a velocity-dependent frictional force that opposes any slide velocity (i.e., f = -cv). This latter approach is relatively simple to implement, but will not entirely eliminate drift. By making c very large, the drift velocity can be made small but it cannot be brought to zero. And, unfortunately, as c is made large, the system equations can become stiff, requiring integrator step size to be reduced, sometimes considerably (at least in explicit integrators).

Part of the speed-up offered by ExponentialSpringForce derives, not from the use of an exponential for the normal force, but from the friction model employed. ExponentialSpringForce uses a spring-based frictional model that includes a velocity-dependent (damping) term AND a position-dependent (elastic) term. By including the elastic term, drift is entirely eliminated and relatively large integration step sizes are maintained.

Computationally, using class ExponentialSpringForce to model contact is usually faster than using class CompliantContactSubsystem, and yet simulated motions are typically quite similar. For default parameter choices, ExponentialSpringForce is about 2x faster. However, if the drift velocity of CompliantContactSubsystem is brought down to 0.001 m/s, ExponentialSpringForce can be 100x faster. Computational comparisons can be performed by building and running the Test_Adhoc - ExponentialSpringsComparison project that is included with Simbody.

Aspects of the exponential spring contact model are described in the following publication:

    Anderson F.C. and Pandy M.G. (1999). A dynamics optimization
    solution for vertical jumping in three dimensions. Computer Methods
    in Biomechanics and Biomedical Engineering 2(3):201-231.

The current class makes several improvements to that contact model, most notably including 1) the ability to rotate and translate the contact plane and 2) the ability to specify both a static and a kinetic coefficient of friction. The computational details of the contact model implemented by this class follow below.

Computations and Coordinate Frames

The positive z-axis of the contact plane defines its normal. The positive z-axis is the axis along which the repelling normal force (modeled using an exponential) is applied. The x-axis and y-axis of the contact plane together define the tangent plane. Friction forces will always be tangent to the x-y plane.

In the equations below, a variable with a "z" suffix (e.g., pz, vz, or cz) refers to a quantity that is normal to the contact plane or that pertains to calculation of the normal force. A variable with an "xy" suffix (e.g., pxy, vxy, or cxy) refers to a quantity that lies in or is tangent to the contact plane or that pertains to calculation of the friction force.

Normal Force (positive z-axis)

The elastic part of the normal force is computed using an exponential whose shape is a function of three parameters (d₀, d₁, and d₂):

    fzElastic = d₁exp(−d₂(pz−d₀))

Note that pz is the displacement of the body station above (pz > 0.0) or below (pz < 0.0) the contact plane. The default values of the shape parameters were chosen to maximize integration step size while maintaining a number of constraints (e.g., the normal force should fall below 0.01 Newtons when pz > 1.0 cm). The damping part of the normal force is linear in velocity and scaled by the elastic part:

    fzDamping = −cz vz fzElastic,

where vz is the normal component of the velocity of the body station and cz is the damping coefficient for the normal direction. All together, the spring force in the normal direction is given by

    fz  = fzElastic + fzDamping
        = d₁exp(d₂(py−d₀)) − cz vz d₁exp(d₂(pz−d₀)))
        = d₁exp(d₂(pz−d₀)) (1 − cz vz)

which has the form of the Hunt & Crossley damping model:

    K. H. Hunt and F. R. E. Crossley (1975). Coefficient of Restitution
    Interpreted as Damping in Vibroimpact. ASME Journal of Applied
    Mechanics, pp. 440-445.

Friction Force (x-y plane)

The friction force is computed by blending two different friction models. The blending is performed based on the 'Sliding' State of the ExponentialSpringForce class. 'Sliding' characterizes the extent to which either static or kinetic conditions are present.

    Sliding = 0.0     static- fully fixed in place (lower bound)
    Sliding = 1.0     kinetic- fully sliding (upper bound)

Details about the Sliding State are given in sections below.

Friction Model 1 - Pure Damping (Sliding = 1.0)

When the body station is sliding with respect to the contact plane, the friction force is computed using a simple damping term:

    fricDamp = −cxy vxy

where cxy is the damping coefficient in the contact plane and vxy is the velocity of the body station in the contact plane expressed in the contact plane. However, the magnitude of the total frictional force is not allowed to exceed the frictional limit:

    fricLimit = μ fz
    if (|fricDamp| > fricLimit)
        fricDamp = −fricLimit vxy / |vxy| = −μ fz vxy / |vxy|

where μ is the instantaneous coefficient of friction (more below). Note that fz is always positive and so fricLimit is a positive scalar. Thus, for velocities in the contact plane above some threshold velocity, which is typically small (i.e., less than 0.1 m/s), this model is consistent with a standard Coulomb Friction model.

Friction Model 2 - Damped Linear Spring (Sliding = 0.0)

When the body station is anchored with respect to the contact plane, the friction force is represented by a damped linear spring. The viscous term is given by the same damping expression as above:

    fricDampSpr = −cxy vxy

and the elastic term is given by

    fricElasSpr = −kxy (pxy−p₀)

where kxy is the friction spring elasticity, pxy is the position of the body station projected onto the contact plane, and p₀ is the current spring zero (i.e., the elastic anchor point of the friction spring). Note that p₀ always resides in the contact plane.

The total friction spring force is then given by the sum of the elastic and viscous terms:

    fricSpr = fricElasSpr + fricDampSpr

If the magnitude of the fricSpr exceeds the magnitude of the friction limit, the terms are scaled down:

    if(|fricSpr| > fricLimit)
        scaleFactor = fricLimit / |fricSpr|
        fricDampSpr = scaleFactor * fricDampSpr
        fricElasSpr = scaleFactor * fricElasSpr
        fricSpr = fricElasSpr + fricDampSpr

Note that scaling down the friction spring force does not alter its direction.

Blending the Friction Models

Blending Model 1 and Model 2 is accomplished using linear expressions of the Sliding State:

    fricElasBlend = fricElasSpr * (1.0 − Sliding)
    fricDampBlend = fricDampSpr + (fricDamp − fricDampSpr)*Sliding
    fricBlend = fricElasBlend + fricDampBlend

Model 1 (Pure Damping) dominates as Sliding → 1.0, and Model 2 (Damped Linear Spring) dominates as Sliding → 0.0. The blending is well behaved and smooth for all values of Sliding between 0.0 and 1.0.

Moving the Elastic Anchor Point

The elastic anchor point (p₀) (i.e., the friction spring zero) is always made to be consistent with the final value of the blended elastic force (fricElasBlend):

    p₀ = pxy + fricElasBlend / kxy;
    p₀[2] = 0.0;  // ensures that p₀ lies in the contact plane

When fricElasBlend = 0.0, notice that p₀ = pxy, p₀[2] = 0.0. In other words, when Sliding = 1.0, p₀ is simply the position of the body station projected onto the contact plane.

In Simbody, p₀ is handled as an Auto Update Discrete State. See State::allocateAutoUpdateDiscreteVariable() for a detailed description. Any change to p₀ is made to the Update Cache (not to the State directly), and the integrator moves this cache value to the actual p₀ State after a successful integration step is obtained.

Coefficients of Friction and the Sliding State

Coefficients of kinetic (sliding) and static (fixed) friction can be specified separately for the spring, subject to the following constraints:

    0.0 ≤ μₖ ≤ μₛ

Note that there is no upper bound on μₛ. The instantaneous coefficient of friction (μ) is calculated based on the value of the Sliding State:

    μ = μₛ − Sliding*(μₛ − μₖ)

Like the elastic anchor point (p₀), Sliding is handled as an Auto Update Discrete State. Again, see State::allocateAutoUpdateDiscreteVariable() for a detailed description. Any change to Sliding is made to the Update Cache (not to the State directly), and the integrator moves the cache value to the actual Sliding State after a successful integration step is obtained.

The value of Sliding is calculated using a continuous function of the ratio of the speed of the elastic anchor point (ṗ₀) to the settle velocity (vSettle). vSettle is a customizable topology-stage parameter that represents the speed at which a body station settles into a static state. See ExponentialSpringParameters::setSettleVelocity() for details. Specifically, Sliding is calculated as follows:

    ṗ₀ = |Δp₀| / Δt
    Sliding = SimTK::stepUp( SimTK::clamp(0.0, ṗ₀/vSettle, 1.0) )

where Δp₀ is the change in p₀ and Δt is the change in time since the last successful integration step. When ṗ₀ ≥ vSettle, Sliding = 1.0, and as ṗ₀ → 0.0, Sliding → 0.0.

Future Enhancements

Enhancements might include the capacity to

Fix the contact plane to a body other than Ground,
Use a polygonal mesh as the contact surface, and
Move the body station in manner that adapts to contact circumstances. For example, to model a coin rolling on a table a small number of body stations could be continually moved to the portion of the coin that is closest to the table.

STATES

Each instance of ExponentialSpringForce possesses 4 states, which are listed below in the appropriate category:

DISCRETE STATES

μₛ (Real) = Static coefficient of friction. 0.0 ≤ μₛ
μₖ (Real) = Kinetic coefficient of friction. 0.0 ≤ μₖ ≤ μₛ

As discrete states, μₛ and μₖ can be changed during the course of a simulation without invalidating the System topology. This feature allows μₛ and μₖ to be altered during a simulation to model, for example, a slippery spot on the floor.

AUTO UPDATE DISCRETE STATES

p₀ (Vec3) = Elastic anchor point of the frictional spring. p₀ always lies in the contact plane.
Sliding (Real) = Sliding state of the body station. 0.0 ≤ Sliding ≤ 1.0. A value of 0.0 indicates that p₀ is "static" or fixed in place, in which case μ = μₛ. A value of 1.0 indicates that p₀ is "kinetic" or sliding, in which case μ = μₖ. A value between 0.0 and 1.0 indicates that a transition from fixed to sliding or from sliding to fixed is underway, in which case μₖ ≤ μ ≤ μₛ. Sliding is also used to blend between friction Model 1 and Model 2 (see above).

PARAMETERS

Customizable Topology-stage parameters specifying the characteristics of the exponential spring are managed using ExponentialSpringParameters.

DATA

Calculated quantities are cached during the appropriate realization stages (i.e., Stage::Position, Stage::Velocity, and Stage::Dynamics). Cached data is accessible via conventional "get" methods (see below).

Constructor & Destructor Documentation

◆ ExponentialSpringForce()

SimTK::ExponentialSpringForce::ExponentialSpringForce	(	GeneralForceSubsystem &	forces,
		const Transform &	X_GP,
		const MobilizedBody &	body_B,
		const Vec3 &	station_B,
		ExponentialSpringParameters	params = `ExponentialSpringParameters()`
	)

Construct an exponential spring force object with customized parameters.

Parameters

forces	The general force subsystem that encapsulates many (and possibly all) of the body forces, torques, and generalized forces applied to the system during a simulation.
X_GP	Transform specifying the location and orientation of the contact plane frame (P) with respect to the Ground frame (G). The positive z-axis of P defines the normal direction; the x-axis and y-axis of P together define the tangent (or friction) plane. Note that X_GP is the operator that transforms a point of P (point_P) to that same point in space but measured from the Ground origin (G₀) and expressed in G (i.e., point_G = X_GP * point_P).
body_B	MobilizedBody that will interact / collide with the contact plane. body_B defines frame B.
station_B	Point on the specified body at which the contact force will be applied. station_B is expressed in the local frame of body_B. The position and velocity of this point relative to the contact plane determine the magnitude and direction of the contact force.
params	Customized Topology-stage parameters. If params is omitted from the argument list, the default set of parameters is used.

Member Function Documentation

◆ getContactPlaneTransform()

const Transform& SimTK::ExponentialSpringForce::getContactPlaneTransform ( ) const

Get the Transform specifying the location and orientation of the Contact Plane with respect to the Ground frame.

This transform can be used to transform quantities expressed in the Contact Plane to the Ground frame and vice versa.

◆ getBody()

const MobilizedBody& SimTK::ExponentialSpringForce::getBody ( ) const

Get the body (i.e., the MobilizedBody) to which the resultant contact force is applied and for which this exponential spring was instantiated.

◆ getStation()

const Vec3& SimTK::ExponentialSpringForce::getStation ( ) const

Get the point (body station) that interacts with the contact plane and at which the resulting contact force is applied.

The body station is expressed in the frame of the body for which this exponential spring was instantiated.

◆ setParameters()

void SimTK::ExponentialSpringForce::setParameters ( const ExponentialSpringParameters & params )

Set the customizable Topology-stage parameters on this exponential spring instance.

To set the customizable Topology-stage parameters, create an ExponentialSpringParameters object, set the desired parameters on that object, and then call this method to modify the parameter values owned by this ExponentialSpringForce instance. Calling this method will invalidate the System at Stage::Topology; therefore, following a call to this method, System::realizeTopology() must be called before simulation can proceed.

Parameters

params Parameters object.

◆ getParameters()

const ExponentialSpringParameters& SimTK::ExponentialSpringForce::getParameters ( ) const

Get a const reference to the parameters object owned by this exponential spring.

The returned reference can be used to inspect the current values of the parameters or to create a copy of the parameters that is not owned by this exponential spring. The returned reference can also be used as the argument to setParameters() on a different spring object in order to assign its parameters to the values of this one. A non-const reference is not made available to the user in order to hinder casual changes made directly to the parameters owned by this subsystem. All changes made to the parameters owned by this subsystem must go through setParameters(). In this way, managing when system needs to be re-realized at Stage::Topology is streamlined.

◆ setMuStatic()

void SimTK::ExponentialSpringForce::setMuStatic	(	State &	state,
		Real	mus
	)

Set the static coefficient of friction (μₛ) for this exponential spring.

The value of μₛ is held in the System's State object. Unlike the parameters managed by ExponentialSpringParameters, μₛ can be set at any time during a simulation. A change to μₛ will invalidate the System at Stage::Dynamics.

Parameters

state	State object that will be modified.
mus	Value of the static coefficient of friction. No upper bound. 0.0 ≤ μₛ. If μₛ < μₖ, μₖ is set equal to μₛ.

◆ getMuStatic()

Real SimTK::ExponentialSpringForce::getMuStatic ( const State & state ) const

Get the static coefficient of friction (μₛ) held by the specified state for this exponential spring.

Parameters

state State object from which to retrieve μₛ.

◆ setMuKinetic()

void SimTK::ExponentialSpringForce::setMuKinetic	(	State &	state,
		Real	muk
	)

Set the kinetic coefficient of friction (μₖ) for this exponential spring.

The value of μₖ is held in the System's State object. Unlike the parameters managed by ExponentialSpringParameters, μₖ can be set at any time during a simulation. A change to μₖ will invalidate the System at Stage::Dynamics.

Parameters

state	State object that will be modified.
muk	Value of the kinetic coefficient of friction. No upper bound. 0.0 ≤ μₖ. If μₖ > μₛ, μₛ is set equal to μₖ.

◆ getMuKinetic()

Real SimTK::ExponentialSpringForce::getMuKinetic ( const State & state ) const

Get the kinetic coefficient of friction (μₖ) held by the specified state for this exponential spring.

Parameters

state State object from which to retrieve μₖ.

◆ getSliding()

Real SimTK::ExponentialSpringForce::getSliding ( const State & state ) const

Get the Sliding state of this exponential spring after it has been updated to be consistent with the System State.

This value should be used when analyzing or visualizing the dynamic behavior of this exponential spring. The System must be realized to Stage::Dynamics to access this data.

Parameters

state State object from which to retrieve the Sliding state.

◆ getAnchorPointPosition()

Vec3 SimTK::ExponentialSpringForce::getAnchorPointPosition	(	const State &	state,
		bool	inGround = `true`
	)		const

Get the position of the elastic anchor point (p₀), which will always lie in the Contact Plane.

p₀ is the spring zero of the damped linear spring used in Friction Model 2. The system must be realized to Stage::Dynamics to access this data.

Parameters

state	State object on which to base the calculations.
inGround	Flag for choosing the frame in which the returned quantity will be expressed. If true (the default), the quantity will be expressed in the Ground frame. If false, the quantity will be expressed in the frame of the contact plane.

◆ resetAnchorPoint()

void SimTK::ExponentialSpringForce::resetAnchorPoint ( State & state ) const

Reset the elastic anchor point (friction spring zero) so that it coincides with the projection of the body station onto the contact plane.

This step is often needed at the beginning of a simulation to ensure that a simulation does not begin with large friction forces. After this call, the elastic portion of the friction force should be 0.0 Calling this method will invalidate the System at Stage::Dynamics.

Parameters

state State object on which to base the reset.

◆ getNormalForceElasticPart()

Vec3 SimTK::ExponentialSpringForce::getNormalForceElasticPart	(	const State &	state,
		bool	inGround = `true`
	)		const

Get the elastic part of the normal force.

The system must be realized to Stage::Dynamics to access this data.

Parameters

state	State object on which to base the calculations.
inGround	Flag for choosing the frame in which the returned quantity will be expressed. If true (the default), the quantity will be expressed in the Ground frame. If false, the quantity will be expressed in the frame of the contact plane.

◆ getNormalForceDampingPart()

Vec3 SimTK::ExponentialSpringForce::getNormalForceDampingPart	(	const State &	state,
		bool	inGround = `true`
	)		const

Get the damping part of the normal force.

The system must be realized to Stage::Dynamics to access this data.

Parameters

state	State object on which to base the calculations.
inGround	Flag for choosing the frame in which the returned quantity will be expressed. If true (the default), the quantity will be expressed in the Ground frame. If false, the quantity will be expressed in the frame of the contact plane.

◆ getNormalForce()

Vec3 SimTK::ExponentialSpringForce::getNormalForce	(	const State &	state,
		bool	inGround = `true`
	)		const

Get the normal force.

The system must be realized to Stage::Dynamics to access this data.

Parameters

state	State object on which to base the calculations.
inGround	Flag for choosing the frame in which the returned quantity will be expressed. If true (the default), the quantity will be expressed in the Ground frame. If false, the quantity will be expressed in the frame of the contact plane.

◆ getMu()

Real SimTK::ExponentialSpringForce::getMu ( const State & state ) const

Get the instantaneous coefficient of friction (μ).

The system must be realized to Stage::Dynamics to access this data. μ is obtained by using the Sliding state to transition between μₖ and μₛ:

    μ = μₛ - Sliding*(μₛ - μₖ)

Because 0.0 ≤ Sliding ≤ 1.0, μₖ ≤ μ ≤ μₛ.

Parameters

state State object on which to base the calculations.

◆ getFrictionForceLimit()

Real SimTK::ExponentialSpringForce::getFrictionForceLimit ( const State & state ) const

Get the friction limit.

The system must be realized to Stage::Dynamics to access this data.

Parameters

state State object on which to base the calculations.

◆ getFrictionForceElasticPart()

Vec3 SimTK::ExponentialSpringForce::getFrictionForceElasticPart	(	const State &	state,
		bool	inGround = `true`
	)		const

Get the elastic part of the friction force.

The system must be realized to Stage::Dynamics to access this data.

Parameters

state	State object on which to base the calculations.
inGround	Flag for choosing the frame in which the returned quantity will be expressed. If true (the default), the quantity will be expressed in the Ground frame. If false, the quantity will be expressed in the frame of the contact plane.

◆ getFrictionForceDampingPart()

Vec3 SimTK::ExponentialSpringForce::getFrictionForceDampingPart	(	const State &	state,
		bool	inGround = `true`
	)		const

Get the damping part of the friction force.

The system must be realized to Stage::Dynamics to access this data.

Parameters

state	State object on which to base the calculations.
inGround	Flag for choosing the frame in which the returned quantity will be expressed. If true (the default), the quantity will be expressed in the Ground frame. If false, the quantity will be expressed in the frame of the contact plane.

◆ getFrictionForce()

Vec3 SimTK::ExponentialSpringForce::getFrictionForce	(	const State &	state,
		bool	inGround = `true`
	)		const

Get the total friction force.

The total frictional force is always just the sum of the elastic part and the damping part of the frictional force, which may be obtained separately by calling getFrictionalForceElasticPart() and getFrictionalForceDampingPart(). The system must be realized to Stage::Dynamics to access this data.

Parameters

state	State object on which to base the calculations.
inGround	Flag for choosing the frame in which the returned quantity will be expressed. If true (the default), the quantity will be expressed in the Ground frame. If false, the quantity will be expressed in the frame of the contact plane.

◆ getForce()

Vec3 SimTK::ExponentialSpringForce::getForce	(	const State &	state,
		bool	inGround = `true`
	)		const

Get the total force applied to the body by this ExponentialSpringForce instance.

The total force is the vector sum of the friction force, which may be obtained by a call to getFrictionForce(), and the normal force, which may be obtained by a call to getNormalForce(). The system must be realized to Stage::Dynamics to access this data.

Parameters

state	State object on which to base the calculations.
inGround	Flag for choosing the frame in which the returned quantity will be expressed. If true (the default), the quantity will be expressed in the Ground frame. If false, the quantity will be expressed in the frame of the contact plane.

◆ getStationPosition()

Vec3 SimTK::ExponentialSpringForce::getStationPosition	(	const State &	state,
		bool	inGround = `true`
	)		const

Get the position of the body station (i.e., the point on the body at which the force generated by this ExponentialSpringForce is applied).

This method differs from getStation() in terms of the frame in which the station is expressed. getStation() expresses the point in the frame of the MobilizedBody. getStationPosition() expresses the point either in the Ground frame or in the frame of the Contact Plane. The system must be realized to Stage::Position to access this data.

Parameters

state	State object on which to base the calculations.
inGround	Flag for choosing the frame in which the returned quantity will be expressed. If true (the default), the quantity will be expressed in the Ground frame. If false, the quantity will be expressed in the frame of the contact plane.

◆ getStationVelocity()

Vec3 SimTK::ExponentialSpringForce::getStationVelocity	(	const State &	state,
		bool	inGround = `true`
	)		const

Get the velocity of the body station (i.e., the point on the body at which the force generated by this ExponentialSpringForce is applied).

The system must be realized to Stage::Velocity to access this data.

Parameters

state	State object on which to base the calculations.
inGround	Flag for choosing the frame in which the returned quantity will be expressed. If true (the default), the quantity will be expressed in the Ground frame. If false, the quantity will be expressed in the frame of the contact plane.

◆ getMuStaticStateIndex()

DiscreteVariableIndex SimTK::ExponentialSpringForce::getMuStaticStateIndex ( ) const

Get the State index of the static coefficient of friction (μₛ) for this exponential spring.

Returns: Index of μₛ.

◆ getMuKineticStateIndex()

DiscreteVariableIndex SimTK::ExponentialSpringForce::getMuKineticStateIndex ( ) const

Get the State index of the kinetic coefficient of friction (μₖ) for this exponential spring.

Returns: Index of μₖ.

◆ getSlidingStateIndex()

DiscreteVariableIndex SimTK::ExponentialSpringForce::getSlidingStateIndex ( ) const

Get the State index of the sliding state (K) for this exponential spring.

Returns: Index of K.

◆ getAnchorPointStateIndex()

DiscreteVariableIndex SimTK::ExponentialSpringForce::getAnchorPointStateIndex ( ) const

Get the State index of the elastic anchor point (p₀) for this exponential spring.

Returns: Index of p₀.

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

ExponentialSpringForce.h

Public Member Functions

Additional Inherited Members

Detailed Description

Computations and Coordinate Frames

Normal Force (positive z-axis)

Friction Force (x-y plane)

Friction Model 1 - Pure Damping (Sliding = 1.0)

Friction Model 2 - Damped Linear Spring (Sliding = 0.0)

Blending the Friction Models

Moving the Elastic Anchor Point

Coefficients of Friction and the Sliding State

Future Enhancements

STATES

DISCRETE STATES

AUTO UPDATE DISCRETE STATES

PARAMETERS

DATA

Constructor & Destructor Documentation

◆ ExponentialSpringForce()

Member Function Documentation

◆ getContactPlaneTransform()

◆ getBody()

◆ getStation()

◆ setParameters()

◆ getParameters()

◆ setMuStatic()

◆ getMuStatic()

◆ setMuKinetic()

◆ getMuKinetic()

◆ getSliding()

◆ getAnchorPointPosition()

◆ resetAnchorPoint()

◆ getNormalForceElasticPart()

◆ getNormalForceDampingPart()

◆ getNormalForce()

◆ getMu()

◆ getFrictionForceLimit()

◆ getFrictionForceElasticPart()

◆ getFrictionForceDampingPart()

◆ getFrictionForce()

◆ getForce()

◆ getStationPosition()

◆ getStationVelocity()

◆ getMuStaticStateIndex()

◆ getMuKineticStateIndex()

◆ getSlidingStateIndex()

◆ getAnchorPointStateIndex()