/******************************************************************************

   README file for the algorithm 3B-31, "Rainfall Combined", Version 5.0.
   
   Ye Hong	09/09/99

******************************************************************************/

1.  Overview of 3B-31

Algorithm 3B-31, "Rainfall Combined", is to produce monthly surface rainfall 
totals for 5x5 degree boxes and monthly means of hydrometeor contents (cloud
liquid water, rain water, cloud ice, and precipitating ice) for 5x5 degree 
boxes and 14 vertical layers.  This algorithm uses instantaneous rain 
retrievals generated in 2B-31 to calibrate retrievals from 2A-12.  The 2B-31
derived vertical hydrometeor profiles and surface rainfall using data from 
the PR and 10 GHz channels of the TMI and is supposed to provide high quality 
retrievals for the narrow swath.  The 2A-12 provides surface rainfall and
hydrometeor profiles using TMI data in a wide swath.  The ratios of monthly
products from 2B-31 to those from 2A-12 in 5x5 degree boxes will also be 
calculated.


2.  Process of 3B-31

The algorithm 3B-31 is executed once per granule.  For each execution,
output data of 2A-12 and 2B-31 are read and then gridded into 0.5 degree 
boxes.  Accumulations of both products are performed and saved in an
intermediate data file which is read and updated for each execution.  
Since the two products are output at different vertical resolutions, 
averaging the outputs of 2B-31 over several radar range gates to match 
the 14 TMI layers is performed.  Also, the rain rate (mm/hr) at each radar 
gate in 2B-31 is converted into rain water content (g/m^3) to match that 
in 2A-12. 

While reading data of 2A-12 and 2B-31, month period flag (begin/middle/end)
is checked.  For the granule in the beginning (or end) of one month, data 
from the previous (or next) month are skipped.  For the granule in the middle
of one month, all data are processed.   If the flag indicates the beginning
of a month, the 3B-31 will perform the initialization.  If the flag indicates
the end of a month, monthly means are computed for 0.5 x 0.5 degree boxes and 
then added to those for 5 x 5 degree boxes.  Monthly surface rainfall totals 
are derived from multiplying monthly mean by the number of hours of that 
month.  Then the 3B-31 products are written into its output file.

There are substantial changes from version 4.51 to 5.0.  Instead of only 
outputing 2A12 rainfall total and the ratio, the totals of 2B31 and 2A12 
convective rainfall have been added.  In addition, the rainfall totals of 
PR & TMI overlaps are also added.


3.  Inputs of 3B-31

The command line for executing 3B-31 is as follows:

L3B31main <2A12 file id> <2B31 file id> <3b31 file id> <interm. file id>
   <VI file id> <begin/middle/end of month flag> <YY> <MM> 

where

L3B31main:         name of 3B-31 executable file;

<2A12 file id>:    name of 2A-12 HDF file.  This file is used (read only) 
                   for each execution.

<2B31 file id>:    name of 2B-31 HDF file.  This file is used (read only) 
                   for each execution.

<3B31 file id>:    name of 3B-31 HDF file.  This file is used (write only) 
                   only for execution of the last granule in one month 
                   (i.e. when the month period flag is 'end').

<interm. file id>: name of 3B-31 intermediate binary data file.  This file 
                   is used (read and update) for each execution.
                                   
<VI file id>:      name of 3B-31 verification intermediate ASCII file.  This
                   file is used (write) for each execution.

<begin/middle/end of month flag>: character string which indicates whether 
                   the current granule is either at the beginning or end 
                   of the processing month. 

<YY>:              4-byte character string indicating the year of the 
                   current granule
                    
<MM>:              2-byte character string indicating the month of the 
                   current granule     


The naming convention of all files can be found in Reference [1].  All
above arguments are needed for each execution.


4.  Error/Warning messages

E_3B31_INCORRECT_NUM_ARGS: Incorrect number of command line arguments.

   Possible Cause(s):  The number of command line arguments is not correct.
   
   Recommended Action(s): Re-enter the correct number of arguments.
   
