Simbody  3.7
SimTK::Motion Class Reference

A Motion object belongs to a particular MobilizedBody and prescribes how the associated motion is to be calculated. More...

+ Inheritance diagram for SimTK::Motion:

Classes

class  Custom
 This class can be used to define new motions. More...
 
class  Sinusoid
 Prescribe position, velocity, or acceleration motion as a sinusoidal function of time, m(t) = a * sin( w*t + p ). More...
 
class  Steady
 This non-holonomic Motion object imposes a constant rate on all mobilities. More...
 

Public Types

enum  Level {
  NoLevel = -1,
  Acceleration = 0,
  Velocity = 1,
  Position = 2
}
 What is the highest level of motion that is driven? Lower levels are also driven; higher levels are determined by integration. More...
 
enum  Method {
  NoMethod = -1,
  Zero = 0,
  Discrete = 1,
  Prescribed = 2,
  Free = 3,
  Fast = 4
}
 There are several ways to specify the motion at this Level, and the selected method also determines lower-level motions. More...
 
- Public Types inherited from SimTK::PIMPLHandle< Motion, MotionImpl, true >
typedef PIMPLHandle< Motion, MotionImpl, PTR > HandleBase
 
typedef HandleBase ParentHandle
 

Public Member Functions

 Motion ()
 Default constructor creates an empty Motion handle that can be assigned to reference any kind of Motion object. More...
 
Level getLevel (const State &) const
 Get the highest level being driven by this Motion. More...
 
Method getLevelMethod (const State &) const
 Get the method being used to control the indicated Level. More...
 
Enabling and disabling

These methods determine whether this Motion object is active in a given State.

When disabled, the concrete Motion object's prescribed motion is ignored. Normally Motion objects are enabled when defined unless explicitly disabled; you can reverse that using the setDisabledByDefault() method below. You can then override the default setting at run time using the enable() and disable() methods to modify the Motion behavior within a particular State.

Note that when a Motion is disabled, the mobilizer to which it belongs is unrestricted by the concrete Motion object, but may be restricted in other ways such as being locked, constrained, or acted upon by forces. Even if a Motion is enabled, a lock request takes priority; the Motion will resume its effect when the mobilizer is unlocked.

void disable (State &state) const
 Disable this Motion, effectively removing it from the mobilizer to which it belongs and allowing the mobilizer to move freely (unless locked). More...
 
void enable (State &state) const
 Enable this Motion, without necessarily satisfying it. More...
 
bool isDisabled (const State &state) const
 Test whether this Motion is currently disabled in the supplied State. More...
 
void setDisabledByDefault (bool shouldBeDisabled)
 Specify that a Motion is to be inactive by default. More...
 
bool isDisabledByDefault () const
 Test whether this Motion is disabled by default in which case it must be explicitly enabled before it will take effect. More...
 
Advanced/Obscure/Debugging

You probably won't need to use these.

const MobilizedBodygetMobilizedBody () const
 Get the MobilizedBody to which this Motion belongs. More...
 
void calcAllMethods (const State &s, Method &qMethod, Method &uMethod, Method &udotMethod) const
 (Advanced) This implements the above table. More...
 
- Public Member Functions inherited from SimTK::PIMPLHandle< Motion, MotionImpl, 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 Motion &other) const
 Determine whether the supplied handle is the same object as "this" PIMPLHandle. More...
 
void disown (Motion &newOwner)
 Give up ownership of the implementation to an empty handle. More...
 
PIMPLHandlereferenceAssign (const Motion &source)
 "Copy" assignment but with shallow (pointer) semantics. More...
 
