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

   README file for the algorithm 3A-12. 

   3A12 product : TMI 0.5 x 0.5 degree gridded monthly mean product

   Ouput parameters:                               Unit

         surfaceRain[720][160]                     mm/h 
         convectRain[720][160]                     mm/h
         stratiformRain[720][160]                  mm/h
         cldWater[14][720][160]                    g/m^3 
         precipWater[14][720][160]                 g/m^3 
         cldIce[14][720][160]                      g/m^3 
         precipIce[14][720][160]                   g/m^3 
         latentHeat[14][720][160]                  deg/hour
         npixTotal[720[160]
         npixRain[720[160]
         npixConvectRain[720[160]
         npixStratiformRain[720[160]
         npixUnclassifiable[720[160]
         npixAmbiguous[720[160]
   
   Log:
   Joyce Chou   06/03/2003     first created
   Joyce Chou   07/28/2003     remove npixTotalConvect[720[160] parameters
   Joyce Chou   05/21/2004     add npixStratiformRain[720[160] parameter
                                   npixUnclassifiable[720[160] parameter
                                   stratiformRain[720[160] parameter

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

1.  Overview of 3A-12

Algorithm 3A-12 is to produce global monthly means of surface rainrate, 
convective surface rainrate and 14 vertical layers hydrometeor contents (cloud
liquid water, rain water, cloud ice, precipitating ice and latent heating) 
for 0.5 x 0.5 degree grids. Various pixel counts are also reported.
All the means and pixel counts include ambiguous pixels.


2.  Process of 3A-12

The algorithm 3A-12 is executed once per granule.  For each execution,
output data of 2A-12 are read and then gridded into 0.5 degree boxes.
Accumulations are performed for all the parameters and saved in an
intermediate data file which is read and updated for each execution.  

While reading data of 2A-12 ,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 3A-12 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.
Then the 3A-12 products are written into its output file in HDF format.

3.  Inputs of 3A-12

The command line for executing 3A-12 is as follows:

LA-12main <2A12 file id> <3A12 file id> <interm. file id>
   <VI file id> <begin/middle/end of month flag> <YYYY> <MM> 

where

L3A12main:         name of 3A-12 executable file;

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

<3A12 file id>:    name of 3A-12 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 3A-12 intermediate binary data file.  This file 
                   is used (read and update) for each execution.
                                   
<VI file id>:      name of 3A-12 verification intermediate ASCII file.  This
                   file is used (written) 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. 

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



All above arguments are needed for each execution.


4.  Error/Warning messages

E_3A12_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_3A12_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):  Ensure that one of the following month period flags
   is given: begin(Begin, BEGIN), middle(Middle, MIDDLE) or end(End, END).
   
E_3A12_NOT_ENOUGH_MEMORY: Not enough memory.

   Possible Cause(s):  Insufficient memory for processing 3A-12.
   Recommended Action(s):  Check with system adminstrator.
   
E_3A12_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_3A12_ERROR_WRITING_3A12METADATA: Error writing 3a-12 metadata.

   Possible Cause(s):  a. Insufficient disk space; b. 3A-12 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_3A12_ERROR_OPENING_LOGFILE: Error opening 3A-12 log file. 

   Possible Cause(s):  Insufficient disk space available to creat the new
   3A-12 log file.
   Recommended Action(s):  Ensure that there exists sufficient disk space to
   creat a new file.
   
E_3A12_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_3A12_ERROR_OPENING_3A12FILE: Error opening 3A-12 file.

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

   Possible Cause(s):  a. Invalid path/file name;  b. 3A-12 intermediate 
   accumulation file is corrupted;
   Recommended Action(s):  a. Enter valid path/file name;  b. Check if the 
   file has the correct size of 35,481,600 bytes.  If not, delete the 
   corrupted file and re-run all previous granules in that month.
   
E_3A12_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_3A12_ERROR_READING_INTMFILE: Error reading intermediate monthly data file.

   Possible Cause(s):  3A-12 intermediate accumulation file is corrupted;
   Recommended Action(s):  Check if the file has the correct size of 
   35,481,600 bytes.  If not, delete the corrupted file and re-run all 
   previous granules in that month.
   
E_3A12_ERROR_REWINDING_INTMFILE: Error rewinding intermediate monthly data 
file.

   Possible Cause(s):  3A-12 intermediate accumulation file is corrupted;
   Recommended Action(s):  Check if the file has the correct size of 
   35,481,600 bytes.  If not, delete the corrupted file and re-run all 
   previous granules in that month.
   
E_3A12_ERROR_WRITING_INTMFILE: Error writing intermediate monthly data file.

   Possible Cause(s):  Insufficient disk space available to write the 3A-12
   intermediate data file.
   Recommended Action(s):  Ensure that there exists sufficient disk space
   (at least 35,481,600 bytes) to write the 3A-12 intermediate data file.
   
E_3A12_ERROR_WRITING_3A12FILE: Error writing 3A-12 output data file.

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

   Possible Cause(s):  The 3A-12 log file is corrupted;
   Recommended Action(s):  Delete the corrupted log file and re-execute the 
   3A-12 algorithm.
   
E_3A12_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_3A12_ERROR_CLOSING_3A12FILE: Error closing 3A-12 HDF file.

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

   Possible Cause(s):  The 3A-12 intermediate data file is corrupted.
   Recommended Action(s):  Delete the corrupted file and re-run all previous
   granules in that month.
   
W_3A12_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.  3A-12 algorithm package

The package of the 3A-12 algorithm includes the following files:

1). source codes:(in the directory of src)
L3A12main.c  --- main routine for algorithm 3A-12.
                 It reads the output data of 2A-12 and then grids them 
                 into 0.5 degree boxes. It accumulates daily data and 
                 computes the monthly means at the end of the month.
                 The intermediate daily and monthly data files are
                 output at the end of each day and monthly, respectively.   
Makefile     --- makefile for 3A-12.
averageMon.c --- compute monthly averages of various parameters for each 
                 grid box
errorMsg.c   --- print fatal error messages and terminate the processing
getTMIdata.c --- reads the output of 2A-12 scan by scan and then grids them
                 into 0.5x0.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
output.c     --- writes the output of 3A-12 into a HDF file and fills in 
                 the follwoing ECS Core metadata elements: Beginning Date, 
                 Beginning Time, Ending Date and Ending Time. 
rangeCheck.c --- check if a variable is within its dynamic range

2). include files:(in the directory of inc)
params.h     --- constants which are used in 3A-12
protos.h     --- function declarations 
TS_3A12.t    --- dotT file used to generate the error code
TS_3A12_68.h --- error code generated by TS_3A12.t
TS_68        --- error code generated by TS_3A12.t


3). ancillary files: (in the directory of doc)
README       --- this file


6.  Data formats

The details of data formats and explanations for standard TRMM products
(3A-12) can be found in Reference [1].   The following
is the data structure for the intermediate accumulation data file: 
 
typedef struct {

   float32        surfaceRain[720][160];
   float32        convectRain[720][160];
   float32        stratiformRain[720][160];

   float32        cldWater[14][720][160];
   float32        precipWater[14][720][160];
   float32        cldIce[14][720][160];
   float32        precipIce[14][720][160];
   float32        latentHeat[14][720][160];

   int32          npixTotal[720][160];
   int32          npixRain[720][160];
   int32          npixConvectRain[720][160];
   int32          npixStratiformRain[720][160];
   int32          npixUnclassifiable[720][160];
   int32          npixAmbiguous[720][160];

}L3A_12_GRID;

7.  Paramemters in the output data file

surfaceRain
The surfaceRain is the monthly mean of the instantaneous rain rate at the
surface for each grid. It ranges from 0.0 to 3000.0 mm/h.

convectRain
The convectRain is the monthly mean of the instantaneous convective rain 
rate at the surface for each grid. It ranges from 0.0 to 3000.0 mm/h.

stratiformRain 
The stratiformRain is the monthly mean of the instantaneous stratiform 
rain rate at the surface for each grid. It ranges from 0.0 to 3000.0 mm/h.

cldWater 
The cldWater is the monthly mean of the cloud liquid water content for 
each grid at each vertical layer. It ranges from 0.0 to 10.0 gm^-3.

precipWater
The precipWater is the monthly mean of the precipitation water content 
for each grid at each vertical layer. It ranges from 0.0 to 10.0 gm^-3.

cldIce 
The cldIce is the monthly mean of the cloud ice water content for each 
grid at each vertical layer. It ranges from 0.0 to 10.0 gm^-3.

precipIce 
The precipIce is the monthly mean of the precipitation ice content for 
each grid at each vertical layer. It ranges from 0.0 to 10.0 gm^-3.

latentHeat 
The latentHeat is the monthly mean of the latent heating release for 
each grid at each vertical layer. It ranges from -256.0 deg/hour to
256.0 deg/hour.

npixTotal
The npixTotal is the monthly accumulation of pixels with surface rain 
greater than or equal to 0.0 (mm/h) for each grid. It is used to compute 
the monthly means described above. It ranges from 0 to 10,000.

npixRain
The npixRain is the monthly accumulation of pixels with surface rain 
greater than 0.0 (mm/h) for each grid. It ranges from 0 to 10,000.

npixConvectRain
The npixConvectRain is the monthly accumulation of pixels with surface 
convective rain greater than 0.0 (mm/h) for each grid. It ranges 
from 0 to 10,000.

npixStratiformRain
The npixConvectRain is the monthly accumulation of pixels with surface 
stratiform rain greater than 0.0 (mm/h) for each grid. It ranges 
from 0 to 10,000.

npixUnclassifiable 
The npixUnclassifiable is the monthly accumulation of pixels with surface 
rain greater than or equal to 0.0 (mm/h) that can not be classified as
convective or stratiform for each grid. It ranges from 0 to 10,000.
 
All the means and pixel counts described above include ambiguous pixels.

npixAmbiguous
The npixAmbiguous is the monthly accumulation of pixels with surface 
rain greater than or equal to 0.0 (mm/h) and rain flag greater than 0 
(indicates ambiguous rain) for each grid. It ranges from 0 to 10,000.


8.  Data ranges in the output file
    The following is an example from Feb 1998 monthly run
    output (3A12.980201.85.HDF):
    
    parameters          min         max       missing value
    ------------------------------------------------------
    surfaceRain         0.0       2.99683     -9999.9
    convectRain         0.0      32.78220     -9999.9
    cldWater            0.0       0.03770     -9999.9 
    precipWater         0.0       0.177192    -9999.9
    cldIce              0.0       0.0139475   -9999.9
    precipIce           0.0       0.180268    -9999.9 
    latentHeat         -0.804240  1.54467     -9999.9
    npixTotal           0         5553
    npixRain            0         1391
    npixConvectRain     0         1391
    npixAmbiguous       0         5281
     

9.  References

[1] "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 1". 
    Appendix C - Non-Standard Algorithms. Release 6.0, June 2004.