E_3B31_INVALID_MONTH_PERIOD_FLAG: Invalid begin/middle/end month period flag.

   Possible Cause(s):  The begin/middle/end month period flag is not valid.
   
   Recommended Action(s):  Insure that one of the following month period flags
   is given: begin(Begin, BEGIN), middle(Middle, MIDDLE) or end(End, END).
   

E_3B31_NOT_ENOUGH_MEMORY: Not enough memory.

   Possible Cause(s):  Insufficient memory for processing 3B-31.
   Recommended Action(s):  Check with system adminstrator.
   
E_3B31_ERROR_READING_2A12METADATA: Error reading 2A-12 metadata.

   Possible Cause(s):  a. 2A-12 HDF file is corrupted; b. 2A-12 metadata is
   in error; c. toolkit package is not updated.
   
   Recommended Action(s):  a. Check if the latest version of TSDIS toolkit is
   used;  b. Contact TSDIS personnel. 
   
E_3B31_ERROR_READING_2B31METADATA: Error reading 2B-31 metadata.
 
   Possible Cause(s):  a. 2B-31 HDF file is corrupted; b. 2B-31 metadata is
   in error; c. toolkit package is not updated.
   Recommended Action(s):  a. Check if the latest version of TSDIS toolkit is
   used;  b. Contact TSDIS personnel. 
   
E_3B31_ERROR_WRITING_3B31METADATA: Error writing 3B-31 metadata.

   Possible Cause(s):  a. Insufficient disk space; b. 3B-31 metadata is in 
   error; c. toolkit package is not updated.
   Recommended Action(s):  a. Ensure there exists sufficient disk space; b. 
   Check if the latest version of TSDIS toolkit is used;  b. Contact TSDIS 
   personnel. 
   
E_3B31_ERROR_OPENING_LOGFILE: Error opening 3B-31 log file. 

   Possible Cause(s):  Insufficient disk space available to creat the new
   3B-31 log file.
   Recommended Action(s):  Ensure that there exists sufficient disk space to
   creat a new file.
   
E_3B31_ERROR_OPENING_2A12FILE: Error opening 2A-12 file.

   Possible Cause(s):  a. 2A-12 HDF file is corrupted; b. Invalid path/file
   name.
   Recommended Action(s):  a. Ensure that the 2A-12 HDF file is fine; b. Enter
   valid path/file name.
   
E_3B31_ERROR_OPENING_2B31FILE: Error opening 2B-31 file.

   Possible Cause(s):  a. 2B-31 HDF file is corrupted; b. Invalid path/file
   name.
   Recommended Action(s):  a. Ensure that the 2B-31 HDF file is fine; b. Enter
   valid path/file name.
   
E_3B31_ERROR_OPENING_3B31FILE: Error opening 3B-31 file.

   Possible Cause(s):  Insufficient disk space available to creat a new 3B-31
   HDF file.
   Recommended Action(s):  Ensure that there exists sufficient disk space to
   creat a new file.
   
E_3B31_ERROR_OPENING_INTMFILE: Error opening intermediate monthly data file.

   Possible Cause(s):  a. Invalid path/file name;  b. 3B-31 intermediate 
   accumulation file is corrupted;
   Recommended Action(s):  a. Enter valid path/file name;  b. Check if the 
   file has the correct size of 46,540,800 bytes.  If not, delete the 
   corrupted file and re-run all previous granules in that month.
   
E_3B31_ERROR_READING_2A12FILE: Error reading 2A-12 file.

   Possible Cause(s):  a. 2A-12 HDF file is corrupted; b. 2A-12 science data
   is in error; c. toolkit package is not updated.
   Recommended Action(s):  a. Check if the latest version of TSDIS toolkit is
   used;  b. Contact TSDIS personnel.
   
E_3B31_ERROR_READING_2B31FILE: Error reading 2B-31 file.

   Possible Cause(s):  a. 2B-31 HDF file is corrupted; b. 2B-31 science data
   is in error; c. toolkit package is not updated.
   Recommended Action(s):  a. Check if the latest version of TSDIS toolkit is
   used;  b. Contact TSDIS personnel.
   
E_3B31_ERROR_READING_INTMFILE: Error reading intermediate monthly data file.

   Possible Cause(s):  3B-31 intermediate accumulation file is corrupted;
   Recommended Action(s):  Check if the file has the correct size of 
   46,540,800 bytes.  If not, delete the corrupted file and re-run all 
   previous granules in that month.
   
E_3B31_ERROR_REWINDING_INTMFILE: Error rewinding intermediate monthly data 
file.

   Possible Cause(s):  3B-31 intermediate accumulation file is corrupted;
   Recommended Action(s):  Check if the file has the correct size of 
   46,540,800 bytes.  If not, delete the corrupted file and re-run all 
   previous granules in that month.
   
E_3B31_ERROR_WRITING_INTMFILE: Error writing intermediate monthly data file.

   Possible Cause(s):  Insufficient disk space available to write the 3B-31
   intermediate data file.
   Recommended Action(s):  Ensure that there exists sufficient disk space
   (at least 46,540,800 bytes) to write the 3B-31 intermediate data file.
   
E_3B31_ERROR_WRITING_3B31FILE: Error writing 3B-31 output data file.

   Possible Cause(s):  Insufficient disk space available to write the 3B-31
   output data file.
   Recommended Action(s):  Ensure that there exists sufficient disk space
   to write the 3B-31 output data file.
   
E_3B31_ERROR_CLOSING_LOGFILE: Error closing 3B-31 log file.

   Possible Cause(s):  The 3B-31 log file is corrupted;
   Recommended Action(s):  Delete the corrupted log file and re-execute the 
   3B-31 algorithm.
   
E_3B31_ERROR_CLOSING_2A12FILE: Error closing 2A-12 HDF file.

   Possible Cause(s):  The 2A-12 HDF file is corrupted.
   Recommended Action(s):  Contact TSDIS personnel.
   
E_3B31_ERROR_CLOSING_2B31FILE: Error closing 2B-31 HDF file.

   Possible Cause(s):  The 2B-31 HDF file is corrupted.
   Recommended Action(s):  Contact TSDIS personnel.
   
E_3B31_ERROR_CLOSING_3B31FILE: Error closing 3B-31 HDF file.

   Possible Cause(s):  The 3B-31 HDF file is corrupted.
   Recommended Action(s):  Delete the corrupted file and re-run all granules
   in that month.
   
E_3B31_ERROR_CLOSING_INTMFILE: Error closing intermediate monthly data file.

   Possible Cause(s):  The 3B-31 intermediate data file is corrupted.
   Recommended Action(s):  Delete the corrupted file and re-run all previous
   granules in that month.
   
W_3B31_INVALID_GATE_INDEX: Invalid gate index in layerIndex.c.

   Possible Cause(s):  Radar range gate index is out of boundary.
   Recommended Action(s):  Ensure that 0 <= gate index <= 0.
   
W_3B31_INVALID_GEOLOC_INDEX: Invalid geolocation index in gridIndex.c.

   Possible Cause(s):  Either latitude or logitude is out of boudary.
   Recommended Action(s):  Ensure that -40. <= latitude <= 40. and 
   -180. <= logitude <= 180.  Re-execute may be needed.
   

                  
5.  3B-31 algorithm package

The package of the 3B-31 algorithm includes the following files:

1). source codes:
L3B31main.c --- main routine for algorithm 3B-31, which uses the retrievals
                in 2B-31 to calibrate the retrievals in 2A-12.   It reads 
                the output data of 2A-12 and 2B-31 and then grids them 
                into 0.5 degree boxes.  Since the two products are output 
                at different vertical resolutions, averaging the outputs 
                of 2B-31 over several radar range gates to match the 14 
                TMI layers is performed.  Also, the rain rate (mm/hr) at 
                each radar gate in 2B-31 is converted into rain water(g/m^3) 
                to match the rain water in 2A-12.  The ratio is computed 
                once per month for 5 degree boxes and 14 layers.  In 
                addition, intermediate daily and monthly data files are
                output at the end of each day and monthly, respectively.   
Makefile    --- makefile for 3B-31
add2fiveAll.c---add parameters in 0.5 degree boxes to those in 5 degree boxes
averageMon.c--- compute monthly averages of various parameters for each 
                grid box