PIMPLHandlecopyAssign (const Motion &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 MotionImpl & getImpl () const
 Get a const reference to the implementation associated with this Handle. More...
 
MotionImpl & 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...
 

Static Public Member Functions

static const char * nameOfLevel (Level)
 Returns a human-readable name corresponding to the given Level; useful for debugging. More...
 
static const char * nameOfMethod (Method)
 Returns a human-readable name corresponding to the given Method; useful for debugging. More...
 

Protected Member Functions

 Motion (MotionImpl *r)
 For internal use: construct a new Motion handle referencing a particular implementation object. More...
 
- Protected Member Functions inherited from SimTK::PIMPLHandle< Motion, MotionImpl, true >
 PIMPLHandle ()
 The default constructor makes this an empty handle. More...
 
 PIMPLHandle (MotionImpl *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 (MotionImpl *p)
 Set the implementation for this empty handle. More...
 
bool hasSameImplementation (const Motion &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 Motion object belongs to a particular MobilizedBody and prescribes how the associated motion is to be calculated.

Motions can provide functionality similar to some constraints, but are much more efficient. There are two independent aspects of prescribed motion:

  • at what level is the motion driven (low to high: acceleration, velocity, or position), and
  • how is the motion at that level specified.

Levels lower than the driven level are also driven; higher levels are free and determined by integration or other solution method.

Concrete Motion objects derived from the base class provide specialized functionality, such as prescribing the mobilizer motion as a function of time. The specialized functionality may be enabled and disabled at run time, with motion determined dynamically if the Motion object is disabled.

For mobilizers with more than one mobility, the associated Motion controls all the mobilities and moreover they are all driven at the same level and by the same method. Using MobilizedBody::lock() temporarily overrides the Motion associated with that mobilizer.

Details

This table shows all the possible ways in which mobilizer motion can be determined, based on the Motion level and method. The default is that we determine motion at the acceleration level from forces, with velocity and position calculated by integrating the acceleration.

                      |                Motion Method
     Level How driven |  Acceleration    Velocity      Position
     ----- ---------- |  ------------    ----------    ----------
      Acc  Zero       |       0           discrete       free
       "   Discrete   |    discrete         free           "
       "   Prescribed |    a(t,q,u)          "             "
       "   Free       |   from forces        "             "      <-- default

      Vel  Zero       |       0              0          discrete
       "   Discrete   |       0           discrete        free
       "   Prescribed |     dv/dt          v(t,q)          "
       "   Fast       |       0           relax(v)         "

      Pos  Zero       |       0              0           0 (ref.)
       "   Discrete   |       0              0          discrete
       "   Prescribed |    d2p/dt2         dp/dt          p(t)
       "   Fast       |       0              0          relax(p)

There are two duplicates in the above table: specifying acceleration as Zero is the same as specifying velocity as Discrete and specifying velocity as Zero is the same as specifying position as Discrete.

Motion is a PIMPL-style abstract base class, with concrete classes defined for each kind of Motion. There is a set of built-in Motions and a generic "Custom" Motion (an abstract base class) from which advanced users may derive their own Motion objects.

Member Enumeration Documentation

◆ Level

What is the highest level of motion that is driven? Lower levels are also driven; higher levels are determined by integration.

Enumerator
NoLevel 

invalid level

Acceleration 

we know udot; integrate to get u, q

Velocity 

we know u and udot; integrate to get q

Position 

we know q, u, and udot

◆ Method

There are several ways to specify the motion at this Level, and the selected method also determines lower-level motions.

Free is only permitted when Level==Acceleration, and Fast is not allowed for that Level.

Enumerator
NoMethod 

invalid method

Zero 

motion at this level and below is always zero

Discrete 

motion is "slow"; lower levels are zero

Prescribed 

motion is function of time and state; <level is derivative

Free 

accel. calculated from forces, pos and vel integrated

Fast 

motion is "fast"; lower levels are zero

Constructor & Destructor Documentation

◆ Motion() [1/2]

SimTK::Motion::Motion ( )
inline

Default constructor creates an empty Motion handle that can be assigned to reference any kind of Motion object.

◆ Motion() [2/2]

SimTK::Motion::Motion ( MotionImpl *  r)
inlineexplicitprotected

For internal use: construct a new Motion handle referencing a particular implementation object.

Member Function Documentation

◆ nameOfLevel()

static const char* SimTK::Motion::nameOfLevel ( Level  )
static

Returns a human-readable name corresponding to the given Level; useful for debugging.

If the Level is unrecognized the method will return some text to that effect rather than crashing.

◆ nameOfMethod()

static const char* SimTK::Motion::nameOfMethod ( Method  )
static

Returns a human-readable name corresponding to the given Method; useful for debugging.

If the Method is unrecognized the method will return some text to that effect rather than crashing.

◆ getLevel()

Level SimTK::Motion::getLevel ( const State ) const

Get the highest level being driven by this Motion.

If the mobilizer is locked, this is the level that would be driven if the mobilizer were unlocked. If this Motion is currently disabled, it returns Motion::NoLevel.

◆ getLevelMethod()

Method SimTK::Motion::getLevelMethod ( const State ) const

Get the method being used to control the indicated Level.

If the mobilizer is locked, this is the method that would be used if the mobilizer were unlocked. If this Motion is currently disabled, it returns Motion::NoMethod.

◆ disable()

void SimTK::Motion::disable ( State state) const

Disable this Motion, effectively removing it from the mobilizer to which it belongs and allowing the mobilizer to move freely (unless locked).

This is an Stage::Instance change and affects the allocation of Motion-related resources in the supplied State.

See also
enable(), setDisabledByDefault(), SimTK::MobilizedBody::lock()

◆ enable()

void SimTK::Motion::enable ( State state) const

Enable this Motion, without necessarily satisfying it.

This is an Instance-stage change and affects the allocation of Motion-related resources in the supplied State. Note that merely enabling a Motion does not ensure that the State's positions and velocities satisfy the Motion's requirements; initial satisfaction requires use of an appropriate prescribe() or project() solver. Also, if the controlled mobilizer is currently locked enabling the Motion will not take effect until the mobilizer is unlocked.

See also
disable(), SimTK::System::prescribe(), SimTK::System::project()
SimTK::MobilizedBody::unlock()

◆ isDisabled()

bool SimTK::Motion::isDisabled ( const State state) const

Test whether this Motion is currently disabled in the supplied State.

◆ setDisabledByDefault()

void SimTK::Motion::setDisabledByDefault ( bool  shouldBeDisabled)

Specify that a Motion is to be inactive by default.

This is a topological change, meaning you'll have to call realizeTopology() again and get a new State. If you just want to disable temporarily, use disable() instead.

See also
isDisabledByDefault(), disable()

◆ isDisabledByDefault()

bool SimTK::Motion::isDisabledByDefault ( ) const

Test whether this Motion is disabled by default in which case it must be explicitly enabled before it will take effect.

See also
setDisabledByDefault(), enable()

◆ getMobilizedBody()

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

Get the MobilizedBody to which this Motion belongs.

◆ calcAllMethods()

void SimTK::Motion::calcAllMethods ( const State s,
Method qMethod,
Method uMethod,
Method udotMethod 
) const

(Advanced) This implements the above table.

Given the (level,method) Motion specification, it reports the actual method to be used for each of the three levels.


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