Merge pull request #28 from glotzerlab/feature/improve_code_quality

Feature/improve code quality

.circleci/config.yml

@@ -1,7 +1,7 @@
 version: 2
 
 references:
-  im36: &im36
+  imtox: &imtox
     docker:
       - image: themattrix/tox
 
@@ -22,16 +22,18 @@ references:
           name: run tests
           command: |
             # Faster to just test one env first
-            pip3.6 install --progress-bar off --user flake8 numpy scipy
-            python3.6 -m flake8 --show-source .
-            python3.6 -m unittest discover tests -v
+            pip3.8 install --progress-bar off --user -U flake8 flake8-black flake8-bugbear flake8-docstrings flake8-rst-docstrings pep8-naming flake8-isort
+            python3.8 -m flake8 --show-source rowan
+            # Ignore isort errors in tests that are due to ambiguity over whether or not rowan is third party.
+            python3.8 -m flake8 --extend-ignore=I001,I004 --show-source tests/
+            python3.8 -m unittest discover tests -v
 
             # Test python-dependency matrix with tox
-            pip3.6 install --progress-bar off --user tox
+            pip3.8 install --progress-bar off --user tox
             tox
 
             # Run with coverage
-            pip3.6 install --progress-bar off --user coverage codacy-coverage
+            pip3.8 install --progress-bar off --user coverage codacy-coverage
             export PATH=~/.local/bin:${PATH}
             coverage run -m unittest discover tests
             apt-get -yq update
@@ -59,9 +61,11 @@ references:
           name: run tests
           command: |
             # Faster to just test one env first
-            pip3.6 install --progress-bar off --user flake8 numpy scipy
-            python3.6 -m flake8 --show-source .
-            python3.6 -m unittest discover tests -v
+            pip3.8 install --progress-bar off --user -U flake8 flake8-black flake8-bugbear flake8-docstrings flake8-rst-docstrings pep8-naming flake8-isort
+            python3.8 -m flake8 --show-source rowan
+            # Ignore isort errors in tests that are due to ambiguity over whether or not rowan is third party.
+            python3.8 -m flake8 --extend-ignore=I001,I004 --show-source tests/
+            python3.8 -m unittest discover tests -v
 
       - save_cache:
           paths:
@@ -75,30 +79,32 @@ references:
       - run:
           name: Deploy dist and wheels
           command: |
-            pip3.6 install --progress-bar off --user flake8 numpy scipy
-            python3.6 -m flake8 --show-source .
-            python3.6 -m unittest discover tests -v
-            python3.6 --version
-            pip3.6 --version
-            pip3.6 install --progress-bar off --user -U twine wheel setuptools
+            pip3.8 install --progress-bar off --user -U flake8 flake8-black flake8-bugbear flake8-docstrings flake8-rst-docstrings pep8-naming flake8-isort
+            python3.8 -m flake8 --show-source rowan
+            # Ignore isort errors in tests that are due to ambiguity over whether or not rowan is third party.
+            python3.8 -m flake8 --extend-ignore=I001,I004 --show-source tests/
+            python3.8 -m unittest discover tests -v
+            python3.8 --version
+            pip3.8 --version
+            pip3.8 install --progress-bar off --user -U twine wheel setuptools
             export PATH=~/.local/bin:${PATH}
             twine --version
             wheel version
