OpenSim::AbstractTool Class Reference

An abstract class for specifying the interface for an investigation. More...

#include <AbstractTool.h>

Inheritance diagram for OpenSim::AbstractTool:

List of all members.

Public Member Functions
virtual	~AbstractTool ()
	Destructor.
	AbstractTool ()
	Default constructor.
	AbstractTool (const std::string &aFileName, bool aUpdateFromXMLNode=true)
	Construct from file, and an optional GuiModel.
	AbstractTool (const AbstractTool &aObject)
	Copy constructor.
	OPENSIM_DECLARE_DERIVED (AbstractTool, Object)
AbstractTool &	operator= (const AbstractTool &aTool)
	Assignment operator.
virtual void	setModel (Model &aModel) SWIG_DECLARE_EXCEPTION
	Set the model to be investigated.
virtual Model &	getModel () const
	Get the model to be investigated.
bool	getReplaceForceSet () const
void	setReplaceForceSet (bool aReplace)
std::string	getNextAvailableForceName (const std::string prefix="Force") const
	A Convenience method to get the next unique.
const ExternalLoads &	getExternalLoads () const
ExternalLoads &	updExternalLoads ()
const std::string &	getExternalLoadsFileName () const
void	setExternalLoadsFileName (const std::string &aFileName)
Array< std::string > &	getForceSetFiles ()
void	setForceSetFiles (const Array< std::string > &aForceSetFiles)
int	getOutputPrecision () const
void	setOutputPrecision (int aPrecision)
AnalysisSet &	getAnalysisSet () const
	Get the analysis set.
const std::string &	getResultsDir () const
	Get Results Directory.
void	setResultsDir (const std::string &aString)
double	getInitialTime () const
double	getFinalTime () const
void	setInitialTime (const double aInitialTime)
void	setFinalTime (const double aFinalTime)
double	getStartTime () const
void	setStartTime (const double aStartTime)
int	getMaximumNumberOfSteps () const
void	setMaximumNumberOfSteps (int aMaxSteps)
double	getMaxDT () const
void	setMaxDT (double aMaxDT)
double	getMinDT () const
void	setMinDT (double aMinDT)
double	getErrorTolerance () const
void	setErrorTolerance (double aErrorTolerance)
const std::string &	getModelFilename () const
void	setModelFilename (const std::string &aModelFile)
bool	getSolveForEquilibrium () const
void	setSolveForEquilibrium (bool aSolve)
void	loadModel (const std::string &aToolSetupFileName, ForceSet *rOriginalForceSet=0)
	Load and construct a model based on the property settings of this investigation.
void	updateModelForces (Model &model, const std::string &aToolSetupFileName, ForceSet *rOriginalForceSet=0) SWIG_DECLARE_EXCEPTION
	Update the forces applied to a model.
void	addAnalysisSetToModel ()
	Adds Analysis objects from analysis set to model.
void	addControllerSetToModel ()
	Adds Controller objects from Controller set to model.
void	removeControllerSetFromModel ()
	Remove Analysis objects that were added earlier from analysis set to model.
void	removeAnalysisSetFromModel ()
	Remove Analysis objects that were added earlier from analysis set to model.
void	setToolOwnsModel (const bool trueFalse)
const bool	getToolOwnsModel () const
std::string	getControlsFileName () const
	Interfaces to build controller from a file and add it to the tool.
void	setControlsFileName (const std::string &controlsFilename)
	A Convenience method to add a ControlSetController from a file and add it to the model.
virtual bool	run () SWIG_DECLARE_EXCEPTION=0
virtual void	printResults (const std::string &aBaseName, const std::string &aDir="", double aDT=-1.0, const std::string &aExtension=".sto")
	Print the results of the analysis.
bool	createExternalLoads (const std::string &aExternalLoadsFileName, Model &aModel, const Storage *loadKinematics=NULL)
virtual void	updateFromXMLNode ()
	Override default implementation by object to intercept and fix the XML node underneath the tool to match current version.
virtual void	loadQStorage (const std::string &statesFileName, Storage &rQStore) const
Protected Attributes
Model *	_model
	Pointer to the model being investigated.
