pyqontrol 0.1.0
Python bindings for Qontrol - A quadratic optimization library for robot control
Requires Python: >=3.9
Keywords: robotics, control, optimization, quadratic-programming, inverse-kinematics

# 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:

```bash
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`:

```bash
# 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](https://auctus-team.gitlabpages.inria.fr/components/control/qontrol/)
- [Examples](https://gitlab.inria.fr/auctus-team/components/control/qontrol/-/tree/main/bindings/python/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:

```bash
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](https://stack-of-tasks.github.io/pinocchio/download.html).
Then to build Qontrol from source :

```bash
# 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

```bash
cd bindings/python
pytest tests/ -v
```

## License

GNU Lesser General Public License v3.0