rowan: A Python package for working with quaternions

Abstract

Numerous fields in science and engineering require methods for rotating objects. Quater-nions are perhaps the most popular formalism for representing spatial rotations due to their natural parameterization of the space of rotations SO(3) and the relative efficiency of computing quaternion-based rotation operations. A simple, uniform, and efficient implementation of quaternion operations is therefore critical to developing code to solve domain-specific problems in areas such as particle simulation and attitude determination. Python implementations of quaternion operations do exist, but they suffer from various drawbacks. Some tools are performance limited due to, e.g., having limited or no support for NumPy style array broadcasting (Wynn 2015, Brett and Gohlke (2009)). Since NumPy is a de facto standard in scientific computing applications, such support is both a prerequisite for a package to be easily incorporated into existing code bases and a Pythonic way to achieve a performant solution. Other packages that do support NumPy may have complex dependencies for accessing their full features or require conversion into some internal format, making them cumbersome to incorporate into existing code bases that need to operate on raw arrays (Boyle 2017). The rowan package, named for William Rowan Hamilton, is a quaternion package that addresses these issues. By operating directly on NumPy arrays and offering first-class support for broadcasting for all modules and functions in the package, rowan ensures high efficiency for operating on the large arrays common in computer graphics or scientific applications. We quantify performance in Figure 1 by comparison to pyquaternion (Wynn 2015) and numpy-quaternion (Boyle 2017), two well-known alternatives to rowan. For small arrays, the performance benefits of numpy-quaternion and rowan are somewhat muted since the Python function calls dominate the total run time. In fact, at this scale rowan performs quite similarly to pyquaternion, which is a pure Python solution, while numpy-quaternion, a hybrid Python-C solution, performs faster than both. For large arrays (e.g. N > 10000) where performance limitations become significant, however, rowan outstrips pyquaternion by roughly two orders of magnitude and approaches the performance of numpy-quaternion. Although a typical function call with rowan is, on average, roughly 4 times slower than numpy-quaternion, this performance difference is offset by rowan's relative ease of installation and incorporation. The package avoids any hard dependencies other than NumPy itself and directly uses NumPy arrays, making rowan an unobtrusive dependency with essentially zero barrier for introduction into existing code bases. A full-featured quaternion library, rowan has extensive capabilities in addition to basic quaternion arithmetic operations. These functions include: methods for point set registration, including some that are specialized for solving the Procrustes problem of superimposing corresponding sets of points; functions for quaternion calculus and interpolation ; the ability to sample random rotation quaternions from SO(3); and functions to compute various distance metrics on the quaternion manifold. For applications focused on rotations, rowan provides the ability to convert between numerous common rotation Ramasubramani et al., (2018). rowan: A Python package for working with quaternions. Journal of Open Source Software, 3(27), 787.