OpenSim::ModelComponent Class Reference

This is the base class for any component which can be added to a Model. More...

#include <ModelComponent.h>

Inheritance diagram for OpenSim::ModelComponent:
OpenSim::Object OpenSim::Body OpenSim::Constraint OpenSim::ContactGeometry OpenSim::Controller OpenSim::Coordinate OpenSim::Force OpenSim::GeometryPath OpenSim::Joint OpenSim::Model

List of all members.

Public Member Functions

 ModelComponent ()
 ModelComponent (const std::string &aFileName, bool aUpdateFromXMLNode=true) SWIG_DECLARE_EXCEPTION
 ModelComponent (const XMLDocument *aDocument)
 ModelComponent (DOMElement *aNode)
 ModelComponent (const ModelComponent &copy)
virtual ~ModelComponent ()
ModelComponentoperator= (const ModelComponent &aModelComponent)
 Assignment operator to copy contents of an existing component.
const ModelgetModel () const
 Get the Model this object is part of.
ModelupdModel ()
 Get a modifiable reference to the Model this object is part of.
virtual void updateDisplayer (const SimTK::State &s)
 In case the ModelCompoenent has a visual representation, override this method to update the representation, typically this's done by recomputing anchor points and positions based on transforms obtained from current state.
virtual int getModelingOption (const SimTK::State &state) const
 Get the value of a ModelingOption flag for this ModelComponent.
virtual void setModelingOption (SimTK::State &state, int flag) const
 Set the value of a discrete variable allocated by this ModelComponent by name.
virtual int getNumStateVariables () const =0
 Gets the number of "Continuous" state variables maintained by the ModelComponent If the ModelComponent defines any that are of interest to the user, names should also be given.
virtual std::string getStateVariableName (int index) const
 Get the name of a state variable allocated by this ModelComponent.
virtual int getStateVariableYIndex (int index) const
 Get the YIndex of a state variable allocated by this ModelComponent.
virtual double getStateVariable (const SimTK::State &state, int index) const
 Get the value of a state variable allocated by this ModelComponent by index.
virtual double getStateVariable (const SimTK::State &state, const std::string &name) const
 Get the value of a state variable allocated by this ModelComponent.
virtual void setStateVariable (SimTK::State &state, int index, double value) const
 Set the value of a state variable allocated by this ModelComponent.
virtual void setStateVariable (SimTK::State &state, const std::string &name, double value) const
 Set the value of a state variable allocated by this ModelComponent by name.
virtual double getDiscreteVariable (const SimTK::State &state, const std::string &name) const
 Get the value of a discrete variable allocated by this ModelComponent by name.
virtual void setDiscreteVariable (SimTK::State &state, const std::string &name, double value) const
 Set the value of a discrete variable allocated by this ModelComponent by name.
template<typename T >
const T & getCacheVariable (const SimTK::State &state, const std::string &name) const
 Get the value of a cache variable allocated by this ModelComponent by name.
template<typename T >
T & updCacheVariable (const SimTK::State &state, const std::string &name) const
 Obtain a writable cache variable value allocated by this ModelComponent by name.
void markCacheVariableValid (const SimTK::State &state, const std::string &name) const
 After updating a cache variable value allocated by this ModelComponent, you can mark its value as valid, which will not change until the realization stage falls below the minimum set at the time the cache variable was created.
bool isCacheVariableValid (const SimTK::State &state, const std::string &name) const
 Enable the component performing a costly evaluation method to monitor the validity of the cache variable value and to use this flag to force a re-evaluation only when necessary.
template<typename T >
void setCacheVariable (const SimTK::State &state, const std::string &name, T &value) const
 Set cache variable value allocated by this ModelComponent by name.
void includeAsSubComponent (ModelComponent *aComponent)
 Include another ModelComponent as a Subcomponent of this ModelComponent.

Protected Member Functions

virtual void setup (Model &model)
 This is called after the Model has been constructed from an XML file.
virtual void createSystem (SimTK::MultibodySystem &system) const
 This is called when a SimTK System is being created for the Model.
virtual void initState (SimTK::State &state) const
 This is called after a SimTK System and State have been created for the Model.
virtual void setDefaultsFromState (const SimTK::State &state)
 Set all default values for this object to match those in a specified State.
