Effective Mass Analysis

This package provides transparency into the effective mass results presented in our work, AthenaZero: a low-inertia, bimanual robot for dynamic manipulation [1]. While the method for computing effective mass at an operational point — visualized as a belted ellipsoid — is standard and taken directly from [2], what is arguably more important to document clearly are the robot dynamic models used, including rotor inertia and gear reduction values.

A key source of discrepancy between effective mass results reported for the same manipulator across the literature is the use of differing dynamic models. This stems from the fact that robot manufacturers typically supply kinematically correct models, but rarely provide dynamically correct ones — and even more rarely disclose rotor inertia and gear reduction values.

This package therefore serves as a consolidated reference for the kinematic and inertial parameters needed to reproduce the effective mass results for AthenaZero and the four baseline robots from [1]: the Franka Research 3, KUKA iiwa14, Universal Robots UR5e, and Barrett WAM.

Installation

1. Clone the repository:

   git clone https://github.com/rai-inst/plot_effective_mass.git
   cd plot_effective_mass

2. Install with uv:

   uv sync

What Running the Script Produces

For a specified robot, joint configuration, and end-effector point, the script produces a 2D plot containing two belted ellipsoids of effective mass projected onto a chosen plane:

• Dashed line — links only: rotor inertia is excluded.
• Solid line — links + actuators: reflected rotor inertia (scaled by gear ratio²) is included.

The maximum effective mass along the plotted axes is annotated on each ellipsoid. A render of the robot in the specified configuration is shown alongside the ellipse plot, with two coloured axis arrows drawn at the end-effector point to indicate the projection plane.

Interpreting the Output

Effective mass is a configuration-dependent scalar quantity associated with a direction $\mathbf{u}$ at an operational point. It is defined as the ratio of an applied force in direction $\mathbf{u}$ to the resulting linear acceleration of the operational point in $\mathbf{u}$. A high effective mass means the robot feels heavy to an external agent pushing in that direction. A low effective mass means it feels light.

Each belted ellipsoid sweeps $\mathbf{u}$ through a full 360° in the chosen plane — every point on the curve represents the effective mass for that particular direction. The extent of the ellipsoid along any direction therefore directly reads off the effective mass in that direction. The ratio of the solid to dashed ellipsoid at any direction indicates how much the reflected rotor inertia contributes relative to the link inertia alone.

Usage

Run the script for a named robot (looks up params/<robot>_params.yaml):

uv run plot-inertia-ellipse --robot fr3

Save the figure to a file:

uv run plot-inertia-ellipse --robot fr3 --output inertia_ellipse.svg

Use a custom parameter file:

uv run plot-inertia-ellipse --params path/to/my_robot_params.yaml

Available robots (out of the box): fr3, iiwa14, ur5e, wam.

Parameter File Format

Custom robots can be specified via a YAML parameter file passed with --params. Required keys:

Key	Description
mjcf_folder	Directory containing the MJCF. Environment variables are expanded; relative paths are resolved from the script's directory.
mjcf_file	MJCF filename inside mjcf_folder.
EE_PARENT	Name of the end-effector parent body in the MJCF.
ee_pt_pos	[x, y, z] offset from EE_PARENT to the operational point (meters).
configuration	List of joint angles (radians), length must equal model.nq.
plane	Projection plane: "xz", "yz", or "xy".
joints	Dict mapping joint name → [rotor_inertia, gear_ratio]. Reflected inertia = rotor_inertia × gear_ratio².
locked_armature	Reflected inertia assigned to locked joints (e.g. 1.0e10).
locked_joints	List of joint names to treat as rigidly locked (e.g. ["joint_1"]). Use [] if none.

Where Did These Models Come From?

Each robot model has two independent sources: the MuJoCo XML (kinematics and link inertia) and the rotor inertia / gear ratio values used to compute reflected actuator inertia. In all cases the base frame is rotated relative to the source model to match the mounting configuration used in our paper. Please refer to the LICENSE files in each robot model folder for relevant license and copyright information. All other content in this repo is licensed under the MIT license, for which a file is provided in the top-level of this repository. Note: some XML files contain armature values, but these are overwritten by the script at runtime.

Simplified AthenaZero

A kinematic and dynamic model for AthenaZero is provided with visual meshes replaced by primitive shapes. Rotor inertia and gear reduction values are as reported in [1]. Note: the wrist uses a parallel mechanism, so its transmission ratio is configuration-dependent. The values provided are valid at the center of the wrist workspace ([0.0, 0.0]) and will vary slightly away from this neutral configuration. The XML file includes PD actuators to make it convenient to configure the robot interactively in the MuJoCo viewer. This does not represent the actuators or control scheme used on the robot hardware.

Barrett WAM

The MuJoCo XML comes from [6]. Rotor inertia and gear reduction values are provided in the publicly available Barrett Inertial Specifications Manual supplied with every WAM arm. A copy is included in wam_description/ for convenience. PD actuators were added to the XML file to make it convenient to configure the robot in the MuJoCo viewer.

Franka Research 3

The MuJoCo XML comes from MuJoCo Menagerie [3] (franka_fr3_v2). Rotor inertia and gear ratio values are taken from the RobotLocomotion models repository [4]. As noted in [4], Franka does not separately disclose rotor inertia and gear ratio — the values are chosen to match the reflected inertia figures that Franka does publish.

Universal Robots UR5e

The MuJoCo XML comes from MuJoCo Menagerie [3]. The rotor inertia and gear ratio values are taken from [5].

KUKA iiwa14

The MuJoCo XML comes from MuJoCo Menagerie [3]. Rotor inertia and gear ratio values are from [4]. As exact values are not provided by KUKA, these are estimated from the specifications of the DLR LWR III, which is known to be similar.

Citations

[1] Fill in AthenaZero citation.

[2] Khatib, Oussama. "Inertial properties in robotic manipulation: An object-level framework." The international journal of robotics research 14.1 (1995): 19-36.

[3] Zakka, Kevin, Tassa, Yuval, and MuJoCo Menagerie Contributors. MuJoCo Menagerie: A collection of high-quality simulation models for MuJoCo. (2022), http://github.com/google-deepmind/mujoco_menagerie, GitHub repository.

[4] RobotLocomotion, Shareable large model files (meshes, etc) for use in RobotLocomotion Group research projects, including Drake. (2022), https://github.com/RobotLocomotion/models, GitHub repository.

[5] Porcelli, Gabriele. Dynamic parameters identification of a UR5 robot manipulator. Diss. Politecnico di Torino, 2020.

[6] Xu, Jianxiang. Mujoco Mobile WAM Simulation. (2022), https://github.com/UW-Advanced-Robotics-Lab/simulation-mujoco-summit-wam, GitHub repository.