API  4.5
For C++ developers
Common Utilities

These are free functions and utility classes in the Common library. More...

Classes

class  OpenSim::FileRemover
 When an instance of this class is destructed, it removes (deletes) the file at the path provided in the constructor. More...
 
class  OpenSim::ThreadsafeJar< T >
 This class lets you store objects of a single type for reuse by multiple threads, ensuring threadsafe access to each of those objects. More...
 

Functions

template<typename T , typename... Args>
std::unique_ptr< T > OpenSim::make_unique (Args &&... args)
 Since OpenSim does not require C++14 (which contains std::make_unique()), here is an implementation of make_unique(). More...
 
OSIMCOMMON_API std::string OpenSim::getFormattedDateTime (bool appendMicroseconds=false, std::string format="%Y-%m-%dT%H%M%S")
 Get a string with the current date and time formatted as Y-m-dTHMS (year, month, day, "T", hour, minute, second). More...
 
OSIMCOMMON_API SimTK::Vector OpenSim::createVectorLinspace (int length, double start, double end)
 Create a SimTK::Vector with the provided length whose elements are uniformly spaced between start and end (same as Matlab's linspace()). More...
 
OSIMCOMMON_API SimTK::Vector OpenSim::createVector (std::initializer_list< SimTK::Real > elements)
 Create a SimTK::Vector using modern C++ syntax. More...
 
OSIMCOMMON_API SimTK::Vector OpenSim::interpolate (const SimTK::Vector &x, const SimTK::Vector &y, const SimTK::Vector &newX, const bool ignoreNaNs=false)
 Linearly interpolate y(x) at new values of x. More...
 
OSIMCOMMON_API std::string OpenSim::convertRelativeFilePathToAbsoluteFromXMLDocument (const std::string &documentFileName, const std::string &filePathRelativeToDirectoryContainingDocument)
 An OpenSim XML file may contain file paths that are relative to the directory containing the XML file; use this function to convert that relative path into an absolute path. More...
 
OSIMCOMMON_API SimTK::Real OpenSim::solveBisection (std::function< double(const double &)> calcResidual, double left, double right, const double &tolerance=1e-6, int maxIterations=1000)
 Solve for the root of a scalar function using the bisection method. More...
 
OSIMCOMMON_API SimTK::Matrix OpenSim::computeKNearestNeighbors (const SimTK::Matrix &x, const SimTK::Matrix &y, int k=1)
 Compute the 'k' nearest neighbors of two matrices 'x' and 'y'. More...
 

Detailed Description

These are free functions and utility classes in the Common library.

Function Documentation

◆ computeKNearestNeighbors()

OSIMCOMMON_API SimTK::Matrix OpenSim::computeKNearestNeighbors ( const SimTK::Matrix &  x,
const SimTK::Matrix &  y,
int  k = 1 
)

Compute the 'k' nearest neighbors of two matrices 'x' and 'y'.

'x' and 'y' should contain the same number of columns, but can have different numbers of rows. The function returns a matrix with 'k' number of columns and the same number of rows as 'y'. Each row in the output matrix contains 'k' distance values, where the first column contains the distance to the nearest neighbor in 'x', the second column contains the distance to the second nearest neighbor in 'x', and so on.

◆ convertRelativeFilePathToAbsoluteFromXMLDocument()

OSIMCOMMON_API std::string OpenSim::convertRelativeFilePathToAbsoluteFromXMLDocument ( const std::string &  documentFileName,
const std::string &  filePathRelativeToDirectoryContainingDocument 
)

An OpenSim XML file may contain file paths that are relative to the directory containing the XML file; use this function to convert that relative path into an absolute path.

◆ createVector()

OSIMCOMMON_API SimTK::Vector OpenSim::createVector ( std::initializer_list< SimTK::Real >  elements)

Create a SimTK::Vector using modern C++ syntax.

◆ createVectorLinspace()

OSIMCOMMON_API SimTK::Vector OpenSim::createVectorLinspace ( int  length,
double  start,
double  end 
)

Create a SimTK::Vector with the provided length whose elements are uniformly spaced between start and end (same as Matlab's linspace()).

◆ getFormattedDateTime()

OSIMCOMMON_API std::string OpenSim::getFormattedDateTime ( bool  appendMicroseconds = false,
std::string  format = "%Y-%m-%dT%H%M%S" 
)

Get a string with the current date and time formatted as Y-m-dTHMS (year, month, day, "T", hour, minute, second).

You can change the datetime format via the format parameter. If you specify "ISO", then we use the ISO 8601 extended datetime format Y-m-dTH:M:S. See https://en.cppreference.com/w/cpp/io/manip/put_time.

Referenced by OpenSim::MocoTropterSolver::TropterProblemBase< T >::TropterProblemBase().

◆ interpolate()

OSIMCOMMON_API SimTK::Vector OpenSim::interpolate ( const SimTK::Vector &  x,
const SimTK::Vector &  y,
const SimTK::Vector &  newX,
const bool  ignoreNaNs = false 
)

Linearly interpolate y(x) at new values of x.

The optional 'ignoreNaNs' argument will ignore any NaN values contained in the input vectors and create the interpolant from the non-NaN values only. Note that this option does not necessarily prevent NaN values from being returned in 'newX', which will have NaN for any values of newX outside of the range of x.

Exceptions
Exceptionif x and y are different sizes, or x or y is empty.

◆ make_unique()

template<typename T , typename... Args>
std::unique_ptr<T> OpenSim::make_unique ( Args &&...  args)

Since OpenSim does not require C++14 (which contains std::make_unique()), here is an implementation of make_unique().

◆ solveBisection()

OSIMCOMMON_API SimTK::Real OpenSim::solveBisection ( std::function< double(const double &)>  calcResidual,
double  left,
double  right,
const double &  tolerance = 1e-6,
int  maxIterations = 1000 
)

Solve for the root of a scalar function using the bisection method.

If the values of calcResidual(left) and calcResidual(right) have the same sign and the logger level is Debug (or more verbose), then this function writes a file solveBisection_residual_<timestamp>.sto containing the residual function.

Parameters
calcResiduala function that computes the error
leftlower bound on the root
rightupper bound on the root
toleranceconvergence requires that the bisection's "left" and "right" are less than tolerance apart.
maxIterationsabort after this many iterations.