########
  natu
########

**Natural units in Python**

.. warning:: This project is currently in a pre-release state.  It will be
   officially released once the unit tests are complete.

natu_ is a free, open-source package to represent physical quantities.  There
are `many Python packages that deal with units and quantities
<http://kdavies4.github.io/natu/seealso.html>`_, but natu_ is uniquely
system-independent.  The units are derived from physical constants with
adjustable values and dimensions.  The value of a unit is factored into a
quantity so that the quantity is not "in" any particular unit.  This has the
following advantages:

- **Flexible**: Different unit systems, including `natural units`_ (hence the
  name "natu"), can be represented by simply adjusting the `base physical
  constants <http://kdavies4.github.io/natu/base-ini.html>`_.
- **Simple**: Unit conversion is inherent.  This results in quick computations
  and a small code base (about  1500 lines).  By default, dimensions and display
  units are tracked to catch errors and for string formatting.  This can be
  disabled to nearly eliminate the computational overhead while still providing
  the core features.
- **Intuitive**: Each unit is a fixed quantity that is treated as a
  mathematical entity.  A variable quantity is expressed as the product of a
  number and a unit, as stated by BIPM_.
- **Representative**: The design reflects the way modern units are defined.
  Standards organizations such as NIST_ assign values to universal physical
  constants so that the values of units can be determined by physical
  experiments instead of prototypes.
- **Scalable**: The values of the base physical constants can scaled to prevent
  exponent overflow, regardless of the units used.

For example, you can do this:

    >>> from natu.units import degC, K
    >>> 0*degC + 100*K
    100.0 degC

Please see `the main website`_ and `the tutorial
<http://nbviewer.ipython.org/github/kdavies4/natu/blob/master/examples/tutorial.ipynb>`_
for more examples.

Installation
~~~~~~~~~~~~

The easiest way to install natu_ is to use pip_::

    > pip install natu

On Linux, it may be necessary to have root privileges::

    $ sudo pip install natu

License terms and development
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

natu_ is published under a `BSD-compatible license
<https://github.com/kdavies4/natu/blob/master/LICENSE.txt>`_.  Please share any
improvements you make, preferably as a pull request to the ``master`` branch of
the `GitHub repository`_.  There are useful development scripts in the `hooks
folder <https://github.com/kdavies4/natu/blob/master/hooks/>`_.  If you find a
bug, have a suggestion, or just want to leave a comment, please `open an issue
<https://github.com/kdavies4/natu/issues/new>`_.


.. _natural units: http://en.wikipedia.org/wiki/Natural_units
.. _Python Standard Library: https://docs.python.org/3/library/
.. _GitHub repository: https://github.com/kdavies4/natu
.. _NIST: http://www.nist.gov/
.. _BIPM: http://www.bipm.org/
.. _pip: https://pypi.python.org/pypi/pip
.. _degree Celsius (degC): http://en.wikipedia.org/wiki/Celsius
.. _decibel (dB): http://en.wikipedia.org/wiki/Decibel
.. _coherent relations: http://en.wikipedia.org/wiki/Coherence_(units_of_measurement)
.. _statcoulomb: http://en.wikipedia.org/wiki/Statcoulomb
.. _math: https://docs.python.org/3/library/math.html
.. _numpy: http://numpy.scipy.org/
.. _the main website: http://kdavies4.github.io/natu/