void setIndexOfSubsystemForAllocations (SimTK::SubsystemIndex subsysIndex)
 Set the index for the subsystem to which new variables (modeling option, state, cache) corresponding to the ModelComponent will be added.
const SimTK::SubsystemIndex getIndexOfSubsystemForAllocations () const
void addModelingOption (const Array< std::string > &optionFlagNames)
 Helper methods for implementing concrete ModelComponents.
void addStateVariables (const Array< std::string > &stateVariableNames)
 Add continuous system state variables belonging to this ModelComponent.
virtual SimTK::Vector computeStateVariableDerivatives (const SimTK::State &s) const
 If state variables are continuous, then computeStateVariableDerivatives() must be implemented so that the evolution of the state variable can be determined.
void addDiscreteVariables (const Array< std::string > &discreteVariableNames, const SimTK::Stage &dependentOnStage)
 Add system discrete variables belonging to this ModelComponent.
template<typename T >
void addCacheVariable (const std::string &cacheVariableName, const T &variablePrototype, const SimTK::Stage &lowestValidStage)
 Add a state cache variable belonging to this ModelComponent.
const SimTK::ZIndex getZIndex (const std::string &name) const
 Get the index of a ModelComponent's conintuous state variable in the Subsystem for allocations.
const SimTK::DiscreteVariableIndex getDiscreteVariableIndex (const std::string &name) const
 Get the index of a ModelComponent's discrete variable in the Subsystem for allocations.
const SimTK::CacheEntryIndex getCacheVariableIndex (const std::string &name) const
 Get the index of a ModelComponent's cache variable in the Subsystem for allocations.
const ModelComponentRepgetRep ()
ModelComponentRepupdRep ()

Protected Attributes

Model_model

Friends

class ModelComponentSet
class ModelComponentRep

Detailed Description

This is the base class for any component which can be added to a Model.

It defines a set of methods which a component must implement to be integrated into the underlying system.

The primary responsibility of a ModelComponent is to add its contributions to the underlying SimTK::System by implementing createSystem().

Additional methods provide support for adding modeling options, state and cache variables.


Constructor & Destructor Documentation

OpenSim::ModelComponent::ModelComponent (  ) 
OpenSim::ModelComponent::ModelComponent ( const std::string &  aFileName,
bool  aUpdateFromXMLNode = true 
)
OpenSim::ModelComponent::ModelComponent ( const XMLDocument aDocument  ) 
OpenSim::ModelComponent::ModelComponent ( DOMElement *  aNode  ) 
OpenSim::ModelComponent::ModelComponent ( const ModelComponent copy  ) 
OpenSim::ModelComponent::~ModelComponent (  )  [virtual]

Member Function Documentation

template<typename T >
void OpenSim::ModelComponent::addCacheVariable ( const std::string &  cacheVariableName,
const T &  variablePrototype,
const SimTK::Stage &  lowestValidStage 
) [inline, protected]

Add a state cache variable belonging to this ModelComponent.

Cache variables are typically computed from the state and provide convenience and/or efficiency by holding on to them in memory (cache) and using the cached value subsequently rather than recomputing. Once the state changes, the cache variable values become invalid and have to be recomputed based on the current state.

Parameters:
cacheVariableName is the name of the variable
variablePrototype is a prototype of the object (type) to be cached
the lowest computational stage at which the cache variable is valid
void OpenSim::ModelComponent::addDiscreteVariables ( const Array< std::string > &  discreteVariableNames,
const SimTK::Stage &  dependentOnStage 
) [protected]

Add system discrete variables belonging to this ModelComponent.

The number of discrete variables is specified by the number of discreteVariableNames, and each allocated discrete variable is assigned the corresponding name. Each variable is allocated as SimTK::Real and is dependent on the same Stage. Use repeated calls with a different Stage for variables that are dependent on other Stages

void OpenSim::ModelComponent::addModelingOption ( const Array< std::string > &  optionFlagNames  )  [protected]

Helper methods for implementing concrete ModelComponents.

These methods can only be called inside of createSystem() and are useful for creating the underlying SimTK::System level variables that are used for computing values of interest. Add a modeling option (integer flag) used by this ModelComponent, with each option identified by a label. Modeling options enable the model component to be configured differently in order to represent different operating modes. For example, in may be useful to ignore excitation-activation dynamics of a muscle, or to apply a known muscle force, which could be modeling options.

