Simbody  3.5
SimTK::Constraint::Rod Class Reference

This constraint consists of one constraint equation that enforces a constant distance between a point on one body and a point on another body. More...

+ Inheritance diagram for SimTK::Constraint::Rod:

List of all members.

Public Member Functions

Construction

Methods in this section refer both to constructors, and to methods that can be used to set or change contruction (Topology-stage) parameters; these specify the values assigned by default to the corresponding state variables.

Note:

  • Changing one of these default parameters invalidates the containing System's topology, meaning that realizeTopology() will have to be called and a new State obtained before subsequent use.
  • The set...() methods return a reference to "this" Rod constraint element (in the manner of an assignment operator) so they can be chained in a single expression.

The default parameters can be overridden in any given State, and modified without affecting Topology; see the "Runtime Changes" section below.

 Rod (MobilizedBody &mobod1, const Vec3 &defaultPointOnBody1, MobilizedBody &mobod2, const Vec3 &defaultPointOnBody2, Real defaultRodLength)
 Construct a Rod (constant distance) constraint as described in the Constraint::Rod class documentation.
 Rod (MobilizedBody &mobod1, MobilizedBody &mobod2, Real defaultRodLength)
 Construct a Rod (constant distance) constraint as described in the Constraint::Rod class documentation, but using the body origins as the Rod end points.
 Rod ()
 Default constructor creates an empty handle that can be used to reference any Rod Constraint.
const MobilizedBodygetMobilizedBody1 () const
 Return a reference to the first MobilizedBody given in the constructor.
const MobilizedBodygetMobilizedBody2 () const
 Return a reference to the second MobilizedBody given in the constructor.
RodsetDefaultPointOnBody1 (const Vec3 &defaultPoint)
 Replace the default location for the point attached to the first body, mobod1, that was supplied on construction.
RodsetDefaultPointOnBody2 (const Vec3 &defaultPoint)
 Replace the default location for the point attached to the second body, mobod2, that was supplied on construction.
RodsetDefaultRodLength (Real defaultRodLength)
 Replace the default rod length (distance), replacing whatever value was supplied on construction.
const Vec3getDefaultPointOnBody1 () const
 Return the default location for the point attached to the first mobilized body, mobod1, as set during construction or by the most recent call to setDefaultPointOnBody1().
const Vec3getDefaultPointOnBody2 () const
 Return the default location for the point attached to the second mobilized body, mobod2, as set during construction or by the most recent call to setDefaultPointOnBody2().
Real getDefaultRodLength () const
 Return the default rod length (distance) as set during construction or by the most recent call to setDefaultRodLength().
Runtime Changes

These refer to Position-stage discrete state variables that determine the sphere parameters to be used to calculate constraint forces from a given State object.

If these are not set explicitly, the parameters are set to those provided in the constructor or via the correponding setDefault...() methods. Note:

  • Changing one of these parameters invalidates the given State's Stage::Position, meaning that the State's stage will be no higher than Stage::Time after the parameter change. That ensures that position constraint errors will be recalculated before they are used.
  • The set...() methods here return a const reference to "this" SphereOnSphereContact element (in the manner of an assignment operator, except read-only) so they can be chained in a single expression.

You can also modify and examine the default parameters; see the "Construction" section above.

const RodsetPointOnBody1 (State &state, const Vec3 &p_B1P) const
 Modify the location of the point P on the first body, mobod1, in this state by providing a new vector p_B1P giving the location of P measured from body 1's origin, and expressed in the B1 frame.
const RodsetPointOnBody2 (State &state, const Vec3 &p_B2Q) const
 Modify the location of the point Q on the second body, mobod2, in this state by providing a new vector p_B2Q giving the location of Q measured from body 2's origin, and expressed in the B2 frame.
const RodsetRodLength (State &state, Real rodLength) const
 Modify the rod length (distance) in this state.
const Vec3getPointOnBody1 (const State &state) const
 Return the position on body 1 of the rod end point P on the first body, mobod1, as currently set in the given state.
const Vec3getPointOnBody2 (const State &state) const
 Return the position on body 2 of the rod end point Q attached to the second body, mobod2, as currently set in the given state.
Real getRodLength (const State &state) const
 Return the rod length (distance) as currently set in the given state.
