====================
Quantities and Units
====================

Introduction
------------

We want to be able to use physical quantities rather than just
measures (represented by e.g. floats or integers on computers) in
order to raise the ambiguity caused by the implicit choice of
units. Serving this purpose, AMUSE comes with a **quantity** class. Like
particle sets (fundamental data structure in AMUSE), quantities are
fundamental variables. When interacting with code all data has units,
even scaled systems. In handling quantities we regard units as being
integral part of the mathematical description of the variable
[D.C. Ipsen, Units, Dimension, and Dimensionless Numbers, 1960,
McGraw-Hill Book Company], i.e. we can state things like:

1 AU = 149597870.691 km

.. code-block:: python

    >>> from amuse.units import units
    >>> q1 = 1.0|units.MSun
    >>> q2 = 1.98892e30|units.kg
    >>> q1 == q2
    True

Quantity objects have basic conversion ability, when different units
belonging to the same dimension exist the quantity object will convert
from one to the other. For more elaborate conversion facilities, like
interfacing with a natural unit code, AMUSE provides the
generic_unit_converter and the derived nbody_system modules.  


Quantities
----------

.. inheritance-diagram:: amuse.units.quantities

.. automodule:: amuse.units.quantities
    
    .. autoclass:: Quantity
        :members:
   
    .. autoclass:: ScalarQuantity
        :members:

    .. autoclass:: VectorQuantity
        :members:

        .. automethod:: __getitem__
       
        .. automethod:: __setitem__
    
    .. autoclass:: NonNumericQuantity
        :members:
        

Units
-----
.. inheritance-diagram:: amuse.units.core

.. automodule:: amuse.units.core
    :members:

Unit systems and converters
---------------------------

The amuse framework gives you the ability to choose a unit system for
your model through the 'generic_unit_converter' module.  This enables
you to work with e.g. natural units or n-body units within AMUSE.

The implementation makes use of a dimension-space, which is a
vector-space where the chosen units form a base. For a detailed
description of the method see e.g.: Maksymowicz, A, *American Journal
of Physics*, Vol.44, No.3, **1976**.         
    
Generic units
~~~~~~~~~~~~~

.. automodule:: amuse.units.generic_unit_system

N-body units
~~~~~~~~~~~~

.. automodule:: amuse.units.nbody_system

Converter
~~~~~~~~~

.. automodule:: amuse.units.generic_unit_converter

     .. autoclass:: ConvertBetweenGenericAndSiUnits
         :members:
                     
Use with codes
~~~~~~~~~~~~~~

For convenience, the gravitational dynamics interface works with a
unit-converter which converts between the units used by the code and
the preferred units in the script (user's choice).

We show two examples. The first one uses the (derived from the generic
units converter) nbody_system converter, which is the logical choice
for dynamics (n-body) codes.

The second one uses the generic unit converter directly, this is just
an example.

~~~~~~~~~~~~~~~~
Usage: example 1
~~~~~~~~~~~~~~~~

.. code-block:: python

    >>> from amuse.community.hermite0.interface import Hermite
    >>> from amuse.units import nbody_system
    >>> from amuse.units import constants, units
    >>> convert_nbody = nbody_system.nbody_to_si(1.0 | units.MSun, 149.5e6 | units.km)
    >>> hermite = Hermite(convert_nbody)

~~~~~~~~~~~~~~~~
Usage: example 2
~~~~~~~~~~~~~~~~

.. code-block:: python
    
    >>> from amuse.community.hermite0.interface import Hermite
    >>> from amuse.units import generic_unit_converter as gc
    >>> from amuse.units import constants, units
    >>> converter = gc.ConvertBetweenGenericAndSiUnits(constants.G, 1.0 | units.MSun, 1 | units.AU) 
    >>> hermite = Hermite(converter)

~~~~~~~
Example
~~~~~~~

More examples can be found in the tutorial, :ref:`working_with_units`

.. automodule:: amuse.community.interface.gd

    .. autoclass:: GravitationalDynamics
        :members: __init__