!     path:      $Source$
!     author:    $Author: mike $
!     revision:  $Revision: 11661 $
!     created:   $Date: 2009-05-22 18:22:22 -0400 (Fri, 22 May 2009) $
!------------------------------------------------------------------------

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

 Original version:   Eli. J. Mlawer, J. S. Delamere, 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_SW/RRTM_SW):  
             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, J. Geophys. Res., 113, D13103, doi:
             10.1029/2008JD009944, 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. 

 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_SW, a correlated k-distribution shortwave radiative transfer 
model developed at AER, Inc. for application to GCMs.  This version of RRTMG_SW 
utilizes a two-stream radiative transfer method as implemented at ECMWF. This
code has also been modified to utilize FORTRAN90 coding features. Two modes of
operation are possible.  RRTMG_SW 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 as a callable subroutine. 

The version of RRTMG_SW provided here utilizes a reduced complement of 112 
g-points, which is half of the 224 g-points used in the standard RRTM_SW, and
a two-stream method for radiative transfer. Additional minor changes have been 
made to enhance computational performance.  Total fluxes are accurate to within 
1-2 W/m2 relative to the standard RRTM_SW (using DISORT) in clear sky and in the
presence of aerosols and within 6 W/m2 in overcast sky.  RRTM_SW with DISORT is
itself accurate to within 2 W/m2 of the data-validated multiple scattering 
model, CHARTS.  Absorption coefficient data can be read in from original 
source statements or from a netCDF file as selected in the makefile. 

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.  Without McICA,
RRTMG_SW is limited to clear sky or overcast cloud conditions.


***********************
RRTMG_SW column version
***********************

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

   README                    : Basic code package information (this file)
   release_notes.txt         : Code archive update information
   rrtmg_sw_instructions.txt : 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_SW in stand-alone mode as a column model:

   rrtmg_sw.1col.f90         : Main module
   rrtmg_sw_cldprop.f90      : Calculation of cloud optical properties
   rrtmg_sw_cldprmc.f90      : Calculation of cloud optical properties (McICA)
   rrtmg_sw_init.f90         : RRTMG_SW initialization routine; reduces g-intervals
                               from 224 to 112
   rrtmg_sw_k_g.f90          : Absorption coefficient data file
   rrtmg_sw_read_nc.f90      : Alternate absorption coefficient data netCDF input
   rrtmg_sw_reftra.f90       : Calculation of two-stream reflectivities and 
                               transmissivities
   rrtmg_sw_setcoef.f90      : Set up routine
   rrtmg_sw_spcvrt.f90       : Top subroutine for two-stream model
   rrtmg_sw_spcvmc.f90       : Top subroutine for two-stream model (McICA)
   rrtmg_sw_taumol.f90       : Calculation of optical depths and Planck fractions for 
                               each spectral band
   rrtmg_sw_vrtqdr.f90       : Two-stream vertical quadrature 
   mcica_random_numbers.f90  : Random number generator for McICA
   mcica_subcol_gen_sw.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_SW 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
   parrrsw.f90               : main configuration parameters
   rrsw_aer.f90              : aerosol property coefficients
   rrsw_cld.f90              : cloud property coefficients
   rrsw_con.f90              : constants
   rrsw_kg**.f90             : absorption coefficient arrays for 16 spectral bands
   rrsw_ncpar.f90            : parameters for netCDF input data option
   rrsw_ref.f90              : reference atmosphere data arrays
   rrsw_tbl.f90              : exponential lookup table arrays
   rrsw_vsn.f90              : version number information
   rrsw_wvn.f90              : spectral band and g-interval array information


INPUT DATA:
   The following file (in directory /column_model/data) is the netCDF file
   containing absorption coefficient and other input data for the model.
   The file is used if netCDF input is selected in the makefile. 

   rrtmg_sw.nc               : Optional netCDF input data file


