Installation

The recommended methods for installing rowan are using pip or conda. To install the package from PyPI, execute:

$ pip install rowan

To install the package from conda, first add the conda-forge channel and then install rowan:

$ conda config --add channels conda-forge
$ conda install rowan

If you wish, you may also install rowan by cloning the repository and running the setup script:

$ git clone https://github.com/glotzerlab/rowan.git
$ cd rowan
$ python setup.py install --user

The minimum requirements for using rowan are:

• Python >= 3.8

• NumPy >= 1.21

To use the mapping subpackage, rowan also requires

• SciPy >= 1.7

Quickstart

This library can be used to work with quaternions by simply instantiating the appropriate NumPy arrays and passing them to the required functions. For example:

import rowan
import numpy as np
one = np.array([10, 0, 0, 0])
one_unit = rowan.normalize(one)
assert(np.all(one_unit == np.array([1, 0, 0, 0])))
if not np.all(one_unit == rowan.multiply(one_unit, one_unit)):
    raise RuntimeError("Multiplication failed!")

one_vec = np.array([1, 0, 0])
rotated_vector = rowan.rotate(one_unit, one_vec)

mat = np.eye(3)
quat_rotate = rowan.from_matrix(mat)
alpha, beta, gamma = rowan.to_euler(quat_rotate)
quat_rotate_returned = rowan.from_euler(alpha, beta, gamma)
identity = rowan.to_matrix(quat_rotate_returned)

Running Tests

The package is currently tested for Python >= 3.6 on Unix-like systems. Continuous integrated testing is performed using CircleCI on these Python versions with NumPy versions 1.15 and above.

To run the packaged unit tests, execute the following line from the root of the repository:

python -m unittest discover tests

Running Benchmarks

Benchmarks for the package are contained in a Jupyter notebook in the benchmarks folder in the root of the repository. If you do not have or do not wish to use the notebook format, an equivalent Benchmarks.py script is also included. The benchmarks compare rowan to two alternative packages, so you will need to install pyquaternion and numpy_quaternion if you wish to see those comparisons.

Building Documentation

You can also build this documentation from source if you clone the repository. The documentation is written in reStructuredText and compiled using Sphinx. To build from source, first install Sphinx:

pip install sphinx sphinx_rtd_theme

You can then use Sphinx to create the actual documentation in either PDF or HTML form by running the following commands in the rowan root directory:

cd doc
make html # For html output
make latexpdf # For a LaTeX compiled PDF file
open build/html/index.html