!===============================================================================
!
! README for OMAERUVd (OMI Daily L3 for OMAERUV)
!
! Peter J.T. Leonard (ADNET)
!
! App Version: 1.6.1
!
! Date: 2017-05-19
!
! OMAERUVd High Level Overview:
!   This is the main program for the OMI (Ozone Monitoring Instrument) OMAERUVd
!   Product Generation Executive (PGE).  The OMAERUVd PGE creates the OMAERUVd
!   data product, which is the primary Level 3 (L3) aerosol product of the U.S.
!   OMI Science Team.  The "d" at the end of "OMAERUVd" represents "daily".
!
!   The OMAERUVd PGE creates a (Total Ozone Mapping Spectrometer) TOMS-like daily
!   L3 gridded data product file from (as many as) three consecutive OMAERUVG
!   daily Level 2G (L2G) gridded data product files, where each OMAERUVG file
!   contains 24 consecutive UTC hours of OMAERUV orbital Level 2 (L2) swath data
!   subsetted onto a 0.25-degree by 0.25-degree grid in longitude and latitude.
!
!   A TOMS L3 day is defined as the ensemble of all L2 ground pixels with pixel
!   centers that have the same local calendar date on the ground.  There are two
!   reasons behind such a definition.  First, a TOMS L3 day provides complete
!   coverage of Earth, since every point on Earth (outside of polar night)
!   experiences daylight on each calendar date (in comparison, 24 consecutive
!   UTC hours of OMI observations do not completely cover Earth).  Second, the
!   TOMS L3 day puts the discontinuity (i.e., where the L2 observations within a
!   given day differ by almost 24 hours) at +/-180 degrees longitude, and, thus,
!   the discontinuity can be placed undistractingly along the extreme left and
!   right edges of several commonly used map projections.
!
!   The calendar date of the TOMS L3 day is the calendar date at Greenwich
!   midway through the TOMS L3 day, and is specified via the L3 day of year
!   parameter in the PCF (Process Control File) of the OMAERUVd PGE.  Note
!   that some of the L2 observations at the beginning of a TOMS L3 day will
!   correspond to the previous calendar date at Greenwich, and some of the L2
!   observations at the end of a TOMS L3 day will correspond to the next
!   calendar date at Greenwich.  Consequently, data from three consecutive OMI
!   L2G files are required to fully populate the L3 grid at all longitudes for
!   any given TOMS L3 day.
!
!   The OMAERUVd PGE was developed for Omar Torres (NASA/GSFC), and is based
!   upon the TOMS Level 3 Gridded Software.  The latter was developed over a
!   period of many years by several people:  W. Byerly, D. Cao, E. Celarier,
!   Q. Choung, S. Huang, B. Irby, D. Lee, L. Liu, R. McPeters, L. Moy, M. Peng,
!   L. Phung, B. Raines, C. Seftor, and, especially, C. Wellemeyer.
!
! Adopted OMAERUVd Grid:
!   The adopted L3 grid is a 1.0-degree by 1.0-degree grid in longitude and
!   latitude.  The dimensions of the grid are 360 by 180.  The center of the
!   first grid cell is located at longitude -179.5 and latitude -89.5.  The
!   center of the final grid cell is located at longitude 179.5 and latitude
!   89.5.  The center of the grid itself is located at longitude 0.0 and
!   latitude 0.0, and corresponds to the corners of four grid cells.
!
!   The adopted L3 grid is consistent with the document entitled "Definition
!   of OMI Grids for Level 3 and Level 4 Data Products" by J.P. Veefkind et al.
!
!   The format of the L3 product files is consistent with the document entitled
!   "A File Format for Satellite Atmospheric Chemistry Data" by C. Craig et al.
!
! OMAERUVd Gridding Algorithm:
!   The values in the OMAERUVd data product file for each L3 grid cell are
!   weighted averages of the values for all of the OMI L2 observations that
!   overlap with the L3 grid cell.  The weight for each L2 observation is the
!   fractional area of overlap of the OMPIXCOR FoV75 ground pixel with the
!   L3 grid cell.
!
!   Each of the OMI L2 observations with ground pixel centers that lie within
!   each L3 grid cell is considered, and compared with several exclusion
!   criteria.  These criteria are summarized here in sequence.
!
!   Let l3_tnoon be the time at noon UTC for the TOMS L3 day, and let l2g_time
!   be the L2 observation time.
!
!   A1) As a rough first cut, L2 observations made outside of the 48-hour time
!       interval centered at l3_tnoon are excluded.  Thus, L2 observations with
!
!       l2g_time <  l3_tnoon - (24 hours - 15 minutes)
!
!       or
!
!       l2g_time >= l3_tnoon + (24 hours - 15 minutes)
!
!       are excluded.
!
!   At any given moment, all points on Earth between the longitude of midnight
!   and the dateline that are on the same side of the dateline have the same
!   calendar date.  The calendar dates on opposite sides of the dateline differ
!   by one day, except at the instant when the longitude of midnight and the
!   dateline coincide, in which case the date is the same everywhere on Earth.
!
!   Let l2_lom be the longitude of midnight at l2g_time, and let l2g_lon be the
!   longitude at the center of the L2 observation.  The dateline is assumed to
!   lie strictly at a longitude of +/-180 degrees for the sake of simplicity,
!   which ignores the zigs and zags of the actual dateline.
!
!   A2) L2 observations with local calendar dates on the ground that correspond
!       to the day before the TOMS L3 day are excluded.  This has been
!       implemented as L2 observations with
!
!       l2g_time <  l3_tnoon - 15 minutes
!
!       and
!
!       -180 degrees <= l2g_lon < l2_lom
!
!       are excluded.
!
!   A3) L2 observations with local calendar dates on the ground that correspond
!       to the day after the TOMS L3 day are excluded.  This has been
!       implemented as L2 observations with
!
!       l2g_time >= l3_tnoon + 15 minutes
!
!       and
!
!       l2_lom <= l2g_lon < 180 degrees
!
!       are excluded.
!
!   Let bit5 be bit 5 (the 6th bit) of the "ground pixel quality flag" of the L2
!   observation.  This is the solar eclipse possibility flag.
!
!   A4) L2 observations with the solar eclipse possibility flag set are excluded.
!       Thus, L2 observations with
!
!       bit5 /= 0
!
!       are excluded.
!
!   At this point there are significant differences in how L2 observations are
!   excluded from the L2 grids for 1) final aerosol absorption optical depth,
!   final aerosol optical depth and final aerosol single scattering albedo,
!   and 2) cloud fraction, cloud optical depth and UV aerosol index.
!
! OMAERUVd Gridding Algorithm for Final Aerosol Absorption Optical Depth, Final
!   Aerosol Optical Depth and Final Aerosol Single Scattering Albedo:
!
!   There is one additinal criterion (beyond A1 through A4 above) for excluding
!   L2 observations from the L3 grid for final aerosol absorption optical depth,
!   final aerosol optical depth and final aerosol single scattering albedo.
!
!   Let l2g_faflg be the final algorithm flags for the L2 observation.
!
!   B5) L2 final aerosol absorption optical depth, final aerosol optical depth
!       and final aerosol single scattering albedo observations with final
!       algorithm flags not equal to 0 are excluded.  Thus, L2 final aerosol
!       absorption optical depth, final aerosol optical depth and final single
!       scattering albedo observations with
!
!       l2g_faflg /= 0
!
!
!       are excluded.
!
! OMAERUVd Gridding Algorithm for Cloud Fraction, Cloud Optical Depth and
!   UV Aerosol Index:
!
!   Beginning with Version 1.6.0 of OMAERUVd there are no longer any criteria
!   in addition to A1 through A4 (above) for excluding L2 observations from
!   the L3 grid for cloud faction, cloud optical depth and UV aerosol index.
!
!===============================================================================