void OpenSim::ModelComponent::addStateVariables ( const Array< std::string > &  stateVariableNames  )  [protected]

Add continuous system state variables belonging to this ModelComponent.

The number of states is defined by the number of stateVariableNames, and each state variable is assigned the corresponding name.

virtual SimTK::Vector OpenSim::ModelComponent::computeStateVariableDerivatives ( const SimTK::State &  s  )  const [inline, protected, virtual]

If state variables are continuous, then computeStateVariableDerivatives() must be implemented so that the evolution of the state variable can be determined.

Otherwise, state variables are intepreted as discrete variables and must be supplied to the model component. Override to return a Vector of the same size as the number of state variables defined, otherwise returns empty (no derivatives are defined).

Reimplemented in OpenSim::ContDerivMuscle, OpenSim::Delp1990Muscle, OpenSim::Schutte1993Muscle, and OpenSim::Thelen2003Muscle.

void OpenSim::ModelComponent::createSystem ( SimTK::MultibodySystem &  system  )  const [protected, virtual]
template<typename T >
const T& OpenSim::ModelComponent::getCacheVariable ( const SimTK::State &  state,
const std::string &  name 
) const [inline]

Get the value of a cache variable allocated by this ModelComponent by name.

Parameters:
state the State for which to set the value
name the name of the cache variable
Returns:
T the variable's cache value
const SimTK::CacheEntryIndex OpenSim::ModelComponent::getCacheVariableIndex ( const std::string &  name  )  const [protected]

Get the index of a ModelComponent's cache variable in the Subsystem for allocations.

This method is intended for derived ModelComponents that may need direct access to its underlying Subsystem.

double OpenSim::ModelComponent::getDiscreteVariable ( const SimTK::State &  state,
const std::string &  name 
) const [virtual]

Get the value of a discrete variable allocated by this ModelComponent by name.

Parameters:
state the State for which to set the value
name the name of the state variable
value the value to get
const SimTK::DiscreteVariableIndex OpenSim::ModelComponent::getDiscreteVariableIndex ( const std::string &  name  )  const [protected]

Get the index of a ModelComponent's discrete variable in the Subsystem for allocations.

This method is intended for derived ModelComponents that may need direct access to its underlying Subsystem.

const SimTK::SubsystemIndex OpenSim::ModelComponent::getIndexOfSubsystemForAllocations (  )  const [protected]
const Model & OpenSim::ModelComponent::getModel (  )  const

Get the Model this object is part of.

Reimplemented in OpenSim::Coordinate.

int OpenSim::ModelComponent::getModelingOption ( const SimTK::State &  state  )  const [virtual]

Get the value of a ModelingOption flag for this ModelComponent.

Parameters:
state the State for which to set the value
Returns:
flag integer value for modeling option
virtual int OpenSim::ModelComponent::getNumStateVariables (  )  const [pure virtual]

Gets the number of "Continuous" state variables maintained by the ModelComponent If the ModelComponent defines any that are of interest to the user, names should also be given.

Implemented in OpenSim::Controller, OpenSim::ActivationFiberLengthMuscle, OpenSim::ContactGeometry, OpenSim::Force, OpenSim::GeometryPath, OpenSim::Model, OpenSim::Body, OpenSim::Constraint, OpenSim::Coordinate, and OpenSim::Joint.

const ModelComponentRep* OpenSim::ModelComponent::getRep (  )  [inline, protected]
double OpenSim::ModelComponent::getStateVariable ( const SimTK::State &  state,
const std::string &  name 
) const [virtual]

Get the value of a state variable allocated by this ModelComponent.

Parameters:
state the State for which to get the value
index the index of the state variable (0 to getNumStateVariables()-1)
double OpenSim::ModelComponent::getStateVariable ( const SimTK::State &  state,
int  index 
) const [virtual]

Get the value of a state variable allocated by this ModelComponent by index.

TODO: This should be deprecated to use name only to avoid any confusion.

Parameters:
state the State for which to get the value
index the index of the state variable (0 to getNumStateVariables()-1)
virtual std::string OpenSim::ModelComponent::getStateVariableName ( int  index  )  const [inline, virtual]

Get the name of a state variable allocated by this ModelComponent.

The default implementation throws an exception, so subclasses that allocate state variables must override it.

