#!/usr/bin/python -tt
#=======================================================================
#                        General Documentation

"""Single-function module.

   See function docstring for description.
"""

#-----------------------------------------------------------------------
#                       Additional Documentation
#
# RCS Revision Code:
#   $Id: eice.py,v 1.2 2004/04/06 20:07:49 jlin Exp $
#
# Modification History:
# - 15 Oct 2003:  Original by Johnny Lin, Computation Institute,
#   University of Chicago.  Email:  air_jlin@yahoo.com.  Passed
#   passably reasonable tests.
# - 15 Nov 2003:  Added capability to accomodate missing values.
#   Passed passably reasonable tests.
#
# Notes:
# - Written for Python 2.2.
# - Module docstrings can be tested using the doctest module.  To
#   test, execute "python eice.py".
# - Non-"built-in" packages and modules required:  atmqty
#
# Copyright (c) 2003 by Johnny Lin.  For licensing, distribution 
# conditions, contact information, and additional documentation see
# the URL http://www.johnny-lin.com/py_pkgs/atmqty/.
#=======================================================================




#---------------- Module General Import and Declarations ---------------

#- Set module version number to package version number:

import package_version
__version__ = package_version.version
del package_version




#----------------------- General Function:  eice -----------------------

def eice(T_in, missing=1e+20):
    """Calculate saturation vapor pressure over liquid water.

    Method Arguments:
    * T_in:  Temperature [K].  Numeric floating point array of any 
      number of dimensions and size.  Required.
    * missing:  If T_in has missing values, this is the missing
      value value.  Floating point scalar.  Default is 1e+20.

    Output:
    * Saturation vapor pressure over liquid water [hPa].  Numeric 
      array of same dimensions and size as T_in.  If there are any
      missing values in output, those values are set to the value
      in argument missing from the input.  If there are missing 
      values in the output due to math errors and missing is set 
      to None, output will fill those missing values with the MA 
      default value of 1e+20.

    Reference:
    * Emanuel, K. A. (1994):  Atmospheric Convection.  New York, NY:
      Oxford University Press, 580 pp.

    Example:
    >>> import eice
    >>> import Numeric as N
    >>> T = N.array([273.1, 260.2, 252.4])
    >>> a = eice.eice(T)
    >>> ['%.7g' % a[i] for i in range(len(a))]
    ['6.081874', '1.990642', '0.9588231']
    >>> T = N.array([273.1, 1e20, 252.4])
    >>> a = eice.eice(T, missing=1e20)
    >>> ['%.7g' % a[i] for i in range(len(a))]
    ['6.081874', '1e+20', '0.9588231']
    """
    import atmqty
    import MA
    import Numeric as N
    from atmconst import AtmConst
    from is_numeric_float import is_numeric_float


    #- Check input is of the correct type:

    if is_numeric_float(T_in) != 1:
        raise TypeError, "eice:  Arg not Numeric floating"


    #- Change input to MA:  just set to input value unless there
    #  are missing values, in which case add mask:
  
    if missing == None:
        T = MA.masked_array(T_in)
    else:
        T = MA.masked_values(T_in, missing, copy=0)


    #- Check T range since equation to calculate eice is only 
    #  "moderately" good from -80C to 0C:

    const = AtmConst()
    if (MA.minimum(T) < (const.C2K_add_offset-80.)) or \
       (MA.maximum(T) > (const.C2K_add_offset+0.0)):
        raise ValueError, "eice:  T out of range"


    #- Calculate and return eice using eqn. 4.4.15 (Emanuel, p. 117):

    return MA.filled( MA.exp( 23.33086 - (6111.72784 / T) \
                      + (0.15215 * MA.log(T)) ) \
                    , missing )




#-------------------------- Main:  Test Module -------------------------

#- Define additional examples for doctest to use:

__test__ = { 'Additional Example 1':
    """
    >>> import eice
    >>> import Numeric as N
    >>> T = N.array([273.15, 263.15, 233.15])
    >>> a = eice.eice(T)
    >>> ['%.6f' % a[i] for i in range(len(a))]
    ['6.107009', '2.594743', '0.128300']
    >>> T = N.array([273.15, 263.15, 233.15, 150.0])
    >>> a = eice.eice(T)
    Traceback (most recent call last):
        ...
    ValueError: eice:  T out of range
    """ }


#- Execute doctest if module is run from command line:

if __name__ == "__main__":
    """Test the module.

    Tests the examples in all the module documentation strings, plus 
    __test__.

    Note:  On at least 2 platforms the doctest module does not execute
    the commands in $HOME/.pythonrc.py when "python eice.py" is
    executed at the command line.  Since atmqty might not be included
    on the default Python path, specifying it in .pythonrc.py is one
    way to insure Python can access the package in an interactive
    session.  If doctest does not execute .pythonrc.py, any call to 
    atmqty will fail.
    
    As the eice module requires the atmqty package (in order to 
    access the AtmConst class) and eice is distributed as part of the 
    atmqty package, the parent directory to the atmqty directory is 
    added to sys.path for this module testing case to enable doctest
    to work on eice.
    """
    import doctest, sys, os
    sys.path.append(os.pardir)
    doctest.testmod(sys.modules[__name__])




# ===== end file =====