diff --git a/OpenSim/Actuators/PolynomialPathFitter.h b/OpenSim/Actuators/PolynomialPathFitter.h index 15307a6eb6..4d287ec34b 100644 --- a/OpenSim/Actuators/PolynomialPathFitter.h +++ b/OpenSim/Actuators/PolynomialPathFitter.h @@ -73,8 +73,7 @@ class OSIMACTUATORS_API PolynomialPathFitterBounds : public Object { * directory to which the results are written can be specified using the * `setOutputDirectory` method. * - * Settings - * -------- + * # Settings * Various settings can be adjusted to control the path fitting process. The * `setMomentArmsThreshold` method determines whether or not a path depends on a * model coordinate. In other words, the absolute value the moment arm of a with @@ -91,10 +90,10 @@ class OSIMACTUATORS_API PolynomialPathFitterBounds : public Object { * lengths computed from the original model paths and the fitted polynomial * paths. The `setNumSamplesPerFrame` method specifies the number of samples * taken per time frame in the coordinate values table used to fit each path. - * The `setParallel` method specifies the number of threads used to parallelize - * the path fitting process. The `setLatinHypercubeAlgorithm` method specifies - * the Latin hypercube sampling algorithm used to sample coordinate values for - * path fitting. + * The `setNumParallelThreads` method specifies the number of threads used to + * parallelize the path fitting process. The `setLatinHypercubeAlgorithm` method + * specifies the Latin hypercube sampling algorithm used to sample coordinate + * values for path fitting. * * The default settings are as follows: * @@ -113,8 +112,7 @@ class OSIMACTUATORS_API PolynomialPathFitterBounds : public Object { * models with larger or smaller anatomical measures (e.g., dinosaur * models). * - * Usage - * ----- + * # Usage * The most basic usage of `PolynomialPathFitter` requires the user to provide * a model and reference trajectory. The model should contain at least one path * object derived from `AbstractGeometryPath` and should not contain any @@ -145,8 +143,7 @@ class OSIMACTUATORS_API PolynomialPathFitterBounds : public Object { * fitter.run(); * @endcode * - * Recommendations - * --------------- + * # Recommendations * Information from each step of the path fitting process is logged to the * console, provided that you have set the OpenSim::Logger to level "info" or * greater. Warnings are printed if the number of samples is likely insufficient @@ -408,7 +405,7 @@ class OSIMACTUATORS_API PolynomialPathFitter : public Object { * of available hardware threads. */ void setNumParallelThreads(int numThreads); - /// @copydoc setParallel() + /// @copydoc setNumParallelThreads(int numThreads) int getNumParallelThreads() const; /** diff --git a/OpenSim/Common/LatinHypercubeDesign.h b/OpenSim/Common/LatinHypercubeDesign.h index 77606e1be8..108a524a29 100644 --- a/OpenSim/Common/LatinHypercubeDesign.h +++ b/OpenSim/Common/LatinHypercubeDesign.h @@ -30,28 +30,33 @@ namespace OpenSim { /** * A class for generating Latin hypercube designs. + * + * # Latin hypercube design * * A Latin hypercube is an m-by-n matrix, where 'm' is the number of design * samples and 'n' is the number of variables in the design. Each sample point * (i.e., each row in the design) is the only sample point in its row and column * in the hypercube defined by the number of variables. - * + * + * \cond * For example, consider a design with 5 samples and 2 variables: * - * grid matrix - * __ __ __ __ __ __ __ - * | x | | 0.6 0.2 | - * | x | | 1.0 0.4 | - * q2 | x | q = | 0.2 0.6 | - * | x | | 0.8 0.8 | - * | x | | 0.4 1.0 | - * ‾‾ ‾‾ ‾‾ ‾‾ ‾‾ ‾‾ ‾‾ + * grid matrix + * __ __ __ __ __ __ __ + * | x | | 0.6 0.2 | + * | x | | 1.0 0.4 | + * q2 | x | q = | 0.2 0.6 | + * | x | | 0.8 0.8 | + * | x | | 0.4 1.0 | + * ‾‾ ‾‾ ‾‾ ‾‾ ‾‾ ‾‾ ‾‾ * q1 - * + * * On the left is the 5-by-5 square grid (i.e., 2-D hypercube) that is produced * if the samples are plotted in the variable space defined by q1 and q2. On the * right is the 5-by-2 design matrix that contains the 5 samples. - * + * \endcond + * + * * Latin hypercube designs are useful for sampling large, multivariate parameter * spaces. Optimal Latin hypercube designs are those that maximize the minimum * distance between samples in the design. This class provides methods for @@ -60,8 +65,7 @@ namespace OpenSim { * algorithm from Viana et al. (2009) and the enhanced stochastic evolutionary * algorithm from Jin et al. (2005). * - * How to create a Latin hypercube design - * -------------------------------------- + * # How to create a Latin hypercube design * To create a Latin hypercube design, you must first specify the number of * variables and samples in the design, and, optionally, the distance criterion * used to evaluate each design. The distance criterion can be either "maximin" @@ -103,8 +107,7 @@ namespace OpenSim { * minimization criterion. While both criteria aim to achieve a similar goal, * the values returned by each are not directly comparable. * - * Recommendations for different sized designs - * ------------------------------------------- + * # Recommendations for different sized designs * To rapidly create a random Latin hypercube design of any size, * generateRandomDesign() is recommended. This method is fast, but does not * guarantee that the design is optimal. @@ -124,8 +127,7 @@ namespace OpenSim { * it is recommended to use the "phi_p" distance criterion, which approximates * "maximin", but is much faster. * - * References - * ---------- + * # References * - [1] Viana, F.A.C., Venter, G. and Balabanov, V. (2010), An algorithm for * fast optimal Latin hypercube design of experiments. Int. J. Numer. Meth. * Engng., 82: 135-156. https://doi.org/10.1002/nme.2750 diff --git a/OpenSim/Common/Object.h b/OpenSim/Common/Object.h index c3605a0fdd..1ab921c522 100644 --- a/OpenSim/Common/Object.h +++ b/OpenSim/Common/Object.h @@ -341,7 +341,9 @@ class OSIMCOMMON_API Object used by the Property declaration macros for fast access to properties. **/ template const Property& getProperty(const PropertyIndex& index) const; - /** @copydoc getProperty(const PropertyIndex&) **/ + /** Get property of known type Property\ as a const reference; + the property must be present and have the right type. This is primarily + used by the Property declaration macros for fast access to properties. **/ template const Property& getPropertyByName(const std::string& name) const; diff --git a/OpenSim/Moco/MocoGoal/MocoOrientationTrackingGoal.h b/OpenSim/Moco/MocoGoal/MocoOrientationTrackingGoal.h index 2ab0c5e2bf..8754977523 100644 --- a/OpenSim/Moco/MocoGoal/MocoOrientationTrackingGoal.h +++ b/OpenSim/Moco/MocoGoal/MocoOrientationTrackingGoal.h @@ -86,7 +86,7 @@ class OSIMMOCO_API MocoOrientationTrackingGoal : public MocoGoal { set_rotation_reference_file(""); m_rotation_table = ref; } - /** @copydoc setRotationReference(const TimeSeriesTable_& ref) */ + /** @copydoc setRotationReference(const TimeSeriesTable_>& ref) */ void setRotationReference(const TimeSeriesTable_>& ref) { set_states_reference(TableProcessor()); set_rotation_reference_file(""); diff --git a/OpenSim/Moco/MocoGoal/MocoOutputGoal.h b/OpenSim/Moco/MocoGoal/MocoOutputGoal.h index b5f6334850..670afeb51d 100644 --- a/OpenSim/Moco/MocoGoal/MocoOutputGoal.h +++ b/OpenSim/Moco/MocoGoal/MocoOutputGoal.h @@ -190,7 +190,7 @@ The goal is computed as follows: \f[ \frac{1}{dm} \int_{t_i}^{t_f} - w_v\beta((\frac{1}{s} (\ln (1 + \exp (s\betav))))^p) ~dt + w_v \beta((\frac{1}{s} (\ln (1 + \exp (s \beta v))))^p) ~dt \f] We use the following notation: - \f$ d \f$: displacement of the system, if `divide_by_displacement` is @@ -199,8 +199,8 @@ We use the following notation: true; 1 otherwise. - \f$ v \f$: the output variable of choice. - \f$ w_v \f$: the weight for output variable \f$ v \f$. -- \f$ \beta \f$: the approximate extremum to be taken (\beta == -1 for - minimum; \beta == 1 for maximum). +- \f$ \beta \f$: the approximate extremum to be taken (\f$ \beta \f$ == -1 for + minimum; \f$ \beta \f$ == 1 for maximum). - \f$ s \f$: the smoothing factor for approximating the extremum. With \f$ s \f$ == 1 the approximation is closer to the true extremum taken. For \f$ v \f$ with potentially large magnitudes (> 2000) during a simulation diff --git a/OpenSim/Moco/MocoUtilities.h b/OpenSim/Moco/MocoUtilities.h index 712cdc1d7e..80fc78d96d 100644 --- a/OpenSim/Moco/MocoUtilities.h +++ b/OpenSim/Moco/MocoUtilities.h @@ -245,20 +245,20 @@ class FileDeletionThrower { /// In general, this utility needs getRecordValues() to report the /// following force and torque information at the specified indices: /// -/// index - component (body) -/// ------------------------ -/// 0 - force-x (foot) -/// 1 - force-y (foot) -/// 2 - force-z (foot) -/// 3 - torque-x (foot) -/// 4 - torque-y (foot) -/// 5 - torque-z (foot) -/// 6 - force-x (contact plane) -/// 7 - force-y (contact plane) -/// 8 - force-z (contact plane) -/// 9 - torque-x (contact plane) -/// 10 - torque-y (contact plane) -/// 11 - torque-z (contact plane) +/// index | component (body) +/// ----- | ---------------- +/// 0 | force-x (foot) +/// 1 | force-y (foot) +/// 2 | force-z (foot) +/// 3 | torque-x (foot) +/// 4 | torque-y (foot) +/// 5 | torque-z (foot) +/// 6 | force-x (contact plane) +/// 7 | force-y (contact plane) +/// 8 | force-z (contact plane) +/// 9 | torque-x (contact plane) +/// 10 | torque-y (contact plane) +/// 11 | torque-z (contact plane) /// /// @ingroup mocoutil OSIMMOCO_API diff --git a/OpenSim/Simulation/Model/FunctionBasedPath.h b/OpenSim/Simulation/Model/FunctionBasedPath.h index e81efb5043..6dddf389b0 100644 --- a/OpenSim/Simulation/Model/FunctionBasedPath.h +++ b/OpenSim/Simulation/Model/FunctionBasedPath.h @@ -94,8 +94,7 @@ namespace OpenSim { * the tension in the path by the moment arms. Therefore, this class only * applies mobility (i.e., generalized) forces to the model. * - * References - * ---------- + * # References * - [1] Meyer AJ, Patten C, Fregly BJ (2017) "Lower extremity EMG-driven * modeling of walking with automated adjustment of musculoskeletal * geometry." PLoS ONE 12(7): e0179698. diff --git a/OpenSim/Simulation/TableProcessor.h b/OpenSim/Simulation/TableProcessor.h index 9947fd2897..847f61bf24 100644 --- a/OpenSim/Simulation/TableProcessor.h +++ b/OpenSim/Simulation/TableProcessor.h @@ -228,7 +228,7 @@ class OSIMSIMULATION_API TabOpUseAbsoluteStateNames : public TableOperator { } }; -/// Invoke SimulationUtilities::appendCoupledCoordinateValues() on the table. +/** Invoke SimulationUtilities::appendCoupledCoordinateValues() on the table. */ class OSIMSIMULATION_API TabOpAppendCoupledCoordinateValues : public TableOperator { OpenSim_DECLARE_CONCRETE_OBJECT(TabOpAppendCoupledCoordinateValues, @@ -256,8 +256,8 @@ class OSIMSIMULATION_API TabOpAppendCoupledCoordinateValues } }; -/// Invoke SimulationUtilities::appendCoordinateValueDerivativesAsSpeeds() on -/// the table. +/** Invoke SimulationUtilities::appendCoordinateValueDerivativesAsSpeeds() on +the table */ class OSIMSIMULATION_API TabOpAppendCoordinateValueDerivativesAsSpeeds : public TableOperator { OpenSim_DECLARE_CONCRETE_OBJECT( diff --git a/doc/Moco/MocoExamples.dox b/doc/Moco/MocoExamples.dox index 8af4e266b9..54d44a7a36 100644 --- a/doc/Moco/MocoExamples.dox +++ b/doc/Moco/MocoExamples.dox @@ -47,8 +47,6 @@ EMG-driven simulation of walking. @example exampleMinimizeJointReaction.m This is an example of MocoJointReactionGoal. - - @example exampleOptimizeMass.m A simple parameter optimization example. @@ -63,6 +61,9 @@ This is Moco's simplest example. This example conducts a 2-D prediction of walking, employing a MocoPerodicityGoal. +@example examplePolynomialPathFitter.m +This example demonstrates how to use PolynomialPathFitter to +create a set of FunctionBasedPaths for a model. @example exampleMocoTrack.py @@ -124,6 +125,10 @@ MocoSolution. This example demonstrates how Moco solves problems with kinematic constraints and includes a visualization of the Lagrange multipliers that Moco solves for. +@example examplePolynomialPathFitter.py +This example demonstrates how to use PolynomialPathFitter to +create a set of FunctionBasedPaths for a model. + @example example2DWalking.cpp @@ -211,6 +216,7 @@ IMUTracking | torque-driven single leg | MocoStudy motion prediction, MocoAccele EMGTracking | lower-limb | MocoInverse, MocoControlTrackingGoal | [MATLAB](@ref exampleEMGTracking_answers.m) [Python](@ref exampleEMGTracking_answers.py) PredictAndTrack | double pendulum | MocoMarkerFinalGoal, MocoFinalTimeGoal, MocoMarkerTrackingGoal, MocoStateTrackingGoal | [Python](@ref examplePredictAndTrack.py) PrototypeCustomGoal | N/A | Sandbox for defining a custom MocoGoal | [MATLAB](@ref examplePrototypeCustomGoal.m) +PolynomialPathFitter | N/A | Fit FunctionBasedPath%s to a model | [MATLAB](@ref examplePolynomialPathFitter.m) [Python](@ref examplePolynomialPathFitter.py) @section Advanced diff --git a/doc/doxyfile_shared.in b/doc/doxyfile_shared.in index 7f0b0b30e7..fe693acdc5 100644 --- a/doc/doxyfile_shared.in +++ b/doc/doxyfile_shared.in @@ -965,7 +965,9 @@ EXCLUDE_SYMBOLS = EXAMPLE_PATH = "@PROJECT_SOURCE_DIR@/OpenSim/Tests/README/testREADME.cpp" \ "@PROJECT_SOURCE_DIR@/Bindings/Java/Matlab/examples/Moco" \ + "@PROJECT_SOURCE_DIR@/Bindings/Java/Matlab/examples/PolynomialPathFitter" \ "@PROJECT_SOURCE_DIR@/Bindings/Python/examples/Moco" \ + "@PROJECT_SOURCE_DIR@/Bindings/Python/examples/PolynomialPathFitter" \ "@PROJECT_SOURCE_DIR@/OpenSim/Examples/Moco" # If the value of the EXAMPLE_PATH tag contains directories, you can use the