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

• [x] Bugs
  • [x] (Open GitHub issues for these)
  • [x] Missing cos(alpha_opt) in rigid tendon musculotendon dynamics
  • [x] Use FiberForceVelocityInverseDeGroote2016 in fiber state elastic tendon musculotendon dynamics.
• [x] https://github.com/sympy/sympy/pull/25400
• [x] https://github.com/sympy/sympy/pull/25424
• [x] mechanics._geometry -> mechanics.geometry (publicizing: #25510)
• [x] mechanics._pathway -> mechanics.pathway (publicizing: https://github.com/sympy/sympy/pull/25511)
• [x] mechanics._actuator -> mechanics.actuator https://github.com/sympy/sympy/pull/25518
• [x] Characteristic curves: https://github.com/brocksam/sympy-biomechanics/blob/main/biomechanics/curve.py
  • [x] https://github.com/sympy/sympy/pull/25441
  • [x] Check fdiff implementation: confirmed that differentiation with respect to a number still fails as expected.
  • [x] https://github.com/sympy/sympy/pull/25509
  • [x] https://github.com/sympy/sympy/pull/25516
  • [x] https://github.com/sympy/sympy/pull/25519
  • [x] https://github.com/sympy/sympy/pull/25530
  • [x] https://github.com/sympy/sympy/pull/25539
  • [x] https://github.com/sympy/sympy/pull/25742
  • [x] https://github.com/sympy/sympy/pull/25549
  • [x] https://github.com/sympy/sympy/pull/25743
• [x] https://github.com/sympy/sympy/pull/25540
• [x] Activation models: https://github.com/brocksam/sympy-biomechanics/blob/main/biomechanics/activation.py
  • [x] https://github.com/sympy/sympy/pull/25548
  • [x] https://github.com/sympy/sympy/pull/25553
• [x] Musculotendon models: https://github.com/brocksam/sympy-biomechanics/blob/main/biomechanics/musculotendon.py
  • [x] https://github.com/sympy/sympy/pull/25567
• [x] Pathways
  • [x] ExtensorPathway: https://github.com/brocksam/sympy-biomechanics/blob/main/biomechanics/pathway.py
• [x] Remove type hints
  • [x] mechanics.actuator / mechanics.tests.test_actuator
  • [x] mechanics.pathway / mechanics.tests.test_pathway
  • [x] mechanics.wrapping_geometry / mechanics.tests.test_wrapping_geometry
  • [x] biomechanics.curves / biomechanics.tests.test_curves
• [ ] Musculotendon dynamics
  • [x] Rigid tendon
  • [x] Fiber length state (undamped elastic tendon)
  • [x] Tendon force state (undamped elastic tendon)
  • [ ] Fiber length state (damped elastic tendon)
  • [ ] Tendon force state (damped elastic tendon)
• [x] https://github.com/sympy/sympy/pull/25772
  • [x] Add release note: physics.biomechanics. Created a new module that acts to extend physics.mechanics with biomechanical modelling functionality.
  • [x] 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.
  • [x] Add release note: Implemented classes for modeling activation dynamics, including first-order activation dynamics based on De Groote et al., 2016.
  • [x] Add release note: Implemented class for modeling musculotendons with both rigid and elastic tendon musculotendon dynamics.
• [x] https://github.com/sympy/sympy/pull/25525
• [ ] https://github.com/sympy/sympy/issues/25787

Other

• [x] https://github.com/sympy/sympy/pull/25560

To-do requests

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

• [x] https://github.com/sympy/sympy/pull/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.
• [x] Refactor rhs method on MusculotendonDeGroote2016 to return simplified RHS equations.
• [x] Introduce a MusculotendonBase class between ForceActuator and MusculotendonDeGroote2016 as most musculotendon implementation will be generic to any musculotendon.
• [x] 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

• [x] mechanics.actuator
• [x] mechanics.geometry
• [x] mechanics.pathway
• [x] mechanics.system
• [x] biomechanics.activation
• [x] biomechanics.curve
• [x] biomechanics.musculotendon

Docstrings

• [x] mechanics.actuator
• [x] mechanics.geometry
• [x] mechanics.pathway
• [x] mechanics.system
• [x] biomechanics.activation
• [x] biomechanics.curve
• [x] biomechanics.musculotendon

Create examples in documentation

• [x] Simple particle/point demonstrations of the different muscles with different pathways and wrapping geometries.
• [x] single arm pushing on a lever (simple steerer): https://github.com/brocksam/sympy-biomechanics/blob/main/examples/muscle_driven_steerer.py https://github.com/sympy/sympy/pull/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 https://github.com/brocksam/sympy-biomechanics/pull/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 https://github.com/sympy/sympy/pull/25744 which will encapsulate the majority of the outstanding things in this list. Following the merging of https://github.com/sympy/sympy/pull/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 https://github.com/sympy/sympy/pull/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.