Skip to content

Fix muscle FLV documentation to match current implementation in engine_util_misc#3305

Open
zchJo wants to merge 1 commit into
google-deepmind:mainfrom
zchJo:fix-muscle-flv-doc
Open

Fix muscle FLV documentation to match current implementation in engine_util_misc#3305
zchJo wants to merge 1 commit into
google-deepmind:mainfrom
zchJo:fix-muscle-flv-doc

Conversation

@zchJo
Copy link
Copy Markdown

@zchJo zchJo commented Jun 1, 2026

Problem

While fitting FLV curve parameters for musculoskeletal modeling, I noticed a discrepancy between the forces computed at runtime by MuJoCo and the reference MATLAB implementation in doc/_static/FLV.m .

In particular, using FLV.m as the reference for parameter fitting produced curves that differed from the forces computed at runtime by MuJoCo. After comparing the documentation script with mju_muscleGainLength and mju_muscleBias, the mismatch appears to be stale documentation/assets rather than a simulator bug.

Summary

This PR updates the muscle FLV documentation assets so they match the current MuJoCo muscle actuator implementation.

The previous doc/_static/FLV.m script still used an older force-length/passive-force curve:

  • active force-length included an extra short-length 0.15 bump that is not present in mju_muscleGainLength;
  • passive force-length used a cubic/linear curve that no longer matches mju_muscleBias;
  • the generated musclemodel figures and the fpmax XML reference text reflected that older passive curve.

The current implementation in src/engine/engine_util_misc.c uses one quadratic active force-length bump and a passive force curve that is half-quadratic up to (1 + lmax) / 2, then linear beyond that point. MuJoCo Warp/MJX mirrors this logic.

Changes

  • Updated doc/_static/FLV.m to match mju_muscleGainLength and mju_muscleBias in src/engine/engine_util_misc.c.
  • Kept the MATLAB figure style, with slightly larger labels, bold activation annotations, and tighter subplot spacing.
  • Regenerated doc/images/modeling/musclemodel.png and doc/images/modeling/musclemodel_dark.png with MATLAB R2024b at the original pixel dimensions.
  • Updated doc/XMLreference.rst so fpmax is described as a passive force scaling parameter instead of passive force exactly at lmax.

Testing

  • Ran git diff --check.
  • Visually inspected the regenerated light and dark muscle model figures.
  • Verified both regenerated PNGs are 1435x1272 pixels.
  • Verified the corrected default passive curve key points: FP(1) = 0, FP((1 + lmax) / 2) = 0.5 * fpmax, FP(lmax) = 1.5 * fpmax.

@google-cla
Copy link
Copy Markdown

google-cla Bot commented Jun 1, 2026

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant