Wrap-up task list for the CZI Biomechanics project

[moorepants]

General

• Review whether we should be using objects subclassed from Basic or not

Merge in remaining functionality

• Bugs
  • (Open GitHub issues for these)
  • Missing cos(alpha_opt) in rigid tendon musculotendon dynamics
  • Use FiberForceVelocityInverseDeGroote2016 in fiber state elastic tendon musculotendon dynamics.
• Implemented WrappingPathway in sympy.physics.mechanics #25400
• Implemented ObstacleSetPathway in sympy.physics.mechanics #25424
• mechanics._geometry -> mechanics.geometry (publicizing: Make physics.mechanics.wrapping_geometry public #25510)
• mechanics._pathway -> mechanics.pathway (publicizing: Make physics.mechanics.pathway public. #25511)
• mechanics._actuator -> mechanics.actuator Make _actuator.py public. #25518
• Characteristic curves: https://github.com/brocksam/sympy-biomechanics/blob/main/biomechanics/curve.py
  • Implemented tendon force-length characteristic curve in sympy.physics._biomechanics #25441
    • Check fdiff implementation: confirmed that differentiation with respect to a number still fails as expected.
  • Implemented inverse tendon force-length characteristic curve in sympy.physics._biomechanics #25509
  • Implemented muscle fibre passive force-length characteristic curve in sympy.physics._biomechanics #25516
  • Implemented muscle fibre passive force-length inverse characteristic curve in sympy.physics._biomechanics #25519
  • Implemented muscle fibre active force-length characteristic curve in sympy.physics._biomechanics #25530
  • Implemented muscle fiber force-velocity characteristic curve in sympy.physics._biomechanics #25539
  • Implemented inverse muscle fiber force-velocity characteristic curve in sympy.physics._biomechanics #25742
  • Rename characteristic curve module to sympy.physics._biomechanics.curve #25549
  • Add examples sections to docstrings of characteristic curves in sympy.physics._biomechanics #25743
• Implemented _NamedMixin mixin class for adding error-checked name attribute to classes #25540
• Activation models: https://github.com/brocksam/sympy-biomechanics/blob/main/biomechanics/activation.py
  • Implemented zeroth-order activation dynamics in sympy.physics._biomechanics #25548
  • Implemented first-order activation dynamics in sympy.physics._biomechanics #25553
• Musculotendon models: https://github.com/brocksam/sympy-biomechanics/blob/main/biomechanics/musculotendon.py
  • Implement start of musculotendon model in sympy.physics._biomechanics #25567
• Pathways
  • ExtensorPathway: https://github.com/brocksam/sympy-biomechanics/blob/main/biomechanics/pathway.py
• Remove type hints
  • mechanics.actuator / mechanics.tests.test_actuator
  • mechanics.pathway / mechanics.tests.test_pathway
  • mechanics.wrapping_geometry / mechanics.tests.test_wrapping_geometry
  • biomechanics.curves / biomechanics.tests.test_curves
• Musculotendon dynamics
  • Rigid tendon
  • Fiber length state (undamped elastic tendon)
  • Tendon force state (undamped elastic tendon)
  • Fiber length state (damped elastic tendon)
  • Tendon force state (damped elastic tendon)
• Make sympy.physics.biomechanics public #25772
  • Add release note: physics.biomechanics. Created a new module that acts to extend physics.mechanics with biomechanical modelling functionality.
  • Add release note: physics.biomechanics. Implemented musculotendon characteristic curves for tendon and muscle fiber force-length and force-velocity relationships based on De Groote et al., 2016.
  • Add release note: Implemented classes for modeling activation dynamics, including first-order activation dynamics based on De Groote et al., 2016.
  • Add release note: Implemented class for modeling musculotendons with both rigid and elastic tendon musculotendon dynamics.
• Biomechanical modeling tutorials #25525
• Validate the musculotendon dynamics equations in MusculotendonBase class #25787

Other

• Make System public #25560

To-do requests

These should all be opened as issues if they don't get completely by 31/08/2023.

• Refactor, extend, and bug fix musculotendon classes in sympy.physics._biomechanics #25744
• Add __str__ to biomechanical modeling components.
• Provide way to use set generalized speeds on PathwayBase classes.
• Add support for substitution, perhaps with subs kwargs on to_loads methods.
• Refactor rhs method on MusculotendonDeGroote2016 to return simplified RHS equations.
• Introduce a MusculotendonBase class between ForceActuator and MusculotendonDeGroote2016 as most musculotendon implementation will be generic to any musculotendon.
• Add attributes to MusculotendonDeGroote2016 for linking to the ...DeGroote2016 musculotendon curves, e.g. MusculotendonDeGroote2016.curves.tendon_force_length = TendonForceLengthDeGroote2016 with MusculotendonDeGroote2016.tendon_force_length pointing to the musculotendon dynamics-specific instance.

Unit test coverage

• mechanics.actuator
• mechanics.geometry
• mechanics.pathway
• mechanics.system
• biomechanics.activation
• biomechanics.curve
• biomechanics.musculotendon

Docstrings

• mechanics.actuator
• mechanics.geometry
• mechanics.pathway
• mechanics.system
• biomechanics.activation
• biomechanics.curve
• biomechanics.musculotendon

Create examples in documentation

• Simple particle/point demonstrations of the different muscles with different pathways and wrapping geometries.
• single arm pushing on a lever (simple steerer): https://github.com/brocksam/sympy-biomechanics/blob/main/examples/muscle_driven_steerer.py Biomechanical modeling tutorials #25525

[moorepants]

I just noticed that the state variables in the muscles are not functions of time, they seem to be simple symbols. We rely heavily on differentiating constants from time varying variables in mechanics by using Function('f')(me.dynamicsymbols._t) for all time varying variables.

[moorepants]

I suggest that we get all the stuff into non-public _biomechanics as you have designed, then we use the example in #25525 and some simpler examples that we can add to a "muscle explanation" page based on various particle style models like brocksam/sympy-biomechanics#19 which can show the basic setup and behavior of the muscle actuators. We can then review the code in _biomechanics as we build out and improve those examples. Finally, we make _biomechanics public along with the tutorial pages.

[moorepants]

@brocksam I've completed my parts of the two tutorial pages (I think). Once you add the remaining two parts it should be ready to merge.

I can open a PR for making _biomechanics public, but were all the docstrings and unit tests completed? I wasn't sure the status.

[brocksam]

@brocksam I've completed my parts of the two tutorial pages (I think). Once you add the remaining two parts it should be ready to merge.

I can open a PR for making _biomechanics public, but where all the docstrings and unit tests completed? I wasn't sure the status.

I'll add my remaining two parts to the tutorial pages tomorrow to complete that PR. You're correct that we still need some docstrings and tests. I'll hopefully get the vital ones done tomorrow too and then I'll open the PR to make the module public. I'll also open issue for the remaining "nice to haves".

[brocksam]

I've opened #25744 which will encapsulate the majority of the outstanding things in this list. Following the merging of #25744, we can open a PR to make the biomechanics module public. Then following that we will be able to fix the Sphinx errors related to the "missing" biomechanics module in #25525. That should then complete the biomechanics portion of our CZI work.

[moorepants]

Ok, sounds good. Let me know when you are ready for review or if you need help on it.