Merge pull request #298 from Simple-Robotics/topic/aligator-py-extension-cmake-macro

Add CMake macro `aligator_create_python_extension()` to export

Author: ManifoldFR

CHANGELOG.md

@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Add CMake macro `aligator_create_python_extension()` to export ([#298](https://github.com/Simple-Robotics/aligator/pull/298))
 - Add macro `ALIGATOR_OUT_OF_RANGE_ERROR` to throw `std::out_of_range` exceptions ([#294](https://github.com/Simple-Robotics/aligator/pull/294))
 
 ### Changed

CMakeLists.txt

@@ -1,5 +1,5 @@
 #
-# Copyright (C) 2022-2024 LAAS-CNRS, INRIA
+# Copyright (C) 2022-2024 LAAS-CNRS, 2022-2025 INRIA
 #
 
 cmake_minimum_required(VERSION 3.16)
@@ -555,6 +555,11 @@ if(BUILD_TESTING)
 endif()
 
 # --- PACKAGING ----------------------------------------------------------------
+
+if(BUILD_PYTHON_INTERFACE)
+  file(READ extra-python-macros.cmake PACKAGE_EXTRA_MACROS)
+endif()
+
 macro(EXPORT_VARIABLE var_name var_value)
   get_directory_property(has_parent PARENT_DIRECTORY)
   if(has_parent)

README.md

@@ -80,21 +80,26 @@ cmake --build . -jNCPUS
 * [typed-argument-parser](https://github.com/swansonk14/typed-argument-parser)
 * [matplotlib](https://matplotlib.org)
 
-### Notes
+### Notes on building
 
 * For developers, add the `-DCMAKE_EXPORT_COMPILE_COMMANDS=1` when working with language servers e.g. clangd.
 * To use the Crocoddyl interface, add `-DBUILD_CROCODDYL_COMPAT=ON`
 * By default, building the library will instantiate the templates for the `double` scalar type.
 * To build against a Conda environment, activate the environment and run `export CMAKE_PREFIX_PATH=$CONDA_PREFIX` before running CMake and use `$CONDA_PREFIX` as your install folder.
 
+## Usage
+
+**aligator** can be used in both C++ (with CMake to create builds) and Python.
+
+Users can refer to [examples](https://github.com/Simple-Robotics/aligator/tree/main/examples) in either language to see how to build a trajectory optimization problem, create a solver instance (with parameters), and solve their problem.
+
+For how to use **aligator** in CMake, including creation of a Python extension module in C++, please refer to the [developer's guide](doc/developers-guide.md).
+
 ## Benchmarking
 
-We recommend using [Flame Graphs](https://github.com/brendangregg/FlameGraph) to evaluate performance.
-If you have the Rust toolchain and `cargo` installed, we suggest you install [cargo-flamegraph](https://github.com/flamegraph-rs/flamegraph). Then, you can create a flame graph with the following command:
+The repo [aligator-bench](https://github.com/Simple-Robotics/aligator-bench) provides a comparison of aligator against other solvers.
 
-```bash
-flamegraph -o my_flamegraph.svg -- ./build/examples/example-croc-talos-arm
-```
+For developer info on benchmarking, see [doc/developers-guide.md](doc/developers-guide.md).
 
 ## Citing Aligator
 
@@ -110,13 +115,18 @@ To cite **Aligator** in your academic research, please use the following bibtex
 Please also consider citing the reference paper for the ProxDDP algorithm:
 
 ```bibtex
-@misc{jalletPROXDDPProximalConstrained2023,
-  title = {{PROXDDP: Proximal Constrained Trajectory Optimization}},
+@article{jalletPROXDDPProximalConstrained2025,
+  title = {PROXDDP: Proximal Constrained Trajectory Optimization},
+  shorttitle = {PROXDDP},
   author = {Jallet, Wilson and Bambade, Antoine and Arlaud, Etienne and {El-Kazdadi}, Sarah and Mansard, Nicolas and Carpentier, Justin},
-  year = {2023},
-  abstract = {Trajectory optimization (TO) has proven, over the last decade, to be a versatile and effective framework for robot control. Several numerical solvers have been demonstrated to be fast enough to allow recomputing full-dynamics trajectories for various systems at control time, enabling model predictive control (MPC) of complex robots. These first implementations of MPC in robotics predominantly utilize some differential dynamic programming (DDP) variant for its computational speed and ease of use in constraint-free settings. Nevertheless, many scenarios in robotics call for adding hard constraints in TO problems (e.g., torque limits, obstacle avoidance), which existing solvers, based on DDP, often struggle to handle. Effectively addressing path constraints still poses optimization challenges (e.g., numerical stability, efficiency, accuracy of constraint satisfaction) that we propose to solve by combining advances in numerical optimization with the foundational efficiency of DDP. In this article, we leverage proximal methods for constrained optimization and introduce a DDP-like method to achieve fast, constrained trajectory optimization with an efficient warm-starting strategy particularly suited for MPC applications. Compared to earlier solvers, our approach effectively manages hard constraints without warm-start limitations and exhibits commendable convergence accuracy. Additionally, we leverage the computational efficiency of DDP, enabling real-time resolution of complex problems such as whole-body quadruped locomotion. We provide a complete implementation as part of an open-source and flexible C++ trajectory optimization library called ALIGATOR. These algorithmic contributions are validated through several trajectory planning scenarios from the robotics literature and the real-time whole-body MPC of a quadruped robot.},
-  langid = {english},
-  note = {https://inria.hal.science/hal-04332348v1}
+  year = {2025},
+  month = mar,
+  journal = {IEEE Transactions on Robotics},
+  volume = {41},
+  pages = {2605--2624},
+  issn = {1941-0468},
+  doi = {10.1109/TRO.2025.3554437},
+  urldate = {2025-04-04}
 }
 ```
 
@@ -145,7 +155,7 @@ The development of **Aligator** is actively supported by the [Willow team](https
 * W. Jallet, N. Mansard, and J. Carpentier, ‘Implicit Differential Dynamic Programming’, in 2022 International Conference on Robotics and Automation (ICRA), Philadelphia, United States: IEEE Robotics and Automation Society, May 2022. doi: 10.1109/ICRA46639.2022.9811647.
 * W. Jallet, A. Bambade, N. Mansard, and J. Carpentier, ‘Constrained Differential Dynamic Programming: A primal-dual augmented Lagrangian approach’, in 2022 IEEE/RSJ International Conference on Intelligent Robots and Systems, Kyoto, Japan, Oct. 2022. doi: 10.1109/IROS47612.2022.9981586.
 * W. Jallet, A. Bambade, N. Mansard, and J. Carpentier, ‘ProxNLP: a primal-dual augmented Lagrangian solver for nonlinear programming in Robotics and beyond’, in 6th Legged Robots Workshop, Philadelphia, Pennsylvania, United States, May 2022. Accessed: Oct. 10, 2022. [Online]. Available: https://hal.archives-ouvertes.fr/hal-03680510
-* W. Jallet, A. Bambade, E. Arlaud, S. El-Kazdadi, N. Mansard, and J. Carpentier, ‘PROXDDP: Proximal Constrained Trajectory Optimization’. 2023. [Online]. Available: https://inria.hal.science/hal-04332348v1
+* W. Jallet, A. Bambade, E. Arlaud, S. El-Kazdadi, N. Mansard, and J. Carpentier, ‘PROXDDP: Proximal Constrained Trajectory Optimization’, IEEE Transactions on Robotics, vol. 41, pp. 2605–2624, Mar. 2025, doi: 10.1109/TRO.2025.3554437.
 * S. Kazdadi, J. Carpentier, and J. Ponce, ‘Equality Constrained Differential Dynamic Programming’, presented at the ICRA 2021 - IEEE International Conference on Robotics and Automation, May 2021. Accessed: Sep. 07, 2021. [Online]. Available: https://hal.inria.fr/hal-03184203
 * A. Bambade, S. El-Kazdadi, A. Taylor, and J. Carpentier, ‘PROX-QP: Yet another Quadratic Programming Solver for Robotics and beyond’, in Robotics: Science and Systems XVIII, Robotics: Science and Systems Foundation, Jun. 2022. doi: 10.15607/RSS.2022.XVIII.040.
 * W. Jallet, E. Dantec, E. Arlaud, N. Mansard, and J. Carpentier, ‘Parallel and Proximal Constrained Linear-Quadratic Methods for Real-Time Nonlinear MPC’, in Proceedings of Robotics: Science and Systems, Delft, Netherlands, Jul. 2024. doi: 10.15607/RSS.2024.XX.002.

bindings/python/CMakeLists.txt

@@ -1,5 +1,5 @@
 #
-# Copyright (C) 2022-2024 LAAS-CNRS, INRIA
+# Copyright (C) 2022-2024 LAAS-CNRS, 2022-2025 INRIA
 #
 include(${JRL_CMAKE_MODULES}/python.cmake)
 if(GENERATE_PYTHON_STUBS)

doc/benchmarks.md

@@ -2,7 +2,25 @@
 
 When creating the CMake build, make sure to add the `-DCMAKE_EXPORT_COMPILE_COMMANDS=1` flag. See its documentation [here](https://cmake.org/cmake/help/latest/variable/CMAKE_EXPORT_COMPILE_COMMANDS.html).
 
-## Debugging a C++ executable
+A template project for using **aligator** with CMake and C++ can be found in the [aligator-cmake-example-project](https://github.com/Simple-Robotics/aligator-cmake-example-project) repository.
+
+## Creating a Python extension module
+
+When **aligator** is installed, the CMake configuration file (`aligatorConfig.cmake`) provides a CMake function to help users easily create a [Python extension module](https://docs.python.org/3/extending/extending.html).
+Users can write an extension module in C++ for performance reasons when providing e.g. custom constraints, cost functions, dynamics, and so on.
+
+The CMake function is called as follows:
+```cmake
+aligator_create_python_extension(<name> [WITH_SOABI] <sources...>)
+```
+
+This will create a CMake `MODULE` target named `<name>` on which the user can set properties and add an `install` directive.
+
+An usage example can be found in [this repo](https://github.com/Simple-Robotics/aligator-cmake-example-project).
+
+## Debugging
+
+### Debugging a C++ executable
 
 This project builds some C++ examples and tests. Debugging them is fairly straightforward using GDB:
 
@@ -18,7 +36,7 @@ If you want to catch `std::exception` instances thrown, enter the following comm
 (gdb) catch throw std::exception
 ```
 
-## Debugging a Python example or test
+### Debugging a Python example or test
 
 In order for debug symbols to be loaded and important variables not being optimized out, you will want to compile in `DEBUG` mode.
 
@@ -30,6 +48,23 @@ gdb --args python example/file.py
 
 If you want to look at Eigen types such as vectors and matrices, you should look into the [`eigengdb`](https://github.com/dmillard/eigengdb) plugin for GDB.
 
-## Hybrid debugging with Visual Studio Code
+### Hybrid debugging with Visual Studio Code
 
 **TODO** Finish documenting this
+
+## Profiling
+
+We use [google benchmark](https://github.com/google/benchmark/tree/v1.5.0) to define C++ benchmarks
+which are able to aggregate data from runs, and [Flame Graphs](https://github.com/brendangregg/FlameGraph) to produce a breakdown of the various function calls and their importance as a proportion of the call stack.
+
+If you have the Rust toolchain and `cargo` installed, we suggest you install [cargo-flamegraph](https://github.com/flamegraph-rs/flamegraph). Then, you can create a flame graph with the following command:
+
+```bash
+flamegraph -o my_flamegraph.svg -- ./build/examples/example-croc-talos-arm
+```
+
+
+Here's Crocoddyl's flame graph:
+![croc-talos-arm](images/flamegraph-croc.svg)
+Here's for `aligator::SolverFDDP`:
+![prox-talos-arm](images/flamegraph-prox.svg)

doc/developers-guide.md

@@ -0,0 +1,21 @@
+# ------
+# aligator_add_python_extension
+#
+#
+# ------
+function(aligator_create_python_extension name)
+  message(STATUS "Adding aligator Python C++ extension ${name}")
+  set(options WITH_SOABI)
+  cmake_parse_arguments(arg "${options}" "" "" ${ARGN})
+  set(_parse_oneValueArgs)
+  foreach(op IN LISTS options)
+    if(${arg_${op}})
+      list(APPEND _parse_oneValueArgs ${op})
+    endif()
+  endforeach()
+  set(_sources ${arg_UNPARSED_ARGUMENTS})
+
+  Python3_add_library(${name} ${_parse_oneValueArgs} ${_sources})
+  target_link_libraries(${name} PRIVATE eigenpy::eigenpy aligator::aligator)
+  target_compile_definitions(${name} PRIVATE PYTHON_MODULE_NAME=${name})
+endfunction()

extra-python-macros.cmake

@@ -31,6 +31,7 @@
                   ./bench
                   ./bindings
                   ./CMakeLists.txt
+                  ./extra-python-macros.cmake
                   ./doc
                   ./examples
                   ./include