PropertyStr	_modelFileProp
	Name of the xml file used to deserialize or construct a model.
std::string &	_modelFile
PropertyBool	_replaceForceSetProp
	Whether the force set included in the model file is replaced (if true) or appended to (if false) with force sets read in from file.
bool &	_replaceForceSet
PropertyStrArray	_forceSetFilesProp
	Names of the xml files used to construct an force set for the model.
Array< std::string > &	_forceSetFiles
PropertyStr	_resultsDirProp
	Directory used for writing results.
std::string &	_resultsDir
PropertyInt	_outputPrecisionProp
	Output precision.
int &	_outputPrecision
PropertyDbl	_tiProp
	Initial time for the investigation.
double &	_ti
PropertyDbl	_tfProp
	Final time for the investigation.
double &	_tf
OpenSim::PropertyBool	_solveForEquilibriumForAuxiliaryStatesProp
	A flag used to specify whether or not equilibrium is solved for for the auxiliary states.
bool &	_solveForEquilibriumForAuxiliaryStates
PropertyInt	_maxStepsProp
	Maximum number of steps for the integrator.
int &	_maxSteps
PropertyDbl	_maxDTProp
	Maximum integration step size.
double &	_maxDT
PropertyDbl	_minDTProp
	Minimum integration step size.
double &	_minDT
PropertyDbl	_errorToleranceProp
	Integrator error tolerance.
double &	_errorTolerance
PropertyObj	_analysisSetProp
	Set of analyses to be run during the study.
AnalysisSet &	_analysisSet
PropertyObj	_controllerSetProp
ControllerSet &	_controllerSet
bool	_toolOwnsModel
	Whether the tool owns the model it operates on.
OpenSim::PropertyStr	_externalLoadsFileNameProp
	Name of the file containing the external loads applied to the model.
std::string &	_externalLoadsFileName
ExternalLoads	_externalLoads
	Actual external forces being applied.

---

Detailed Description

An abstract class for specifying the interface for an investigation.

Author:

Frank C. Anderson

Version:

1.0

---

Constructor & Destructor Documentation

AbstractTool::~AbstractTool

(

)

[virtual]

Destructor.

AbstractTool::AbstractTool

(

)

Default constructor.

OpenSim::AbstractTool::AbstractTool	(	const std::string &	aFileName,
		bool	aUpdateFromXMLNode = true
	)

Construct from file, and an optional GuiModel.

The object is constructed from the root element of the XML document. The type of object is the tag name of the XML root element.

Parameters:

aFileName

File name of the document.

AbstractTool::AbstractTool

(

const AbstractTool &

aTool

)

Copy constructor.

Copy constructors for all SimulationTools only copy the non-XML variable members of the object; that is, the object's DOMnode and XMLDocument are not copied but set to NULL. This is because the object and all its derived classes need to establish the correct connection to the XML document nodes. Thus the object needs to reconstruct based on the XML document, not the values of the object's member variables.

There are three proper ways to generate an XML document for a AbstractTool:

1) Construction based on XML file (

See also:

AbstractTool(const char *aFileName)). In this case, the XML document is created by parsing the XML file.

2) Construction by AbstractTool(const XMLDocument *aDocument). This constructor explictly requests construction based on an XML document. In this way the proper connection between an object's node and the corresponding node within the XML document is established. This constructor is a copy constructor of sorts because all essential AbstractTool member variables should be held within the XML document. The advantage of this style of construction is that nodes within the XML document, such as comments that may not have any associated AbstractTool member variable, are preserved.

3) A call to generateXMLDocument(). This method generates an XML document for the AbstractTool from scratch. Only the essential document nodes are created (that is, nodes that correspond directly to member variables.).

Parameters:

aTool

Object to be copied.

See also:

AbstractTool(const XMLDocument *aDocument)

AbstractTool(const char *aFileName)

generateXMLDocument()

Copy constructors for all SimulationTools only copy the non-XML variable members of the object; that is, the object's DOMnode and XMLDocument are not copied but set to NULL. The reason for this is that for the object and all its derived classes to establish the correct connection to the XML document nodes, the the object would need to reconstruct based on the XML document not the values of the object's member variables.

