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

"""Single-function module.

   See function docstring for description.
"""

#-----------------------------------------------------------------------
#                       Additional Documentation
#
# RCS Revision Code:
#   $Id: virt_temp.py,v 1.2 2004/04/06 20:07:50 jlin Exp $
#
# Modification History:
# - 19 Nov 2003:  Original by Johnny Lin, Computation Institute,
#   University of Chicago.  Email:  air_jlin@yahoo.com.  Passed
#   passably reasonable tests.
#
# Notes:
# - Written for Python 2.2.
# - Module docstrings can be tested using the doctest module.  To
#   test, execute "python virt_temp.py".
# - See import statements throughout for non-"built-in" packages 
#   and modules required.
#
# 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:  virt_temp --------------------

def virt_temp(r_in, T_in, missing=1e+20):
    """Calculate virtual temperature.

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

    Output:
    * Virtual temperature [K].  Numeric array of same dimensions and 
      size as input.  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 without missing values:
    >>> from virt_temp import virt_temp
    >>> import Numeric as N
    >>> r = N.array([5.5e-3, 15e-3, 8.9e-3])
    >>> T = N.array([273.1, 290.2, 288.4])
    >>> a = virt_temp(r, T)
    >>> ['%.8g' % a[i] for i in range(len(a))]
    ['274.00801', '292.80682', '289.94641']

    Example with missing values:
    >>> r = N.array([5.5e-3, 5.4e-3, 6.2e-3, 18e-3])
    >>> T = N.array([283.9, 290.2, 1e+20, 305.7])
    >>> a = virt_temp(r, T, missing=1e+20)
    >>> ['%.8g' % a[i] for i in range(len(a))]
    ['284.84392', '291.14742', '1e+20', '308.98555']
    """
    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(r_in, T_in) != 1:
        raise TypeError, "virt_temp:  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:
        r = MA.masked_array(r_in)
        T = MA.masked_array(T_in)
    else:
        r = MA.masked_values(r_in, missing, copy=0)
        T = MA.masked_values(T_in, missing, copy=0)


    #- Test r and T arrays weren't reversed:

    if MA.maximum(r) > 50.0:
        raise ValueError, "virt_temp:  r and T likely reversed"


    #- Load atmospheric constants:

    const = AtmConst()


    #- Calculate/return virtual temp. (vt) using eqn. 4.3.1 (Emanuel, 
    #  p. 112):

    return MA.filled( T * (1.0 + (r/const.epsilon)) / (1.0 + r) \
                    , missing )




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

#- Define additional examples for doctest to use:

__test__ = { 'Additional Example 1':
    """
    >>> from virt_temp import virt_temp
    >>> import Numeric as N
    >>> r = N.array([20e-3, 1e+20, 3.9e-3])
    >>> T = N.array([303.16, 243.15, 293.15])
    >>> a = virt_temp(r, T, missing=1e+20)
    >>> ['%.8g' % a[i] for i in range(len(a))]
    ['306.77318', '1e+20', '293.84223']
    >>> a = virt_temp(T, r, missing=1e+20)
    Traceback (most recent call last):
        ...
    ValueError: virt_temp:  r and T likely reversed
    """ }


#- 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__.  The parent directory is added to sys.path for this 
    module testing case.
    """
    import doctest, sys, os
    sys.path.append(os.pardir)
    doctest.testmod(sys.modules[__name__])




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