Computations

Methods here provide access to values already calculated by this constraint element, and provide operators you can call to calculate related values.

Real getPositionError (const State &) const
 This is the signed violation of the position constraint, in length units.
Real getVelocityError (const State &) const
 This is the time derivative of the value returned by getPositionError(); in this case it is the relative velocity of the two points projected onto the direction of the line between them.
Real getAccelerationError (const State &) const
 This is the time derivative of the value returned by getVelocityError().
Real getMultiplier (const State &) const
 This is the Lagrange multiplier required to enforce the constraint equation generated here.
Real getRodTension (const State &) const
 This returns the tension in the Rod being used to enforce the constraint.
UnitVec3 findRodOrientationInG (const State &state) const
 Return the instantaneous orientation of the Rod in the Ground frame.
Real findLengthViolation (const State &state) const
 Calculate the amount by which this constraint is violated.
Advanced/Obscure/Obsolete/Debugging

You probably don't want to use the methods in this section.

MobilizedBodyIndex getBody1MobilizedBodyIndex () const
 (Obscure) Use getMobilizedBody1() instead.
MobilizedBodyIndex getBody2MobilizedBodyIndex () const
 (Obscure) Use getMobilizedBody2() instead.

Detailed Description

This constraint consists of one constraint equation that enforces a constant distance between a point on one body and a point on another body.

This is like connecting them by a rigid, massless rod with ball joints at either end. The constraint is enforced by a force acting along the rod with opposite signs at either end. When positive, this represents tension in the rod pulling the points together; when negative it represents compression keeping the points separated.

Warning:
You can't use this to enforce a distance of zero between two points. That takes three constraints because there is no restriction on the force direction. For a distance of zero (i.e., you want the points to be coincident) use a Ball constraint, a.k.a. CoincidentPoints constraint.

Constructor & Destructor Documentation

SimTK::Constraint::Rod::Rod ( MobilizedBody mobod1,
const Vec3 defaultPointOnBody1,
MobilizedBody mobod2,
const Vec3 defaultPointOnBody2,
Real  defaultRodLength 
)

Construct a Rod (constant distance) constraint as described in the Constraint::Rod class documentation.

Parameters:
mobod1The first MobilizedBody object to which one of the rod endpoints is fixed.
defaultPointOnBody1This is the location of a point P on mobod1, given as a vector p_B1P from the B1 frame origin to the point P, expressed in the mobod1 body frame B1. This is the point location that will be present in a default State; you can modify it later.
mobod2The second MobilizedBody object to which the other rod endpoint is fixed.
defaultPointOnBody2This is the location of a point Q on mobod2, given as a vector p_B2Q from the B2 frame origin to the point Q, expressed in the mobod2 body frame B2. This is the point location that will be present in a default State; you can modify it later.
defaultRodLengthThe rod length (required distance between points P and Q). This is the value that will be present in a default State; you can modify it later.
SimTK::Constraint::Rod::Rod ( MobilizedBody mobod1,
MobilizedBody mobod2,
Real  defaultRodLength 
)

Construct a Rod (constant distance) constraint as described in the Constraint::Rod class documentation, but using the body origins as the Rod end points.

Parameters:
mobod1The first MobilizedBody object whose origin is used as one of the end points. This is the same as specifying Vec3(0) for defaultPointOnBody1 in the preceding constructor. This is the value that will be present in a default State; you can modify it later.
mobod2The second MobilizedBody object whose origin is used as one of the end points. This is the same as specifying Vec3(0) for defaultPointOnBody2 in the preceding constructor. This is the value that will be present in a default State; you can modify it later.
defaultRodLengthThe rod length (required distance between points P and Q). This is the value that will be present in a default State; you can modify it later.

Default constructor creates an empty handle that can be used to reference any Rod Constraint.


Member Function Documentation

Return a reference to the first MobilizedBody given in the constructor.

This cannot be changed after construction.

Return a reference to the second MobilizedBody given in the constructor.

This cannot be changed after construction.

Replace the default location for the point attached to the first body, mobod1, that was supplied on construction.

This is a topological change; you'll have to call realizeTopology() again if you call this method.

See also:
setPointOnBody1()

