Qontrol Python Bindings

Python bindings for Qontrol - A quadratic optimization library for hierarchical robot control.

Qontrol enables efficient inverse kinematics and dynamics with task priorities, joint limits, and custom constraints using quadratic programming.

Features

• Four control levels: Joint Position, Velocity, Acceleration, and Torque control.
• Hierarchical task priorities: Weighted and prioritize multiple tasks (Generalized Hierarchical Control)
• Comprehensive constraints: Joint limits, Cartesian planes, custom constraints
• Multiple solvers: qpOASES, qpmad support (and more coming)
• High performance: Minimal overhead C++ bindings via nanobind

Installation

Install from PyPI:

pip install pyqontrol

Requirements

• Python 3.9+
• NumPy >= 2.0
• Pinocchio >= 2.6 (automatically installed as pin package)

Core Concepts

Control Levels

Qontrol supports three levels of control:

• JointVelocityProblem: Direct velocity control (kinematic)
• JointAccelerationProblem: Acceleration control with dynamics preview
• JointTorqueProblem: Torque-level control with full inverse dynamics

For each control level it is possible to also compute the resulting joint position command.

Tasks

Tasks define control objectives with configurable weights and priorities:

• CartesianVelocity/Acceleration: End-effector tracking
• JointVelocity/Acceleration/Torque: Joint-space control
• Custom tasks via generic task interface

Task often represents how a robot should follow a trajectory or a reference pose/configuration.

Constraints

Hard constraints that must be satisfied:

• JointConfigurationConstraint: Position limits
• JointVelocityConstraint: Velocity limits
• JointTorqueConstraint: Torque limits
• CartesianPlaneConstraint: Collision avoidance planes

Every constraints can be softened using Slack variables

Resolution Strategies

• Weighted: Combine tasks with weights (QP)
• Generalized: Generalized hierarchical control (GHC). Multiple task with complete hierarchy handling

Examples

The package includes interactive examples demonstrating various control scenarios. After installing with pip install pyqontrol mujoco pin:

# Download example resources (URDF files) from the repository
git clone https://gitlab.inria.fr/auctus-team/components/control/qontrol.git
cd qontrol/bindings/python/examples

# Run interactive velocity control
python velocity_control_interactive.py panda

# Run torque control with dynamics
python torque_control_interactive.py panda

Documentation

• Full documentation
• Examples

Development

Building from Source

If you want to contribute or build from source, the project requires CMake, a C++ compiler, and Eigen3. On Ubuntu/Debian, install the required packages with:

sudo apt install build-essential cmake libeigen3-dev

Qontrol uses the Pinocchio library by default for robot modeling. To install Pinocchio, follow the official installation guide and choose the method that best fits your system: Pinocchio installation guide. Then to build Qontrol from source :

# Clone the repository
git clone https://gitlab.inria.fr/auctus-team/components/control/qontrol
cd qontrol/bindings/python

# Install in editable mode (automatically builds C++ library and Python bindings)
pip install -e .

Running Tests

cd bindings/python
pytest tests/ -v

License

GNU Lesser General Public License v3.0