metablmath 1.6.1
Active fork of blmath, a collection math-related utilities developed at Body Labs
License: MIT

metablmath
==========

|pip install| |version| |python versions| |build status| |last commit|
|open pull requests|

This is an active fork of
`blmath <https://github.com/bodylabs/blmath>`__, a collection
math-related utilities developed at Body Labs.

The fork’s goals are moderate:

-  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.
-  Add additional functionality which relates well to what is here.
-  Respond to community contributions.

It’s used by related forks such as
`lace <https://github.com/metabolize/lace>`__.

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 metablmath

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

Contribute
----------

-  Issue Tracker: https://github.com/metabolize/blmath/issues
-  Source Code: https://github.com/metabolize/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>`__.

License
-------

The project is licensed under the two-clause BSD license.

.. |pip install| image:: https://img.shields.io/badge/pip%20install-metablmath-f441b8.svg?style=flat-square
   :target: https://pypi.org/project/metablmath/
.. |version| image:: https://img.shields.io/pypi/v/metablmath.svg?style=flat-square
   :target: https://pypi.org/project/metablmath/
.. |python versions| image:: https://img.shields.io/pypi/pyversions/metablmath.svg?style=flat-square
   :target: https://pypi.org/project/metablmath/
.. |build status| image:: https://img.shields.io/circleci/project/github/metabolize/blmath/master.svg?style=flat-square
   :target: https://circleci.com/gh/metabolize/blmath
.. |last commit| image:: https://img.shields.io/github/last-commit/metabolize/blmath.svg?style=flat-square
   :target: https://github.com/metabolize/blmath/commits/master
.. |open pull requests| image:: https://img.shields.io/github/issues-pr/metabolize/blmath.svg?style=flat-square
   :target: https://github.com/metabolize/blmath/pulls