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 MobilizedBody &	getMobilizedBody () 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...

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

PIMPLHandle &	copyAssign (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...

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

void	setImpl (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

enum SimTK::Motion::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

enum SimTK::Motion::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:

Motion.h

Classes

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions