!     path:      $Source: /storm/rc1/cvsroot/rc/rrtmg_lw/README,v $
!     author:    $Author: mike $
!     revision:  $Revision: 1.8 $
!     created:   $Date: 2008/04/24 16:17:25 $
! ---------------------------------------------------------------------

 RRTMG_LW: Longwave Radiative Transfer Model for GCMs
 Atmospheric and Environmental Research, Inc., 
 131 Hartwell Avenue, Lexington, MA 02421

 Original version:   E. J. Mlawer, et al. (AER)
 Revision for GCMs:  Michael J. Iacono (AER)

 Contact:  Michael J. Iacono   (E-mail: miacono@aer.com)

 Web Site: www.rtweb.aer.com

 References (RRTMG_LW/RRTM_LW): 
             Iacono, M.J., J.S. Delamere, E.J. Mlawer, M.W. Shephard,
             S.A. Clough, and W.D. Collins, Radiative forcing by long-
             lived greenhouse gases: Calculations with the AER radiative
             transfer models, accepted by J. Geophys. Res., 2008.

             Clough, S.A., M.W. Shephard, E.J. Mlawer, J.S. Delamere, 
             M.J. Iacono, K. Cady-Pereira, S. Boukabara, and P.D. Brown,
             Atmospheric radiative transfer modeling: a summary of the
             AER codes, J. Quant., Spectrosc. Radiat. Transfer, 91, 
             233-244, 2005.
  
             Iacono, M.J., J.S. Delamere, E.J. Mlawer, and S.A. Clough,
             Evaluation of upper tropospheric water vapor in the NCAR
             Community Climate Model (CCM3) using modeled and observed
             HIRS radiances. J. Geophys. Res., 108(D2), 4037, doi:10.1029/
             2002JD002539, 2003.

             Iacono, M.J., E.J. Mlawer, S.A. Clough, and J.-J. Morcrette,
             Impact of an improved longwave radiation model, RRTM, on the
             energy budget and thermodynamic properties of the NCAR Community
             Climate Model, CCM3, J. Geophys. Res., 105, 14873-14890, 2000.

             Mlawer, E.J., S.J. Taubman, P.D. Brown, M.J. Iacono, and S.A.
             Clough:  Radiative transfer for inhomogeneous atmospheres: RRTM,
             a validated correlated-k model for the longwave.  J. Geophys.
             Res., 102, 16663-16682, 1997.

 Reference (McICA):
             Pincus, R., H. W. Barker, and J.-J. Morcrette, A fast, flexible,
             approximation technique for computing radiative transfer in
             inhomogeneous cloud fields, J. Geophys. Res., 108(D13), 4376,
             doi:10.1029/2002JD003322, 2003.
******************************************************************************

This package contains the source code and sample makefiles necessary to run the
latest version of RRTMG_LW, a correlated k-distribution longwave radiative transfer 
model developed at AER, Inc for application to GCMs.  This version of RRTMG_LW 
has been modified from the standard RRTM_LW distributed by AER to enhance its 
performance for use within general circulation models.  This code has also
been modified to utilize FORTRAN90 coding features.  Two modes of operation 
are possible.  RRTMG_LW can be run in stand-alone mode using the input files 
and source modules described below, or it can be attached to an atmospheric 
general circulation model or single column model.

The version of RRTMG_LW provided here has been modified from the standard 
RRTM_LW to enhance performance with little effect on the accuracy.  The total 
number of g-points used has been reduced from 256 to 140. Fluxes are accurate
to within 0.5 W/m2 and cooling rate within 0.1 K/day relative to the standard
RRTM_LW, which is itself accurate to within 1 W/m2 of the data-validated 
line-by-line radiative transfer model, LBLRTM.  

This model can also utilize McICA, the Monte-Carlo Independent Column 
Approximation, to represent sub-grid scale cloud variability such as cloud 
fraction and cloud overlap.  If the McICA option is selected to model a cloudy 
profile in column mode, then the model will run stochastically, and the output 
fluxes and heating rates will be an average over 200 samples. 


*************************
RRTMG_LW : Column Version
*************************

DOCUMENTATION:
   The following text files (some in /column_model/doc directory) provide information
   on using and running RRTMG_LW:

   README                    : Basic code package information (this file)
   README.release_notes      : Code archive update information
   rrtmg_lw_instructions     : Input instructions for files INPUT_RRTM, IN_CLD_RRTM 
                               and IN_AER_RRTM


SOURCE CODE:
   The following source files (in /column_model/src directory) must be used to run 
   RRTMG_LW in stand-alone mode as a column model:

   rrtmg_lw.1col.f90         : RRTMG_LW main module
   rrtmg_lw_cldprop.f90      : Calculation of cloud optical properties
   rrtmg_lw_cldprmc.f90      : Calculation of cloud optical properties (McICA)
   rrtmg_lw_init.f90         : RRTMG_LW initialization routine; reduces g-intervals
                               from 256 to 140
   rrtmg_lw_k_g.f90          : Absorption coefficient data file
   rrtmg_lw_rtrn.f90         : Calculation of clear and cloudy radiative transfer 
                               using random cloud overlap
   rrtmg_lw_rtrnmr.f90       : Calculation of clear and cloudy radiative transfer
                               using maximum-random cloud overlap
   rrtmg_lw_rtrnmc.f90       : Calculation of clear and cloudy radiative transfer
                               using McICA (with selectable overlap method)
   rrtmg_lw_setcoef.f90      : Set up routine
   rrtmg_lw_taumol.f90       : Calculation of optical depths and Planck fractions for 
                               each spectral band
   mcica_random_numbers.f90  : Random number generator for McICA
   mcica_subcol_gen_lw.1col.f90 : Sub-column generator for McICA
   rrtatm.f                  : Process user-defined input data files
   extra.f                   : Process input data files
   util_**.f                 : Utilities (available for multiple platforms)

   The following module files (in /column_model/modules directory) must be used to run 
   RRTMG_LW in stand-alone mode as a column model (these must be compiled before the
   source code files):

   parkind.f90               : real and integer kind type parameters
   parrrtm.f90               : main configuration parameters
   rrlw_cld.f90              : cloud property coefficients
   rrlw_con.f90              : constants
   rrlw_kg**.f90             : absorption coefficient arrays for 16 spectral bands
   rrlw_ref.f90              : reference atmosphere data arrays
   rrlw_tbl.f90              : exponential look up table arrays
   rrlw_vsn.f90              : version number information
   rrlw_wvn.f90              : spectral band and g-interval array information


MAKEFILES:
   The following files (in directory /column_model/build/makefiles) can be used to 
   compile RRTMG_LW in stand-alone mode as a column model on various platforms.  Link 
   one of these into the /column_model/build directory to compile. 

   make_rrtmg_lw_sgi         : Sample makefile for SGI
   make_rrtmg_lw_sun         : Sample makefile for SUN
   make_rrtmg_lw_linux_pgi   : Sample makefile for LINUX (PGI compiler)
   make_rrtmg_lw_aix_xlf90   : Sample makefile for AIX (XLF90 compiler)
   make_rrtmg_lw_OS_X_g95    : Sample makefile for OS_X (G95 compiler)


