Simbody  3.3
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
SimTK::MobilizedBody Class Reference

A MobilizedBody is Simbody's fundamental body-and-joint object used to parameterize a system's motion by constructing a multibody tree containing each body and its unique "mobilizer" (internal coordinate joint). More...

#include <MobilizedBody.h>

+ Inheritance diagram for SimTK::MobilizedBody:

Classes

class  Ball
 Three mobilities – unrestricted orientation modeled with a quaternion which is never singular. More...
 
class  BendStretch
 Two mobilities: The z axis of the parent's F frame is used for rotation (and that is always aligned with the M frame z axis). More...
 
class  Bushing
 Six mobilities – arbitrary relative motion modeled as x-y-z translation followed by an x-y-z body-fixed Euler angle sequence, though with a singularity when the middle angle is +/- 90 degrees. More...
 
class  Custom
 The handle class MobilizedBody::Custom (dataless) and its companion class MobilizedBody::Custom::Implementation can be used together to define new MobilizedBody types with arbitrary properties. More...
 
class  Cylinder
 Two mobilities – rotation and translation along the common z axis of the inboard and outboard mobilizer frames. More...
 
class  Ellipsoid
 Three mobilities – coordinated rotation and translation along the surface of an ellipsoid fixed to the parent (inboard) body. More...
 
class  Free
 Unrestricted motion for a rigid body (six mobilities). More...
 
class  FreeLine
 Five mobilities, representing unrestricted motion for a body which is inertialess along its own z axis. More...
 
class  FunctionBased
 This is a subclass of MobilizedBody::Custom which uses a set of Function objects to define the behavior of the MobilizedBody. More...
 
class  Gimbal
 Three mobilities – unrestricted orientation modeled as a 1-2-3 body-fixed Euler angle sequence, though with a singularity when the middle angle is +/- 90 degrees. More...
 
class  Ground
 This is a special type of "mobilized" body generated automatically by Simbody as a placeholder for Ground in the 0th slot for a SimbodyMatterSubsystem's mobilized bodies; don't create this yourself. More...
 
class  LineOrientation
 Two mobilities, representing unrestricted orientation for a body which is inertialess along its own z axis. More...
 
class  Pin
 Provides one rotational mobility about the common z axis of the F and M frames of the mobilizer. More...
 
class  Planar
 Three mobilities – z rotation and x,y translation. More...
 
class  Screw
 One mobility – coordinated rotation and translation along the common z axis of the inboard and outboard mobilizer frames. More...
 
class  Slider
 One mobility – translation along the common x axis of the F (inboard) and M (outboard) mobilizer frames. More...
 
class  SphericalCoords
 Three mobilities – body fixed 3-2 (z-y) rotation followed by translation along body z or body x. More...
 
class  Translation
 Three translational mobilities describing the Cartesian motion of a point. More...
 
class  Universal
 Two mobilities – rotation about the x axis, followed by a rotation about the new y axis. More...
 
class  Weld
 Zero mobilities. More...
 

Public Types

enum  Direction {
  Forward = 0,
  Reverse = 1
}
 Constructors can take an argument of this type to indicate that the mobilizer is being defined in the reverse direction, meaning from the outboard (child) body to the inboard (parent) body. More...
 
typedef Pin Torsion
 Synonym for Pin mobilizer. More...
 
typedef Pin Revolute
 Synonym for Pin mobilizer. More...
 
typedef Slider Prismatic
 Synonym for Slider mobilizer. More...
 
typedef Translation Cartesian
 Synonym for Translation mobilizer. More...
 
typedef Translation CartesianCoords
 Synonym for Translation mobilizer. More...
 
typedef BendStretch PolarCoords
 Synonym for BendStretch mobilizer. More...
 
typedef Ball Orientation
 Synonym for Ball mobilizer. More...
 
typedef Ball Spherical
 Synonym for Ball mobilizer. More...
 
- Public Types inherited from SimTK::PIMPLHandle< MobilizedBody, MobilizedBodyImpl, true >
typedef PIMPLHandle
< MobilizedBody,
MobilizedBodyImpl, PTR > 
HandleBase
 
typedef HandleBase ParentHandle
 

Public Member Functions

 MobilizedBody ()
 The default constructor provides an empty MobilizedBody handle that can be assigned to reference any type of MobilizedBody. More...
 
 MobilizedBody (MobilizedBodyImpl *r)
 Internal use only. More...
 
Mobilizer locking and unlocking

Every MobilizedBody object supports locking and unlocking of the mobilizer it contains.

You can lock the mobilizer's position, velocity, or acceleration. In all cases the generalized accelerations udot of a locked mobilizer are prescribed. If you lock just the accelerations, then velocity and position remain free. If you lock velocity, then the generalized speeds u are prescribed to specified values, accelerations udot are prescribed to zero, and positions will remain free. If you lock position (the default locking level) then the generalized coordinates q are prescribed to specified values and the speeds u and accelerations udot are prescribed to zero. Prescribed values may be obtained from the current state, or set explicitly. The lock() and lockAt() methods when called at position level will modify q in the given state if necessary to satisfy the locked position, and will set u to zero. When called at velocity level they will modify u if necessary to satisfied the locked velocity, but will leave q unchanged.

You can also specify that a mobilizer is locked by default (at acceleration, velocity, or position level). In that case the prescribed value is recorded when the state is realized to Stage::Model, using values taken from the state at that time.

If this mobilizer is driven by a Motion object, locking overrides that while the lock is active; when unlocked the Motion object resumes control.

void lock (State &state, Motion::Level level=Motion::Position) const
 Lock this mobilizer's position or velocity at its current value, or lock the acceleration to zero, depending on the level parameter. More...
 
void lockAt (State &state, Real value, Motion::Level level=Motion::Position) const
 Lock this mobilizer's q, u, or udot to the given scalar value, depending on level. More...
 
void lockAt (State &state, const Vector &value, Motion::Level level=Motion::Position) const
 Lock this mobilizer's q, u, or udot to the given Vector value, depending on level. More...
 
template<int N>
void lockAt (State &state, const Vec< N > &value, Motion::Level level=Motion::Position) const
 Lock this mobilizer's q, u, or udot to the given Vec<N> value, depending on the level. More...
 
void unlock (State &state) const
 Unlock this mobilizer, returning it to its normal behavior which may be free motion or may be controlled by a Motion object. More...
 
bool isLocked (const State &state) const
 Check whether this mobilizer is currently locked in the given state. More...
 
Motion::Level getLockLevel (const State &state) const
 Returns the lock level if the mobilizer is locked in the given state, otherwise Motion::NoLevel. More...
 
Vector getLockValueAsVector (const State &state) const
 Return the q, u, or udot value at which this mobilizer is locked, depending on the lock level, as a Vector of the appropriate length. More...
 
MobilizedBodylockByDefault (Motion::Level level=Motion::Position)
 Change whether this mobilizer is initially locked. More...
 
bool isLockedByDefault () const
 Check whether this mobilizer is to be locked in the default state. More...
 
Motion::Level getLockByDefaultLevel () const
 Returns the level at which the mobilizer is locked by default, if it is locked by default, otherwise Motion::NoLevel. More...
 
State Access - Bodies

These methods extract already-computed information from the State or State cache, or set values in the State.

const TransformgetBodyTransform (const State &state) const
 Extract from the state cache the already-calculated spatial configuration X_GB of body B's body frame, measured with respect to the Ground frame and expressed in the Ground frame. More...
 
const RotationgetBodyRotation (const State &state) const
 Extract from the state cache the already-calculated spatial orientation R_GB of body B's body frame x, y, and z axes expressed in the Ground frame, as the Rotation matrix R_GB. More...
 
const Vec3getBodyOriginLocation (const State &state) const
 Extract from the state cache the already-calculated spatial location of body B's body frame origin Bo, measured from the Ground origin Go and expressed in the Ground frame, as the position vector p_GB (== p_GoBo). More...
 
const TransformgetMobilizerTransform (const State &state) const
 At stage Position or higher, return the cross-mobilizer transform X_FM, the body's inboard mobilizer frame M measured and expressed in the parent body's corresponding outboard frame F. More...
 
const SpatialVecgetBodyVelocity (const State &state) const
 Extract from the state cache the already-calculated spatial velocity V_GB of this body's reference frame B, measured with respect to the Ground frame and expressed in the Ground frame. More...
 
const Vec3getBodyAngularVelocity (const State &state) const
 Extract from the state cache the already-calculated inertial angular velocity vector w_GB of this body B, measured with respect to the Ground frame and expressed in the Ground frame. More...
 
const Vec3getBodyOriginVelocity (const State &state) const
 Extract from the state cache the already-calculated inertial linear velocity vector v_GB (more explicitly, v_GBo) of this body B's origin point Bo, measured with respect to the Ground frame and expressed in the Ground frame. More...
 
const SpatialVecgetMobilizerVelocity (const State &state) const
 At stage Velocity or higher, return the cross-mobilizer velocity V_FM, the relative velocity of this body's "moving" mobilizer frame M in the parent body's corresponding "fixed" frame F, measured and expressed in F. More...
 
const SpatialVecgetBodyAcceleration (const State &state) const
 Extract from the state cache the already-calculated spatial acceleration A_GB of this body's reference frame B, measured with respect to the Ground frame and expressed in the Ground frame. More...
 
const Vec3getBodyAngularAcceleration (const State &state) const
 Extract from the state cache the already-calculated inertial angular acceleration vector b_GB of this body B, measured with respect to the Ground frame and expressed in the Ground frame. More...
 
const Vec3getBodyOriginAcceleration (const State &state) const
 Extract from the state cache the already-calculated inertial linear acceleration vector a_GB (more explicitly, a_GBo) of this body B's origin point Bo, measured with respect to the Ground frame and expressed in the Ground frame. More...
 
const SpatialVecgetMobilizerAcceleration (const State &state) const
 TODO: Not implemented yet – any volunteers? At stage Acceleration, return the cross-mobilizer acceleration A_FM, the relative acceleration of body B's "moving" mobilizer frame M in the parent body's corresponding "fixed" frame F, measured and expressed in F. More...
 
const MassPropertiesgetBodyMassProperties (const State &state) const
 Return a reference to this body's mass properties in the State cache. More...
 
const SpatialInertiagetBodySpatialInertiaInGround (const State &state) const
 Return a reference to the already-calculated SpatialInertia of this body, taken about the body's origin (not its mass center), and expressed in the Ground frame. More...
 
Real getBodyMass (const State &state) const
 Return the mass of this body. More...
 
const Vec3getBodyMassCenterStation (const State &state) const
 Return this body's center of mass station (i.e., the vector fixed in the body, going from body origin to body mass center, expressed in the body frame.) The State must have been realized to Stage::Instance or higher. More...
 
const UnitInertiagetBodyUnitInertiaAboutBodyOrigin (const State &state) const
 Return a reference to this body's unit inertia matrix in the State cache, taken about the body origin and expressed in the body frame. More...
 
const TransformgetInboardFrame (const State &state) const
 Return a reference to this mobilizer's frame F fixed on the parent body P, as the fixed Transform from P's body frame to the frame F fixed to P. More...
 
const TransformgetOutboardFrame (const State &state) const
 Return a reference to this MobilizedBody's mobilizer frame M, as the fixed Transform from this body B's frame to the frame M fixed on B. More...
 
void setInboardFrame (State &state, const Transform &X_PF) const
 TODO: not implemented yet. More...
 
void setOutboardFrame (State &state, const Transform &X_BM) const
 TODO: not implemented yet. More...
 
State Access - Mobilizer generalized coordinates q and speeds u

These methods extract q- or u-related information from the State or State cache, or set q or u values in the State.

int getNumQ (const State &state) const
 Return the number of generalized coordinates q currently in use by this mobilizer. More...
 
int getNumU (const State &state) const
 Return the number of generalized speeds u currently in use by this mobilizer. More...
 
QIndex getFirstQIndex (const State &state) const
 Return the global QIndex of the first q for this mobilizer; all the q's range from getFirstQIndex() to QIndex(getFirstQIndex()+getNumQ()-1). More...
 
UIndex getFirstUIndex (const State &state) const
 Return the global UIndex of the first u for this mobilizer; all the u's range from getFirstUIndex() to UIndex(getFirstUIndex()+getNumU()-1). More...
 
Motion::Method getQMotionMethod (const State &state) const
 Determine how generalized coordinate q values are being determined. More...
 
Motion::Method getUMotionMethod (const State &state) const
 Determine how generalized speed u values are being determined. More...
 
Motion::Method getUDotMotionMethod (const State &state) const
 Determine how generalized acceleration udot values are being determined. More...
 
Real getOneQ (const State &state, int which) const
 Return one of the generalized coordinates q from this mobilizer's partition of the matter subsystem's full q vector in the State. More...
 
