WISCO_Ligament implementation

[clnsmith]

Hi all,

After a long delay... I have the ligament model working and ready for input. Still needs some cleanup.

https://github.com/clnsmith/wisco_opensim/blob/master/plugin/WISCO_Ligament.cpp
https://github.com/clnsmith/wisco_opensim/blob/master/plugin/WISCO_Ligament.h

A lot of the comments in those files are from the previous OpenSim 3.3 version and need updating.

Here is a document with a general overview of the ligament model (again implementation details need updating):
https://github.com/clnsmith/wisco_opensim/blob/master/documentation/UWLigamentUserGuide.pdf

There are two main parameters that must be selected for each ligament strand: Linear Stiffness and slack length. Linear stiffness is pretty straight forward (currently must be defined in N/strain, would be nice to add an option for N/mm).

There are three ways that would be useful to be able to define slack length:

slack_length: input the actual slack length of the ligament

reference_strain: input the strain in the ligament when the model is posed at the default coordinates (this is nice for scaling because it remains constant and then a new slack length can be computed for the scaled geometries). This is what we currently use for nearly everything, common in multibody knee model literature.

reference_force: input the force in the ligament when the model is posed at the default coordinates. This is nice for surgical simulations (ACL reconstruction etc) where pretension (ligament force at a certain flexion angle) is something the surgeon sets.

These options are implemented as optional properties: "slack_length", "reference_force", and "reference_strain". Another property "defining_slack_length_property" determines which one of the three options are used by the model. There is also a method "equilibriateSlackLengthProperties(state)" that will compute the other two options from the defining_slack_length_property.

I have written some simple tests for the ligament here:
https://github.com/clnsmith/wisco_opensim/tree/master/tests/testWISCOLigament

Currently it tests for the force at multiple strains/strain rates and checks that energy is conserved in a simple block hanging from a ligament simulation.

Aside from cleanup, the last major thing I can think of to implement is scaling. Right now it just has whatever scaling methods were in the OpenSim Ligament class that I started from.

[aseth1]

Thanks @clnsmith for sharing your code with us. This is a very nice alternative to the current Ligament class. Having different ways of initializing the stiffness and rest length parameters seems particularly helpful and less error prone for users. We are happy to give you feedback on your ligament as a plugin, but I would strongly encourage you to work with us to get your class into OpenSim code base.

We really really want outside groups to make contributions to OpenSim core and I cannot think of a better example than the ligament, where yours already performs well and has nice options for initializing and scaling. It would be awesome for you and your group to own code that is in OpenSim.

If you are interested or just want to see how the process might go, start by making an issue that describes the need for the new ligament. Then make a PR into opensim-core master adding a new WISCOLigament class (after your cleanup) in response to that issue.

After being reviewed and merged, we could leave it at that or continue to make WISCOLigament the Ligament and deprecate the existing class. I would love to see that happen.

[aseth1]

Just to clarify, we do think there is a need for a replacement (e.g. #240) and it would be good to document the issues you wanted to overcome by implementing your class, before getting started. It doesn't have to be long at all.

[chrisdembia]

I agree with @aseth1 (except about replacing the existing ligament :) ). In case you haven't already seen it, make sure to check out the CONTRIBUTING.md file in this repo.

EDIT: I'm fine with deprecating the existing Ligament. I meant that I think it should remain in the code base somewhere.

[clnsmith]

Totally agree on moving it into opensim-core. I'll work on putting together the PR.