SAMPLE INPUT/OUTPUT: 
   Several sample input (and output) files are included in the /runs_std_atm directory.
   Note that user-defined profiles may be used for as many as 200 layers.

   INPUT_RRTM                : Required input file for (clear sky) atmospheric 
                               specification 
   IN_CLD_RRTM               : Required input file for cloud specification if clouds
                               are present
   IN_AER_RRTM               : Required input file for aerosol specification if aerosols
                               are present
   OUTPUT_RRTM               : Main output file for atmospheric fluxes and heating rates
   input_rrtm.MLS            : Sample 51 layer mid-latitude summer standard atmosphere
   input_rrtm.MLS-cld-imca0  : Sample 51 layer mid-latitude summer standard atmosphere
                               with cloud flag turned on (without McICA)
   input_rrtm.MLS-cld-imca1  : Sample 51 layer mid-latitude summer standard atmosphere
                               with cloud flag turned on (with McICA)
   input_rrtm.MLS-xsec       : Sample 51 layer mid-latitude summer standard atmosphere
                               with cross-section input (CFCs, etc.)
   input_rrtm.MLW            : Sample 51 layer mid-latitude winter standard atmosphere
   input_rrtm.SAW            : Sample 51 layer sub-arctic winter standard atmosphere
   input_rrtm.TROP           : Sample 51 layer tropical standard atmosphere
   in_cld_rrtm-cld5          : Sample cloud input file



*********************
RRTMG_LW: GCM version
*********************

DOCUMENTATION:
   README                    : Basic code package information (this file)


SOURCE CODE:
   The following source files (in /gcm_model/src directory) must be used to run 
   RRTMG_LW as a callable subroutine:

   rrtmg_lw.f90              : RRTMG_LW main module (with McICA)
   rrtmg_lw.nomcica.f90      : Optional RRTMG_LW main module (without McICA only)
   rrtmg_lw_cldprop.f90      : Calculation of cloud optical properties
   rrtmg_lw_cldprmc.f90      : Calculation of cloud optical properties (McICA)
   rrtmg_lw_init.f90         : RRTMG_LW initialization routine; reduces g-intervals 
                               from 256 to 140; (This has to run only once and should 
                               be installed in the GCM initialization section)
   rrtmg_lw_k_g.f90          : Absorption coefficient data file
   rrtmg_lw_rtrn.f90         : Calculation of clear and cloudy radiative transfer 
                               using random cloud overlap
   rrtmg_lw_rtrnmr.f90       : Calculation of clear and cloudy radiative transfer
                               using maximum-random cloud overlap
   rrtmg_lw_rtrnmc.f90       : Calculation of clear and cloudy radiative transfer
                               using McICA (with selectable overlap method)
   rrtmg_lw_setcoef.f90      : Set up routine
   rrtmg_lw_taumol.f90       : Calculation of optical depths and Planck fractions for 
                               each spectral band
   mcica_random_numbers.f90  : Random number generator for McICA
   mcica_subcol_gen_lw.f90   : Sub-column generator for McICA (must be called in GCM
                               just before call to RRTMG)

   The following module files (in /gcm_model/modules directory) must be used to run 
   RRTMG_LW as a callable subroutine (these must be compiled before the source code
   files)

   parkind.f90               : real and integer kind type parameters
   parrrtm.f90               : main configuration parameters
   rrlw_cld.f90              : cloud property coefficients
   rrlw_con.f90              : constants
   rrlw_kg**.f90             : absorption coefficient arrays for 16 spectral bands
   rrlw_ref.f90              : reference atmosphere data arrays
   rrlw_tbl.f90              : look up table arrays
   rrlw_vsn.f90              : version number information
   rrlw_wvn.f90              : spectral band and g-interval array information


Notes regarding GCM version:

   1) The module rrtmg_lw_init.f90 is the initialization routine that has to be 
      called only once.  The call to this subroutine should be moved to the 
      initialization section of the host model if RRTMG_LW is called by a GCM or SCM. 

   2) The number of model layers and the number of columns to be looped over should
      be passed into RRTMG_LW through the subroutine call along with the other model
      profile arrays.  

   3) To utilize McICA, the sub-column generator (mcica_subcol_gen_lw.f90) must be
      implemented in the GCM so that it is called just before RRTMG.
      If McICA is utilized, this will run only a single statistical sample per
      model grid box.  There are two options for the random number generator used
      with McICA, which is selected with the variable irnd in mcica_subcol_gen_lw.f90.
      When using McICA, then the main module is rrtmg_lw.f90.  If McICA is not used,
      then the main module is rrtmg_lw.nomcica.f90 and the cloud overlap method is
      selected by setting flag icld. 

