##############################################################################
# MDTraj: A Python Library for Loading, Saving, and Manipulating
#         Molecular Dynamics Trajectories.
# Copyright 2012-2013 Stanford University and the Authors
#
# Authors: Robert McGibbon
# Contributors:
#
# MDTraj is free software: you can redistribute it and/or modify
# it under the terms of the GNU Lesser General Public License as
# published by the Free Software Foundation, either version 2.1
# of the License, or (at your option) any later version.
#
# This library is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public
# License along with MDTraj. If not, see <http://www.gnu.org/licenses/>.
##############################################################################
"""

Unit processing for MDTraj. This subpackage is a port of simtk.unit from
OpenMM. Unlike in simtk.openmm, the MDTraj library **does not pass around
"united quantities"**

The only publicly facing API from this package, for the purpose of MDTraj,
is "in_units_of", which does unit conversion of numbers or numpy arrays
where the input and output units are passed as strings.

"""
import ast
import sys
import numpy as np
from mdtraj.utils.unit.quantity import Quantity
from mdtraj.utils.unit import unit_definitions
from mdtraj.utils import import_, six
UNIT_DEFINITIONS = unit_definitions
try:
    import simtk.unit as simtk_unit
except ImportError:
    pass

__all__ = ['in_units_of']

class _UnitContext(ast.NodeTransformer):
    """Node transformer for an AST hack that turns raw strings into
    complex simt.unit.Unit expressions. See _str_to_unit for how this
    is used -- it's not really meant to stand on its own
    """
    # we want to do some validation to ensure that the AST only
    # contains "safe" operations. These are operations that can reasonably
    # appear in unit expressions
    allowed_ops = [ast.Expression, ast.BinOp, ast.Name, ast.Attribute,
                   ast.Pow, ast.Div, ast.Mult, ast.Num]

    def visit(self, node):
        if not any(isinstance(node, a) for a in self.allowed_ops):
            raise ValueError('Invalid unit expression. Contains dissallowed '
                             'operation %s' % node.__class__.__name__)
        return super(_UnitContext, self).visit(node)

    def visit_Name(self, node):
        # we want to prefix all names to look like unit.nanometers instead
        # of just "nanometers", because I don't want to import * from
        # units into this module
        if not hasattr(unit_definitions, node.id):
            # also, let's take this opporunity to check that the node.id
            # (which supposed to be the name of the unit, like "nanometers")
            # is actually an attribute in simtk.unit
            raise ValueError('%s is not a valid unit' % node.id)

        return ast.Attribute(value=ast.Name(id='unit_definitions', ctx=ast.Load()),
                             attr=node.id, ctx=ast.Load())
_unit_context = _UnitContext()  # global instance of the visitor


def _str_to_unit(unit_string, simtk=False):
    """eval() based transformer that extracts a simtk.unit object
    from a string description.

    Parameters
    ----------
    unit_string : str
        string description of a unit. this may contain expressions with
        multiplication, division, powers, etc.

    Examples
    --------
    >>> type(_str_to_unit('nanometers**2/meters*gigajoules'))
    <class 'simtk.unit.unit.Unit'>
    >>> str(_str_to_unit('nanometers**2/meters*gigajoules'))
    'nanometer**2*gigajoule/meter'

    """
    # parse the string with the ast, and then run out unit context
    # visitor on it, which will basically change bare names like
    # "nanometers" into "unit.nanometers" and simulataniously check that
    # there's no nefarious stuff in the expression.

    assert isinstance(unit_string, six.string_types)
    unit_definitions = UNIT_DEFINITIONS
    if simtk:
        unit_definitions = import_('simtk.unit').unit_definitions
    parsed = ast.parse(unit_string, mode='eval')
    node = _unit_context.visit(parsed)
    fixed_node = ast.fix_missing_locations(node)
    output = eval(compile(fixed_node, '<string>', mode='eval'), {}, locals())
    return output


def in_units_of(quantity, units_in, units_out, inplace=False):
    """Convert a numerical quantity between unit systems.

    Parameters
    ----------
    quantity : {number, np.ndarray, simtk.unit.Quantity}
        quantity can either be a unitted quantity -- i.e. instance of
        simtk.unit.Quantity, or just a bare number or numpy array
    units_in : str
        If you supply a quantity that's not a simtk.unit.Quantity, you should
        tell me what units it is in. If you don't, i'm just going to echo you
        back your quantity without doing any unit checking.
    units_out : str
        A string description of the units you want out. This should look
        like "nanometers/picosecond" or "nanometers**3" or whatever
    inplace : bool
        Attempt to do the transformation inplace, by mutating the `quantity`
        argument and avoiding a copy. This is only possible if `quantity` is a
        writable numpy array.

    Returns
    -------
    rquantity : {number, np.ndarray}
        The resulting quantity, in the new unit system. If the function was
        called with `inplace=True` and `quantity` was a writable numpy array,
        `rquantity` will alias the same memory as the input `quantity`, which
        will have been changed inplace. Otherwise, if a copy was required,
        `rquantity` will point to new memory.

    Examples
    --------
    >>> in_units_of(1, 'meter**2/second', 'nanometers**2/picosecond')
    1000000.0
    """
    if quantity is None:
        return quantity

    if 'simtk.unit' in sys.modules and isinstance(quantity, simtk_unit.Quantity):
        units_in = quantity.unit
        units_out = _str_to_unit(units_out, simtk=True)
        quantity = quantity._value
    elif isinstance(quantity, Quantity):
        units_in = quantity.unit
        units_out = _str_to_unit(units_out)
        quantity = quantity._value
    else:
        if units_in is None:
            return quantity
        units_in = _str_to_unit(units_in)
        units_out = _str_to_unit(units_out)

    if not units_in.is_compatible(units_out):
        raise TypeError('Unit "%s" is not compatible with Unit "%s".' % (units_in, units_out))

    factor = units_in.conversion_factor_to(units_out)
    if inplace and (isinstance(quantity, np.ndarray) and quantity.flags['WRITEABLE']):
        quantity *= factor
        return quantity
    return quantity * factor

