BEST PRACTICES AND TROUBLESHOOTING TIPS FOR OPENSIM
By: Samuel Hamner, Ajay Seth, Matt DeMers, Jennifer Hicks
This page is meant to give you some best practices and troubleshooting tips when using the standard workflow tools in OpenSim (i.e., scale, inverse kinematics, inverse dyanmics, static optimization, reduced residual algorithm, and computed muscle control).
- Take pictures of your subjects when collecting data in the static pose.
- Calculate functional joint centers by having your subjects perform movements at the hip, knee, ankle, and/or shoulders.
- Measure subject specifics, like height, mass, body segment lengths, mass distribution (if DXA is available), and strength (if a Biodex is available).
- Only use reliable markers that match anatomical/bony landmarks and function joint centers to position and scale the model. Do not use all of the markers from motion-capture. Use the marker position errors of anatomical markers to assess the quality of your scaling results.
- Some segments, like the pelvis are best scaled non-uniformly.
- In general, maximum marker errors for bony landmarks should be less than 2 cm.
- Use what you know about your subject’s static pose when looking at the results of Scale. For example, the ankle angle should generally be less than 5º and the hip flexion angle should be less than 10º.
- Use the “preview static pose” option in the GUI to visualize the scaled model’s anatomical marker positions relative to the experimental counterparts to see how well the model “fits” the data before adjusting all the markers to match the experimental data.
INVERSE KINEMATICS (IK)
- When collecting experimental data, place three non-collinear markers per body segment that you want to track.
- Place markers on anatomical locations with minimum skin/muscle motion.
- Weight “motion” segment markers (from a triad, for example) more heavily than anatomical markers affixed to landmarks like the greater trochanter and the acromion, which can be helpful for scaling, but are influenced by muscle and other soft tissue movements during motion.
- Relative marker weightings are more important than their absolute values. For example, a weighting of 10 vs. 1 is 10 times more important whereas 20 vs. 10 is only twice as important. Markers are not tracked better because they both have higher weightings.
- Total RMS and max marker errors are reported in the messages window. Use these values to guide changes in weightings, or if necessary to redo marker placement and possibly scaling. Maximum marker error should generally be less than 2cm and RMS under 1cm is achievable.
- Compare your results to similar data reported in the literature. Your results from an unimpaired average adult should generally be within one standard deviation.
- If possible, compare your results to data reported in the literature. Your results should be within one standard deviation (sd) of reported values.
- Filter your raw coordinate data, since noise is amplified by differentiation. Without filtering, the calculated forces and torques will be very noisy.
- Check the residual forces and moments (i.e., pelvis_tx, pelvis_ty, pelvis_tz, pelvis_tilt, pelvis_list, pelvis_rotation) in the results file from Inverse Dynamics to see if values are reasonable. If not, external loads (i.e., ground reaction forces) may not be applied correctly. To double check forces are being applied properly, visualize GRFs with IK data (you can either use the IK tool or preview motion data).
- If possible, compare your results to data reported in the literature. Your results should be within one sd of reported values.
You can use IK or RRA results as input kinematics. If using IK results, you usually need to filter them, either externally or using the OpenSim analyze/static optimization field. If using RRA results, you usually do not have to filter.
- Add residual actuators to the first free joint in the model (typically the ground-pelvis joint).
- If the actuators/muscles are weak, the optimization will take a long time to converge or never converge at all. This takes a long time. If troubleshooting a weak model and each time, optimization is slow, try reducing the parameter that defines the max number of iterations.
- Increase the maximum control value of a residual or reserve actuator, while lowering its maximum force. This allows the optimizer to generate a large force (if necessary) to match accelerations but large control values are penalized more heavily. In static optimization, ideal actuator excitations are treated as activations in the cost function.
- Check the Messages window. Large values (either positive or negative) reported for "Performance" and "Constraint Violation" means the Static Optimization tool is struggling to find a good solution.
RESIDUAL REDUCTION ALGORITHM (RRA)
- RMS difference in joint angle between the input IK and output RRA movement should be less than 2-5º (or less than 2 cm for translations). Check the file with the appended ending "_pErr.sto" for the difference (or error) for each degree of freedom in the model.
- Peak Residual Forces should be less than 10-20 N.
- Compare the residual moments from RRA to the moments from ID. You should see a 30-50% reduction in peak residual moments.
- Compare the joint torques/forces to established literature (if available). Try to find data with multiple subjects. Your results should be within one s.d. of the literature.
- Optimal forces for residuals should be low to prevent optimizer for "wanting" to use residual actuators (an actuator with large optimal force and low excitation is "cheap" in the optimizer cost).
- To help minimize residuals, make an initial pass with default inputs, then check residuals and coordinate errors. To reduce residuals further, decrease tracking weights on coordinates with low error. You can also try decreasing the maximum excitation on residuals or the actuator optimal force.
- If RRA is failing, try increasing the max excitation for residuals by 10x until the simulation runs. Then try working your way back down while also "relaxing" tracking weights on coordinates.
- If reserves are very large (typically, this is greater than 2-3x BW, depending on the motion), there is probably something wrong with either (i) the scaled model, (ii) the IK solution, or (iii) the applied GRFs. To double check forces are being applied properly, visualize GRFs with IK data (you can either use the IK tool or preview motion data).
COMPUTED MUSCLE CONTROL (CMC)
- Compare the activations to EMG data (either recorded from your subject or from the literature). Activations should exhibit similar timing and magnitude to your EMG data.
- In general, for a "good" simulation, peak reserve actuators torques should typically be less than 10-20% of the peak joint torque.
- In general, if performing Perturbation or Induced Acceleration Analysis, you should verify that reserves and residuals contribute less than 1-5% to the net acceleration of interest.
- Compare your results (muscle activations or forces) to other simulations, if available.
- To help minimize reserve torques, make an initial pass with default inputs, then check reserves, residuals, and joint angle errors. To reduce reserves further, decrease tracking weights on coordinates with low error.
- Optimal forces for reserves should be low to prevent optimizer from "wanting" to use reserve actuators (an actuator with large optimal force and low excitation is "cheap" in the optimizer cost). Increase the maximum control value of residuals so they can generate sufficient force, but are penalized for doing so.
- If CMC is failing, try increasing the max excitation for reserves and residuals by 10x until the simulation runs. Then try working your way back down while also "relaxing" tracking weights on coordinates.