 
      CALL SEQUENCE...
       gsathl  GSFLD GSLNSP GSTEMP GTHFLD INPUT OUTPUT [ -na ] \ 
             [ -n VAL1 -a VAL2 -b VAL3 -c VAL4 -kind VAL5 \ 
               -d VAL6 -i VAL7 -def ]
 
 
      DESCRIPTION...
       gsathl  - INTERPOLATES A FIELD FROM SIGMA/HYBRID OR PRESSURE LEVELS
                 TO NTHL THETA (POTENTIAL TEMPERATURE) LEVELS
 
 
      AUTHOR  - J. Koshyk, July 27/94.
      LAST REVISION: $Header: /data/armnraid1/cvs/RMNLIB/utils/rdiag/lspgm/gsathl.ptn,v 4.28 2011/02/10 17:08:07 dugas Exp $
 
 
      PURPOSE - INTERPOLATES FROM ETA (SIGMA/HYBRID) OR PRESSURE LEVELS TO NTHL
                POTENTIAL TEMPERATURE (THETA) LEVELS. THE INTERPOLATION IS LINEAR
                IN LN(THETA).  EXTRAPOLATION UP AND DOWN IS BY LAPSE RATES,
                DF/D(LN THETA) SPECIFIED BY THE USER.
 
 
      INPUT FILES...
       GSFLD  = SETS OF ETA (SIGMA/HYBRID) OR PRESSURE LEVEL GRID DATA.
       GSLNSP = SERIES OF GRIDS OF LN(SF PRES IN MB) (IGNORED IF COORD='PRES')
       GSTEMP = SERIES OF GRIDS OF TEMPERATURE.
 
      OUTPUT FILE...
       GTHFLD = SETS OF THETA LEVEL GRID DATA.
 
 
      INPUT PARAMETERS...
 
       NTHL  (n)    = NUMBER OF REQUESTED THETA LEVELS (DEF 5, MAX 999).
                      IF NTHL IS NEGATIVE, EACH -NTHL LEVTH VALUES ARE READ WITH
                      A I10 FORMAT OR AN E10.0 IF ITS VALUE CONTAINS A DECIMAL
                      POINT.
       RLUP  (a)    = LAPSE RATE, (D FLD/D LN(THETA)) USED TO EXTRAPOLATE UPWARDS,
       RLDN  (b)    = LAPSE RATE USED TO EXTRAPOLATE DOWNWARDS,
       COORD (kind) = 'SIG'/'ETA'/'ET10'/'ET15' FOR INPUT VERTICAL COORDINATES AND
                      'GEM2'/'GEM3'/'GEM4' FOR VARIANTS OF THE GEM VERTICAL COORDINATES
                      'PRES' FOR INPUT PRESSURE COORDINATES.
 
       PTOIT (c)    = PRESSURE (PA) AT THE LID OF MODEL.
       PREF  (d)    = REF PRESSURE USED WHEN COORD='GEM2' OR 'GEM3' (DEF 80000 PA).
       R     (i)    = EXPONENT USED ONLY WHEN COORD='GEM2' OR 'GEM3' (DEF 1.0)
 
       LEVTH        = THETA LEVELS (K) (MONOTONE DECREASING I.E. TOP OF
                      ATMOSPHERE TO BOTTOM). THE DEFAULTS ARE AS SPECIFIED
                      IN THE EXAMPLE BELOW.
 
       Notes: 1) The first input line is NOT read if any of
                 its parametres are passed via the command line.
              2) Furthermore, the second line will not be read either
                 if the "-def" defaults processing mode is requested.
              3) Specifying "-na' prevents the routine EATHL from
                 aborting when it find a well-mixed theta layer.
              4) RLUP and RLDN are ignored when COORD='GEM' or 'GEM2'.
              5) GEM2 is the Original hybrid coordinate as implemented
                 by Edouard & Gravel in GEM/DM v2.2.0. GEM3 is the
                 normalized  that was implemented in the v2.3.1 GEM/DM.
                 'GEM4' is the version by GEM/DM from v4.0.6.
              6) The default value of COORD is determined by the file type
                 and the program will also try to determine it by the
                 (internal) coding used for the coordinate itself.
 
       READ(5,5010) NTHL,RLUP,RLDN,COORD,PTOIT,PREF,R
       IF (NTHL.GT.0)
       READ( 5,5020 ) (LEVTH(I),I=1,NTHL)
       IF (NTHL.LT.0)
       READ( 5,5030 ) (LEVTH(I),I=1,-NTHL)
 5010  FORMAT(10X,I5,2E10.0,1X,A4,3E10.0)
 5020  FORMAT(16E5.0)
 5030  FORMAT(8E10.0)
 
 
      EXAMPLE OF INPUT CARDS...
 
  GSATHL.     5        0.        0. PRES      0.01
 850. 700. 550. 400. 330.
 
         0123456789012345678901234567890123456789012345678901234567890
         1         2         3         4         5         6         7
 
      EXIT CONDITIONS...
        0 NO PROBLEMS
        1 NUMBER OF THETA LEVELS GREATER THAN MAXLEV
        2 THETA NOT MONOTONIC DECREASING
        3 ERROR READING FIRST TEMPERATURE SET
        4 ERROR READING FIRST FIELD IN GSLNSP
        5 ERROR READING FIRST SET IN GSFLD
        6 GSFLD,GSLNSP OR GSTEMP NOT THE SAME SIZE
        7 MORE THAN ONE SIZE IN GSFLD
        8 MISSING GSLNSP SET
        9 MORE THAN ONE SIZE IN GSLNSP
       10 MISSING GSTEMP SET
       11 MORE THAN ONE SIZE IN GSTEMP
       12 GSTEMP DOES NOT CONTAIN TEMPERATURES
       13 EROR ABORT READING INPUT CARD 1
       14 ERROR ABORT READING INPUT CARD 2
       15 GSFLD AND GSTEMP VERT COORDINATE DIFFER
       16 GSFLD VERT COORDINATE NOT MONOTONIC
       17 UNSUPPORTED VERTICAL COORDINATE IN GSTEMP
       18 COORD PARAMETRE AND GSTEMP MISMATCH
       19 PTOIT GREATER THAN TOP MODEL LEVEL (=ETA(TOP)*PREF)
       20 GSLNSP DOES NOT CONTAIN LN( SURFP ) FOR EARTH
       21 FOUND UNSUPPORTED DATA TYPE
       22 LEVTH DOES NOT CONTAIN THETA DATA
       23 INCONSISTENT GSFLD AND GSTEMP LEVELS
 