Real getOneU (const State &state, int which) const
 Return one of the generalized speeds u from this mobilizer's partition of the matter subsystem's full u vector in the State. More...
 
Vector getQAsVector (const State &state) const
 Return as a Vector of length getNumQ() all the generalized coordinates q currently in use by this mobilizer, from this mobilizer's partion in the matter subsystem's full q vector in the State. More...
 
Vector getUAsVector (const State &state) const
 Return as a Vector of length getNumU() all the generalized speeds u currently in use by this mobilizer, from this mobilizer's partion in the matter subsystem's full u vector in the State. More...
 
Real getOneQDot (const State &state, int which) const
 Return one of the generalized coordinate derivatives qdot from this mobilizer's partition of the matter subsystem's full qdot vector in the State cache. More...
 
Vector getQDotAsVector (const State &state) const
 Return as a Vector of length getNumQ() all the generalized coordinate derivatives qdot currently in use by this mobilizer, from this mobilizer's partition in the matter subsystem's full qdot vector in the State cache. More...
 
Real getOneUDot (const State &state, int which) const
 Return one of the generalized accelerations udot from this mobilizer's partition of the matter subsystem's full udot vector in the State cache. More...
 
Real getOneQDotDot (const State &state, int which) const
 Return one of the generalized coordinate second derivatives qdotdot from this mobilizer's partition of the matter subsystem's full qdotdot vector in the State cache. More...
 
Vector getUDotAsVector (const State &state) const
 Return as a Vector of length getNumU() all the generalized accelerations udot currently in use by this mobilizer, from this mobilizer's partion in the matter subsystem's full udot vector in the State cache. More...
 
Vector getQDotDotAsVector (const State &state) const
 Return as a Vector of length getNumQ() all the generalized coordinate second derivatives qdotdot currently in use by this mobilizer, from this mobilizer's partion in the matter subsystem's full qdotdot vector in the State cache. More...
 
Vector getTauAsVector (const State &state) const
 Return the generalized forces tau resulting from prescribed (known) acceleration, corresponding to each of this mobilizer's mobilities, as a Vector of length nu=getNumU(). More...
 
Real getOneTau (const State &state, MobilizerUIndex which) const
 Return one of the tau forces resulting from prescribed (known) acceleration, corresponding to one of this mobilizer's mobilities as selected here using the which parameter, numbered from zero to getNumU()-1. More...
 
void setOneQ (State &state, int which, Real v) const
 Set one of the generalized coordinates q to value v, in this mobilizer's partition of the matter subsystem's full q vector in the State. More...
 
void setOneU (State &state, int which, Real v) const
 Set one of the generalized speeds u to value v, in this mobilizer's partition of the matter subsystem's full u vector in the State. More...
 
void setQFromVector (State &state, const Vector &v) const
 Set all of the generalized coordinates q to value v (a Vector of length getNumQ()), in this mobilizer's partition of the matter subsystem's full q vector in the State. More...
 
void setUFromVector (State &state, const Vector &v) const
 Set all of the generalized speeds u to value v (a Vector of length getNumU()), in this mobilizer's partition of the matter subsystem's full u vector in the State. More...
 
void setQToFitTransform (State &state, const Transform &X_FM) const
 Adjust this mobilizer's q's to best approximate the supplied Transform which requests a particular relative orientation and translation between the F "fixed" frame and M "moving" frame connected by this mobilizer. More...
 
void setQToFitRotation (State &state, const Rotation &R_FM) const
 Adjust this mobilizer's q's to best approximate the supplied Rotation matrix which requests a particular relative orientation between the "fixed" frame F and "moving" frame M connected by this mobilizer. More...
 
void setQToFitTranslation (State &state, const Vec3 &p_FM) const
 Adjust this mobilizer's q's to best approximate the supplied position vector which requests a particular offset between the origins of the F "fixed" frame and M "moving" frame connected by this mobilizer, with any q's (rotational or translational) being modified if doing so helps satisfy the request. More...
 
void setUToFitVelocity (State &state, const SpatialVec &V_FM) const
 Adjust this mobilizer's u's (generalized speeds) to best approximate the supplied spatial velocity V_FM which requests the relative angular and linear velocity between the "fixed" and "moving" frames connected by this mobilizer. More...
 
void setUToFitAngularVelocity (State &state, const Vec3 &w_FM) const
 Adjust this mobilizer's u's (generalized speeds) to best approximate the supplied angular velocity w_FM which requests a particular relative angular between the "fixed" and "moving" frames connected by this mobilizer. More...
 
void setUToFitLinearVelocity (State &state, const Vec3 &v_FM) const
 Adjust any of this mobilizer's u's (generalized speeds) to best approximate the supplied linear velocity v_FM which requests a particular velocity for the "moving" frame M origin in the "fixed" frame F on the parent where these are the frames connected by this mobilizer. More...
 
SpatialVec getHCol (const State &state, MobilizerUIndex ux) const
 Expert use only: obtain a column of the hinge matrix H corresponding to one of this mobilizer's mobilities (actually a column of H_PB_G; what Jain calls H* and Schwieters calls H^T). More...
 
SpatialVec getH_FMCol (const State &state, MobilizerUIndex ux) const
 Expert use only: obtain a column of the mobilizer-local hinge matrix H_FM which maps generalized speeds u to cross-mobilizer spatial velocity V_FM via V_FM=H_FM*u. More...
 
Basic Operators

These methods use state variables and Response methods to compute basic quantities which cannot be precomputed, but which can be implemented with an inline combination of basic floating point operations which can be reliably determined at compile time.

The method names and descriptions use the following terms:

  • Body or ThisBody: the Body B associated with the current MobilizedBody. ThisBody is implied when no other Body is mentioned.
  • Ground: the "MobilizedBody" G representing the Ground reference frame which never moves.
  • AnotherBody: the Body A being referenced, which in general is neither ThisBody nor Ground.
  • Station: a point S fixed on ThisBody B, located by a position vector p_BS (or more explicitly, p_BoS) from the B-frame origin Bo to the point S, expressed in the B-frame coordinate system.
  • Vector: a vector v fixed on ThisBody B, given by a vector v_B expressed in the B-frame coordinate system.
  • Direction: a unit vector u fixed on ThisBody B, given by a unit vector u_B expressed in the B-frame coordinate system.
  • Frame: an origin and coordinate axes F fixed on ThisBody B, given by a transform X_BF that locates F's origin (a Station) in B and expresses each of F's axes (Directions) in B.
  • Origin: the Station located at (0,0,0) in ThisBody frame B, that is, body B's origin point.
  • MassCenter: the Station on ThisBody B which is the center of mass for B.
  • GroundPoint, GroundVector: a Point P or Vector v on the Ground "Body" G. These are measured and expressed in the Ground frame, as p_GP or v_G.
  • AnotherBodyStation, AnotherBodyVector, etc.: a Station S or Vector v on AnotherBody A. These are measured and expressed in the A frame, as p_AS or v_A.
  • Mobilizer frame M: the mobilizer's outboard "moving" frame, fixed to ThisBody B.
  • Mobilizer frame F: the mobilizer's inboard "fixed" frame, fixed to the parent body P.
Transform findBodyTransformInAnotherBody (const State &state, const MobilizedBody &inBodyA) const
 Return X_AB, the spatial transform giving this body B's frame in body A's frame. More...
 
Rotation findBodyRotationInAnotherBody (const State &state, const MobilizedBody &inBodyA) const
 Return R_AB, the rotation matrix giving this body B's axes in body A's frame. More...
 
Vec3 findBodyOriginLocationInAnotherBody (const State &state, const MobilizedBody &toBodyA) const
 Return the station on another body A (that is, a point measured and expressed in A) that is currently coincident in space with the origin Bo of this body B. More...
 
SpatialVec findBodyVelocityInAnotherBody (const State &state, const MobilizedBody &inBodyA) const
 Return the angular and linear velocity of body B's frame in body A's frame, expressed in body A, and arranged as a SpatialVec. More...
 
Vec3 findBodyAngularVelocityInAnotherBody (const State &state, const MobilizedBody &inBodyA) const
 Return the angular velocity w_AB of body B's frame in body A's frame, expressed in body A. More...
 
Vec3 findBodyOriginVelocityInAnotherBody (const State &state, const MobilizedBody &inBodyA) const
 Return the velocity of body B's origin point in body A's frame, expressed in body A. More...
 
SpatialVec findBodyAccelerationInAnotherBody (const State &state, const MobilizedBody &inBodyA) const
 Return the angular and linear acceleration of body B's frame in body A's frame, expressed in body A, and arranged as a SpatialVec. More...
 
Vec3 findBodyAngularAccelerationInAnotherBody (const State &state, const MobilizedBody &inBodyA) const
 Return the angular acceleration of body B's frame in body A's frame, expressed in body A. More...
 
Vec3 findBodyOriginAccelerationInAnotherBody (const State &state, const MobilizedBody &inBodyA) const
 Return the acceleration of body B's origin point in body A's frame, expressed in body A. More...
 
SpatialVec findMobilizerReactionOnBodyAtMInGround (const State &state) const
 Return the spatial reaction force (moment and force) applied by the mobilizer to body B at the location of the mobilizer frame M (fixed to body B, but not necessarily at the body frame origin), expressed in Ground. More...
 
SpatialVec findMobilizerReactionOnBodyAtOriginInGround (const State &state) const
 Return the spatial reaction force (moment and force) applied by the mobilizer to body B but shifted to the B frame origin, and expressed in Ground. More...
 
SpatialVec findMobilizerReactionOnParentAtFInGround (const State &state) const
 Return the spatial reaction force (moment and force) applied by the mobilizer to the parent (inboard) body P at the location of the inboard "fixed" mobilizer frame F (fixed to body P, but not necessarily at the P frame origin), expressed in Ground. More...
 
SpatialVec findMobilizerReactionOnParentAtOriginInGround (const State &state) const
 Return the spatial reaction force (moment and force) applied by the mobilizer to the parent (inboard) body P at the location of the P frame origin, and expressed in Ground. More...
 
Vec3 findStationLocationInGround (const State &state, const Vec3 &stationOnB) const
 Return the Cartesian (ground) location that is currently coincident with a station (point) S fixed on body B. More...
 
Vec3 findStationLocationInAnotherBody (const State &state, const Vec3 &stationOnB, const MobilizedBody &toBodyA) const
 Given a station S on this body B, return the location on another body A which is at the same location in space. More...
 
Vec3 findStationVelocityInGround (const State &state, const Vec3 &stationOnB) const
 Given a station fixed on body B, return its inertial (Cartesian) velocity, that is, its velocity relative to the Ground frame, expressed in the Ground frame. More...
 
Vec3 findStationVelocityInAnotherBody (const State &state, const Vec3 &stationOnBodyB, const MobilizedBody &inBodyA) const
 Return the velocity of a station S fixed on body B, in body A's frame, expressed in body A. More...
 
Vec3 findStationAccelerationInGround (const State &state, const Vec3 &stationOnB) const
 Given a station fixed on body B, return its inertial (Cartesian) acceleration, that is, its acceleration relative to the ground frame, expressed in the ground frame. More...
 
Vec3 findStationAccelerationInAnotherBody (const State &state, const Vec3 &stationOnBodyB, const MobilizedBody &inBodyA) const
 Return the acceleration of a station S fixed on body B, in another body A's frame, expressed in body A. More...
 
void findStationLocationAndVelocityInGround (const State &state, const Vec3 &locationOnB, Vec3 &locationOnGround, Vec3 &velocityInGround) const
 It is cheaper to calculate a station's ground location and velocity together than to do them separately. More...
 
void findStationLocationVelocityAndAccelerationInGround (const State &state, const Vec3 &locationOnB, Vec3 &locationOnGround, Vec3 &velocityInGround, Vec3 &accelerationInGround) const
 It is cheaper to calculate a station's ground location, velocity, and acceleration together than to do them separately. More...
 
Vec3 findMassCenterLocationInGround (const State &state) const
 Return the Cartesian (ground) location of this body B's mass center. More...
 
Vec3 findMassCenterLocationInAnotherBody (const State &state, const MobilizedBody &toBodyA) const
 Return the point of another body A that is currently coincident in space with the mass center CB of this body B. More...
 
Vec3 findStationAtGroundPoint (const State &state, const Vec3 &locationInG) const
 Return the station (point) S of this body B that is coincident with the given Ground location. More...
 
Vec3 findStationAtAnotherBodyStation (const State &state, const MobilizedBody &fromBodyA, const Vec3 &stationOnA) const
 Return the station (point) on this body B that is coincident with the given station on another body A. More...
 
Vec3 findStationAtAnotherBodyOrigin (const State &state, const MobilizedBody &fromBodyA) const
 Return the station S of this body that is currently coincident in space with the origin Ao of another body A. More...
 