There are three proper ways to generate an XML document for a AbstractTool:

1) Construction based on XML file (

See also:

AbstractTool(const char *aFileName)). In this case, the XML document is created by parsing the XML file.

2) Construction by AbstractTool(const XMLDocument *aDocument). This constructor explictly requests construction based on an XML document. In this way the proper connection between an object's node and the corresponding node within the XML document is established. This constructor is a copy constructor of sorts because all essential AbstractTool member variables should be held within the XML document. The advantage of this style of construction is that nodes within the XML document, such as comments that may not have any associated AbstractTool member variable, are preserved.

3) A call to generateXMLDocument(). This method generates an XML document for the AbstractTool from scratch. Only the essential document nodes are created (that is, nodes that correspond directly to member variables.).

Parameters:

aTool

Object to be copied.

See also:

AbstractTool(const XMLDocument *aDocument)

AbstractTool(const char *aFileName)

generateXMLDocument()

---

Member Function Documentation

void AbstractTool::addAnalysisSetToModel

(

)

Adds Analysis objects from analysis set to model.

NOTE: Makes copies of analyses. Also, both this tool and the model have ownership of their analysis objects, thereofre making a copy is necessary so a single analysis won't be deleted twice.

To avoid leaking when the tool is run from the GUI, pointers to the model's copy of the analyses are kept around so that they can be removed at the end of tool execution. _analysisCopies is used to do this book keeping.

NOTE: Makes copies of analyses. Also, both this tool and the model have ownership of their analysis objects, so making a copy is necessary so a single analysis won't be deleted twice.

To avoid leaking when the tool is run from the GUI, pointers to the model's copy of the analyses are kept around so that they can be removed at the end of tool execution. _analysisCopies is used to do this book keeping.

void AbstractTool::addControllerSetToModel

(

)

Adds Controller objects from Controller set to model.

NOTE: Makes copies of Controller. Also, both this tool and the model have ownership of their Controller objects, so making a copy is necessary so a single analysis won't be deleted twice.

To avoid leaking when the tool is run from the GUI, pointers to the model's copy of the Controller are kept around so that they can be removed at the end of tool execution. _controllerCopies is used to do this book keeping.

bool OpenSim::AbstractTool::createExternalLoads	(	const std::string &	aExternalLoadsFileName,
		Model &	aModel,
		const Storage *	loadKinematics = NULL
	)

AnalysisSet & AbstractTool::getAnalysisSet

(

)

const

Get the analysis set.

std::string AbstractTool::getControlsFileName

(

)

const

Interfaces to build controller from a file and add it to the tool.

double OpenSim::AbstractTool::getErrorTolerance

(

)

const [inline]

const ExternalLoads& OpenSim::AbstractTool::getExternalLoads

(

)

const [inline]

const std::string& OpenSim::AbstractTool::getExternalLoadsFileName

(

)

const [inline]

Reimplemented in OpenSim::CMCTool, and OpenSim::RRATool.

double OpenSim::AbstractTool::getFinalTime

(

)

const [inline]

Array<std::string>& OpenSim::AbstractTool::getForceSetFiles

(

)

[inline]

double OpenSim::AbstractTool::getInitialTime

(

)

const [inline]

double OpenSim::AbstractTool::getMaxDT

(

)

const [inline]

int OpenSim::AbstractTool::getMaximumNumberOfSteps

(

)

const [inline]

double OpenSim::AbstractTool::getMinDT

(

)

const [inline]

Model & AbstractTool::getModel

(

)

const [virtual]

Get the model to be investigated.

const std::string& OpenSim::AbstractTool::getModelFilename

(

)

const [inline]

std::string AbstractTool::getNextAvailableForceName

(

const std::string

prefix = "Force"

)

const

A Convenience method to get the next unique.

int OpenSim::AbstractTool::getOutputPrecision

(

)

const [inline]

bool OpenSim::AbstractTool::getReplaceForceSet

(

)

const [inline]

const std::string& OpenSim::AbstractTool::getResultsDir

(

)

const [inline]

