Generalized Rigid Body Dynamics Algorithms

Summary

This repository contains a C++ library of rigid-body dynamics algorithms that are compatible with kinematic loops and especially efficient for those induced by common actuation sub-mechanisms like geared transmissions, differential drives, and closed-chain linkages.
The algorithms are based on the principle of constraint embedding, originally developed by Jain 1, and revisited through our propagation-based perspective. Details of this propagation perspective are presented in our accompanying paper. Our software reflects this complementary formulation that generalizes the traditional concept of joint models and motion/force subspaces—extending them from single rigid bodies to groups of bodies linked through local loops.

Note: For notational continuity with the literature, our paper refers to these groups of bodies as "aggregate links" and the constraints between them as "aggregate joints". However, in this repository, we refer to them as "clusters" and "cluster joints" respectively.

Actuation sub-mechanisms are increasingly common in robotic systems, yet no open-source library existed to compute their dynamics efficiently.
The loops these mechanisms induce violate assumptions of conventional recursive dynamics algorithms.
Constraint embedding resolves this by grouping bodies into clusters, allowing the loop constraints to be resolved locally during forward/backward passes.
This repository provides the first open-source implementation of these ideas in a modern, templated C++ library.

Table of Contents

1. Installation
2. Usage
3. Configuration
4. License
5. Contact Information
6. Citation

Installation

Dependencies

• C++17 or higher
• CMake 3.15 or higher
• Eigen 3.3.7 or higher
• Casadi 3.6.3 or higher

They can be installed using the provided install script.

Supported Operating Systems

• Ubuntu 18.04 or higher
• MacOS 10.15 or higher (Note: When compiling on a machine with Apple M1 chip, you can optimize the performance by using the following command: cmake -DM1_BUILD=ON ..)

Building

To run the unit tests and bencmarks

• Create a build directory: mkdir build && cd build
• Run CMake: cmake ..
• Build: make
• Unit tests can be run all at once with ctest or individually with ./bin/<name-of-unit-test-binary>
• The benchmark can be run with ./bin/pinocchio_benchmark

To incorporate the library into your own project, see Configuration.

Usage

As a general purpose rigid-body dynamics library, the project can be used in a variety of ways. The most common uses are as follows:

• Dynamic Simulation: Using the constrained forward dynamics algorithms and the contact dynamics algorithms, the repository can be used as part of a simulator for contact-rich robotic systems.
• Model-Based Control: Using the inverse dynamics algorithms, the repository can be used to as part of a whole-body controller to compute the control torques required to achieve a desired state.

We offer multiple ways to construct a model, including:

• Manual Model Construction: The user can manually construct a model by following these steps:

  • Register all of the bodies contained in a cluster by providing their connectivity and inertia information.
  • Append those bodies to the model by providing information about the cluster joint that connects them.
  • Repeat the above steps for each cluster in the system.

  User can leverage the provided specialized classes for common cluster joint types. Specific examples of how to build a model can be found in the README detailing the process.

• URDF Parsing: For robots without kinematics loops, the user can parse a standard URDF file to automatically construct the model. For systems with loops, we support the URDF+ format—a minimal extension of URDF to specify kinematic loops. URDF+ preserves compatibility with existing tooling while enabling loop specification directly in XML. We refer readers to the URDF+ format paper for full details.

Configuration

You can use this repository in your project using CMake by:

1. Adding the include directory in your project's include path.
2. Linking against the generalized_rbda library.

The following example shows how to do this in CMake:

set(GRBDA_INCLUDE_DIR /path/to/generalized_rbda/include)
find_library(GRBDA_LIBRARY
    NAMES generalized_rbda
    HINTS ${GRBDA_INCLUDE_DIR}/../build)
if(GRBDA_LIBRARY)
    set(GRBDA_LIBRARIES ${GRBDA_LIBRARIES} ${GRBDA_LIBRARY})
endif()

include_directories(`${GRBDA_INCLUDE_DIR}`)
target_link_libraries(${PROJECT_NAME} ${GRBDA_LIBRARIES})

License

The code is licensed under the MIT license. See the LICENSE file for more details.

Contact Information:

For further questions or collaboration inquiries, please contact the developers at:

• Matthew Chignoli

Citation

To cite this library in your research, please use the following citation for the accompanying paper:

@article{chignoli2023recursive,
  title={A Propagation Perspective on Recursive Forward Dynamics for Systems with Kinematic Loops},
  author={Chignoli, Matthew and Adrian, Nicholas and Kim, Sangbae and Wensing, Patrick M.},
  journal={arXiv preprint arXiv:2311.13732},
  year={2024}
}

and the following citation for the codebase:

@misc{grbdaweb,
   author = {Matthew Chignoli, Nicholas Adrian, and Patrick M. Wensing},
   title = {GRBDA: Generalized Rigid-Body Dynamics Algorithms},
   howpublished = {https://github.com/ROAM-Lab-ND/generalized_rbda},
   year = {2023}
}