Updates docstring clarifications for joint modeling in 4.5 vs 5.0 by matthewtrepte · Pull Request #3869 · isaac-sim/IsaacLab

matthewtrepte · 2025-10-29T00:13:01Z

Description

Add docstring clarifications for joint modeling in 4.5 vs 5.0

Replaces this MR - #3461

Type of change

Documentation update

Screenshots

Please attach before and after screenshots of the change if applicable.

Checklist

I have read and understood the contribution guidelines
I have run the pre-commit checks with ./isaaclab.sh --format
I have made corresponding changes to the documentation
My changes generate no new warnings
I have added tests that prove my fix is effective or that my feature works
I have updated the changelog and the corresponding version in the extension's config/extension.toml file
I have added my name to the CONTRIBUTORS.md or my name already exists there

greptile-apps

Greptile Overview

Greptile Summary

This PR adds documentation clarifications to highlight a breaking change in joint friction modeling between Isaac Sim 4.5 and 5.0+. In version 4.5, friction parameters (friction, dynamic_friction, and their corresponding coefficients in ArticulationData) were dimensionless coefficients, whereas in version 5.0+, they represent effort values (torque or force). The changes are exclusively documentation additions to docstrings in the actuator configuration and articulation data classes, along with a corresponding version bump to 0.47.4 and changelog entry. These notes help users understand how friction parameter values should be interpreted when working across different Isaac Sim versions, preventing potential simulation behavior issues when migrating or maintaining code that spans both versions.

Important Files Changed

Filename	Score	Overview
source/isaaclab/config/extension.toml	5/5	Version bump from 0.47.3 to 0.47.4 to track this documentation update
source/isaaclab/docs/CHANGELOG.rst	5/5	Added version 0.47.4 entry documenting friction coefficient modeling clarifications
source/isaaclab/isaaclab/actuators/actuator_cfg.py	5/5	Added docstring notes for `friction` and `dynamic_friction` parameters explaining coefficient vs effort modeling
source/isaaclab/isaaclab/assets/articulation/articulation_data.py	5/5	Added docstring notes for all joint friction properties explaining the modeling difference across versions

Confidence score: 5/5

This is a documentation-only PR with no code changes, making it extremely safe to merge with no risk to production functionality
The changes are accurate, well-placed, and address an important version compatibility concern that could confuse users
No files require special attention - all documentation additions are clear and consistent

Sequence Diagram

sequenceDiagram
    participant User
    participant Documentation
    participant ActuatorConfig
    participant ArticulationData
    
    User->>Documentation: "Read about joint friction modeling"
    Documentation-->>User: "Note: Isaac Sim 4.5 uses coefficient, 5.0+ uses effort"
    
    User->>ActuatorConfig: "Configure actuator friction parameter"
    Note over ActuatorConfig: friction: dict[str, float] | float | None
    ActuatorConfig-->>User: "Friction coefficient value"
    
    User->>ArticulationData: "Access joint_friction_coeff property"
    Note over ArticulationData: Shape: (num_instances, num_joints)
    ArticulationData-->>User: "Returns friction coefficient from simulation"
    
    Note over Documentation,ArticulationData: Docstrings clarify modeling differences<br/>between Isaac Sim versions

_{4 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}

greptile-apps · 2025-10-29T00:13:56Z

+    Note: In Isaac Sim 4.5, this parameter is modeled as a coefficient. In Isaac Sim 5.0 and later,
+    it is modeled as an effort (torque or force).


style: The note format differs from the existing friction docstring structure. The main description already ends with 'If None...' so this note should likely be integrated into the existing docstring using a formal reStructuredText admonition block like .. note:: for consistency with other documentation in this file.

greptile-apps · 2025-10-29T00:13:57Z

+    Note: In Isaac Sim 4.5, this parameter is modeled as a coefficient. In Isaac Sim 5.0 and later,
+    it is modeled as an effort (torque or force).


style: Missing detailed description similar to the friction parameter. Should explain what dynamic friction coefficient represents and how it behaves in the physics engine before the version note.

greptile-apps

Greptile Overview

Greptile Summary

This PR adds important clarification notes to docstrings explaining that joint friction parameters (friction and dynamic_friction) are modeled differently between Isaac Sim versions: as coefficients in version 4.5, and as efforts (torque or force) in version 5.0 and later.

Changes Made

actuator_cfg.py: Added version-specific modeling notes to friction and dynamic_friction parameter docstrings in ActuatorBaseCfg
articulation_data.py: Added the same clarifying notes to six friction-related attributes (three default attributes and three active attributes)
CHANGELOG.rst: Documented the change in version 0.47.5
extension.toml: Version bump to 0.47.5

Consistency with Codebase

The notes align with existing implementation in articulation.py:834-857 which already documents this version difference in detail, showing that Isaac Sim 5.0+ uses a more sophisticated friction model combining static, dynamic, and viscous components.

Confidence Score: 5/5

This PR is safe to merge with no risk - it only adds clarifying documentation
Documentation-only change that adds important clarifications about version-specific behavior. The notes are accurate based on the existing implementation code. No functional code changes, no risk of runtime errors or breaking changes.
No files require special attention

Important Files Changed

File Analysis

Filename	Score	Overview
source/isaaclab/isaaclab/actuators/actuator_cfg.py	5/5	Added clarifying notes about friction modeling differences between Isaac Sim 4.5 and 5.0 for `friction` and `dynamic_friction` parameters
source/isaaclab/isaaclab/assets/articulation/articulation_data.py	5/5	Added clarifying notes about friction modeling differences for default and active friction coefficient attributes

Sequence Diagram