MAKEFILES:
   The following files (in directory /column_model/build/makefiles) can be used to compile 
   RRTMG_SW 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_sw_sgi         : Sample makefile for SGI
   make_rrtmg_sw_sun         : Sample makefile for SUN
   make_rrtmg_sw_linux_pgi   : Sample makefile for LINUX (PGI compiler)
   make_rrtmg_sw_aix_xlf90   : Sample makefile for AIX (XLF90 compiler)
   make_rrtmg_sw_OS_X_g95    : Sample makefile for OS_X (G95 compiler)
   make_rrtmg_sw_OS_X_ibm_xl : Sample makefile for OS_X (IBM XL 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-clr        : Sample 51 layer mid-latitude summer standard atmosphere
   input_rrtm.MLS-cld-imca0  : Sample 51 layer mid-latitude summer standard atmosphere
                               with cloud flag turn on (without McICA)
   input_rrtm.MLS-cld-imca1  : Sample 51 layer mid-latitude summer standard atmosphere
                               with cloud flag turn on (with McICA)
   input_rrtm.MLS-clr-aer12  : Sample 51 layer mid-latitude summer standard atmosphere
                               with aerosol flag set
   input_rrtm.MLW-clr        : Sample 51 layer mid-latitude winter standard atmosphere
   input_rrtm.SAW-clr        : Sample 51 layer sub-arctic winter standard atmosphere
   input_rrtm.TROP-clr       : Sample 51 layer tropical standard atmosphere
   in_cld_rrtm-cld5          : Sample cloud input file
   in_aer_rrtm-aer12         : Sample aerosol input file



*********************
RRTMG_SW: 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_SW as a callable subroutine:
   NOTE: Only one of rrtmg_sw_k_g.f90 or rrtmg_sw_read_nc.f90 is required. 

   rrtmg_sw_rad.f90          : RRTMG_SW main module (with McICA)
   rrtmg_sw_rad.nomcica.f90  : Optional RRTMG_SW main module (without McICA only)
   rrtmg_sw_cldprop.f90      : Calculation of cloud optical properties
   rrtmg_sw_cldprmc.f90      : Calculation of cloud optical properties (McICA)
   rrtmg_sw_init.f90         : RRTMG_SW initialization routine; reduces g-intervals
                               from 224 to 112; (This has to run only once and should 
                               be installed in the GCM initialization section)
   rrtmg_sw_k_g.f90          : Absorption coefficient data file
   rrtmg_sw_read_nc.f90      : Alternate absorption coefficient data netCDF input
   rrtmg_sw_reftra.f90       : Calculation of two-stream reflectivities and 
                               transmissivities
   rrtmg_sw_setcoef.f90      : Set up routine
   rrtmg_sw_spcvrt.f90       : Top subroutine for two-stream model
   rrtmg_sw_spcvmc.f90       : Top subroutine for two-stream model (McICA)
   rrtmg_sw_taumol.f90       : Calculation of optical depths and Planck fractions for 
                               each spectral band
   rrtmg_sw_vrtqdr.f90       : Two-stream vertical quadrature 
   mcica_random_numbers.f90  : Random number generator for McICA
   mcica_subcol_gen_sw.f90   : Sub-column generator for McICA

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

   parkind.f90               : real and integer kind type parameters
   parrrsw.f90               : main configuration parameters
   rrsw_aer.f90              : aerosol property coefficients
   rrsw_cld.f90              : cloud property coefficients
   rrsw_con.f90              : constants
   rrsw_kg**.f90             : absorption coefficient arrays for 16 spectral bands
   rrsw_ncpar.f90            : parameters for netCDF input data option
   rrsw_ref.f90              : reference atmosphere data arrays
   rrsw_tbl.f90              : exponential lookup table arrays
   rrsw_vsn.f90              : version number information
   rrsw_wvn.f90              : spectral band and g-interval array information


INPUT DATA:
   The following file (in directory /gcm_model/data) is the netCDF file
   containing absorption coefficient and other input data for the model.
   The file is used if source file rrtmg_sw_read_nc.f90 is used in place
   of rrtmg_sw_k_g.f90 (only one or the other is required). 

   rrtmg_sw.nc               : Optional netCDF input data file


Notes regarding GCM version:

   1) The module rrtmg_sw_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_SW 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_SW through the subroutine call along with the other model
      profile arrays.

   3) To utilize McICA, the sub-column generator (mcica_subcol_gen_sw.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_sw.f90.
      When using McICA, the main RRTMG_SW module is rrtmg_sw_rad.f90.  If McICA is not
      used, then the main module is rrtmg_sw_rad.nomcica.f90, though cloud specification
      is limited to overcast clouds.

