Developer notes

This section documents internal functions and other notes shared between contributors to this project.

Development environment

Everything runs through pixi, which provides the C compiler and every dependency:

pixi run -e test-py312 test   # run tests
pixi run build                # compile the C extension
pixi run lint                 # clang-format, mypy, pylint and ruff
pixi run docs-open            # build this documentation and open it

The test task currently requires specifying which Python version to use by specifying the corresponding test-py3xx environment. For the other tasks, pixi will pick up the appropriate environment automatically.

You can also use the example task to run examples in the examples environment. It takes the path to the example as argument:

pixi run example examples/ur3_end_effector_tracking.py

Design guidelines

• Pinker is designed for clarity before performance (except in the C extension implemented pinker/kinematics/_kinematics_c.c, whose code is more terse).

• Exceptions raised by the library all derive from a Pinker exception base class to avoid abstraction leakage. See this design decision for more details on the rationale behind this choice.

• Task representation strings:

  • We commonly define __repr__ at the bottom of task Python source files.

  • Only report parameters that have an effect (for instance, the damping task does not report its lm_damping since its error is always zero).

  • Parent-class attributes come after the class’s own.

Exceptions

Exceptions specific to Pinker.

exception pinker.exceptions.FrameNotFound(name, frames)

Exception raised when a frame is not found in the robot model.

exception pinker.exceptions.InvalidCollisionPairs

IF the number of collision pairs is invalid.

exception pinker.exceptions.NegativeMinimumDistance

If the minimum distance in body spherical barrier is negative.

exception pinker.exceptions.NoPositionLimitProvided

If neither minimum nor maximum position limits are provided.

exception pinker.exceptions.NoSolutionFound(problem, results)

The QP solver did not find a solution to the differential IK problem.

exception pinker.exceptions.NotWithinConfigurationLimits(joint, value, lower, upper)

Exception thrown when a robot configuration violates its limits.

joint

Index of the joint in the configuration vector.

value

Invalid value of the joint.

lower

Minimum allowed value for this joint.

upper

Maximum allowed value for this joint.

exception pinker.exceptions.PinkerError

Base class for Pinker exceptions.

exception pinker.exceptions.TargetNotSet

Exception raised when attempting to compute with an unset target.

exception pinker.exceptions.TaskDefinitionError

Exception raised when a task definition is ill-formed.

exception pinker.exceptions.TaskJacobianNotSet

Exception raised when attempting to compute without a task Jacobian.

Utility functions

Utility classes and functions.

class pinker.utils.VectorSpace(dim)

Wrapper to refer to a vector space and its characteristic matrices.

property eye: ndarray

Identity matrix from and to the vector space.

property ones: ndarray

Vector full of ones, dimension of the space.

property zeros: ndarray

Zero vector of the space.