[CZI] Addition of biomechanical modelling to SymPy

[brocksam]

CZI EOSS Grant & Biomechanics

One stated outcome from the CZI work is the development of performance-critical musculoskeletal models using SymPy. Creation of musculoskeletal models requires the merging of multibody dynamics and biomechanical models. The former is already implemented supported by SymPy thanks to sympy.physics.mechanics. The latter requires the development of additional SymPy-based classes, functions, and integrations.

Development Proposal

I propose that certain biomechanical modelling capabilities are added directly into SymPy. This would be done through the creation of a new biomechanics submodule. The intention would be for this to be sympy.physics.biomechanics. However, it would initially be developed as the private development submodule sympy.physics._biomechanics. This would allow for the submodule to be developed transparently, with other SymPy users able to contribute and feed back during its development, while also not adding any restrictions around backwards compatibility guarantees or breaking changes.

Eventually, once the submodule features and API have been reviewed and tested, the intention would be to transition sympy.physics._biomechanics to the public module sympy.physics.biomechanics.

Development Workflow

• PR [CZI] Create sympy.physics._biomechanics for symbolic biomechanics #24228 shows the current state of development of the biomechanics submodule and its diff to master
• This work is related to other work on building a high-level API for sympy.physics.mechanics (PR Physics mechanics devel #24234)
• New issues will be opened to initiate discussion around, and gather feedback on, more specific areas
• Announcements will be made on a new discussion on the SymPy mailing list

Submodule Requirements

• Extends and interfaces nicely with sympy.physics.mechanics and sympy.physics.vector.
• Implements published models from the literature.
• Supports torque- and muscle-driven musculoskeletal models.
• Supports creation of 2D and 3D musculoskeletal models.
• Fully documented, tested, and benchmarked.
• Provides a basic set of sample models for users to get started with.

[brocksam]

Features Proposal

• Sample models
  • Bicep curl model - based on the simple bicep curl model in the OpenSim tutorial
  • Tug of War model - based on the simple tug of war model in the OpenSim models collection
  • Five-link biped-walker model - based on "Kelly, M, An introduction to trajectory optimization: How to do your own direct collocation, SIAM Review, 59(4), (2017), pp. 849-904"
  • 2D sit-to-stand model - based on the sit-to-stand OpenSim Moco example
  • 2D pedalling cyclist model - based on "Bobbert, M. F., Casius, L. R., van der Zwaard, S., & Jaspers, R. T., Effect of vasti morphology on peak sprint cycling power of a human musculoskeletal simulation model, Journal of applied physiology, 128(2), (2020), pp. 445-455"
  • 3D pedalling cyclist model - based on "Park, S., Caldwell, G. E., & Umberger, B. R., A direct collocation framework for optimal control simulation of pedaling using OpenSim, Plos one, 17(2), (2022), e0264346"
• Musculotendon models
  • Extend actuator from sympy.physics.mechanics
  • Implement equations of musculotendon dynamics for a model involving an elastic tendon in series with a parallel contractile element, damping element, and elastic element
  • Implement characteristic (force-length and force-velocity) curves from the literature
  • MusculotendonABC - abstract base class for all musculotendon implementations to inherit from
  • Brockie2021Musculotendon - based on "Brockie, S. G., Predictive Simulation of Musculoskeletal Models Using Direct Collocation, PhD Thesis, University of Cambridge, (2021) pp. 234-241"
  • DeGroote2016Musculotendon - based on "De Groote, F., Kinney, A. L., Rao, A. V., & Fregly, B. J., Evaluation of direct collocation optimal control problem formulations for solving the muscle redundancy problem, Annals of biomedical engineering, 44(10), (2016) pp. 2922-2936"
  • Millard2013Musculotendon - based on "Millard, M., Uchida, T., Seth, A., Delp, S. L., Flexing computational muscle: modeling and simulation of musculotendon dynamics. Journal of biomechanical engineering, 135(2), (2013)"
• Activation dynamics models
  • Implement dynamics mapping musculotendon excitation to musculotendon activation
  • ActivationDynamicsABC - abstract base class for all activation dynamics implementations to inherit from
  • ZerothOrderActivationDynamics - (trivial)
  • DeGroote2016ActivationDynamics - based on "De Groote, F., Kinney, A. L., Rao, A. V., & Fregly, B. J., Evaluation of direct collocation optimal control problem formulations for solving the muscle redundancy problem, Annals of biomedical engineering, 44(10), (2016) pp. 2922-2936"
• Musculotendon pathway modelling
  • ViaPoint - (reference TBC)
  • WrappingSurfaceABC - abstract base class for all musculotendon wrapping surface implementations to inherit from
  • CylindricalWrappingSurface - (reference TBC)
  • SphericalWrappingSurface - (reference TBC)

[brocksam]

Related Issues and PRs

• (None yet)

[moorepants]

I discussed this issue with Sam today. This seems like a good approach and getting _biomechanics started with these is a good launching point. Some things to think about are:

• Whether or how we maintain the symbolic-numeric divide (like we've had with mechanics & PyDy) and what should we be doing on the sympy side when the mathematical models increase in complexity and tightly rely on specific floating point parameter values. I don't think I've seen a similar class design in SymPy that stores numerical values for symbolics, so we should evaluate if that's the right direction.
• How will the mathematical expressions be accessible from these classes?
• Sam will show some of the example problems so we can see how these classes will work.
• We also discussed some how these classes relate to code gen and how they connect. Some thought is needed on that.

@brocksam feel free to add other notes you took here. Good that we keep the info public on these issues/PRs.

[ThePauliPrinciple]

• I don't think I've seen a similar class design in SymPy
• How will the mathematical expressions be accessible from these classes?

It could be considered to only add generic mechanics functionality to SymPy and create a seperate library for biomechanics instead of a module inside SymPy.

• tightly rely on specific floating point parameter values

I think in most cases people should use a Rational rather than a Float to accurately represent what they want when they think they want to use Float (at least in SymPy). To obtain float-like behaviour as one might expect in a numerical framework, it's probably best to ensure that the biomechanics classes work with lambdify.

[brocksam]

Closing as #25772 has made sympy.physics.biomechanics public.