Replace the default location for the point attached to the second body, mobod2, that was supplied on construction.

This is a topological change; you'll have to call realizeTopology() again if you call this method.

See also:
setPointOnBody2()

Replace the default rod length (distance), replacing whatever value was supplied on construction.

This is a topological change; you'll have to call realizeTopology() again if you call this method.

See also:
setRodLength()

Return the default location for the point attached to the first mobilized body, mobod1, as set during construction or by the most recent call to setDefaultPointOnBody1().

See also:
getPointOnBody1()

Return the default location for the point attached to the second mobilized body, mobod2, as set during construction or by the most recent call to setDefaultPointOnBody2().

See also:
getPointOnBody2()

Return the default rod length (distance) as set during construction or by the most recent call to setDefaultRodLength().

See also:
getRodLength()
const Rod& SimTK::Constraint::Rod::setPointOnBody1 ( State state,
const Vec3 p_B1P 
) const

Modify the location of the point P on the first body, mobod1, in this state by providing a new vector p_B1P giving the location of P measured from body 1's origin, and expressed in the B1 frame.

This overrides the defaultPointOnBody1 in the given state, whose Stage::Position is invalidated.

See also:
getPointOnBody1(), setDefaultPointOnBody1()
const Rod& SimTK::Constraint::Rod::setPointOnBody2 ( State state,
const Vec3 p_B2Q 
) const

Modify the location of the point Q on the second body, mobod2, in this state by providing a new vector p_B2Q giving the location of Q measured from body 2's origin, and expressed in the B2 frame.

This overrides the defaultPointOnBody2 in the given state, whose Stage::Position is invalidated.

See also:
getPointOnBody2(), setDefaultPointOnBody2()
const Rod& SimTK::Constraint::Rod::setRodLength ( State state,
Real  rodLength 
) const

Modify the rod length (distance) in this state.

This overrides the defaultRodLength in the given state, whose Stage::Position is invalidated.

See also:
getRodLength(), setDefaultRodLength()
const Vec3& SimTK::Constraint::Rod::getPointOnBody1 ( const State state) const

Return the position on body 1 of the rod end point P on the first body, mobod1, as currently set in the given state.

The value is returned as a vector p_B1P from body 1's origin to the point P, expressed in the B1 frame.

See also:
setPointOnBody1(), getDefaultPointOnBody1()
const Vec3& SimTK::Constraint::Rod::getPointOnBody2 ( const State state) const

Return the position on body 2 of the rod end point Q attached to the second body, mobod2, as currently set in the given state.

The value is returned as a vector p_B2Q from body 2's origin to the point Q, expressed in the B2 frame.

See also:
setPointOnBody2(), getDefaultPointOnBody2()

Return the rod length (distance) as currently set in the given state.

See also:
setRodLength(), getDefaultRodLength()

This is the signed violation of the position constraint, in length units.

It is positive when the two points are separated by more than the required distance; negative when closer than the required distance. The given state must have already been realized through Stage::Position.

This is the time derivative of the value returned by getPositionError(); in this case it is the relative velocity of the two points projected onto the direction of the line between them.

This is the time derivative of the value returned by getVelocityError().

This is the Lagrange multiplier required to enforce the constraint equation generated here.

For this Constraint it has units of force, but recall that the sign convention for multipliers is opposite that of forces. Use the other provided methods if you want to get meaningful forces. The given state must already be realized to Stage::Acceleration.

This returns the tension in the Rod being used to enforce the constraint.

It is positive if the Rod is in tension, negative if in compression. The result is zero if the constraint is currently disabled. The given state must already be realized to Stage::Acceleration.

Return the instantaneous orientation of the Rod in the Ground frame.

This is a unit vector along the direction from point1 (on body 1) to point2 (on body 2), unless the points overlap in which case it is an arbitrary direction. This method calculates a valid value even if this constraint is currently disabled. The given state must already be realized to Stage::Position.

Calculate the amount by which this constraint is violated.

It is positive when the distance between the points is greater than the specified Rod length, negative when less. If the constraint is currently enabled then this returns the same value as getPositionError(); however, this method calculates a valid value even if the constraint is currently disabled. The given state must be realized to Stage::Position.


The documentation for this class was generated from the following file:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines