 
      CALL SEQUENCE...
       varspec  IN SP2OUT SP1OUT XOUT INPUT OUTPUT [ -a VAL1 -b VAL2 \ 
                                                     -c VAL3 -d VAL4 \ 
                                                     -j VAL5 -k VAL6 ] 
 
 
      DESCRIPTION...
       VARSPEC - COMPUTE SPECTRUM FROM GRIDED VALUES
 
 
      AUTHOR - B.Denis, May 2002
      LAST REVISION: $Header: /data/armnraid1/cvs/RMNLIB/utils/rdiag/lspgm/varspec.ptn,v 4.9 2011/11/22 19:35:07 dugas Exp $
 
 
      CONTACT: BERTRAND DENIS, PH.D.
               METEOROLOGICAL SERVICE OF CANADA
               EMAIL:bertrand.denis@ec.gc.ca
               TEL:514-421-7264 
 
 
      PURPOSE - COMPUTES SPECTRAL VARIANCE ARRAY AND POWER SPECTRUM FROM
                GRIDED DATA. DEPENDING ON THE NATURE OF THE PERIODICITY OF
                THE 2D GRID, THE USER MAY HAVE THE CHOICE OF 2 TRIGOMETRIC
                TRANSFORMS:   THE DCT (DISCRETE COSINE  TRANSFORM) 
                           OR THE DFT (DISCRETE FOURIER TRANSFORM).
    
                REFERENCE:'SPECTRAL DECOMPOSTION OF TWO-DIMENSIONAL ATMOSPHERIC 
                           FIELDS ON LIMITED-AREA DOMAINS USING 
                           THE DISCRETE COSINE TRANSFORM (DCT)'
                           BY B. DENIS, J. COTE AND R. LAPRISE 
                           IN MONTHLY WEATHER REVIEW, 2002, VOL.130,NO.7
 
       INPUT FILE...
        IN = INPUT ARRAYS (TYPE 'GRID' OR 'SUBA') FILE (UNIT = 1)
 
 
       OUTPUT FILES...
        SP2OUT = 2D ARRAY CONTAINING THE VARIANCE ASSOCIATED
                 WITH EACH SPECTRAL COEFFICIENT.(UNIT = 2)
 
        SP1OUT = 1D ARRAY (TYPE 'ZONL') CONTAINING THE VARIANCE COMPUTED
                 BY SUMMING VARIANCES FROM SP1OUT OVER ANNULUS WAVEBANDS
                 THIS GIVES THE STANDARD POWER SPECTRUM.(UNIT = 3)
 
        XOUT   = WAVELENGTH ASSOCIATED TO EACH COMPONENT.(UNIT = 4)
 
       NOTE THAT THE FIRST ELEMENT OF SP1OUT AND SP2OUT IS
       THE SQUARE OF THE FIELD AVERAGE.             
                                       
                                       
      PARAMETRES...                   
       CAS   (a) = TYPE OF TRANSFORM.            
                                       
        4 => COS SHIFTED ONLY.  RECOMMENDED FOR NON-PERIODIC DATA. THIS IS THE
                                SO-CALLED DISCRETE COSIN TRANSFORM (DCT).
                                       
        5 => DFT: STANDARD PERIODIC DISCRETE FOURIER TRANSFORM
                  NOT RECOMMENDED FOR NON-PERIODIC DATA: 
                  USE CAS=4 INSTEAD.
                  NB: IT IS POSSBILE TO APPLY DETRENDING TO MAKE
                  THE DATA PERIODIC BEFORE THE APPLICATION OF THE DFT.
                  SEE THE 'DET' OPTION BELOW.
                                       
        NB: ( CAS=4 ) THE DIMENSIONS OF THE INPUT DATA MUST BE *EVEN*
 
            ( CAS=5 ) THE DIMENSIONS OF THE INPUT DATA MUST BE
                      *ODD* AND THE FIELD WIL BE CONSIDERED PERIODIC,
                      I.E. IN(1,J) = IN(NI+1,J) AND IN(I,1) = (I,NJ+1).            
                  
               *** CAS=1, CAS=2, CAS=3 are not available anymore ***
                                       
                                       
       LOGV  (b) = TO GET OR NOT THE LOG BASE 10 OF VARIANCE COEFF. IN SP2OUT.
                                       
              0=>  LOG BASE 10 IS *NOT* COMPUTED
              1=>  LOG BASE 10 IS COMPUTED (DEFAULT)
                                       
       CLUST (c) = ONLY USED WHEN CAS=1,2,3,4. TO CLUSTER HALF AND FULL
                   WAVENUMBERs TOGETHER TO GIVE SIMILAR POWER SPECTRA AS
                   PRODUCED BY CAS=5
                                       
              0=>  NO CLUSTERING. A NI X NI GRID WOULD GIVE SPECTRUM
                   GOING FROM 0 TO NI-1 ELEMENT.        
                                       
              1=>  CLUSTER WAVENUMBERS 1 & 1 1/2, 2 & 2 1/2 & 3 & 3 1/2 ....
                   - IN THIS CASE VARIANCE RELATED TO WAVENUMBER 1/2 WOULD
                     BE MISSING.                
                                       
              2=>  CLUSTER WAVENUMBERS 1/2 & 1,  1 1/2 @ 2,  2 1/2 & 3  ....
                   - IN THIS CASE VARIANCE RELATED TO THE LAST WAVENUMBER WOULD
                     BE MISSING. *** THIS IS THE DEFAULT *** 
 
              3=>  CLUSTER :  0.5*N1/2 + N + 0.5*N3/2               
                   THIS IS A MOVING AVERAGE.                                        
                                       
       DX    (d) = GRID SPACING IN KILOMETER. THIS IS OPTIONAL: IT USED TO
                   PRODUCE FILE XOUT THAT CONTAINS A VECTOR OF THE 
                   WAVELENGTH ASSOCIATED TO EACH COMPONANT. THIS IS USEFUL
                   FOR PLOTING PURPOSES.
 
       DET   (j) = FOR DETRENDING THE FIELDS BEFORE APPLYING THE DFT 
                   WHEN THE DFT IS USED.
 
             (0) = NO DETRENDING APPLYIED
 
             (1) = DETRENDING APPLYIED (DEFAULT FOR THE DFT; NOT AVAILABLE FOR DCT)
 
       AVG1D (k) = TO COMPUTE SPECTRA BY DOING 2D SPECTRAL TRANSFORMS
                   OR 1D SPECTRAL TRANSFORMS (IN X OR IN Y).
                   THIS LAST OPTION IS TO MIMIC IN-SITU MEASURES TAKEN BY 
                   AIRFLIGHTS. FIRSTLY, 1D SPECTRA ARE COMPUTED FOR EVERY ROW 
                   OR COLUMN.SECONDLY, THE AVERAGE OF THOSE 1-D SPECTRA ARE
                    COMPUTED. THIS METHODOLOGY IS INSPIRED FROM THIS PAPER:
                   'EVALUATING MESOSCALE NWP MODELS USING KINETIC ENERGY SPECTRA'
                   BY W.C. SKAMAROCK. MWR, DECEMBRE 2004.
 
             (0)= DO 2D SPECTRAL TRANSFORM (DEFAULT).
                  (DO NOT AVERAGE 1D SPECTRA)
 
             (1)= DO AVERAGE OF 1D WEST-EAST SPECTRA 
 
             (2)= DO AVERAGE OF 1D SOUTH-NORTH SPECTRA
 
 
      READ(5,5000) CAS,LOGV,CLUST,DX,DET,AVG1D
 5000 FORMAT(10X,3I5,E5.0,4I5)
 
                                       
      EXAMPLE OF INPUT CARD...              
                                       
  VARSPEC     4    1    2  45.    1    0
 
         0123456789012345678901234567890123456789012345678901234567890
         1         2         3         4         5      
 
      
      EXIT CONDITIONS...
        0 NO PROBLEMS
        1 PROBLEM WITH CAS VALUE
        2 PROBLEM WITH LOGV VALUE
        3 PROBLEM WITH CLUST VALUE
        4 PROBLEM WITH DET VALUE
        5 PROBLEM WITH AVG1D VALUE
        6 UNABLE TO READ FIRST FIELD
        7 PROBLEM WITH DIMENSIONS
        8 EVEN DIMENSIONS WITH STANDARD PERIODIC FFTs
        9 ODD DIMENSIONS WITH DISCRETE COSINE TRANSFORMS
        10 UNABLE TO READ INPUT DIRECTIVES