-            python3.6 setup.py sdist
-            python3.6 setup.py bdist_wheel
+            python3.8 setup.py sdist
+            python3.8 setup.py bdist_wheel
             twine upload --username vramasub --password ${PYPI_PASSWORD} dist/*
 
 jobs:
   complete:
-    <<: *im36
+    <<: *imtox
     <<: *wd
     <<: *runall
   test_only:
-    <<: *im36
+    <<: *imtox
     <<: *wd
     <<: *run_tests_only
   build_and_deploy:
-    <<: *im36
+    <<: *imtox
     <<: *wd
     <<: *pypi_wheels
 

doc/conf.py

@@ -41,6 +41,14 @@
     'sphinx.ext.coverage',
     'sphinx.ext.mathjax']
 
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+    'numpy': ('https://docs.scipy.org/doc/numpy', None),
+}
+
+# The reST default role to use for all documents.
+default_role = 'any'
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 

rowan/__init__.py

@@ -1,42 +1,95 @@
 # Copyright (c) 2019 The Regents of the University of Michigan
 # All rights reserved.
 # This software is licensed under the BSD 3-Clause License.
-R"""
-The core :py:mod:`rowan` package contains functions for operating on
+"""The rowan package for working with quaternions.
+
+The core :mod:`rowan` package contains functions for operating on
 quaternions. The core package is focused on robust implementations of key
 functions like multiplication, exponentiation, norms, and others. Simple
 functionality such as addition is inherited directly from NumPy due to
 the representation of quaternions as NumPy arrays. Many core NumPy functions
 implemented for normal arrays are reimplemented to work on quaternions (
-such as :py:func:`allclose` and :py:func:`isfinite`). Additionally, `NumPy
+such as :func:`allclose` and :func:`isfinite`). Additionally, `NumPy
 broadcasting
 <https://docs.scipy.org/doc/numpy-1.14.0/user/basics.broadcasting.html#>`_
 is enabled throughout rowan unless otherwise specified. This means that
 any function of 2 (or more) quaternions can take arrays of shapes that do
 not match and return results according to NumPy's broadcasting rules.
 """
 
-from . import calculus
-from . import geometry
-from . import interpolate
-from . import mapping
-from . import random
-
-from .functions import (allclose, conjugate, divide, exp, expb, exp10, equal,
-                        from_axis_angle, from_euler, from_matrix,
-                        from_mirror_plane, inverse, isclose, isinf, isfinite,
-                        isnan, is_unit, log, logb, log10, multiply, norm,
-                        normalize, not_equal, power, reflect, rotate,
-                        to_axis_angle, to_euler, to_matrix,
-                        vector_vector_rotation)
+from . import calculus, geometry, interpolate, mapping, random
+from .functions import (
+    allclose,
+    conjugate,
+    divide,
+    equal,
+    exp,
+    exp10,
+    expb,
+    from_axis_angle,
+    from_euler,
+    from_matrix,
+    from_mirror_plane,
+    inverse,
+    is_unit,
+    isclose,
+    isfinite,
+    isinf,
+    isnan,
+    log,
+    log10,
+    logb,
+    multiply,
+    norm,
+    normalize,
+    not_equal,
+    power,
+    reflect,
+    rotate,
+    to_axis_angle,
+    to_euler,
+    to_matrix,
+    vector_vector_rotation,
+)
 
 # Get the version
-__version__ = '1.2.2'
+__version__ = "1.2.2"
 
-__all__ = ['calculus', 'geometry', 'interpolate', 'mapping', 'random',
-           'allclose', 'conjugate', 'divide', 'exp', 'expb', 'exp10', 'equal',
-           'from_axis_angle', 'from_euler', 'from_matrix', 'from_mirror_plane',
-           'inverse', 'isclose', 'isinf', 'isfinite', 'isnan', 'is_unit',
-           'log', 'logb', 'log10', 'multiply', 'norm', 'normalize',
-           'not_equal', 'power', 'reflect', 'rotate', 'to_axis_angle',
-           'to_euler', 'to_matrix', 'vector_vector_rotation']
+__all__ = [
+    "calculus",
+    "geometry",
+    "interpolate",
+    "mapping",
+    "random",
+    "allclose",
+    "conjugate",
+    "divide",
+    "exp",
+    "expb",
+    "exp10",
+    "equal",
+    "from_axis_angle",
+    "from_euler",
+    "from_matrix",
+    "from_mirror_plane",
+    "inverse",
+    "isclose",
+    "isinf",
+    "isfinite",
+    "isnan",
+    "is_unit",
+    "log",
+    "logb",
+    "log10",
+    "multiply",
+    "norm",
+    "normalize",
+    "not_equal",
+    "power",
+    "reflect",
+    "rotate",
+    "to_axis_angle",
+    "to_euler",
+    "to_matrix",
+    "vector_vector_rotation",
+]

rowan/calculus/__init__.py

@@ -1,21 +1,19 @@
 # Copyright (c) 2019 The Regents of the University of Michigan
 # All rights reserved.
 # This software is licensed under the BSD 3-Clause License.
-R"""This subpackage provides the ability to compute the derivative and
-integral of a quaternion.
-"""
+r"""Compute derivatives and integrals of quaternions."""
 
 import numpy as np
 
-from ..functions import multiply, _promote_vec, _validate_unit, exp
+from ..functions import _promote_vec, _validate_unit, exp, multiply
 
-__all__ = ['derivative',
-           'integrate']
+__all__ = ["derivative", "integrate"]
 
 
 def derivative(q, v):
-    R"""Compute the instantaneous derivative of unit quaternions, which is
-    defined as
+    r"""Compute the instantaneous derivative of unit quaternions.
+
+    Derivatives of quaternions are defined by the equation:
 
     .. math::
         \dot{q} = \frac{1}{2} \boldsymbol{v} q
@@ -28,26 +26,28 @@ def derivative(q, v):
                    2012/08/24/quaternion-differentiation/
 
     Args:
-        q ((..., 4) np.array): Array of quaternions.
-        v ((..., 3) np.array): Array of angular velocities.
+        q ((..., 4) :class:`numpy.ndarray`): Array of quaternions.
+        v ((..., 3) :class:`numpy.ndarray`): Array of angular velocities.
 
     Returns:
         Array of shape (..., 4) containing element-wise derivatives of q.
 
     Example::
 
-        q_prime = rowan.calculus.derivative([1, 0, 0, 0], [1, 0, 0])
+        >>> rowan.calculus.derivative([1, 0, 0, 0], [1, 0, 0])
+        array([0. , 0.5, 0. , 0. ])
     """
     q = np.asarray(q)
     v = np.asarray(v)
 
     _validate_unit(q)
-    return 0.5*multiply(q, _promote_vec(v))
+    return 0.5 * multiply(q, _promote_vec(v))
 
 
 def integrate(q, v, dt):
-    R"""Integrate unit quaternions by angular velocity using the following
-    equation:
+    r"""Integrate unit quaternions by angular velocity.
+
+    The integral uses the following equation:
 
     .. math::
         \dot{q} = \exp\left(\frac{1}{2} \boldsymbol{v} dt\right) q
@@ -66,21 +66,22 @@ def integrate(q, v, dt):
                  how-to-integrate-quaternions/
 
     Args:
-        q ((..., 4) np.array): Array of quaternions.
-        v ((..., 3) np.array): Array of angular velocities.
-        dt ((...) np.array): Array of timesteps.
+        q ((..., 4) :class:`numpy.ndarray`): Array of quaternions.
+        v ((..., 3) :class:`numpy.ndarray`): Array of angular velocities.
+        dt ((...) :class:`numpy.ndarray`): Array of timesteps.
 
     Returns:
         Array of shape (..., 4) containing element-wise integrals of q.
 
     Example::
 
-        v_next = rowan.calculus.integrate([1, 0, 0, 0], [0, 0, 1e-2], 1)
+        >>> rowan.calculus.integrate([1, 0, 0, 0], [0, 0, 1e-2], 1)
+        array([0.9999875 , 0.        , 0.        , 0.00499998])
     """
     q = np.asarray(q)
     v = np.asarray(v)
     dt = np.asarray(dt)
 
     _validate_unit(q)
 
-    return multiply(exp(_promote_vec(v*dt/2)), q)
+    return multiply(exp(_promote_vec(v * dt / 2)), q)