Metadata-Version: 2.1
Name: pyqontrol
Version: 0.1.0
Summary: Python bindings for Qontrol - A quadratic optimization library for robot control
Keywords: robotics,control,optimization,quadratic-programming,inverse-kinematics
Author-Email: Lucas Joseph <lucas.joseph@inria.fr>
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Project-URL: Homepage, https://gitlab.inria.fr/auctus-team/components/control/qontrol
Project-URL: Documentation, https://auctus-team.gitlabpages.inria.fr/components/control/qontrol/python
Project-URL: Repository, https://gitlab.inria.fr/auctus-team/components/control/qontrol
Project-URL: Issues, https://gitlab.inria.fr/auctus-team/components/control/qontrol/-/issues
Requires-Python: >=3.9
Requires-Dist: numpy>=1.20
Requires-Dist: pin>=3.8.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=5.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0; extra == "docs"
Requires-Dist: breathe>=4.35; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=1.19; extra == "docs"
Provides-Extra: mujoco
Requires-Dist: mujoco>=3.0.0; extra == "mujoco"
Provides-Extra: examples
Requires-Dist: mujoco>=3.0.0; extra == "examples"
Provides-Extra: all
Requires-Dist: pytest>=6.0; extra == "all"
Requires-Dist: pytest-cov; extra == "all"
Requires-Dist: black; extra == "all"
Requires-Dist: isort; extra == "all"
Requires-Dist: mypy; extra == "all"
Requires-Dist: mujoco>=3.0.0; extra == "all"
Requires-Dist: sphinx>=5.0; extra == "all"
Requires-Dist: sphinx-rtd-theme>=1.0; extra == "all"
Requires-Dist: breathe>=4.35; extra == "all"
Requires-Dist: sphinx-autodoc-typehints>=1.19; extra == "all"
Description-Content-Type: text/markdown

# 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

