This release adds the JointVelocityTask whose aim is to track a reference joint-velocity vector via $\arg\min_v \Vert v_{ref} - v \Vert^2$. This task can be used, for instance, if a reference velocity is computed by other means (optimal control, reinforcement-learned policy, ...), and the differential IK acts as a constraint-enforcing filter. An example illustrates this with a Unitree Z1 tracking a trajectory that would violate joint limits:

(In the example, joint limits don't prevent self-collisions when the arm is folded on itself.)

Added

• Task: JointVelocityTask for tracking a reference joint-velocity trajectory

Fixed

• Save problem instance in NoSolutionFound exception

Removed

• Remove unused attribute of SelfCollisionBarrier

This version adds (1) a constraints argument to solve_ik, to enforce tasks as QP equality constraints rather than in the objective function, and (2) the omniwheel task, which is like a rolling task but allows lateral motion.

Note that, internally, exceptions have been grouped into the pink.exceptions submodule. We don't count this as an API-breaking change, although strictly speaking it is 😊, as the expected way to handle Pink exceptions is to catch PinkError.

Thanks to @jorisv for contributing to this release 👍

Added

• CICD: Unit test fixture for the rolling task
• CICD: Unit test fixture for the omniwheel task
• Introduce constraints to enforce tasks as QP equality constraints
• Task: Add missing task __repr__ functions
• Task: Omniwheel task, like a rolling task but allowing lateral motion

Changed

• CICD: Switch to Pixi for code coverage, documentation, linting and testing
• Move pink.barriers.exceptions to pink.exceptions
• Move pink.tasks.exceptions to pink.exceptions
• Task: Make __repr__ of base class abstract to ensure tasks define their own
• docs: Refactor Tasks page and update references
• examples: Update installation hints when example dependencies are missing

Fixed

• CICD: Improve Pixi configuration (thanks to @jorisv)
• Task: Fix damping task when the robot model has a mobile root joint
• Task: Report LM damping in CoM task representation

This release introduces the NoSolutionFound exception (previously an AssertionError), and makes a stricter check that the QP solver reports successfully converging to a solution. It is still possible to catch cases where the solver converged (but not to a solution) as follows:

try:
    velocity = solve_ik(configuration, tasks, dt, solver=solver)
except NoSolutionFound as exn:
    if exn.results.x is not None:  # QP solver converged but not to a solution
        velocity = exn.results.x
    raise exn

This release also removes an unrequired dependency on quadprog. This solver is still great for IK, but we cannot distribute it with Pink (permissive license: Apache-2.0) as it is licensed under the GPL-2.0. Feel free to install and use it on your own!

Thanks to @ashwinvkNV and @peterd-NV for helping address this licensing issue 👍

Added

• Add NoSolutionFound exception
• Add open keyword argument to start_meshcat_visualizer
• examples: Detail that quadprog works best on Stretch examples
• examples: Installation instruction for loop-rate-limiters
• examples: Switch to DAQP solvers in examples where it works well
• examples: Switch to ProxQP on JVRC-1 example
• examples: Switch to ProxQP on one-dof configuration limit example

Changed

• CICD: Switch from tox to Anaconda environments
• CICD: Update QP solvers used in unit tests
• CICD: Update checkout action to v4
• Raise custom NoSolutionFound rather than AssertionError in solve_ik
• Update supported Python versions

Fixed

• CICD: Update unit test for self-collision barrier

Removed

• Remove dependency on quadprog (thanks to @peterd-NV)

This release adds the RollingTask for rolling without slipping. Here is an example:

• Wheeled biped: Upkie rolling without slipping

Added

• Example: Upkie rolling without slipping on a horizontal floor
• Task: RollingTask for rolling without slipping on a plane

Changed

• Rename "end-effector to target" example to "inverse kinematics UR10"
• Update icon of documentation website

Fixed

• Update documentation Sphinx and theme versions
• Fix Jacobian of SelfCollisionBarrier for floating-base robots

This major release adds Control Barrier Functions developed by @domrachev03 and @simeon-ned 👍 Examples of what we can do with barriers include:

• Arm: UR5: with joints and end effector limits
• Humanoid: G1: G1 humanoid squatting via a CoM task
• Quadruped: Go2: Go 2 squatting with floating base position limits
• Dual Arms: Yumi: self-collision avoidance with spheres
• Dual Arms: Iiwa: whole-body self-collision avoidance

Another API-breaking change to the library is that limits are now optional and can be extended (for instance with the new acceleration limit) or disabled. New limits and tasks include:

• Limit: AccelerationLimit
• Task: ComTask for center-of-mass tracking (thanks to @simeon-ned)
• Task: LowAccelerationTask for smoother velocities.

Check out the full changelog below for other changes and fixes. May the Motion be with you!

Added

• Breaking: Updated the logic for handling the joint limits:
  • Add a limits argument to build_ik and solve_ik
  • The check_limits method now includes an optional safety_break argument to control whether execution should stop on exception.
  • The solve_ik function now includes the safety_break that is forwarded to check_limits.
• Control Barrier Functions, namely: (thanks to @domrachev03 and @simeon-ned)
  • Abstract Barrier Barrier
  • Frame Position Barrier PositionBarrier
  • Body Spherical Barrier BodySphericalBarrier
  • Whole-body Self-Collision Avoidance Barrier SelfCollisionBarrier
• Example: UR5 manipulator and GO2 quadruped robot with PositionBarrier
• Example: YUMI two-armed manipulator with BodySphericalBarrier
• Example: G1 humanoid squatting through regulating CoM.
• Limit: AccelerationLimit
• Task: ComTask for center-of-mass tracking (thanks to @simeon-ned)
• Task: LowAccelerationTask for smoother velocities.

Changed

• Breaking: remove lm_damping parameter from DampingTask where it wasn't used
• CICD: Update ruff to 0.4.3
• Configuration accepts list of Control Barrier Functions
• DampingTask: Simplify implementation
• Update to Pinocchio 3 with 2.7 backward compatibility

Fixed

• PostureTask: Match implementation and documentation formula
• Fix broken documentation links

Removed

• CICD: Disable macOS checks until upstream PyPI package is fixed

This release adds the RelativeFrameTask developed with @ymontmarin 👍 This new task is a generalization of the frame task that accepts targets with respect to any robot frame. For example:

• Left: relative frame task (stretch_relative_target.py example)
• Right: frame task (stretch_world_target.py example)

This release also brings a few quality-of-use improvements to configurations and costs.

Added

• Function get_transform in the Configuration class
• Task: relative frame task, where target is w.r.t another robot frame

Changed

• Configuration: update function now accepts a configuration vector argument
• Costs: setting cost in relative frame task now accepts plain float

This release brings a number of fixes and completes the renaming of the BodyTask to FrameTask (details below). It also distributes Pink on conda-forge, which is now the recommended way to install for best performance:

conda install -c conda-forge pink

Added

• Add gain keyword argument to all task constructors where is makes sense
• Damping task that minimizes joint velocities
• Distribute package on conda-forge
• Example on how differential IK may converge to a local constrained optimum
• Expose all tasks from the top-level pink module
• Handle unbounded joints in custom configuration vectors
• Unit test for posture task Jacobian

Changed

• Breaking: Define task Jacobian as derivative of the task error
• Breaking: Rename BodyNotFound exception to FrameNotFound
• Breaking: Rename FrameTask.body to FrameTask.frame

Removed

• Body-minus utility function
• Spatial-minus utility function

This release fixes a bug when handling configuration limits for models that contain unbounded revolute joints.

Changed

• Don't check configuration limits when building IK matrices

Fixed

• Configuration limits when model has unbounded revolute joints

This is the first major release of Pink, Python inverse kinematics for articulated robot models, based on Pinocchio. The main update since v0.11.0 is the definition of a proper linear holonomic task on tangent spaces, with accompanying documentation, by @ymontmarin. Thanks! 👍

API-wise, Levenberg-Marquardt damping is now defined in the base Task class and can therefore be set in any task. This release drops support for Python 3.7, and brings a seasonal batch of new examples and bug fixes.

Added

• Example: UR5 arm
• Example: flying dual-arm with UR3
• General linear holonomic task

Changed

• Cost vector is now defined for all tasks
• Drop support for Python 3.7
• Levenberg-Marquardt damping is now defined for all tasks
• Update joint-coupling task to derive from general linear holonomic task

Fixed

• Example: Draco 3 numerical stability

This release upgrades the BodyTask to a FrameTask handling all kinds of frames defined in the robot description. It was contributed by @proyan, thanks! 😃

Added

• Example: Stretch RE1

Changed

• Handle all frames, including non-body frames
• Rename BodyTask to FrameTask