Vec3 findStationAtAnotherBodyMassCenter (const State &state, const MobilizedBody &fromBodyA) const
 Return the station S of this body that is currently coincident in space with the mass center Ac of another body A. More...
 
Transform findFrameTransformInGround (const State &state, const Transform &frameOnB) const
 Return the current Ground-frame pose (position and orientation) of a frame F that is fixed to body B. More...
 
SpatialVec findFrameVelocityInGround (const State &state, const Transform &frameOnB) const
 Return the current Ground-frame spatial velocity V_GF (that is, angular and linear velocity) of a frame F that is fixed to body B. More...
 
SpatialVec findFrameAccelerationInGround (const State &state, const Transform &frameOnB) const
 Return the current Ground-frame spatial acceleration A_GF (that is, angular and linear acceleration) of a frame F that is fixed to body B. More...
 
Vec3 expressVectorInGroundFrame (const State &state, const Vec3 &vectorInB) const
 Re-express a vector expressed in this body B's frame into the same vector in G, by applying only a rotation. More...
 
Vec3 expressGroundVectorInBodyFrame (const State &state, const Vec3 &vectorInG) const
 Re-express a vector expressed in Ground into the same vector expressed in this body B, by applying only rotation. More...
 
Vec3 expressVectorInAnotherBodyFrame (const State &state, const Vec3 &vectorInB, const MobilizedBody &inBodyA) const
 Re-express a vector expressed in this body B into the same vector expressed in body A, by applying only a rotation. More...
 
MassProperties expressMassPropertiesInGroundFrame (const State &state) const
 Re-express this body B's mass properties in Ground by applying only a rotation, not a shift of reference point. More...
 
MassProperties expressMassPropertiesInAnotherBodyFrame (const State &state, const MobilizedBody &inBodyA) const
 Re-express this body B's mass properties in another body A's frame by applying only a rotation, not a shift of reference point. More...
 
High-Level Operators

High level operators combine State Access and Basic Operators with run-time tests to calculate more complex MobilizedBody-specific quantities, with more complicated implementations that can exploit special cases at run time.

SpatialMat calcBodySpatialInertiaMatrixInGround (const State &state) const
 Return the mass properties of body B, measured from and about the B origin Bo, but expressed in Ground and then returned as a Spatial Inertia Matrix. More...
 
Inertia calcBodyCentralInertia (const State &state, MobilizedBodyIndex objectBodyB) const
 Return the central inertia for body B, that is, the inertia taken about body B's mass center Bc, and expressed in B. More...
 
Inertia calcBodyInertiaAboutAnotherBodyStation (const State &state, const MobilizedBody &inBodyA, const Vec3 &aboutLocationOnBodyA) const
 Return the inertia of this body B, taken about an arbitrary point PA of body A, and expressed in body A. More...
 
SpatialVec calcBodyMomentumAboutBodyOriginInGround (const State &state)
 Calculate body B's momentum (angular, linear) measured and expressed in Ground, but taken about the body origin Bo. More...
 
SpatialVec calcBodyMomentumAboutBodyMassCenterInGround (const State &state) const
 Calculate body B's momentum (angular, linear) measured and expressed in Ground, but taken about the body mass center Bc. More...
 
Real calcStationToStationDistance (const State &state, const Vec3 &locationOnBodyB, const MobilizedBody &bodyA, const Vec3 &locationOnBodyA) const
 Calculate the distance from a station PB on body B to a station PA on body A. More...
 
Real calcStationToStationDistanceTimeDerivative (const State &state, const Vec3 &locationOnBodyB, const MobilizedBody &bodyA, const Vec3 &locationOnBodyA) const
 Calculate the time rate of change of distance from a fixed point PB on body B to a fixed point PA on body A. More...
 
Real calcStationToStationDistance2ndTimeDerivative (const State &state, const Vec3 &locationOnBodyB, const MobilizedBody &bodyA, const Vec3 &locationOnBodyA) const
 Calculate the second time derivative of distance from a fixed point PB on body B to a fixed point PA on body A. More...
 
Vec3 calcBodyMovingPointVelocityInBody (const State &state, const Vec3 &locationOnBodyB, const Vec3 &velocityOnBodyB, const MobilizedBody &inBodyA) const
 TODO: not implemented yet – any volunteers? Return the velocity of a point P moving on body B, in body A's frame, expressed in body A. More...
 
Vec3 calcBodyMovingPointAccelerationInBody (const State &state, const Vec3 &locationOnBodyB, const Vec3 &velocityOnBodyB, const Vec3 &accelerationOnBodyB, const MobilizedBody &inBodyA) const
 TODO: not implemented yet – any volunteers? Return the velocity of a point P moving (and possibly accelerating) on body B, in body A's frame, expressed in body A. More...
 
Real calcMovingPointToPointDistanceTimeDerivative (const State &state, const Vec3 &locationOnBodyB, const Vec3 &velocityOnBodyB, const MobilizedBody &bodyA, const Vec3 &locationOnBodyA, const Vec3 &velocityOnBodyA) const
 TODO: not implemented yet – any volunteers? Calculate the time rate of change of distance from a moving point PB on body B to a moving point PA on body A. More...
 
Real calcMovingPointToPointDistance2ndTimeDerivative (const State &state, const Vec3 &locationOnBodyB, const Vec3 &velocityOnBodyB, const Vec3 &accelerationOnBodyB, const MobilizedBody &bodyA, const Vec3 &locationOnBodyA, const Vec3 &velocityOnBodyA, const Vec3 &accelerationOnBodyA) const
 TODO: not implemented yet – any volunteers? Calculate the second time derivative of distance from a moving point PB on body B to a moving point PA on body A. More...
 
Construction and Misc Methods

These methods are the base class services which are used while building a concrete MobilizedBody, or to query a MobilizedBody to find out how it was built.

These are unlikely to be used by end users of MobilizedBodies.

const BodygetBody () const
 Return a const reference to the Body contained within this MobilizedBody. More...
 
BodyupdBody ()
 Return a writable reference to the Body contained within this MobilizedBody. More...
 
MobilizedBodysetBody (const Body &)
 Replace the Body contained within this MobilizedBody with a new one. More...
 
int addBodyDecoration (const Transform &X_BD, const DecorativeGeometry &geometry)
 Add decorative geometry specified relative to the new (outboard) body's reference frame B. More...
 
int addBodyDecoration (const DecorativeGeometry &geometry)
 Convenience method for use when the geometry is supplied in the body frame. More...
 
int addOutboardDecoration (const Transform &X_MD, const DecorativeGeometry &geometry)
 Add decorative geometry specified relative to the outboard mobilizer frame M attached to body B. More...
 
int getNumOutboardDecorations () const
 Return the count of decorations added with addOutboardDecoration(). More...
 
const DecorativeGeometrygetOutboardDecoration (int i) const
 Return a const reference to the i'th outboard decoration. More...
 
DecorativeGeometryupdOutboardDecoration (int i)
 Return a writable reference to the i'th outboard decoration. More...
 
int addInboardDecoration (const Transform &X_FD, const DecorativeGeometry &geometry)
 Add decorative geometry specified relative to the inboard mobilizer frame F attached to the parent body P. More...
 
int getNumInboardDecorations () const
 Return the count of decorations added with addInboardDecoration(). More...
 
const DecorativeGeometrygetInboardDecoration (int i) const
 Return a const reference to the i'th inboard decoration. More...
 
DecorativeGeometryupdInboardDecoration (int i)
 Return a writable reference to the i'th inboard decoration. More...
 
MobilizedBodysetDefaultMassProperties (const MassProperties &m)
 If the contained Body can have its mass properties set to the supplied value m its mass properties are changed, otherwise the method fails. More...
 
const MassPropertiesgetDefaultMassProperties () const
 Return the mass properties of the Body stored within this MobilizedBody. More...
 
void adoptMotion (Motion &ownerHandle)
 Provide a unique Motion object for this MobilizedBody. More...
 
void clearMotion ()
 If there is a Motion object associated with this MobilizedBody it is removed; otherwise, nothing happens. More...
 
bool hasMotion () const
 Check whether this MobilizedBody has an associated Motion object. More...
 
const MotiongetMotion () const
 If there is a Motion object associated with this MobilizedBody, this returns a const reference to it. More...
 
MobilizedBodysetDefaultInboardFrame (const Transform &X_PF)
 Change this mobilizer's frame F on the parent body P. More...
 
MobilizedBodysetDefaultOutboardFrame (const Transform &X_BM)
 Change this mobilizer's frame M fixed on this (the outboard) body B. More...
 
const TransformgetDefaultInboardFrame () const
 Return a reference to this mobilizer's default for the frame F fixed on the parent (inboard) body P, as the fixed Transform from P's body frame to the frame F fixed to P. More...
 
const TransformgetDefaultOutboardFrame () const
 Return a reference to this MobilizedBody's default for mobilizer frame M, as the fixed Transform from this body B's frame to the frame M fixed on B. More...
 
 operator MobilizedBodyIndex () const
 This is an implicit conversion from MobilizedBody to MobilizedBodyIndex when needed. More...
 
MobilizedBodyIndex getMobilizedBodyIndex () const
 Return the MobilizedBodyIndex of this MobilizedBody within the owning SimbodyMatterSubsystem. More...
 
const MobilizedBodygetParentMobilizedBody () const
 Return a reference to the MobilizedBody serving as the parent body of the current MobilizedBody. More...
 
const MobilizedBodygetBaseMobilizedBody () const
 Return a reference to this MobilizedBody's oldest ancestor other than Ground, or return Ground if this MobilizedBody is Ground. More...
 
const SimbodyMatterSubsystemgetMatterSubsystem () const
 Obtain a reference to the SimbodyMatterSubsystem which contains this MobilizedBody. More...
 
SimbodyMatterSubsystemupdMatterSubsystem ()
 Obtain a writable reference to the SimbodyMatterSubsystem which contains this MobilizedBody. More...
 
bool isInSubsystem () const
 Determine whether the current MobilizedBody object is owned by a matter subsystem. More...
 
bool isInSameSubsystem (const MobilizedBody &mobod) const
 Determine whether a given MobilizedBody mobod is in the same matter subsystem as the current body. More...
 
bool isSameMobilizedBody (const MobilizedBody &mobod) const
 Determine whether a given MobilizedBody mobod is the same MobilizedBody as this one. More...
 
bool isGround () const
 Determine whether this body is Ground, meaning that it is actually body 0 of some matter subsytem, not just that its body type is Ground. More...
 
int getLevelInMultibodyTree () const
 Return this body's level in the tree of bodies, starting with ground at 0, bodies directly connected to ground at 1, bodies directly connected to those at 2, etc. More...
 
MobilizedBodycloneForNewParent (MobilizedBody &parent) const
 Create a new MobilizedBody which is identical to this one, except that it has a different parent (and consequently might belong to a different MultibodySystem). More...
 
Real getOneFromQPartition (const State &state, int which, const Vector &qlike) const
 This utility selects one of the q's (generalized coordinates) associated with this mobilizer from a supplied "q-like" Vector, meaning a Vector which is the same length as the Vector of q's for the containing matter subsystem. More...
 
Real & updOneFromQPartition (const State &state, int which, Vector &qlike) const
 This utility returns a writable reference to one of the q's (generalized coordinates) associated with this mobilizer from a supplied "q-like" Vector, meaning a Vector which is the same length as the Vector of q's for the containing matter subsystem. More...
 
Real getOneFromUPartition (const State &state, int which, const Vector &ulike) const
 This utility selects one of the u's (generalized speeds) associated with this mobilizer from a supplied "u-like" Vector, meaning a Vector which is the same length as the Vector of u's for the containing matter subsystem. More...
 
Real & updOneFromUPartition (const State &state, int which, Vector &ulike) const
 This utility returns a writable reference to one of the u's (generalized speeds) associated with this mobilizer from a supplied "u-like" Vector, meaning a Vector which is the same length as the Vector of u's for the containing matter subsystem. More...
 
void applyOneMobilityForce (const State &state, int which, Real f, Vector &mobilityForces) const
 This utility adds in the supplied generalized force f (a scalar) to the appropriate slot of the supplied mobilityForces Vector, which is a "u-like" Vector. More...
 
void convertQForceToUForce (const State &state, const Array_< Real, MobilizerQIndex > &fq, Array_< Real, MobilizerUIndex > &fu) const
 Given a generalized force in the q-space of this mobilizer, convert it to the equivalent generalized mobility force (u-space force). More...
 