Parameters:
index the index of the state variable (0 to getNumStateVariables()-1)

Reimplemented in OpenSim::ActivationFiberLengthMuscle, and OpenSim::Coordinate.

virtual int OpenSim::ModelComponent::getStateVariableYIndex ( int  index  )  const [inline, virtual]

Get the YIndex of a state variable allocated by this ModelComponent.

The default implementation throws an exception, so subclasses that allocate state variables must override it.

Parameters:
index the index of the state variable (0 to getNumStateVariables()-1)

Reimplemented in OpenSim::Delp1990Muscle, OpenSim::Schutte1993Muscle, OpenSim::Thelen2003Muscle, and OpenSim::Coordinate.

const SimTK::ZIndex OpenSim::ModelComponent::getZIndex ( const std::string &  name  )  const [protected]

Get the index of a ModelComponent's conintuous state variable in the Subsystem for allocations.

This method is intended for derived ModelComponents that may need direct access to its underlying Subsystem.

void OpenSim::ModelComponent::includeAsSubComponent ( ModelComponent aComponent  ) 

Include another ModelComponent as a Subcomponent of this ModelComponent.

Include another ModelComponent as a subcomponent of this one.

ModelComponent methods (e.g. createSystem(), initState(), ...) are therefore invoked on Subcomponents when called on the parent. Realization is also performed automatically on subcomponents. This ModelComponent does not take ownership of the subcomponent.

If already a subcomponent it is not added to the list again.

virtual void OpenSim::ModelComponent::initState ( SimTK::State &  state  )  const [inline, protected, virtual]
bool OpenSim::ModelComponent::isCacheVariableValid ( const SimTK::State &  state,
const std::string &  name 
) const [inline]

Enable the component performing a costly evaluation method to monitor the validity of the cache variable value and to use this flag to force a re-evaluation only when necessary.

Parameters:
state the State for which to set the value
name the name of the state variable
void OpenSim::ModelComponent::markCacheVariableValid ( const SimTK::State &  state,
const std::string &  name 
) const [inline]

After updating a cache variable value allocated by this ModelComponent, you can mark its value as valid, which will not change until the realization stage falls below the minimum set at the time the cache variable was created.

If not marked as valid, the evaluation method monitoring this flag will force a re-evaluation rather that just reading the value from the cache.

Parameters:
state the State for which to set the value
name the name of the state variable
ModelComponent & OpenSim::ModelComponent::operator= ( const ModelComponent aModelComponent  ) 
template<typename T >
void OpenSim::ModelComponent::setCacheVariable ( const SimTK::State &  state,
const std::string &  name,
T &  value 
) const [inline]

Set cache variable value allocated by this ModelComponent by name.

All cache entries are lazily evaluated (on a need basis) so a set also marks the cache as valid.

Parameters:
state the State for which to set the value
name the name of the state variable
Returns:
value the variable's cache value to update
virtual void OpenSim::ModelComponent::setDefaultsFromState ( const SimTK::State &  state  )  [inline, protected, virtual]

Set all default values for this object to match those in a specified State.

It must be implemented/overriden to set any default values defined by each subclass.

Parameters:
state the State from which to take values that should become the defaults for this object

Reimplemented in OpenSim::RigidTendonMuscle, OpenSim::Controller, OpenSim::ActivationFiberLengthMuscle, OpenSim::Actuator_, OpenSim::Actuator, OpenSim::ContactGeometry, OpenSim::Force, OpenSim::GeometryPath, OpenSim::Model, OpenSim::Muscle, OpenSim::BallJoint, OpenSim::Body, OpenSim::Constraint, OpenSim::Coordinate, OpenSim::EllipsoidJoint, OpenSim::FreeJoint, OpenSim::Joint, and OpenSim::RollingOnSurfaceConstraint.

void OpenSim::ModelComponent::setDiscreteVariable ( SimTK::State &  state,
const std::string &  name,
double  value 
) const [virtual]

Set the value of a discrete variable allocated by this ModelComponent by name.

Parameters:
state the State for which to set the value
name the name of the dsicrete variable
value the value to set
void OpenSim::ModelComponent::setIndexOfSubsystemForAllocations ( SimTK::SubsystemIndex  subsysIndex  )  [protected]