sequenceDiagram
    participant User
    participant ActuatorCfg as ActuatorBaseCfg
    participant Articulation
    participant ArticulationData
    participant PhysX as PhysX Engine
    
    User->>ActuatorCfg: Configure friction parameters<br/>(friction, dynamic_friction, viscous_friction)
    Note over ActuatorCfg: Docstrings clarify:<br/>4.5: coefficient<br/>5.0+: effort (torque/force)
    
    ActuatorCfg->>Articulation: Initialize with friction config
    Articulation->>ArticulationData: Set default_joint_friction_coeff
    Articulation->>ArticulationData: Set default_joint_dynamic_friction_coeff
    Note over ArticulationData: Docstrings clarify:<br/>4.5: coefficient<br/>5.0+: effort (torque/force)
    
    Articulation->>ArticulationData: Copy to joint_friction_coeff
    Articulation->>ArticulationData: Copy to joint_dynamic_friction_coeff
    Note over ArticulationData: Docstrings clarify:<br/>4.5: coefficient<br/>5.0+: effort (torque/force)
    
    Articulation->>PhysX: Write friction coefficients
    alt Isaac Sim < 5.0
        Articulation->>PhysX: set_dof_friction_coefficients(static only)
        Note over PhysX: Uses coefficient model
    else Isaac Sim >= 5.0
        Articulation->>PhysX: set_dof_friction_coefficients(static)
        Articulation->>PhysX: set_dof_dynamic_friction_coefficients(dynamic)
        Articulation->>PhysX: set_dof_viscous_friction_coefficients(viscous)
        Note over PhysX: Uses effort model (torque/force)
    end

_{4 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

…aac-sim#3869)  Add docstring clarifications for joint modeling in 4.5 vs 5.0 Replaces this MR - isaac-sim#3461   - Documentation update Please attach before and after screenshots of the change if applicable.  - [ ] I have read and understood the [contribution guidelines](https://isaac-sim.github.io/IsaacLab/main/source/refs/contributing.html) - [ ] I have run the [`pre-commit` checks](https://pre-commit.com/) with `./isaaclab.sh --format` - [ ] I have made corresponding changes to the documentation - [ ] My changes generate no new warnings - [ ] I have added tests that prove my fix is effective or that my feature works - [ ] I have updated the changelog and the corresponding version in the extension's `config/extension.toml` file - [ ] I have added my name to the `CONTRIBUTORS.md` or my name already exists there

…aac-sim#3869) # Description  Add docstring clarifications for joint modeling in 4.5 vs 5.0 Replaces this MR - isaac-sim#3461  ## Type of change  - Documentation update ## Screenshots Please attach before and after screenshots of the change if applicable.  ## Checklist - [ ] I have read and understood the [contribution guidelines](https://isaac-sim.github.io/IsaacLab/main/source/refs/contributing.html) - [ ] I have run the [`pre-commit` checks](https://pre-commit.com/) with `./isaaclab.sh --format` - [ ] I have made corresponding changes to the documentation - [ ] My changes generate no new warnings - [ ] I have added tests that prove my fix is effective or that my feature works - [ ] I have updated the changelog and the corresponding version in the extension's `config/extension.toml` file - [ ] I have added my name to the `CONTRIBUTORS.md` or my name already exists there

add docstring clarifications for joint modeling in 4.5 vs 5.0

756725a

matthewtrepte requested review from Mayankm96, jtigue-bdai and kellyguo11 as code owners October 29, 2025 00:13

github-actions Bot added the isaac-lab Related to Isaac Lab team label Oct 29, 2025

greptile-apps Bot reviewed Oct 29, 2025

View reviewed changes

kellyguo11 approved these changes Oct 29, 2025

View reviewed changes

kellyguo11 changed the title ~~add docstring clarifications for joint modeling in 4.5 vs 5.0~~ Updates docstring clarifications for joint modeling in 4.5 vs 5.0 Oct 29, 2025

jtigue-bdai approved these changes Oct 29, 2025

View reviewed changes

sync

b737871

greptile-apps Bot reviewed Oct 30, 2025

View reviewed changes

kellyguo11 merged commit 90af2be into isaac-sim:main Oct 31, 2025
8 of 9 checks passed

Mayankm96 mentioned this pull request Nov 3, 2025

Renames joint dynamic and static friction variables #3461

Closed

7 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Updates docstring clarifications for joint modeling in 4.5 vs 5.0#3869

Updates docstring clarifications for joint modeling in 4.5 vs 5.0#3869
kellyguo11 merged 2 commits into
isaac-sim:mainfrom
matthewtrepte:mtrepte/joint_name_docstrings

matthewtrepte commented Oct 29, 2025

Uh oh!

greptile-apps Bot left a comment

Uh oh!

greptile-apps Bot Oct 29, 2025

Uh oh!

greptile-apps Bot Oct 29, 2025

Uh oh!

greptile-apps Bot left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		Note: In Isaac Sim 4.5, this parameter is modeled as a coefficient. In Isaac Sim 5.0 and later,
		it is modeled as an effort (torque or force).

Conversation

matthewtrepte commented Oct 29, 2025

Description

Type of change

Screenshots

Checklist

Uh oh!

greptile-apps Bot left a comment

Choose a reason for hiding this comment

Greptile Overview

Greptile Summary

Important Files Changed

Confidence score: 5/5

Sequence Diagram

Uh oh!

greptile-apps Bot Oct 29, 2025

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot Oct 29, 2025

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot left a comment

Choose a reason for hiding this comment

Greptile Overview

Greptile Summary

Changes Made

Consistency with Codebase

Confidence Score: 5/5

Important Files Changed

Sequence Diagram

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants