blmath
======
|version| |python versions| |build status|
Collection of math-related utilities developed at Body Labs.
This is a legacy library in active maintenance. The goals are:
- Keep the library working in current versions of Python and other
tools.
- Make bug fixes.
- Provide API stability and backward compatibility with the upstream
version.
The main thrust is to transition the functionality in this library (and
the code which depends on it, such as
`lace <https://github.com/lace/lace>`__ to new libraries include
`vg <https://github.com/lace/vg>`__ and
`polliwog <https://github.com/lace/polliwog>`__. In general, new
functionality should be added in the new libraries. As needed,
additional libraries can be added to the lace org.
Installation
------------
Install dependencies
~~~~~~~~~~~~~~~~~~~~
On macOS:
::
brew install homebrew/science/suite-sparse
brew install homebrew/science/opencv --without-numpy
On Linux:
::
sudo apt-get install python-opencv libsuitesparse-dev
Install the library
~~~~~~~~~~~~~~~~~~~
.. code:: sh
pip install blmath
And import it just like the upstream library:
.. code:: py
from blmath.numerics import vx
A collection of math related utilities used by many bits of BodyLabs’
code.
blmath.numerics
---------------
Functions for manipulating numeric arrays, numbers, and linear algebra.
The `most commonly used of these <__init__.py>`__ are directly imported
into ``blmath.numerics``.
- `blmath.numerics.vx <vector_shortcuts.py>`__ is a namespace of common
linear algebra operations. These are easily expressed in numpy, but
abstracted for readability purposes.
- `blmath.numerics.coercion <coercion.py>`__ contains a validation
function ``as_numeric_array``, which produces useful error messages
up front on bad inputs, in place of cryptic messages like “cannot
broadcast…” later on.
- `blmath.numerics.operations <operations.py>`__ contains basic
numerical operations such as ``zero_safe_divide``.
- `blmath.numerics.predicates <predicates.py>`__ contains functions
like ``isnumeric``.
- `blmath.numerics.rounding <rounding.py>`__ contains functions
including “round to nearest” and ``roundedlist``.
- `blmath.numerics.numpy_ext <numpy_ext.py>`__ contains numpy utility
functions.
- `blmath.numerics.matlab <matlab.py>`__ contains some matlab shortcuts
which have no numpy equivalent. At MPI the fitting code was
originally written in Matlab before it was ported to Python.
`blmath.numerics.linalg <linalg>`__ contains linear algebra operations.
- `blmath.numerics.linalg.sparse_cg <linalg/sparse_cg.py>`__ contains a
faster matrix solve optimized for sparse Jacobians.
- `blmath.numerics.linalg.lchol <linalg/lchol.py>`__ contains a
Cythonized implementation of Cholesky factorization.
- `blmath.numerics.linalg.isomorphism <linalg/isomorphism.py>`__
computes the isomorphism between two bases.
- `blmath.numerics.linalg.gram_schmidt <linalg/gram_schmidt.py>`__
provides a function for orthonormalization.
blmath.geometry
---------------
Geometric operations, transforms, and primitives, in 2D and 3D.
The `most commonly used of these <__init__.py>`__ are directly imported
into ``blmath.geometry``.
- `blmath.geometry.Box <primitives/box.py>`__ represents an
axis-aligned cuboid.
- `blmath.geometry.Plane <primitives/plane.py>`__ represents a 2-D
plane in 3-space (not a hyperplane).
- `blmath.geometry.Polyline <primitives/polyline.py>`__ represents an
unconstrained polygonal chain in 3-space.
``blmath.geometry.transform`` includes code for 3D transforms.
- `blmath.geometry.transform.CompositeTransform <transform/composite.py>`__
represents a composite transform using homogeneous coordinates.
(Thanks avd!)
- `blmath.geometry.transform.CoordinateManager <transform/coordinate_manager.py>`__
provides a convenient interface for named reference frames within a
stack of transforms and projecting points from one reference frame to
another.
- `blmath.geometry.transform.find_rigid_transform <transform/rigid_transform.py>`__
finds a rotation and translation that closely transforms one set of
points to another. Its cousin ``find_rigid_rotation`` does the same,
but only allows rotation, not translation.
- `blmath.geometry.transform.rotation.rotation_from_up_and_look <transform/rotation.py>`__
produces a rotation matrix that gets a mesh into the canonical
reference frame from “up” and “look” vectors.
Other modules:
- `blmath.geometry.apex <apex.py>`__ provides functions for finding the
most extreme point.
- `blmath.geometry.barycentric <barycentric.py>`__ provides a function
for projecting a point to a triangle using barycentric coordinates.
- `blmath.geometry.convexify <convexify.py>`__ provides a function for
producing a convex hull from a mostly-planar curve.
- `blmath.geometry.segment <segment.py>`__ provides functions for
working with line segments in n-space.
blmath.value
------------
Class for wrapping and manipulating ``value``/``units`` pairs.
blmath.units
------------
TODO write something here
blmath.console
--------------
- `blmath.console.input_float <console.py>`__ reads and returns a float
from console.
- `blmath.console.input_value <console.py>`__ combines ``units`` with a
float input from console and returns ``Value`` object.
Development
-----------
.. code:: sh
pip install -r requirements_dev.txt
pip install -e . # builds the native extension
rake unittest
rake lint
Tests are configured to run in both python 2.7 and 3.6 locally via tox
as well as in CircleCI. To run tests in multiple versions of python, run
``tox``:
.. code:: sh
pip install -r requirements_dev.txt
tox
You need to make sure that ``python2.7`` and ``python3.6`` are valid
commands; this can be done in pyenv via ``pyenv global 3.6.5 2.7.15``
Contribute
----------
- Issue Tracker: https://github.com/lace/blmath/issues
- Source Code: https://github.com/lace/blmath
Pull requests welcome!
Support
-------
If you are having issues, please let us know.
Acknowledgements
----------------
This collection was developed at Body Labs and includes a combination of
code developed at Body Labs, from legacy code and significant new
portions by `Eric Rachlin <https://github.com/eerac>`__, `Alex
Weiss <https://github.com/algrs>`__, and `Paul
Melnikow <https://github.com/paulmelnikow>`__. It was extracted from the
Body Labs codebase and open-sourced by `Alex
Weiss <https://github.com/algrs>`__. In 2018 it was `forked by Paul
Melnikow <https://github.com/metabolize/blmath>`__ and published as
`metablmath <https://pypi.org/project/metablmath/>`__. Thanks to a
repository and package transfer from Body Labs, the fork has been merged
back into the original.
License
-------
The project is licensed under the two-clause BSD license.
.. |version| image:: https://img.shields.io/pypi/v/blmath?style=flat-square
:target: https://pypi.org/project/blmath/
.. |python versions| image:: https://img.shields.io/pypi/pyversions/blmath?style=flat-square
:target: https://pypi.org/project/blmath/
.. |build status| image:: https://img.shields.io/circleci/project/github/lace/blmath/master.svg?style=flat-square
:target: https://circleci.com/gh/lace/blmath