PLM_TRIM (3/95)                 suntrans                 PLM_TRIM (3/95)



NAME
    PLM_TRIM  --  generates specifications for a latitude-longitude grid
    in the heliographic coordinate system, magnitudes  of  the  Legendre
    coefficients   and   trimming  limits  for  use  in  performing  the 
    spherical harmonic transform.
    
    
USAGE
    plm_trim coef_out trim_out file_id (lmax m_type lattype ncolat maxlat dellat 
            nlong maxlong pplmmn pplmscale spamax)
    
    
PARAMETERS
    
    coef_out
        output image of summed Legendre coefficient Plm values  for  all
        values of latitude
    
    trim_out
        output  ASCII  trimming limit file containing specifications for
        the latitude-longitude grid and the  mode  coefficient  trimming
        limits
    
    file_id
        identifying  ASCII label for the  trimming limit file containing
        specifications for the  latitude-longitude  grid  and  the  mode
        coefficient trimming limits
    
    (lmax = 250)
        maximum  l  value.   Values  2  and above are accepted.  See the
        current .par file for absolute limits.  For the even  m  option,
        LMAX  MUST  BE  EVEN!!   The current scheme of file organization
        will not support lmax<2.
        
        (m_type = all_m)
            m  values  for  mode  coefficients.   Accepted  inputs   are 
            "even_m" and "all_m".
        
        (lattype = sinlat)
            type  of  latitude  spacing--angle  (lat)  or  sine of angle
            (sinlat).
        
        (ncolat = 220)
            number of interpolated  points  in  latitude  (whole  disk).
            Values  100  and  above  are accepted.  See the current .par
            file for absolute limits.
        
        (maxlat = 0.88)
            fraction of disk to cover  in  latitude.   If  greater  than
            1.0,  the input is assumed to be in degrees.  Values between
            0.10 and 90.00 are accepted.
        
        (dellat = -1.00)
            estimated spacing of points  in  latitude  IN  RADIANS.   If
            dellat  is  less  than  0.00,  the  value  for  the latitude
            spacing is computed from the  number  of  colatitude  points
            ncolat,  and the maximum colatitude value maxlat.  If dellat
            is greater than 0.00,  a  spacing  very  close  to  but  not
            neccessarily  exactly  equal  to  the input spacing is used.
            Values between -1.00 and 1.00 are accepted.
        
        (nlong = 512)
            number of interpolated points  in  longitude  (whole  disk).
            Values   between   128   and  2048  inclusive  are  accepted 
            currentll.  This input MUST be a power of 2.
        
        (maxlong = 0.73)
            fraction of disk to cover  in  longitude.  If  greater  than
            1.0,  the input is assumed to be in degrees.  Values between
            0.10 and 90.00 are accepted.
        
        (pplmmn = -30)
            log(10)  of  minimum  mode  coefficient  magnitude   to   be 
            included.
        
        (pplmscale = 2)
            log(10)   of  maximum  coefficient  mode  coefficient  found 
            before scaling is imposed.
        
        (spamax = 12000)
            space required for  trimming  coefficients.   If  more  than
            12000  words  of  space  are required, a message will appear
            upon execution and the task  should  be  reexecuted  with  a
            higher limit, as in example 4.
        
        
DESCRIPTION
    Task   PLM_TRIM   determines   the   specifications  for  the  solar 
    latitude-longitude grid  and  computes  the  corresponding  trimming
    limits  for  the  mode  coefficients.  The use of precomputed limits
    for the computation of  mode  coefficients  in  OTRANS  reduces  the
    computation  time  required  for  the  spherical harmonic transform.
    This task need only be run once for any set of images to  which  the
    same maximum l value and latitude-longitude grid are applied.
    
    
EXAMPLES
    1.   Generate  a  file of latitude-longitude grid specifications and
    corresponding mode  coefficient  trimming  limits  for  the  default
    value  latitude-longitude  grid for a maximum l value of 200.  Write
    the mode coefficient file into the image coefout, and the  grid  and
    trimming  limit  file  into  the  ASCII  file mod200.dat.  The ASCII
    label is "grid for lmax=200".
    
            su> plm_trim coefout mod200.dat "grid for lmax=200" lmax=200
    
    2.  Generate a file of latitude-longitude  grid  specifications  and
    corresponding  mode  coefficient  trimming  limits  for  the default
    value latitude-longitude grid for the default  maximum  l.   Compute
    all  of  the  m  coefficients.  Write the mode coefficient file into
    the image coefout, and the grid and trimming  limit  file  into  the
    ASCII  file,  allmod250.dat.   The  ASCII  label  is  "grid for GONG
    lmax=250".
    
            su> plm_trim coefout allmod250.dat "grid for GONG lmax=250" m_type=all_m
    
    3.  Generate a file of latitude-longitude  grid  specifications  and
    corresponding  mode  coefficient  trimming  limits  for  the default
    value latitude-longitude grid for the default maximum l  value  with
    a  minimum mode coefficient magnitude to be included of E-20.  Write
    the mode coefficient file into the image coefout, and the  grid  and
    trimming  limit  file  into  the  ASCII  file mod250.dat.  The ASCII
    label is "grid for GONG higher minimum inclusion".
    
            su> plm_trim coefout mod250.dat 
                "grid for GONG higher minimum inclusion" pplmmn=-20
    
    4.  Generate a file of latitude-longitude  grid  specifications  and
    corresponding  mode  coefficient  trimming  limits  for  the default
    value latitude-longitude grid  for  the  maximum  l  value  of  500.
    Increase  the  amount  of  space required in the buffer for the mode
    trimming coefficients to 48000 words.  The buffer size  increase  is
    often  needed  for  values  of lmax above about 300.  Write the mode
    coefficient file into the image coefout  and  a  grid  and  trimming
    limit file into mod500.dat.  The ASCII label is "grid for lmax=500".
    
            su> plm_trim coefout mod500.dat "grid for lmax=500" lmax=500 
                spamax=48000
    
    
TIME REQUIREMENTS
    Generation  of  the  ASCII  file requires somewhat more time than is
    required to perform the spherical harmonic transform  for  a  single
    image,  that  is  about  5  seconds  of  cpu  time and 10 seconds of
    elapsed time on a DECstation 3100.
    
    
BUGS
    None known.  PLM_TRIM is designed to  compute  trimming  limits  for
    even-m values and all-m values.
    
    
SEE ALSO
    otrans, remap, filt_map
    
    grid_file for description of the grid and trimming limit file
    
    modecoef_file for description of the mode coefficient file
    
    NOTE:   The  output  trimming  limits  file is required as input for tasks:
    filt_map, lat_sin, maskdisk, otr_burst, otrans & remap