Set the index for the subsystem to which new variables (modeling option, state, cache) corresponding to the ModelComponent will be added.

This method is intended to override use of the defaultSubsystem by concrete subclasses.

void OpenSim::ModelComponent::setModelingOption ( SimTK::State &  state,
int  flag 
) const [virtual]

Set the value of a discrete variable allocated by this ModelComponent by name.

Parameters:
state the State in which to set the flag
void OpenSim::ModelComponent::setStateVariable ( SimTK::State &  state,
const std::string &  name,
double  value 
) const [virtual]

Set the value of a state variable allocated by this ModelComponent by name.

Parameters:
state the State for which to set the value
name the name of the state variable
value the value to set
void OpenSim::ModelComponent::setStateVariable ( SimTK::State &  state,
int  index,
double  value 
) const [virtual]

Set the value of a state variable allocated by this ModelComponent.

Parameters:
state the State for which to set the value
index the index of the state variable (0 to getNumStateVariables()-1)
value the value to set
void OpenSim::ModelComponent::setup ( Model model  )  [protected, virtual]

This is called after the Model has been constructed from an XML file.

Set the Model this object is part of and then so do required initialization, such as looking up references to other objects in the Model (which might not have existed yet when this object was instantiated). Override this method as necessary but always call the parent class setup to ensure all members (belonging to parent and child) are initialized.

Reimplemented in OpenSim::ContDerivMuscle, OpenSim::CoordinateActuator, OpenSim::CoordinateLimitForce, OpenSim::Delp1990Muscle, OpenSim::PointActuator, OpenSim::PointToPointActuator, OpenSim::RigidTendonMuscle, OpenSim::Schutte1993Muscle, OpenSim::SpringGeneralizedForce, OpenSim::Thelen2003Muscle, OpenSim::TorqueActuator, OpenSim::ConstantController, OpenSim::Controller, OpenSim::ControlSetController, OpenSim::ActivationFiberLengthMuscle, OpenSim::Actuator_, OpenSim::Actuator, OpenSim::BushingForce, OpenSim::ContactGeometry, OpenSim::ExternalForce, OpenSim::Force, OpenSim::GeometryPath, OpenSim::Ligament, OpenSim::LinearSpring, OpenSim::Muscle, OpenSim::PathActuator, OpenSim::PointToPointSpring, OpenSim::PrescribedForce, OpenSim::BallJoint, OpenSim::Body, OpenSim::Constraint, OpenSim::Coordinate, OpenSim::CoordinateCouplerConstraint, OpenSim::CustomJoint, OpenSim::EllipsoidJoint, OpenSim::FreeJoint, OpenSim::Joint, OpenSim::PinJoint, OpenSim::PointConstraint, OpenSim::PointOnLineConstraint, OpenSim::RollingOnSurfaceConstraint, OpenSim::SliderJoint, OpenSim::UnilateralConstraint, OpenSim::WeldConstraint, OpenSim::WeldJoint, OpenSim::CMC, and OpenSim::CorrectionController.

virtual void OpenSim::ModelComponent::updateDisplayer ( const SimTK::State &  s  )  [inline, virtual]

In case the ModelCompoenent has a visual representation, override this method to update the representation, typically this's done by recomputing anchor points and positions based on transforms obtained from current state.

Reimplemented in OpenSim::GeometryPath, OpenSim::Ligament, OpenSim::PathActuator, and OpenSim::PointToPointSpring.

template<typename T >
T& OpenSim::ModelComponent::updCacheVariable ( const SimTK::State &  state,
const std::string &  name 
) const [inline]

Obtain a writable cache variable value allocated by this ModelComponent by name.

Do not forget to mark the cache value as valid after updating, otherwise it will force a reevaluation if the evaluation method is monitoring the validity of the cache value.

Parameters:
state the State for which to set the value
name the name of the state variable
Returns:
value the variable's cache value to update
Model & OpenSim::ModelComponent::updModel (  ) 

Get a modifiable reference to the Model this object is part of.

ModelComponentRep* OpenSim::ModelComponent::updRep (  )  [inline, protected]

Friends And Related Function Documentation

friend class ModelComponentRep [friend]
friend class ModelComponentSet [friend]

Member Data Documentation


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

Generated on Sun Sep 25 00:19:59 2011 for OpenSim by  doxygen 1.6.1