void applyBodyForce (const State &state, const SpatialVec &spatialForceInG, Vector_< SpatialVec > &bodyForcesInG) const
 This utility adds in the supplied spatial force spatialForceInG (consisting of a torque vector, and a force vector to be applied at the current body's origin) to the appropriate slot of the supplied bodyForcesInG Vector. More...
 
void applyBodyTorque (const State &state, const Vec3 &torqueInG, Vector_< SpatialVec > &bodyForcesInG) const
 This utility adds in the supplied pure torque torqueInG to the appropriate slot of the supplied bodyForcesInG Vector. More...
 
void applyForceToBodyPoint (const State &state, const Vec3 &pointInB, const Vec3 &forceInG, Vector_< SpatialVec > &bodyForcesInG) const
 This utility adds in the supplied force forceInG applied at a point pointInB to the appropriate slot of the supplied bodyForcesInG Vector. More...
 
- Public Member Functions inherited from SimTK::PIMPLHandle< MobilizedBody, MobilizedBodyImpl, 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 MobilizedBody &other) const
 Determine whether the supplied handle is the same object as "this" PIMPLHandle. More...
 
void disown (MobilizedBody &newOwner)
 Give up ownership of the implementation to an empty handle. More...
 
PIMPLHandlereferenceAssign (const MobilizedBody &source)
 "Copy" assignment but with shallow (pointer) semantics. More...
 
PIMPLHandlecopyAssign (const MobilizedBody &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 MobilizedBodyImpl & getImpl () const
 Get a const reference to the implementation associated with this Handle. More...
 
MobilizedBodyImpl & 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...
 

Related Functions

(Note that these are not member functions.)

typedef MobilizedBody Mobod
 Mobod is the approved abbreviation for MobilizedBody. Feel free to use it if you get tired of typing or seeing the full name. More...
 

Additional Inherited Members

- Protected Member Functions inherited from SimTK::PIMPLHandle< MobilizedBody, MobilizedBodyImpl, true >
 PIMPLHandle ()
 The default constructor makes this an empty handle. More...
 
 PIMPLHandle (MobilizedBodyImpl *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...
 
PIMPLHandleoperator= (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 (MobilizedBodyImpl *p)
 Set the implementation for this empty handle. More...
 
bool hasSameImplementation (const MobilizedBody &other) const
 Determine whether the supplied handle is a reference to the same implementation object as is referenced by "this" PIMPLHandle. More...
 

Detailed Description

A MobilizedBody is Simbody's fundamental body-and-joint object used to parameterize a system's motion by constructing a multibody tree containing each body and its unique "mobilizer" (internal coordinate joint).

A MobilizedBody connects a new body (the "child", "outboard", or "successor" body) with a mobilizer and a reference frame to an existing MobilizedBody (the "parent", "inboard", or "predecessor" body) that is already part of a SimbodyMatterSubsystem. In the topology of the multibody tree, the parent mobilized body is always closer to Ground ("inboard") than is the child.

This is the base class for all MobilizedBody classes, which include a body and a particular kind of mobilizer. Each built-in MobilizedBody type is a local subclass within MobilizedBody, so the built-ins have names like MobilizedBody::Pin. All concrete MobilizedBody classes, including the built-ins, are derived from MobilizedBody. There is a MobilizedBody::Custom class available for defining your own mobilizer types.

Normally, a MobilizedBody's motion is unknown and Simbody calculates it using forward dynamics where the motion results from external or internal forces. However, a MobilizedBody may be locked or controlled by an associated Motion object which defines how it is to move; those are inverse dynamics conditions in which the motion is known but the generalized forces required to produce that motion are to be determined. In general a system may contain a mix of forward- and inverse-dynamics mobilizers, and mobilizers may be switched between forward and inverse dynamics during simulations.

The MobilizedBody class supports a large number of methods useful for obtaining and modifying body-specific and mobilizer-specific information and for performing useful computations. These are organized in three sets:

  • State Access
  • Basic Operators
  • High Level Operators

State Access methods simply extract already-calculated data from the State or State Cache, or set state values. They involve no additional computation, have names beginning with "get" and "upd" (update) and return references to the requested quantities rather than calculated values. We divide these into routines which deal with bodies and routines which deal with mobilizers and mobilities.

Basic Operators use State Access methods to compute basic quantities which cannot be precomputed, such as the velocity of an arbitrary point, using an inline combination of basic floating point operations which can be reliably determined at compile time. These have names beginning with "find" or a more specific verb, as a reminder that they do not require a great deal of computation.

High Level Operators combine responses and basic operators with run-time tests to calculate more complex quantities, with more complicated implementations that can exploit special cases at run time. These begin with "calc" (calculate) as a reminder that they may involve substantial run time computation.

There is also a set of methods used for construction, and miscellaneous utilities.

Mobilizer Terminology and Notation

Refer to the figure below for the terminology we use when discussing mobilizers and mobilized bodies.

MobilizerTerminology.png
Terminology and notation for mobilized bodies

The figure shows the coordinate frames used in describing the mobility of MobilizedBody B with respect to its inboard parent body P. Everything blue in the figure is associated with B. The origin point O of each frame is labeled. A new MobilizedBody with body frame B is added to the multibody tree by choosing a parent body P that is already present in the tree. There are two frames associated with the mobilizer: the "fixed" frame F that is attached to the parent, and the "moving" frame M that is attached to the new body B. Frame F is specified by giving its transform X_PF relative to the P frame. Frame M is specified by giving its transform X_BM relative to the B frame. At run time the transform X_FM between the two mobilizer frames represents translation and rotation of the mobilizer. That motion is parameterized via generalized coordinates q and generalized speeds u, the specific meaning of which is a unique property of each type of mobilizer.

In the API below, we'll refer to the current ("this") MobilizedBody as "body B". It is the "object" or "main" body with which we are concerned. Often there will be another body mentioned in the argument list as a target for some conversion. That "another" body will be called "body A". The Ground body is abbreviated "G".

We use Fo to mean "the origin of frame F", Bc is "the mass center of body B". R_AF is the rotation matrix giving frame F's orientation in frame A, such that a vector v expressed in F is reexpressed in A by v_A = R_AF*v_F. X_AF is the spatial transform giving frame F's origin location and orientation in frame A, such that a point P whose location is measured from F's origin Fo and expressed in F by position vector p_FP (or more explicitly p_FoP) is remeasured from frame A's origin Ao and reexpressed in A via p_AP = X_AF*p_FP, where p_AP==p_AoP.

Theory

For the mathematical and computational theory behind Simbody's mobilizers, see

  • the paper Seth, A.; Sherman, M.A.; Eastman, P.; Delp, S.L. "Minimal formulation of joint motion for biomechanisms" Nonlinear Dynamics 62:291-303 (2010), or
  • the Simbody Theory Manual.

Member Typedef Documentation

Synonym for Pin mobilizer.

Synonym for Pin mobilizer.

Synonym for Slider mobilizer.

Synonym for Ball mobilizer.

Synonym for Ball mobilizer.

Member Enumeration Documentation

Constructors can take an argument of this type to indicate that the mobilizer is being defined in the reverse direction, meaning from the outboard (child) body to the inboard (parent) body.

That means that the mobilizer coordinates and speeds will be defined as though the tree had been built in the opposite direction. It does not actually affect which body is the inboard one and which is the outboard; it just affects the definitions of the generalized coordinates q and speeds u that parameterize the motion of the outboard body with respect to the inboard one. This is a topological setting and can't be changed dynamically.

Enumerator
Forward 

Use default definitions for q and u (inboard to outboard).

Reverse 

Define q and u in the reverse order (outboard to inboard).

Constructor & Destructor Documentation

SimTK::MobilizedBody::MobilizedBody ( )
inline

The default constructor provides an empty MobilizedBody handle that can be assigned to reference any type of MobilizedBody.

SimTK::MobilizedBody::MobilizedBody ( MobilizedBodyImpl *  r)
explicit

Internal use only.

Member Function Documentation

void SimTK::MobilizedBody::lock ( State state,
Motion::Level  level = Motion::Position 
) const

Lock this mobilizer's position or velocity at its current value, or lock the acceleration to zero, depending on the level parameter.

The prescribed position or velocity is taken from state and recorded. If the lock is at the position (q) level then the generalized speeds u for this mobilizer are set to zero in the state. If the mobilizer was already locked, the new lock specification overrides it. The state must already have been realized to at least Stage::Model and will be lowered to Stage::Model on return since a lock is an Instance-stage change.

void SimTK::MobilizedBody::lockAt ( State state,
Real  value,
Motion::Level  level = Motion::Position 
) const

Lock this mobilizer's q, u, or udot to the given scalar value, depending on level.

When locking at the position level (the default), this mobilizer's q in state is set to value, and u in state is set to zero. When locking at velocity level, this mobilizer's u in state is set to value but the q is left unchanged. This signature of lockAt(), taking value as a scalar, is only permitted for mobilizers that have just a single q and u, such as a Pin or Slider mobilizer. See the other signatures of lockAt() for multi-coordinate mobilizers.

void SimTK::MobilizedBody::lockAt ( State state,
const Vector value,
Motion::Level  level = Motion::Position 
) const

Lock this mobilizer's q, u, or udot to the given Vector value, depending on level.

When locking at the position level (the default), this mobilizer's q's in state is set to value, and its u's in state are set to zero. When locking at velocity level, this mobilizer's u's in state are set to value but its q's are left unchanged. The Vector must be the expected length, either nq=getNumQ() for the default Motion::Position level, or nu=getNumU() for Motion::Velocity or Motion::Acceleration levels.

See Also
getNumQ(), getNumU()
template<int N>
void SimTK::MobilizedBody::lockAt ( State state,
const Vec< N > &  value,
Motion::Level  level = Motion::Position 
) const

Lock this mobilizer's q, u, or udot to the given Vec<N> value, depending on the level.

When locking at the position level (the default), this mobilizer's q's in state is set to value, and its u's in state are set to zero. When locking at velocity level, this mobilizer's u's in state are set to value but its q's are left unchanged. The size N of the given Vec must match the expected length, either nq=getNumQ() for the default Motion::Position level, or nu=getNumU() for Motion::Velocity or Motion::Acceleration levels.

See Also
getNumQ(), getNumU()
void SimTK::MobilizedBody::unlock ( State state) const

Unlock this mobilizer, returning it to its normal behavior which may be free motion or may be controlled by a Motion object.

If the mobilizer is already unlocked nothing happens.

bool SimTK::MobilizedBody::isLocked ( const State state) const
inline

Check whether this mobilizer is currently locked in the given state.

Motion::Level SimTK::MobilizedBody::getLockLevel ( const State state) const

Returns the lock level if the mobilizer is locked in the given state, otherwise Motion::NoLevel.

Vector SimTK::MobilizedBody::getLockValueAsVector ( const State state) const

Return the q, u, or udot value at which this mobilizer is locked, depending on the lock level, as a Vector of the appropriate length.

If the mobilizer is not currently locked, a zero-length Vector is returned.

MobilizedBody& SimTK::MobilizedBody::lockByDefault ( Motion::Level  level = Motion::Position)

Change whether this mobilizer is initially locked.

On construction the mobilizer is unlocked by default; you can change that here. To respecify that the motion is unlocked, use Motion::NoLevel as the level. This is a topological change; you'll have to call realizeTopology() again and get a new State if you call this method. If the default lock is at the position or velocity level, the required q or u value is recorded at the time a state is realized to Stage::Model. A default Motion::Acceleration lock always prescribes the accelerations udot to zero.

bool SimTK::MobilizedBody::isLockedByDefault ( ) const
inline

Check whether this mobilizer is to be locked in the default state.

Motion::Level SimTK::MobilizedBody::getLockByDefaultLevel ( ) const

Returns the level at which the mobilizer is locked by default, if it is locked by default, otherwise Motion::NoLevel.

const Transform& SimTK::MobilizedBody::getBodyTransform ( const State state) const

Extract from the state cache the already-calculated spatial configuration X_GB of body B's body frame, measured with respect to the Ground frame and expressed in the Ground frame.

That is, we return the location of the body frame's origin, and the orientation of its x, y, and z axes, as the Transform X_GB. This notation is intended to convey unambiguously the sense of this transform, which is as follows: if you have a station (body fixed point) S on body B, represented by position vector p_BS (a.k.a. p_BoS) from the origin Bo of B to the point S and expressed in the B frame, then p_GS=X_GB*p_BS where p_GS (== p_GoS) is the position vector from the Ground origin Go to the point in space currently coincident with S and expressed in the Ground frame. The inverse transformation is obtained using the "~" operator where ~X_GB=X_BG, so that p_BS = ~X_GB*p_GS. This response is available at Position stage.

const Rotation& SimTK::MobilizedBody::getBodyRotation ( const State state) const
inline

Extract from the state cache the already-calculated spatial orientation R_GB of body B's body frame x, y, and z axes expressed in the Ground frame, as the Rotation matrix R_GB.

The sense of this rotation matrix is such that if you have a vector v fixed on body B, represented by the vector v_B expressed in the B frame, then v_G=R_GB*v_B where v_G is the same vector but re-expressed in the Ground frame. The inverse transformation is obtained using the "~" operator where ~R_GB=R_BG, so that v_B = ~R_GB*v_G. This response is available at Position stage.

const Vec3& SimTK::MobilizedBody::getBodyOriginLocation ( const State state) const
inline

Extract from the state cache the already-calculated spatial location of body B's body frame origin Bo, measured from the Ground origin Go and expressed in the Ground frame, as the position vector p_GB (== p_GoBo).

This response is available at Position stage.

const Transform& SimTK::MobilizedBody::getMobilizerTransform ( const State state) const

At stage Position or higher, return the cross-mobilizer transform X_FM, the body's inboard mobilizer frame M measured and expressed in the parent body's corresponding outboard frame F.

const SpatialVec& SimTK::MobilizedBody::getBodyVelocity ( const State state) const

Extract from the state cache the already-calculated spatial velocity V_GB of this body's reference frame B, measured with respect to the Ground frame and expressed in the Ground frame.

That is, we return the linear velocity v_GB of the body frame's origin in G, and the body's angular velocity w_GB as the spatial velocity vector V_GB = {w_GB, v_GB}. This response is available at Velocity stage.

const Vec3& SimTK::MobilizedBody::getBodyAngularVelocity ( const State state) const
inline

Extract from the state cache the already-calculated inertial angular velocity vector w_GB of this body B, measured with respect to the Ground frame and expressed in the Ground frame.

This response is available at Velocity stage.

const Vec3& SimTK::MobilizedBody::getBodyOriginVelocity ( const State state) const
inline

Extract from the state cache the already-calculated inertial linear velocity vector v_GB (more explicitly, v_GBo) of this body B's origin point Bo, measured with respect to the Ground frame and expressed in the Ground frame.

This response is available at Velocity stage.

const SpatialVec& SimTK::MobilizedBody::getMobilizerVelocity ( const State state) const

At stage Velocity or higher, return the cross-mobilizer velocity V_FM, the relative velocity of this body's "moving" mobilizer frame M in the parent body's corresponding "fixed" frame F, measured and expressed in F.

Note that this isn't the usual spatial velocity since it isn't expressed in G.

const SpatialVec& SimTK::MobilizedBody::getBodyAcceleration ( const State state) const

Extract from the state cache the already-calculated spatial acceleration A_GB of this body's reference frame B, measured with respect to the Ground frame and expressed in the Ground frame.

That is, we return the linear acceleration a_GB of the body frame's origin in G, and the body's angular acceleration b_GB as the spatial acceleration vector A_GB = {b_GB, a_GB}. This response is available at Acceleration stage.

const Vec3& SimTK::MobilizedBody::getBodyAngularAcceleration ( const State state) const
inline

Extract from the state cache the already-calculated inertial angular acceleration vector b_GB of this body B, measured with respect to the Ground frame and expressed in the Ground frame.

This response is available at Acceleration stage.

const Vec3& SimTK::MobilizedBody::getBodyOriginAcceleration ( const State state) const
inline

Extract from the state cache the already-calculated inertial linear acceleration vector a_GB (more explicitly, a_GBo) of this body B's origin point Bo, measured with respect to the Ground frame and expressed in the Ground frame.

This response is available at Acceleration stage.

const SpatialVec& SimTK::MobilizedBody::getMobilizerAcceleration ( const State state) const
inline

TODO: Not implemented yet – any volunteers? At stage Acceleration, return the cross-mobilizer acceleration A_FM, the relative acceleration of body B's "moving" mobilizer frame M in the parent body's corresponding "fixed" frame F, measured and expressed in F.

Note that this isn't the usual spatial acceleration since it isn't expressed in G.

const MassProperties& SimTK::MobilizedBody::getBodyMassProperties ( const State state) const

Return a reference to this body's mass properties in the State cache.

The State must have been realized to Stage::Instance or higher.

const SpatialInertia& SimTK::MobilizedBody::getBodySpatialInertiaInGround ( const State state) const

Return a reference to the already-calculated SpatialInertia of this body, taken about the body's origin (not its mass center), and expressed in the Ground frame.

The State must have been realized to Stage::Position or higher.

Real SimTK::MobilizedBody::getBodyMass ( const State state) const
inline

Return the mass of this body.

The State must have been realized to Stage::Instance.

const Vec3& SimTK::MobilizedBody::getBodyMassCenterStation ( const State state) const
inline

Return this body's center of mass station (i.e., the vector fixed in the body, going from body origin to body mass center, expressed in the body frame.) The State must have been realized to Stage::Instance or higher.

const UnitInertia& SimTK::MobilizedBody::getBodyUnitInertiaAboutBodyOrigin ( const State state) const
inline

Return a reference to this body's unit inertia matrix in the State cache, taken about the body origin and expressed in the body frame.

The State must have been realized to Stage::Instance or higher.

const Transform& SimTK::MobilizedBody::getInboardFrame ( const State state) const

Return a reference to this mobilizer's frame F fixed on the parent body P, as the fixed Transform from P's body frame to the frame F fixed to P.

If this frame is changeable, the result comes from the State cache, otherwise it is from the MobilizedBody object itself. The State must have been realized to Stage::Instance or higher.

const Transform& SimTK::MobilizedBody::getOutboardFrame ( const State state) const

Return a reference to this MobilizedBody's mobilizer frame M, as the fixed Transform from this body B's frame to the frame M fixed on B.

If this frame is changeable, the result comes from the State cache, otherwise it is from the MobilizedBody object itself. The State must have been realized to Stage::Instance or higher.

void SimTK::MobilizedBody::setInboardFrame ( State state,
const Transform X_PF 
) const

TODO: not implemented yet.

Set the location and orientation of the inboard (parent) mobilizer frame F, fixed to this mobilizer's parent body P.

See Also
setDefaultInboardFrame()
void SimTK::MobilizedBody::setOutboardFrame ( State state,
const Transform X_BM 
) const

TODO: not implemented yet.

Set the location and orientation of the outboard mobilizer frame M, fixed to this body B.

See Also
setDefaultOutboardFrame()
int SimTK::MobilizedBody::getNumQ ( const State state) const

Return the number of generalized coordinates q currently in use by this mobilizer.

State must have been realized to Stage::Model.

int SimTK::MobilizedBody::getNumU ( const State state) const

Return the number of generalized speeds u currently in use by this mobilizer.

State must have been realized to Stage::Model.

QIndex SimTK::MobilizedBody::getFirstQIndex ( const State state) const

Return the global QIndex of the first q for this mobilizer; all the q's range from getFirstQIndex() to QIndex(getFirstQIndex()+getNumQ()-1).

UIndex SimTK::MobilizedBody::getFirstUIndex ( const State state) const

Return the global UIndex of the first u for this mobilizer; all the u's range from getFirstUIndex() to UIndex(getFirstUIndex()+getNumU()-1).

Motion::Method SimTK::MobilizedBody::getQMotionMethod ( const State state) const

Determine how generalized coordinate q values are being determined.

Parameters
[in]stateMust be realized to Instance stage.
Motion::Method SimTK::MobilizedBody::getUMotionMethod ( const State state) const

Determine how generalized speed u values are being determined.

Parameters
[in]stateMust be realized to Instance stage.
Motion::Method SimTK::MobilizedBody::getUDotMotionMethod ( const State state) const

Determine how generalized acceleration udot values are being determined.

Parameters
[in]stateMust be realized to Instance stage.
Real SimTK::MobilizedBody::getOneQ ( const State state,
int  which 
) const

Return one of the generalized coordinates q from this mobilizer's partition of the matter subsystem's full q vector in the State.

The particular coordinate is selected using the which parameter, numbering from zero to getNumQ()-1.

Real SimTK::MobilizedBody::getOneU ( const State state,
int  which 
) const

Return one of the generalized speeds u from this mobilizer's partition of the matter subsystem's full u vector in the State.

The particular coordinate is selected using the which parameter, numbering from zero to getNumU()-1.

Vector SimTK::MobilizedBody::getQAsVector ( const State state) const

Return as a Vector of length getNumQ() all the generalized coordinates q currently in use by this mobilizer, from this mobilizer's partion in the matter subsystem's full q vector in the State.

Vector SimTK::MobilizedBody::getUAsVector ( const State state) const

Return as a Vector of length getNumU() all the generalized speeds u currently in use by this mobilizer, from this mobilizer's partion in the matter subsystem's full u vector in the State.

Real SimTK::MobilizedBody::getOneQDot ( const State state,
int  which 
) const

Return one of the generalized coordinate derivatives qdot from this mobilizer's partition of the matter subsystem's full qdot vector in the State cache.

The particular coordinate is selected using the which parameter, numbering from zero to getNumQ()-1.

Vector SimTK::MobilizedBody::getQDotAsVector ( const State state) const

Return as a Vector of length getNumQ() all the generalized coordinate derivatives qdot currently in use by this mobilizer, from this mobilizer's partition in the matter subsystem's full qdot vector in the State cache.

Real SimTK::MobilizedBody::getOneUDot ( const State state,
int  which 
) const

Return one of the generalized accelerations udot from this mobilizer's partition of the matter subsystem's full udot vector in the State cache.

The particular coordinate is selected using the which parameter, numbering from zero to getNumU()-1.

Real SimTK::MobilizedBody::getOneQDotDot ( const State state,
int  which 
) const

Return one of the generalized coordinate second derivatives qdotdot from this mobilizer's partition of the matter subsystem's full qdotdot vector in the State cache.

The particular coordinate is selected using the which parameter, numbering from zero to getNumQ()-1.

Vector SimTK::MobilizedBody::getUDotAsVector ( const State state) const

Return as a Vector of length getNumU() all the generalized accelerations udot currently in use by this mobilizer, from this mobilizer's partion in the matter subsystem's full udot vector in the State cache.

Vector SimTK::MobilizedBody::getQDotDotAsVector ( const State state) const

Return as a Vector of length getNumQ() all the generalized coordinate second derivatives qdotdot currently in use by this mobilizer, from this mobilizer's partion in the matter subsystem's full qdotdot vector in the State cache.

Vector SimTK::MobilizedBody::getTauAsVector ( const State state) const

Return the generalized forces tau resulting from prescribed (known) acceleration, corresponding to each of this mobilizer's mobilities, as a Vector of length nu=getNumU().

If this mobilizer has prescribed accelerations udot due to an active lock or Motion object, the set of generalized forces tau that must be added in order to produce those accelerations is calculated at Acceleration stage. There is one scalar tau per mobility and they can be returned individually or as a Vector. The return value is zero if this mobilizer is currently free.

Real SimTK::MobilizedBody::getOneTau ( const State state,
MobilizerUIndex  which 
) const

Return one of the tau forces resulting from prescribed (known) acceleration, corresponding to one of this mobilizer's mobilities as selected here using the which parameter, numbered from zero to getNumU()-1.

See Also
getTauAsVector() for more information
void SimTK::MobilizedBody::setOneQ ( State state,
int  which,
Real  v 
) const

Set one of the generalized coordinates q to value v, in this mobilizer's partition of the matter subsystem's full q vector in the State.

The particular coordinate is selected using the which parameter, numbering from zero to getNumQ()-1.

void SimTK::MobilizedBody::setOneU ( State state,
int  which,
Real  v 
) const

Set one of the generalized speeds u to value v, in this mobilizer's partition of the matter subsystem's full u vector in the State.

The particular coordinate is selected using the which parameter, numbering from zero to getNumU()-1.

void SimTK::MobilizedBody::setQFromVector ( State state,
const Vector v 
) const

Set all of the generalized coordinates q to value v (a Vector of length getNumQ()), in this mobilizer's partition of the matter subsystem's full q vector in the State.

void SimTK::MobilizedBody::setUFromVector ( State state,
const Vector v 
) const

Set all of the generalized speeds u to value v (a Vector of length getNumU()), in this mobilizer's partition of the matter subsystem's full u vector in the State.

void SimTK::MobilizedBody::setQToFitTransform ( State state,
const Transform X_FM 
) const

Adjust this mobilizer's q's to best approximate the supplied Transform which requests a particular relative orientation and translation between the F "fixed" frame and M "moving" frame connected by this mobilizer.

This set of methods sets the generalized coordinates, or speeds (state variables) for just the mobilizer associated with this MobilizedBody (ignoring all other mobilizers and constraints), without requiring knowledge of the meanings of the individual state variables. The idea here is to provide a physically-meaningful quantity relating the mobilizer's inboard and outboard frames, and then ask the mobilizer to set its state variables to reproduce that quantity to the extent it can.

These methods can be called in Stage::Model, however the routines may consult the current values of the state variables in some cases, so you must make sure they have been set to reasonable, or at least innocuous values (zero will work). In no circumstance will any of these methods look at any state variables that belong to another mobilizer; they are limited to working locally with just the current mobilizer.

Routines which specify only translation (linear velocity) may use rotational coordinates to help satisfy the translation requirement. An alternate "Only" method is available to forbid modification of purely rotational coordinates in that case. When a mobilizer uses state variables which have combined rotational and translational character (e.g. a screw joint) consult the documentation for the derived MobilizedBody class to find out how that mobilizer responds to these routines.

There is no guarantee that the desired physical quantity will be achieved by these routines; you can check on return if you're worried. Individual mobilizers make specific promises about what they will do; consult the documentation. These routines do not throw exceptions even for absurd requests like specifying a rotation for a sliding mobilizer. Nothing happens if there are no mobilities here, i.e. Ground or a Weld mobilizer.

void SimTK::MobilizedBody::setQToFitRotation ( State state,
const Rotation R_FM 
) const

Adjust this mobilizer's q's to best approximate the supplied Rotation matrix which requests a particular relative orientation between the "fixed" frame F and "moving" frame M connected by this mobilizer.

See Also
setQToFitTransform()
void SimTK::MobilizedBody::setQToFitTranslation ( State state,
const Vec3 p_FM 
) const

Adjust this mobilizer's q's to best approximate the supplied position vector which requests a particular offset between the origins of the F "fixed" frame and M "moving" frame connected by this mobilizer, with any q's (rotational or translational) being modified if doing so helps satisfy the request.

See Also
setQToFitTransform()
void SimTK::MobilizedBody::setUToFitVelocity ( State state,
const SpatialVec V_FM 
) const

Adjust this mobilizer's u's (generalized speeds) to best approximate the supplied spatial velocity V_FM which requests the relative angular and linear velocity between the "fixed" and "moving" frames connected by this mobilizer.

Routines which affect generalized speeds u depend on the generalized coordinates q already having been set; they never change these coordinates.

See Also
setQToFitTransform()
void SimTK::MobilizedBody::setUToFitAngularVelocity ( State state,
const Vec3 w_FM 
) const

Adjust this mobilizer's u's (generalized speeds) to best approximate the supplied angular velocity w_FM which requests a particular relative angular between the "fixed" and "moving" frames connected by this mobilizer.

See Also
setQToFitTransform(), setUToFitVelocity()
void SimTK::MobilizedBody::setUToFitLinearVelocity ( State state,
const Vec3 v_FM 
) const

Adjust any of this mobilizer's u's (generalized speeds) to best approximate the supplied linear velocity v_FM which requests a particular velocity for the "moving" frame M origin in the "fixed" frame F on the parent where these are the frames connected by this mobilizer.

See Also
setQToFitTransform(), setUToFitVelocity()
SpatialVec SimTK::MobilizedBody::getHCol ( const State state,
MobilizerUIndex  ux 
) const

Expert use only: obtain a column of the hinge matrix H corresponding to one of this mobilizer's mobilities (actually a column of H_PB_G; what Jain calls H* and Schwieters calls H^T).

This is the matrix that maps generalized speeds u to the cross-body relative spatial velocity V_PB_G via V_PB_G=H*u. Note that although H relates child body B to parent body B, it is expressed in the ground frame G so the resulting cross-body velocity of B in P is also expressed in G. The supplied state must have been realized through Position stage because H varies with this mobilizer's generalized coordinates q.

See Also
getH_FMCol()
SpatialVec SimTK::MobilizedBody::getH_FMCol ( const State state,
MobilizerUIndex  ux 
) const

Expert use only: obtain a column of the mobilizer-local hinge matrix H_FM which maps generalized speeds u to cross-mobilizer spatial velocity V_FM via V_FM=H_FM*u.

Note that H and V here are expressed in the parent body's (inboard) frame F. The supplied state must have been realized through Position stage because H varies with this mobilizer's generalized coordinates q.

See Also
getHCol()
Transform SimTK::MobilizedBody::findBodyTransformInAnotherBody ( const State state,
const MobilizedBody inBodyA 
) const
inline

Return X_AB, the spatial transform giving this body B's frame in body A's frame.

Cost is 63 flops. If you know that one of the bodies is Ground, use the 0-cost response getBodyTransform() instead of this operators. This operator is available in Position stage.

See Also
getBodyTransform()
Rotation SimTK::MobilizedBody::findBodyRotationInAnotherBody ( const State state,
const MobilizedBody inBodyA 
) const
inline

Return R_AB, the rotation matrix giving this body B's axes in body A's frame.

Cost is 45 flops. If you know that one of the bodies is Ground, use the 0-cost response getBodyRotation() instead of this operators. This operator is available in Position stage.

See Also
getBodyRotation()
Vec3 SimTK::MobilizedBody::findBodyOriginLocationInAnotherBody ( const State state,
const MobilizedBody toBodyA 
) const
inline

Return the station on another body A (that is, a point measured and expressed in A) that is currently coincident in space with the origin Bo of this body B.

Cost is 18 flops. This operator is available at Position stage. Note: "findBodyOriginLocationInGround" doesn't exist because it would be the same as the no-cost response method getBodyOriginLocation().

See Also
getBodyOriginLocation()
SpatialVec SimTK::MobilizedBody::findBodyVelocityInAnotherBody ( const State state,
const MobilizedBody inBodyA 
) const
inline

Return the angular and linear velocity of body B's frame in body A's frame, expressed in body A, and arranged as a SpatialVec.

Cost is 51 flops. If you know inBodyA is Ground, don't use this routine; use the response method getBodyVelocity() which is free. This operator is available in Velocity stage.

See Also
getBodyVelocity()
Vec3 SimTK::MobilizedBody::findBodyAngularVelocityInAnotherBody ( const State state,
const MobilizedBody inBodyA 
) const
inline

Return the angular velocity w_AB of body B's frame in body A's frame, expressed in body A.

Cost is 18 flops. If you know inBodyA is Ground, don't use this routine; use the response method getBodyAngularVelocity() which is free. This operator is available in Velocity stage.

See Also
getBodyAngularVelocity()
Vec3 SimTK::MobilizedBody::findBodyOriginVelocityInAnotherBody ( const State state,
const MobilizedBody inBodyA 
) const
inline

Return the velocity of body B's origin point in body A's frame, expressed in body A.

Cost is 51 flops. If you know inBodyA is Ground, don't use this routine; use the response method getBodyOriginVelocity() which is free. This operator is available in Velocity stage.

See Also
getBodyOriginVelocity()
SpatialVec SimTK::MobilizedBody::findBodyAccelerationInAnotherBody ( const State state,
const MobilizedBody inBodyA 
) const
inline

Return the angular and linear acceleration of body B's frame in body A's frame, expressed in body A, and arranged as a SpatialVec.

Cost is 105 flops. If you know that inBodyA is Ground, don't use this operator; instead, use the response method getBodyAcceleration() which is free. This operator is available in Acceleration stage.

See Also
getBodyAcceleration()
Vec3 SimTK::MobilizedBody::findBodyAngularAccelerationInAnotherBody ( const State state,
const MobilizedBody inBodyA 
) const
inline

Return the angular acceleration of body B's frame in body A's frame, expressed in body A.

Cost is 33 flops. If you know inBodyA is Ground, don't use this operator; instead use the response method getBodyAngularAccleration() which is free. This operator is available at AccelerationStage.

See Also
getBodyAngularAcceleration()
Vec3 SimTK::MobilizedBody::findBodyOriginAccelerationInAnotherBody ( const State state,
const MobilizedBody inBodyA 
) const
inline

Return the acceleration of body B's origin point in body A's frame, expressed in body A.

Cost is 105 flops. If you know that inBodyA is Ground, don't use this operator; instead, use the response method getBodyOriginAcceleration() which is free. This operator is available at Acceleration stage.

See Also
getBodyOriginAcceleration()
SpatialVec SimTK::MobilizedBody::findMobilizerReactionOnBodyAtMInGround ( const State state) const

Return the spatial reaction force (moment and force) applied by the mobilizer to body B at the location of the mobilizer frame M (fixed to body B, but not necessarily at the body frame origin), expressed in Ground.

This operator is available at Acceleration stage. Cost is about 120 flops.

See Also
findMobilizerReactionOnParentAtFInGround()
findMobilizerReactionOnBodyAtOriginInGround()
SimTK::SimbodyMatterSubsystem::calcMobilizerReactionForces()
SpatialVec SimTK::MobilizedBody::findMobilizerReactionOnBodyAtOriginInGround ( const State state) const

Return the spatial reaction force (moment and force) applied by the mobilizer to body B but shifted to the B frame origin, and expressed in Ground.

This operator is available at Acceleration stage. Cost is about 90 flops.

See Also
findMobilizerReactionOnParentAtOriginInGround()
findMobilizerReactionOnBodyAtMInGround()
SimTK::SimbodyMatterSubsystem::calcMobilizerReactionForces()
SpatialVec SimTK::MobilizedBody::findMobilizerReactionOnParentAtFInGround ( const State state) const

Return the spatial reaction force (moment and force) applied by the mobilizer to the parent (inboard) body P at the location of the inboard "fixed" mobilizer frame F (fixed to body P, but not necessarily at the P frame origin), expressed in Ground.

This operator is available at Acceleration stage. Cost is about 140 flops.

See Also
findMobilizerReactionOnBodyAtMInGround()
findMobilizerReactionOnParentAtOriginInGround()
SimTK::SimbodyMatterSubsystem::calcMobilizerReactionForces()
SpatialVec SimTK::MobilizedBody::findMobilizerReactionOnParentAtOriginInGround ( const State state) const

Return the spatial reaction force (moment and force) applied by the mobilizer to the parent (inboard) body P at the location of the P frame origin, and expressed in Ground.

This operator is available at Acceleration stage. Cost is about 110 flops.

See Also
findMobilizerReactionOnBodyAtOriginInGround()
findMobilizerReactionOnParentAtFInGround()
SimTK::SimbodyMatterSubsystem::calcMobilizerReactionForces()
Vec3 SimTK::MobilizedBody::findStationLocationInGround ( const State state,
const Vec3 stationOnB 
) const
inline

Return the Cartesian (ground) location that is currently coincident with a station (point) S fixed on body B.

That is, we return locationInG=X_GB*stationOnB which means the result is measured from the Ground origin and expressed in Ground. In more precise notation, we're calculating p_GS = X_GB * p_BS for position vectors p_GS and p_BS. Cost is 18 flops. This operator is available at Position stage.

Vec3 SimTK::MobilizedBody::findStationLocationInAnotherBody ( const State state,
const Vec3 stationOnB,
const MobilizedBody toBodyA 
) const
inline

Given a station S on this body B, return the location on another body A which is at the same location in space.

That is, we return locationOnA=X_AB*locationOnB, which means the result is measured from the body A origin and expressed in body A. In more precise notation, we're calculating p_AS = X_AB * p_BS, which we actually calculate as p_AS = X_AG*(X_GB*p_BS). Cost is 36 flops. Note: if you know that one of the bodies is Ground, use one of the routines above which is specialized for Ground to avoid half the work. This operator is available at Position stage or higher.

Vec3 SimTK::MobilizedBody::findStationVelocityInGround ( const State state,
const Vec3 stationOnB 
) const
inline

Given a station fixed on body B, return its inertial (Cartesian) velocity, that is, its velocity relative to the Ground frame, expressed in the Ground frame.

Cost is 27 flops. If you know the station is the body origin (0,0,0) don't use this routine; use the response getBodyOriginVelocity() which is free. This operator is available at Velocity stage.

See Also
getBodyOriginVelocity()
Vec3 SimTK::MobilizedBody::findStationVelocityInAnotherBody ( const State state,
const Vec3 stationOnBodyB,
const MobilizedBody inBodyA 
) const
inline

Return the velocity of a station S fixed on body B, in body A's frame, expressed in body A.

Cost is 93 flops. If you know inBodyA is Ground, don't use this operator; instead use the operator findStationVelocityInGround() which is much cheaper. This operator is available in Velocity stage.

See Also
findStationVelocityInGround()
Vec3 SimTK::MobilizedBody::findStationAccelerationInGround ( const State state,
const Vec3 stationOnB 
) const
inline

Given a station fixed on body B, return its inertial (Cartesian) acceleration, that is, its acceleration relative to the ground frame, expressed in the ground frame.

Cost is 48 flops. If you know the station is the body origin (0,0,0) don't use this routine; use the response getBodyOriginAcceleration() which is free. This operator is available at Acceleration stage.

See Also
getBodyOriginAcceleration()
Vec3 SimTK::MobilizedBody::findStationAccelerationInAnotherBody ( const State state,
const Vec3 stationOnBodyB,
const MobilizedBody inBodyA 
) const
inline

Return the acceleration of a station S fixed on body B, in another body A's frame, expressed in body A.

Cost is 186 flops. If you know that inBodyA is Ground, don't use this operator; instead, use the operator findStationAccelerationInGround() which is much cheaper. This operator is available in Acceleration stage.

void SimTK::MobilizedBody::findStationLocationAndVelocityInGround ( const State state,
const Vec3 locationOnB,
Vec3 locationOnGround,
Vec3 velocityInGround 
) const
inline

It is cheaper to calculate a station's ground location and velocity together than to do them separately.

Here we can return them both in 30 flops, vs. 45 to do them in two calls. This operator is available at Velocity stage.

void SimTK::MobilizedBody::findStationLocationVelocityAndAccelerationInGround ( const State state,
const Vec3 locationOnB,
Vec3 locationOnGround,
Vec3 velocityInGround,
Vec3 accelerationInGround 
) const
inline

It is cheaper to calculate a station's ground location, velocity, and acceleration together than to do them separately.

Here we can return them all in 54 flops, vs. 93 to do them in three calls. This operator is available at Acceleration stage.

Vec3 SimTK::MobilizedBody::findMassCenterLocationInGround ( const State state) const
inline

Return the Cartesian (ground) location of this body B's mass center.

Cost is 18 flops. This operator is available at Position stage.

Vec3 SimTK::MobilizedBody::findMassCenterLocationInAnotherBody ( const State state,
const MobilizedBody toBodyA 
) const
inline

Return the point of another body A that is currently coincident in space with the mass center CB of this body B.

Cost is 36 flops. This operator is available at Position stage.

Vec3 SimTK::MobilizedBody::findStationAtGroundPoint ( const State state,
const Vec3 locationInG 
) const
inline

Return the station (point) S of this body B that is coincident with the given Ground location.

That is we return locationOnB = X_BG*locationInG, which means the result is measured from the body origin Bo and expressed in the body frame. In more precise notation, we're calculating p_BS = X_BG*p_GS. Cost is 18 flops. This operator is available at Position stage.

Vec3 SimTK::MobilizedBody::findStationAtAnotherBodyStation ( const State state,
const MobilizedBody fromBodyA,
const Vec3 stationOnA 
) const
inline

Return the station (point) on this body B that is coincident with the given station on another body A.

That is we return stationOnB = X_BA * stationOnA, which means the result is measured from the body origin Bo and expressed in the body frame. Cost is 36 flops. This operator is available at Position stage.

See Also
findStationLocationInAnotherBody()
Vec3 SimTK::MobilizedBody::findStationAtAnotherBodyOrigin ( const State state,
const MobilizedBody fromBodyA 
) const
inline

Return the station S of this body that is currently coincident in space with the origin Ao of another body A.

Cost is 18 flops. This operator is available at Position stage.

Vec3 SimTK::MobilizedBody::findStationAtAnotherBodyMassCenter ( const State state,
const MobilizedBody fromBodyA 
) const
inline

Return the station S of this body that is currently coincident in space with the mass center Ac of another body A.

Cost is 36 flops. This operator is available at Position stage.

Transform SimTK::MobilizedBody::findFrameTransformInGround ( const State state,
const Transform frameOnB 
) const
inline

Return the current Ground-frame pose (position and orientation) of a frame F that is fixed to body B.

That is, we return X_GF=X_GB*X_BF. Cost is 63 flops. This operator is available at Position stage.

SpatialVec SimTK::MobilizedBody::findFrameVelocityInGround ( const State state,
const Transform frameOnB 
) const
inline

Return the current Ground-frame spatial velocity V_GF (that is, angular and linear velocity) of a frame F that is fixed to body B.

The angular velocity of F is the same as that of B, but the linear velocity is the velocity of F's origin Fo rather than B's origin Bo. This operator is available at Velocity stage. Cost is 27 flops.

SpatialVec SimTK::MobilizedBody::findFrameAccelerationInGround ( const State state,
const Transform frameOnB 
) const
inline

Return the current Ground-frame spatial acceleration A_GF (that is, angular and linear acceleration) of a frame F that is fixed to body B.

The angular acceleration of F is the same as that of B, but the linear acceleration is the acceleration of F's origin Fo rather than B's origin Bo. This operator is available at Acceleration stage. Cost is 48 flops.

Vec3 SimTK::MobilizedBody::expressVectorInGroundFrame ( const State state,
const Vec3 vectorInB 
) const
inline

Re-express a vector expressed in this body B's frame into the same vector in G, by applying only a rotation.

That is, we return vectorInG = R_GB * vectorInB. Cost is 15 flops. This operator is available at Position stage.

Vec3 SimTK::MobilizedBody::expressGroundVectorInBodyFrame ( const State state,
const Vec3 vectorInG 
) const
inline

Re-express a vector expressed in Ground into the same vector expressed in this body B, by applying only rotation.

That is, we return vectorInB = R_BG * vectorInG. Cost is 15 flops. This operator is available at Position stage.

Vec3 SimTK::MobilizedBody::expressVectorInAnotherBodyFrame ( const State state,
const Vec3 vectorInB,
const MobilizedBody inBodyA 
) const
inline

Re-express a vector expressed in this body B into the same vector expressed in body A, by applying only a rotation.

That is, we return vectorInA = R_AB * vectorInB. Cost is 30 flops. This operator is available at Position stage. Note: if you know one of the bodies is Ground, call one of the specialized methods above to save 15 flops.

MassProperties SimTK::MobilizedBody::expressMassPropertiesInGroundFrame ( const State state) const
inline

Re-express this body B's mass properties in Ground by applying only a rotation, not a shift of reference point.

The mass properties remain measured in the body B frame, taken about the body B origin Bo, but are reexpressed in Ground.

MassProperties SimTK::MobilizedBody::expressMassPropertiesInAnotherBodyFrame ( const State state,
const MobilizedBody inBodyA 
) const
inline

Re-express this body B's mass properties in another body A's frame by applying only a rotation, not a shift of reference point.

The mass properties remain measured in the body B frame, taken about the body B origin Bo, but are reexpressed in A.

SpatialMat SimTK::MobilizedBody::calcBodySpatialInertiaMatrixInGround ( const State state) const
inline

Return the mass properties of body B, measured from and about the B origin Bo, but expressed in Ground and then returned as a Spatial Inertia Matrix.

The mass properties are arranged in the SpatialMat like this:

        M=[      I_Bo      crossMat(m*Bc) ]
        [ ~crossMat(m*Bc)   diag(m)     ]

where I_Bo is the inertia taken about the B frame origin Bo, and Bc is the vector p_BoBc from B's origin to its mass center.

The Spatial Inertia Matrix for Ground has infinite mass and inertia, with the cross terms set to zero. That is, it looks like a 6x6 diagonal matrix with Infinity on the diagonals.

Required stage
Stage::Position, unless objectBodyB == GroundIndex
Inertia SimTK::MobilizedBody::calcBodyCentralInertia ( const State state,
MobilizedBodyIndex  objectBodyB 
) const
inline

Return the central inertia for body B, that is, the inertia taken about body B's mass center Bc, and expressed in B.

/

Required stage
Stage::Instance
Inertia SimTK::MobilizedBody::calcBodyInertiaAboutAnotherBodyStation ( const State state,
const MobilizedBody inBodyA,
const Vec3 aboutLocationOnBodyA 
) const
inline

Return the inertia of this body B, taken about an arbitrary point PA of body A, and expressed in body A.

TODO: this needs testing!

SpatialVec SimTK::MobilizedBody::calcBodyMomentumAboutBodyOriginInGround ( const State state)
inline

Calculate body B's momentum (angular, linear) measured and expressed in Ground, but taken about the body origin Bo.

SpatialVec SimTK::MobilizedBody::calcBodyMomentumAboutBodyMassCenterInGround ( const State state) const
inline

Calculate body B's momentum (angular, linear) measured and expressed in Ground, but taken about the body mass center Bc.

Real SimTK::MobilizedBody::calcStationToStationDistance ( const State state,
const Vec3 locationOnBodyB,
const MobilizedBody bodyA,
const Vec3 locationOnBodyA 
) const
inline

Calculate the distance from a station PB on body B to a station PA on body A.

We are given the location vectors (stations) p_Bo_PB and p_Ao_PA, expressed in their respective frames. We return |p_PB_PA|.

Real SimTK::MobilizedBody::calcStationToStationDistanceTimeDerivative ( const State state,
const Vec3 locationOnBodyB,
const MobilizedBody bodyA,
const Vec3 locationOnBodyA 
) const
inline

Calculate the time rate of change of distance from a fixed point PB on body B to a fixed point PA on body A.

We are given the location vectors p_Bo_PB and p_Ao_PA, expressed in their respective frames. We return d/dt |p_BoAo|, under the assumption that the time derivatives of the two given vectors in their own frames is zero.

Real SimTK::MobilizedBody::calcStationToStationDistance2ndTimeDerivative ( const State state,
const Vec3 locationOnBodyB,
const MobilizedBody bodyA,
const Vec3 locationOnBodyA 
) const
inline

Calculate the second time derivative of distance from a fixed point PB on body B to a fixed point PA on body A.

We are given the position vectors (stations) p_Bo_PB and p_Ao_PA, expressed in their respective frames. We return d^2/dt^2 |p_PB_PA|, under the assumption that the time derivatives of the two given vectors in their own frames is zero.

Vec3 SimTK::MobilizedBody::calcBodyMovingPointVelocityInBody ( const State state,
const Vec3 locationOnBodyB,
const Vec3 velocityOnBodyB,
const MobilizedBody inBodyA 
) const
inline

TODO: not implemented yet – any volunteers? Return the velocity of a point P moving on body B, in body A's frame, expressed in body A.

Vec3 SimTK::MobilizedBody::calcBodyMovingPointAccelerationInBody ( const State state,
const Vec3 locationOnBodyB,
const Vec3 velocityOnBodyB,
const Vec3 accelerationOnBodyB,
const MobilizedBody inBodyA 
) const
inline

TODO: not implemented yet – any volunteers? Return the velocity of a point P moving (and possibly accelerating) on body B, in body A's frame, expressed in body A.

Real SimTK::MobilizedBody::calcMovingPointToPointDistanceTimeDerivative ( const State state,
const Vec3 locationOnBodyB,
const Vec3 velocityOnBodyB,
const MobilizedBody bodyA,
const Vec3 locationOnBodyA,
const Vec3 velocityOnBodyA 
) const
inline

TODO: not implemented yet – any volunteers? Calculate the time rate of change of distance from a moving point PB on body B to a moving point PA on body A.

We are given the location vectors p_Bo_PB and p_Ao_PA, and the velocities of PB in B and PA in A, all expressed in their respective frames. We return d/dt |p_BoAo|, taking into account the (given) time derivatives of the locations in their local frames, as well as the relative velocities of the bodies.

Real SimTK::MobilizedBody::calcMovingPointToPointDistance2ndTimeDerivative ( const State state,
const Vec3 locationOnBodyB,
const Vec3 velocityOnBodyB,
const Vec3 accelerationOnBodyB,
const MobilizedBody bodyA,
const Vec3 locationOnBodyA,
const Vec3 velocityOnBodyA,
const Vec3 accelerationOnBodyA 
) const
inline

TODO: not implemented yet – any volunteers? Calculate the second time derivative of distance from a moving point PB on body B to a moving point PA on body A.

We are given the location vectors p_Bo_PB and p_Ao_PA, and the velocities and accelerations of PB in B and PA in A, all expressed in their respective frames. We return d^2/dt^2 |p_AoBo|, taking into account the time derivatives of the locations in their local frames, as well as the relative velocities and accelerations of the bodies.

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

Return a const reference to the Body contained within this MobilizedBody.

This refers to an internal copy of the Body that is owned by the MobilizedBody.

Body& SimTK::MobilizedBody::updBody ( )

Return a writable reference to the Body contained within this MobilizedBody.

This refers to an internal copy of the Body that is owned by the MobilizedBody. Calling this method invalidates the MobilizedBody's topology, so the containing System's realizeTopology() method must be called again.

MobilizedBody& SimTK::MobilizedBody::setBody ( const Body )

Replace the Body contained within this MobilizedBody with a new one.

Calling this method invalidates the MobilizedBody's topology, so the containing System's realizeTopology() method must be called again. A reference to this MobilizedBody is returned so that this can be chained like an assignment operator.

int SimTK::MobilizedBody::addBodyDecoration ( const Transform X_BD,
const DecorativeGeometry geometry 
)
inline

Add decorative geometry specified relative to the new (outboard) body's reference frame B.

Note that the body itself may already have had some decorative geometry on it when it was first put into this MobilizedBody; this just adds more and the returned index is larger. Use the underlying Body object's accessors to find this decorative geometry again. The given geometry object is copied here; we do not keep a reference to the supplied object.

int SimTK::MobilizedBody::addBodyDecoration ( const DecorativeGeometry geometry)
inline

Convenience method for use when the geometry is supplied in the body frame.

This is the same as addBodyDecoration(Transform(),geometry).

int SimTK::MobilizedBody::addOutboardDecoration ( const Transform X_MD,
const DecorativeGeometry geometry 
)

Add decorative geometry specified relative to the outboard mobilizer frame M attached to body B.

If body B already has decorative geometry on it, this just adds some more, but kept in a separate list from the body decorations and inboard decorations. Returns a unique index that can be used to identify this outboard decoration later (numbered starting from zero for outboard decorations only).

int SimTK::MobilizedBody::getNumOutboardDecorations ( ) const

Return the count of decorations added with addOutboardDecoration().

const DecorativeGeometry& SimTK::MobilizedBody::getOutboardDecoration ( int  i) const

Return a const reference to the i'th outboard decoration.

DecorativeGeometry& SimTK::MobilizedBody::updOutboardDecoration ( int  i)

Return a writable reference to the i'th outboard decoration.

int SimTK::MobilizedBody::addInboardDecoration ( const Transform X_FD,
const DecorativeGeometry geometry 
)

Add decorative geometry specified relative to the inboard mobilizer frame F attached to the parent body P.

If body P already has decorative geometry on it, this just adds some more, but kept in a separate list from the body decorations and outboard decorations. Returns a unique index that can be used to identify this inboard decoration later (numbered starting from zero for inboard decorations only).

int SimTK::MobilizedBody::getNumInboardDecorations ( ) const

Return the count of decorations added with addInboardDecoration().

const DecorativeGeometry& SimTK::MobilizedBody::getInboardDecoration ( int  i) const

Return a const reference to the i'th inboard decoration.

DecorativeGeometry& SimTK::MobilizedBody::updInboardDecoration ( int  i)

Return a writable reference to the i'th inboard decoration.

MobilizedBody& SimTK::MobilizedBody::setDefaultMassProperties ( const MassProperties m)
inline

If the contained Body can have its mass properties set to the supplied value m its mass properties are changed, otherwise the method fails.

Calling this method invalidates the MobilizedBody's topology, so the containing matter subsystem's realizeTopology() method must be called again. A reference to this MobilizedBody is returned so that this can be chained like an assignment operator.

const MassProperties& SimTK::MobilizedBody::getDefaultMassProperties ( ) const
inline

Return the mass properties of the Body stored within this MobilizedBody.

void SimTK::MobilizedBody::adoptMotion ( Motion ownerHandle)

Provide a unique Motion object for this MobilizedBody.

The MobilizedBody takes over ownership of the Motion object and is responsible for cleaning up its heap space when the time comes. This is a Topology-changing operation and consequently requires write access to the MobilizedBody which will propagate to invalidate the containing Subsystem and System's topology. There can only be one Motion object per mobilizer; this method will throw an exception if there is already one here.

void SimTK::MobilizedBody::clearMotion ( )

If there is a Motion object associated with this MobilizedBody it is removed; otherwise, nothing happens.

If a Motion is deleted, the containing System's topology is invalidated.

bool SimTK::MobilizedBody::hasMotion ( ) const

Check whether this MobilizedBody has an associated Motion object.

This does not tell you whether the Motion object is currently enabled or in use; just whether it is available.

const Motion& SimTK::MobilizedBody::getMotion ( ) const

If there is a Motion object associated with this MobilizedBody, this returns a const reference to it.

Otherwise it will throw an exception. You can check first using hasMotion(). Note that there is no provision to obtain a writable reference to the contained Motion object; if you want to change it clear the existing object instead and replace it with a new one.

See Also
hasMotion()
MobilizedBody& SimTK::MobilizedBody::setDefaultInboardFrame ( const Transform X_PF)

Change this mobilizer's frame F on the parent body P.

Calling this method invalidates the MobilizedBody's topology, so the containing matter subsystem's realizeTopology() method must be called again. A reference to this MobilizedBody is returned so that this can be chained like an assignment operator.

MobilizedBody& SimTK::MobilizedBody::setDefaultOutboardFrame ( const Transform X_BM)

Change this mobilizer's frame M fixed on this (the outboard) body B.

Calling this method invalidates the MobilizedBody's topology, so the containing matter subsystem's realizeTopology() method must be called again. A reference to this MobilizedBody is returned so that this can be chained like an assignment operator.

const Transform& SimTK::MobilizedBody::getDefaultInboardFrame ( ) const

Return a reference to this mobilizer's default for the frame F fixed on the parent (inboard) body P, as the fixed Transform from P's body frame to the frame F fixed to P.

This default Transform is stored with the MobilizedBody object, not the State.

const Transform& SimTK::MobilizedBody::getDefaultOutboardFrame ( ) const

Return a reference to this MobilizedBody's default for mobilizer frame M, as the fixed Transform from this body B's frame to the frame M fixed on B.

This default Transform is stored with the MobilizedBody object, not the State.

SimTK::MobilizedBody::operator MobilizedBodyIndex ( ) const
inline

This is an implicit conversion from MobilizedBody to MobilizedBodyIndex when needed.

This will fail unless this MobilizedBody is owned by some SimbodyMatterSubsystem. We guarantee that the MobilizedBodyIndex of a mobilized body is numerically larger than the MobilizedBodyIndex of its parent.

MobilizedBodyIndex SimTK::MobilizedBody::getMobilizedBodyIndex ( ) const

Return the MobilizedBodyIndex of this MobilizedBody within the owning SimbodyMatterSubsystem.

This will fail unless this MobilizedBody is owned by some SimbodyMatterSubsystem. We guarantee that the MobilizedBodyIndex of a mobilized body is numerically larger than the MobilizedBodyIndex of its parent.

const MobilizedBody& SimTK::MobilizedBody::getParentMobilizedBody ( ) const

Return a reference to the MobilizedBody serving as the parent body of the current MobilizedBody.

This call will fail if the current MobilizedBody is Ground, since Ground has no parent.

const MobilizedBody& SimTK::MobilizedBody::getBaseMobilizedBody ( ) const

Return a reference to this MobilizedBody's oldest ancestor other than Ground, or return Ground if this MobilizedBody is Ground.

That is, we return the "base" MobilizedBody for this MobilizedBody, meaning the one which connects this branch of the multibody tree directly to Ground.

const SimbodyMatterSubsystem& SimTK::MobilizedBody::getMatterSubsystem ( ) const

Obtain a reference to the SimbodyMatterSubsystem which contains this MobilizedBody.

This will fail unless this MobilizedBody is owned by some SimbodyMatterSubsystem.

SimbodyMatterSubsystem& SimTK::MobilizedBody::updMatterSubsystem ( )

Obtain a writable reference to the SimbodyMatterSubsystem which contains this MobilizedBody.

This will fail unless this MobilizedBody is owned by some SimbodyMatterSubsystem.

bool SimTK::MobilizedBody::isInSubsystem ( ) const

Determine whether the current MobilizedBody object is owned by a matter subsystem.

bool SimTK::MobilizedBody::isInSameSubsystem ( const MobilizedBody mobod) const

Determine whether a given MobilizedBody mobod is in the same matter subsystem as the current body.

If the bodies are not in a subsystem, this routine will return false.

bool SimTK::MobilizedBody::isSameMobilizedBody ( const MobilizedBody mobod) const

Determine whether a given MobilizedBody mobod is the same MobilizedBody as this one.

For this to be true the handles must not be empty, and the implementation objects must be the same object not separate objects with identical contents.

bool SimTK::MobilizedBody::isGround ( ) const

Determine whether this body is Ground, meaning that it is actually body 0 of some matter subsytem, not just that its body type is Ground.

int SimTK::MobilizedBody::getLevelInMultibodyTree ( ) const

Return this body's level in the tree of bodies, starting with ground at 0, bodies directly connected to ground at 1, bodies directly connected to those at 2, etc.

This is callable after realizeTopology(). This is the graph distance of the body from Ground.

MobilizedBody& SimTK::MobilizedBody::cloneForNewParent ( MobilizedBody parent) const

Create a new MobilizedBody which is identical to this one, except that it has a different parent (and consequently might belong to a different MultibodySystem).

Real SimTK::MobilizedBody::getOneFromQPartition ( const State state,
int  which,
const Vector qlike 
) const

This utility selects one of the q's (generalized coordinates) associated with this mobilizer from a supplied "q-like" Vector, meaning a Vector which is the same length as the Vector of q's for the containing matter subsystem.

Real& SimTK::MobilizedBody::updOneFromQPartition ( const State state,
int  which,
Vector qlike 
) const

This utility returns a writable reference to one of the q's (generalized coordinates) associated with this mobilizer from a supplied "q-like" Vector, meaning a Vector which is the same length as the Vector of q's for the containing matter subsystem.

Real SimTK::MobilizedBody::getOneFromUPartition ( const State state,
int  which,
const Vector ulike 
) const

This utility selects one of the u's (generalized speeds) associated with this mobilizer from a supplied "u-like" Vector, meaning a Vector which is the same length as the Vector of u's for the containing matter subsystem.

Real& SimTK::MobilizedBody::updOneFromUPartition ( const State state,
int  which,
Vector ulike 
) const

This utility returns a writable reference to one of the u's (generalized speeds) associated with this mobilizer from a supplied "u-like" Vector, meaning a Vector which is the same length as the Vector of u's for the containing matter subsystem.

void SimTK::MobilizedBody::applyOneMobilityForce ( const State state,
int  which,
Real  f,
Vector mobilityForces 
) const
inline

This utility adds in the supplied generalized force f (a scalar) to the appropriate slot of the supplied mobilityForces Vector, which is a "u-like" Vector.

Note that we are adding this not setting it so it important that mobilityForces be initialized to zero before making a set of calls to applyOneMobilityForce().

void SimTK::MobilizedBody::convertQForceToUForce ( const State state,
const Array_< Real, MobilizerQIndex > &  fq,
Array_< Real, MobilizerUIndex > &  fu 
) const

Given a generalized force in the q-space of this mobilizer, convert it to the equivalent generalized mobility force (u-space force).

This uses the kinematic coupling matrix N that appears in equation (1) qdot=N*u. Here we compute (2) fu = ~N*fq (that's N transpose, not inverse).

Simbody deals with generalized forces in mobility (u) space, but sometimes these are more convenient to generate in generalized coordinate (q) space. In that case this utility method is useful to perform the conversion from q space to u space that is necessary for communicating the force to Simbody.

Parameters
[in]stateA State already realized through Position stage, from which this mobilizer's kinematic coupling matrix N(q) is obtained.
[in]fqThis is a generalized force in the space of the generalized coordinates q rather than the generalized speeds u. The length of fq must be nq, the number of q's currently being used by this mobilizer in the given state. (This can depend on a Model-stage state variable.)
[out]fuThis is the generalized force in mobility space (the space of the generalized speeds u) that is equivalent to fq. fu will be resized if necessary to length nu, the number of u's being used by this mobilizer.

Theory

The physical quantity power (force times velocity) must not change as a result of a change of coordinates. Hence we must have ~fq*qdot==~fu*u which follows from equations (1) and (2): multiply (1) by ~fq to get

    ~fq*qdot= ~fq*N*u
            = ~(~N*fq)*u
            = ~fu*u           from equation (2).

For any mobilizer where qdot==u this simply copies the input to the output. Otherwise a multiplication by ~N is done, but that is very fast since N has already been computed. Cost depends on type of mobilizer but is unlikely to exceed 25 flops.

void SimTK::MobilizedBody::applyBodyForce ( const State state,
const SpatialVec spatialForceInG,
Vector_< SpatialVec > &  bodyForcesInG 
) const

This utility adds in the supplied spatial force spatialForceInG (consisting of a torque vector, and a force vector to be applied at the current body's origin) to the appropriate slot of the supplied bodyForcesInG Vector.

Note that we are adding this not setting it so it is important that bodyForcesInG be initialized to zero before making a set of calls to applyBodyForce().

void SimTK::MobilizedBody::applyBodyTorque ( const State state,
const Vec3 torqueInG,
Vector_< SpatialVec > &  bodyForcesInG 
) const

This utility adds in the supplied pure torque torqueInG to the appropriate slot of the supplied bodyForcesInG Vector.

Note that we are adding this not setting it so it is important that bodyForcesInG be initialized to zero before making a set of calls to applyBodyTorque().

void SimTK::MobilizedBody::applyForceToBodyPoint ( const State state,
const Vec3 pointInB,
const Vec3 forceInG,
Vector_< SpatialVec > &  bodyForcesInG 
) const

This utility adds in the supplied force forceInG applied at a point pointInB to the appropriate slot of the supplied bodyForcesInG Vector.

Notes:

  • we are adding this not setting it so it is important that bodyForcesInG be initialized to zero before making a set of calls to applyForceToBodyPoint().
  • pointInB represents a fixed station of B and is provided by giving the vector from body B's origin to the point, expressed in the B frame, while the applied force (and resulting body forces and torques) are expressed in the ground frame.

Friends And Related Function Documentation

typedef MobilizedBody Mobod
related

Mobod is the approved abbreviation for MobilizedBody. Feel free to use it if you get tired of typing or seeing the full name.


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