errorMsg.c  --- print fatal error messages and terminate the processing
getOverlap.c--- finds overlap TMI and PR data
getPRdata.c --- reads the output of 2B-31 scan by scan and then grids them 
                into 0.5 degree boxes
getTMIdata.c--- reads the output of 2A-12 scan by scan and then grids them
                into 0.5 degree boxes
gridIndex.c --- converts the latitude and longitude in degrees to those in 
                indices of grid boxes
initMon.c   --- initialize the arrays for monthly intermediate data file
layerIndex.c--- convert the radar range gate index in 2B-31 to the layer 
                index in 2A-12
monTotal.c  --- computes monthly total of surface rainfall
output.c    --- writes the output of 3B-31 into a HDF file and fills in 
                the follwoing ECS Core metadata elements: Beginning Date, 
                Beginning Time, Ending Date and Ending Time. 
params.h    --- constants which are used in 3B-31
protos.h    --- function declarations 
rangeCheck.c--- check if a variable is within its dynamic range
rate2density.c--- convert the rain water in kg/m^3  to the rain rate in mm/hr
ratioAll.c  --- computes the rainfall ratio of the retrievals in 2B-31 to
                the retrievals in 2A-12 for each grid box
struct.h    --- definitions of data structures

2). data files (in the directory of DATA):
3B31.980201.4.HDF --- 3b31 data file 

3). ancillary files: 
README      --- this file
CHANGELOG   --- log of changes


6.  Data formats

The details of data formats and explanations for standard TRMM products
(2A-12, 2B-31, and 3B-31) can be found in Reference [2].   The following
is the data structure for the intermediate accumulation data file: 
 
typedef struct {
   float	rain_tmi[NLYR][NLON_05][NLAT_05];
   float	clw[NLYR][NLON_05][NLAT_05];
   float	ciw[NLYR][NLON_05][NLAT_05];
   float	ice[NLYR][NLON_05][NLAT_05];
   float	Q1[NLYR][NLON_05][NLAT_05];
   float	rain_pr[NLYR][NLON_05][NLAT_05];
   
   float	sfcrain_pr[NLON_05][NLAT_05];
   float	sfcrain_tmi[NLON_05][NLAT_05];
   float	convect_tmi[NLON_05][NLAT_05];

   long	npix_pr_lyr[NLYR][NLON_05][NLAT_05];
   short	npix_pr_sfc[NLON_05][NLAT_05];
   short	npix_tmi_lyr[NLYR][NLON_05][NLAT_05];
   short	npix_tmi_sfc[NLON_05][NLAT_05];
   
   short      npix_pr_amb[NLON_05][NLAT_05];
   short      npix_tmi_amb[NLON_05][NLAT_05];
   
   short      npix_pr_rain[NLON_05][NLAT_05];
   short      npix_tmi_rain[NLON_05][NLAT_05];

   float      sfcrain_tmi_ovlp[NLON_05][NLAT_05];
   float      convect_tmi_ovlp[NLON_05][NLAT_05];
   short      npix_tmi_ovlp[NLON_05][NLAT_05];
   short      npix_tmi_rain_ovlp[NLON_05][NLAT_05];
   
   float      sfcrain_pr_ovlp[NLON_05][NLAT_05];
   short      npix_pr_ovlp[NLON_05][NLAT_05];
   short      npix_pr_rain_ovlp[NLON_05][NLAT_05];

}PARAMS_05;

     where NLYR=14, NLON_05=720, NLAT_05=160.  The size of the binary data
     file is 53,452,800 bytes.
     

7.  References

[1] "Tropical Rainfall Measuring Mission Science Data and Information System
    (TSDIS) Software Design Specification, Volume 6A - Data Manager, Version
    1", NASA/GSFC, October, 1996.
    
[2] "Interface Control Specification Between the Tropical Rainfall Measuring
    Mission Science Data and Information System (TSDIS) and the TSDIS Science
    User (TSU), Volume 3, File specifications for TSDIS Products - Level 2 
    and Level 3", NASA/GSFC, October, 1996