Get Results Directory.

bool OpenSim::AbstractTool::getSolveForEquilibrium

(

)

const [inline]

double OpenSim::AbstractTool::getStartTime

(

)

const [inline]

const bool OpenSim::AbstractTool::getToolOwnsModel

(

)

const [inline]

void OpenSim::AbstractTool::loadModel	(	const std::string &	aToolSetupFileName,
		ForceSet *	rOriginalForceSet = 0
	)

Load and construct a model based on the property settings of this investigation.

void AbstractTool::loadQStorage	(	const std::string &	statesFileName,
		Storage &	rQStore
	)			const [virtual]

OpenSim::AbstractTool::OPENSIM_DECLARE_DERIVED	(	AbstractTool	,
		Object
	)

AbstractTool & AbstractTool::operator=

(

const AbstractTool &

aTool

)

Assignment operator.

Returns:

Reference to this object.

Reimplemented from OpenSim::Object.

Reimplemented in OpenSim::AnalyzeTool, OpenSim::CMCTool, OpenSim::ForwardTool, and OpenSim::RRATool.

virtual void OpenSim::AbstractTool::printResults	(	const std::string &	aBaseName,
		const std::string &	aDir = "",
		double	aDT = -1.0,
		const std::string &	aExtension = ".sto"
	)			[virtual]

Print the results of the analysis.

Parameters:

	aFileName	File to which to print the data.
	aDT	Time interval between results (linear interpolation is used). If not included as an argument or negative, all time steps are printed without interpolation.
	aExtension	Extension for written files.

void AbstractTool::removeAnalysisSetFromModel

(

)

Remove Analysis objects that were added earlier from analysis set to model.

NOTE: Pointers to the .

void AbstractTool::removeControllerSetFromModel

(

)

Remove Analysis objects that were added earlier from analysis set to model.

virtual bool OpenSim::AbstractTool::run

(

)

[pure virtual]

Implemented in OpenSim::AnalyzeTool, OpenSim::CMCTool, OpenSim::ForwardTool, and OpenSim::RRATool.

void AbstractTool::setControlsFileName

(

const std::string &

controlsFilename

)

A Convenience method to add a ControlSetController from a file and add it to the model.

void OpenSim::AbstractTool::setErrorTolerance

(

double

aErrorTolerance

)

[inline]

void OpenSim::AbstractTool::setExternalLoadsFileName

(

const std::string &

aFileName

)

[inline]

Reimplemented in OpenSim::CMCTool, and OpenSim::RRATool.

void OpenSim::AbstractTool::setFinalTime

(

const double

aFinalTime

)

[inline]

void OpenSim::AbstractTool::setForceSetFiles

(

const Array< std::string > &

aForceSetFiles

)

[inline]

void OpenSim::AbstractTool::setInitialTime

(

const double

aInitialTime

)

[inline]

void OpenSim::AbstractTool::setMaxDT

(

double

aMaxDT

)

[inline]

void OpenSim::AbstractTool::setMaximumNumberOfSteps

(

int

aMaxSteps

)

[inline]

void OpenSim::AbstractTool::setMinDT

(

double

aMinDT

)

[inline]

void AbstractTool::setModel

(

Model &

aModel

)

[virtual]

Set the model to be investigated.

NOTE: setup() should have been called on the model prior to calling this method

void OpenSim::AbstractTool::setModelFilename

(

const std::string &

aModelFile

)

[inline]

void OpenSim::AbstractTool::setOutputPrecision

(

int

aPrecision

)

[inline]

void OpenSim::AbstractTool::setReplaceForceSet

(

bool

aReplace

)

[inline]

void OpenSim::AbstractTool::setResultsDir

(

const std::string &

aString

)

[inline]

void OpenSim::AbstractTool::setSolveForEquilibrium

(

bool

aSolve

)

[inline]

void OpenSim::AbstractTool::setStartTime

(

const double

aStartTime

)

[inline]

void OpenSim::AbstractTool::setToolOwnsModel

(

const bool

trueFalse

)

[inline]

void AbstractTool::updateFromXMLNode

(

)

[virtual]

Override default implementation by object to intercept and fix the XML node underneath the tool to match current version.

Reimplemented from OpenSim::Object.

Reimplemented in OpenSim::ForwardTool, and OpenSim::RRATool.

void OpenSim::AbstractTool::updateModelForces	(	Model &	model,
		const std::string &	aToolSetupFileName,
		ForceSet *	rOriginalForceSet = 0
	)

Update the forces applied to a model.

ExternalLoads& OpenSim::AbstractTool::updExternalLoads

(

)

[inline]

---

Member Data Documentation

AnalysisSet& OpenSim::AbstractTool::_analysisSet [protected]

PropertyObj OpenSim::AbstractTool::_analysisSetProp [protected]

Set of analyses to be run during the study.

ControllerSet& OpenSim::AbstractTool::_controllerSet [protected]

PropertyObj OpenSim::AbstractTool::_controllerSetProp [protected]

double& OpenSim::AbstractTool::_errorTolerance [protected]

PropertyDbl OpenSim::AbstractTool::_errorToleranceProp [protected]

Integrator error tolerance.

When the error is greater, the integrator step size is decreased.

ExternalLoads OpenSim::AbstractTool::_externalLoads [protected]

Actual external forces being applied.

e.g. GRF

std::string& OpenSim::AbstractTool::_externalLoadsFileName [protected]

OpenSim::PropertyStr OpenSim::AbstractTool::_externalLoadsFileNameProp [protected]

Name of the file containing the external loads applied to the model.

Array<std::string>& OpenSim::AbstractTool::_forceSetFiles [protected]

PropertyStrArray OpenSim::AbstractTool::_forceSetFilesProp [protected]

Names of the xml files used to construct an force set for the model.

double& OpenSim::AbstractTool::_maxDT [protected]

PropertyDbl OpenSim::AbstractTool::_maxDTProp [protected]

Maximum integration step size.

int& OpenSim::AbstractTool::_maxSteps [protected]

PropertyInt OpenSim::AbstractTool::_maxStepsProp [protected]

Maximum number of steps for the integrator.

double& OpenSim::AbstractTool::_minDT [protected]

PropertyDbl OpenSim::AbstractTool::_minDTProp [protected]

Minimum integration step size.

Model* OpenSim::AbstractTool::_model [protected]

Pointer to the model being investigated.

std::string& OpenSim::AbstractTool::_modelFile [protected]

PropertyStr OpenSim::AbstractTool::_modelFileProp [protected]

Name of the xml file used to deserialize or construct a model.

int& OpenSim::AbstractTool::_outputPrecision [protected]

PropertyInt OpenSim::AbstractTool::_outputPrecisionProp [protected]

Output precision.

bool& OpenSim::AbstractTool::_replaceForceSet [protected]

PropertyBool OpenSim::AbstractTool::_replaceForceSetProp [protected]

Whether the force set included in the model file is replaced (if true) or appended to (if false) with force sets read in from file.

std::string& OpenSim::AbstractTool::_resultsDir [protected]

PropertyStr OpenSim::AbstractTool::_resultsDirProp [protected]

Directory used for writing results.

bool& OpenSim::AbstractTool::_solveForEquilibriumForAuxiliaryStates [protected]

OpenSim::PropertyBool OpenSim::AbstractTool::_solveForEquilibriumForAuxiliaryStatesProp [protected]

A flag used to specify whether or not equilibrium is solved for for the auxiliary states.

This often needs to be done auxiliary sates whose starting values are unknown (e.g., muscle fiber lengths).

double& OpenSim::AbstractTool::_tf [protected]

PropertyDbl OpenSim::AbstractTool::_tfProp [protected]

Final time for the investigation.

double& OpenSim::AbstractTool::_ti [protected]

PropertyDbl OpenSim::AbstractTool::_tiProp [protected]

Initial time for the investigation.

bool OpenSim::AbstractTool::_toolOwnsModel [protected]

Whether the tool owns the model it operates on.

Important for cleanup when done

---

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

• OpenSim/Simulation/Model/AbstractTool.h
• OpenSim/Simulation/Model/AbstractTool.cpp