Make sympy.physics.biomechanics public

[brocksam]

References to other Issues or PRs

Makes public the majority of the CZI biomechanics work program described in #24240. Addresses many of the outstanding pieces noted in #25508.

Brief description of what is fixed or changed

This PR makes public the new biomechanics module in sympy.physics.

Other comments

• Requires merging of Refactor, extend, and bug fix musculotendon classes in sympy.physics._biomechanics #25744.

Release Notes

• physics.biomechanics
  • Created a new module that acts to extend physics.mechanics with biomechanical modelling functionality.
  • Implemented musculotendon characteristic curves for tendon and muscle fiber force-length and force-velocity relationships based on De Groote et al., 2016.
  • Implemented classes for modeling activation dynamics, including first-order activation dynamics based on De Groote et al., 2016.
  • Implemented classes for modeling musculotendons with both rigid and elastic tendon musculotendon dynamics.

[sympy-bot]

✅

Hi, I am the SymPy bot. I'm here to help you write a release notes entry. Please read the guide on how to write release notes.

Your release notes are in good order.

Here is what the release notes will look like:

• physics.biomechanics

  • Created a new module that acts to extend physics.mechanics with biomechanical modelling functionality. (#25772 by @brocksam)

  • Implemented musculotendon characteristic curves for tendon and muscle fiber force-length and force-velocity relationships based on De Groote et al., 2016. (#25772 by @brocksam)

  • Implemented classes for modeling activation dynamics, including first-order activation dynamics based on De Groote et al., 2016. (#25772 by @brocksam)

  • Implemented classes for modeling musculotendons with both rigid and elastic tendon musculotendon dynamics. (#25772 by @brocksam)

This will be added to https://github.com/sympy/sympy/wiki/Release-Notes-for-1.13.

Click here to see the pull request description that was parsed.

<!-- Your title above should be a short description of what
was changed. Do not include the issue number in the title. -->

#### References to other Issues or PRs
<!-- If this pull request fixes an issue, write "Fixes #NNNN" in that exact
format, e.g. "Fixes #1234" (see
https://tinyurl.com/auto-closing for more information). Also, please
write a comment on that issue linking back to this pull request once it is
open. -->
Makes public the majority of the CZI biomechanics work program described in https://github.com/sympy/sympy/issues/24240. Addresses many of the outstanding pieces noted in https://github.com/sympy/sympy/issues/25508.

#### Brief description of what is fixed or changed
This PR makes public the new `biomechanics` module in `sympy.physics`.

#### Other comments
- [x] Requires merging of #25744.

#### Release Notes

<!-- Write the release notes for this release below between the BEGIN and END
statements. The basic format is a bulleted list with the name of the subpackage
and the release note for this PR. For example:

* solvers
  * Added a new solver for logarithmic equations.

* functions
  * Fixed a bug with log of integers. Formerly, `log(-x)` incorrectly gave `-log(x)`.

* physics.units
  * Corrected a semantical error in the conversion between volt and statvolt which
    reported the volt as being larger than the statvolt.

or if no release note(s) should be included use:

NO ENTRY

See https://github.com/sympy/sympy/wiki/Writing-Release-Notes for more
information on how to write release notes. The bot will check your release
notes automatically to see if they are formatted correctly. -->

<!-- BEGIN RELEASE NOTES -->
* physics.biomechanics
  * Created a new module that acts to extend physics.mechanics with biomechanical modelling functionality.
  * Implemented musculotendon characteristic curves for tendon and muscle fiber force-length and force-velocity relationships based on De Groote et al., 2016.
  * Implemented classes for modeling activation dynamics, including first-order activation dynamics based on De Groote et al., 2016.
  * Implemented classes for modeling musculotendons with both rigid and elastic tendon musculotendon dynamics.
<!-- END RELEASE NOTES -->

Update

The release notes on the wiki have been updated.

[brocksam]

A lot of the doctest output in the MusculotendonDeGroote2016 class contains long expected lines. I've tried line wrapping these and inserting ellipses and neither approach works reliably. I'm seeing pretty unexplainable doctest failures using both SymPy's runner but also with pytest-doctestplus for both of these approaches to keeping the file width within ~80 chars. I've left the lines unwrapped as I'm not sure how else to approach and get CI to pass.

[sympy-bot]

🟠

Hi, I am the SymPy bot. I've noticed that some of your commits add or delete files. Since this is sometimes done unintentionally, I wanted to alert you about it.

This is an experimental feature of SymPy Bot. If you have any feedback on it, please comment at sympy/sympy-bot#75.

The following commits add new files:

• c1ad16f:
  • doc/src/modules/physics/biomechanics/api/activation.rst
  • doc/src/modules/physics/biomechanics/api/curve.rst
  • doc/src/modules/physics/biomechanics/api/index.rst
  • doc/src/modules/physics/biomechanics/api/musculotendon.rst
  • doc/src/modules/physics/biomechanics/index.rst

If these files were added/deleted on purpose, you can ignore this message.

[github-actions]

Benchmark results from GitHub Actions

Lower numbers are good, higher numbers are bad. A ratio less than 1
means a speed up and greater than 1 means a slowdown. Green lines
beginning with + are slowdowns (the PR is slower then master or
master is slower than the previous release). Red lines beginning
with - are speedups.

Significantly changed benchmark results (PR vs master)

Significantly changed benchmark results (master vs previous release)

| Change   | Before [8059df73] <sympy-1.12^0>   | After [5cc71ab2]    |   Ratio | Benchmark (Parameter)                                                |
|----------|------------------------------------|---------------------|---------|----------------------------------------------------------------------|
| -        | 103±3ms                            | 69.0±1ms            |    0.67 | integrate.TimeIntegrationRisch02.time_doit_risch(10)                 |
| +        | 25.6±0.2μs                         | 41.0±0.2μs          |    1.6  | integrate.TimeIntegrationRisch03.time_doit(1)                        |
| -        | 8.23±0.01ms                        | 4.52±0.01ms         |    0.55 | logic.LogicSuite.time_load_file                                      |
| -        | 2.45±0ms                           | 785±2μs             |    0.32 | polys.TimePREM_LinearDenseQuadraticGCD.time_op(3, 'sparse')          |
| -        | 12.0±0.02ms                        | 2.35±0ms            |    0.2  | polys.TimePREM_LinearDenseQuadraticGCD.time_op(5, 'sparse')          |
| -        | 436±0.8μs                          | 98.8±2μs            |    0.23 | polys.TimePREM_QuadraticNonMonicGCD.time_op(1, 'sparse')             |
| -        | 5.60±0.02ms                        | 436±1μs             |    0.08 | polys.TimePREM_QuadraticNonMonicGCD.time_op(3, 'sparse')             |
| -        | 12.2±0.04ms                        | 1.31±0ms            |    0.11 | polys.TimePREM_QuadraticNonMonicGCD.time_op(5, 'sparse')             |
| -        | 7.37±0.02ms                        | 4.73±0.01ms         |    0.64 | polys.TimeSUBRESULTANTS_LinearDenseQuadraticGCD.time_op(2, 'sparse') |
| -        | 31.8±0.04ms                        | 14.4±0.02ms         |    0.45 | polys.TimeSUBRESULTANTS_LinearDenseQuadraticGCD.time_op(3, 'sparse') |
| -        | 8.74±0.09ms                        | 1.40±0ms            |    0.16 | polys.TimeSUBRESULTANTS_QuadraticNonMonicGCD.time_op(1, 'sparse')    |
| -        | 19.3±0.05ms                        | 11.0±0.01ms         |    0.57 | polys.TimeSUBRESULTANTS_QuadraticNonMonicGCD.time_op(2, 'sparse')    |
| -        | 245±0.4ms                          | 84.4±0.1ms          |    0.34 | polys.TimeSUBRESULTANTS_QuadraticNonMonicGCD.time_op(3, 'sparse')    |
| -        | 7.35±0.01ms                        | 647±8μs             |    0.09 | polys.TimeSUBRESULTANTS_SparseGCDHighDegree.time_op(3, 'sparse')     |
| -        | 31.8±0.04ms                        | 1.02±0ms            |    0.03 | polys.TimeSUBRESULTANTS_SparseGCDHighDegree.time_op(5, 'sparse')     |
| -        | 718±3μs                            | 241±10μs            |    0.34 | polys.TimeSUBRESULTANTS_SparseNonMonicQuadratic.time_op(1, 'sparse') |
| -        | 7.55±0.1ms                         | 249±30μs            |    0.03 | polys.TimeSUBRESULTANTS_SparseNonMonicQuadratic.time_op(3, 'sparse') |
| -        | 19.6±0.07ms                        | 245±2μs             |    0.01 | polys.TimeSUBRESULTANTS_SparseNonMonicQuadratic.time_op(5, 'sparse') |
| -        | 191±0.3μs                          | 105±0.2μs           |    0.55 | solve.TimeMatrixOperations.time_rref(3, 0)                           |
| -        | 365±1μs                            | 128±0.6μs           |    0.35 | solve.TimeMatrixOperations.time_rref(4, 0)                           |
| -        | 38.3±0.9ms                         | 16.2±0.07ms         |    0.42 | solve.TimeSolveLinSys189x49.time_solve_lin_sys                       |

Full benchmark results can be found as artifacts in GitHub Actions
(click on checks at the top of the PR).

[brocksam]

@moorepants I've added you as the code owner for sympy.physics.biomechanics.

[brocksam]

@asmeurer and @oscarbenjamin, in case you're curious about the output from our side of the CZI grant, this PR makes public all of the biomechanics-related code that we've added in the form of a new module.

[moorepants]

What are these changes for? Seems unrelated.

[brocksam]

MusculotendonBase has an attribute called beta. For some reason Sphinx was getting confused about whether to link to the beta function from the functions.special module or the beta attribute on MusculotendonBase in the physics.biomechanics module. The solution was to provide the full paths here so that Sphinx knew which of the two to use.

What's not clear to me is why Sphinx was getting confused between a class and an attribute on a class with the same name. I'd have thought that it shouldn't be considering attributes in this case, but it was.

[moorepants]

Ok. Let's merge this!

[moorepants]

This is ready to go in other than the one comment.

[moorepants]

Congrats! Merging.