#--------------------------------------------------------------------------- 
# HELP FILE FOR mpigridr
# S.T. Myers (NRAO)
#
# Version 2006-06-30  STM CITA
# Updated 2006-07-31  STM CITA
# Updated 2006-08-23  STM CITA
# Updated 2006-09-18  STM CITA Beta release version
#
#--------------------------------------------------------------------------- 
#
# DISTRIBUTION OF THIS SOFTWARE DOES NOT IMPLY ANY WARRANTY!  USERS BEWARE.
#
# This software is part of the CBI interferometer reduction pipeline.
#
# For a description of the gridded method, see the paper 
#    "A Fast Gridded Method for the Estimation of the Power 
#     Spectrum of the Cosmic Microwave Background from Interferometer Data 
#     with Application to the Cosmic Background Imager" 
#  by S.T. Myers et al., ApJ, 591, 575-598 (2003).
#
# IMPORTANT NOTE: This software assumes that the interferometer is 
# observing in circular polarization (RCP and LCP).  If your interferometer
# is observing in lineary polarizations (X and Y) then extensive changes
# would need to be made to the program in the routines scangridder and
# write_bands in file mpigridr.F90.
#
#--------------------------------------------------------------------------- 
# COMPILATION NOTES:
#--------------------------------------------------------------------------- 
# Required files:
#   Makefile                 to compile code (uses Intel compiler)
#   mpimain.f90		     main program
#   mpiparams.F90	     global parameters and variables, with defaults
#   mpigridr.F90	     principal subroutines	     
#   mpiutils.F90	     auxiliary subroutines and functions
#   mpireadmod.f90	     I/O related subroutines
#   mpi_merge_cre_uname.c    allows writing of gzipped output files
#
# Optional files:
#   uvfread_pol.c            UV-FITS reading routines for CBI data
#                            (not needed if idouvfits<1)
#   beamsky.dat              CBI 1-D primary beam function (set through
#                            file_beamsky, not needed if idogaus.NE.1)
#
# Extra stuff:
#   help_mpigridr.txt        this file!
#   WMAP3_CMBall.cl          c_l shape file (from WMAP3) as an example
#   c2048-0330_con_mock.uvf  mock CBI uv-fits data file (using WMAP3 cl)
#   c2048-0330_con_mock.mat  ASCII version of data file
#   bobgrid_deep_test        example shell script for running mpigridr
#                            (assumes MPI lam)
# To compile:
#   make                     compile mpigridr
#   make clean               will remove .o and .mod files (but not compile)
#
#--------------------------------------------------------------------------- 
# NOTE: command-line arguments
#--------------------------------------------------------------------------- 
# Not supported in Intel 8.1 or earlier.  Therefore, in mpimain.f90 this
# has been disable.
#
# If compiled using Intel Fortran Compiler 9.0 or later with Fortran 2003
# extensions to include command_argument_count(), get_command_argument,
# then this program will take command-line arguments.  Uncomment the
# relevant lines in mpimain.f90 and recompile.  To use:
#
# mpigridr_test <parfile> <datfile>
#
# If parfile argument present, then will read parameters from this file.
# 
# If datfile argument is present, then will read list of uv data files from
# this file.
#
#--------------------------------------------------------------------------- 
# PARAMTER SETTING OPTIONS:
#--------------------------------------------------------------------------- 
# These are entered as lines
# set key=val key=val ... &
# ...
# set lastkey = lastval 
# 
# the & is the continuation character as a final key without value
#
# These are read from stdin or from parfile.
#
# The maximum number of key=value pairs allowed per line is
#
# Comment lines: you can place comments after the " & " continuation key
#   Lines that start with the continuation key are also allowed
#   Lines that start with characters "!","#" are treated as comment lines
#
# If reading from parfile, then it will stop only when it hits end-of-file,
# or hits a line that starts with the "end" key.  It will continue reading 
# lines even if it hits one it cannot interpret. It will ignore blank lines
# when reading from parfile.
#
# If in compatibility mode (see below) and reading from stdin (interactive 
# or script) then parameter reading will terminate when it hits a "set ..." 
# line without continuation, or a line it can interpret as old-style param 
# line, e.g. "1 0 1".  If it hits a line it cannot interpret, it will abort 
# if reading from stdin.
#
#--------------------------------------------------------------------------- 
# UV DATA FILE FORMATS: 
#
#  USAGE: idouvfits>0     uv data in uv-fits format (need uvfreadpol.c)
#         idocompat<1	  (DEFAULT) ASCII file input
#
#  NOTE: in the released version, only ASCII file input is enabled.  If
#  you wish to use uv-fits files, then you must uncomment the relevant
#  lines in subroutine readscans in file mpireadmod.f90 (the ones that
#  CALL uvfvis and CALL inuvf, just search for "idouvfits").  Note that
#  this requires these routines which are in uvfread_pol.c for the CBI.
#  The CBI reading routines in turn require some fits libraries from 
#  Martin Shepherd, and may not read your UV-FITS format as they are
#  designed for CBI format or difmap format.  We recommend you write your
#  own using uvfread_pol.c as a model.
#
# ASCII Formats:
#
#  These are supported in the in_ascii and header_ascii routines in
#  the file mpireadmod.f90.  These can easily be altered to allow other
#  ascii formats.
#
#  Released version supports read of ASCII files such as vsa .vbn or 
#  CBI matlab format.
#
#  Expected formats:
#  
#  Headers: should be first non-blank lines (in any order, though
#      can have only RA and DEC if desired (CBI format does not need
#      FREQUENCY).  Note that if RA and DEC are not specified, then
#      use ra_center and dec_center to set a single RA and DEC for
#      all files without RA DEC.
#  
#  RA: HH:MM:SS.SS
#  DEC: sDD:MM:SS.S
#  FREQUENCY: freq
#  
#  Data lines:
#  A) VSA style, single channel, single (RR) polarization:
#  base_id, u, v, re, im, er
#  ... repeat for each vis
#      base_id = 100*ia + ib for antenna pair ia, ib
#  
#  B) CBI matlab style, either single pol (RR) or add ip as 11th key
#  ia ib fq u v uvr re im er wt <ip>
#  ... repeat for each vis
#      where ia,ib are antenna numbers, fq is obs freq (GHz), uvr (uv-radius)
#      is not used but need something in this column
#
#--------------------------------------------------------------------------- 
# COMPATIBILITY MODE: 
#
#  USAGE: idocompat>0     turn on compatibility mode
#         idocompat<1	  (DEFAULT) turn off compatibility mode
#
# If the toggle idparam is set, then mpigridr will run in compatibility
# mode so it can take parameter inputs in earlier version scripts.
#
# Note that if compatibility mode is enabled, then if some parameters are
# not set (such as n_bandlines_max, n_srcfiles_max) then it will prompt
# stdin for input at the necessary points in the execution, which may
# cause inappropriate behavior if unexpected.  If not using compatibility
# mode then you should turn it off using idocompat=0.
#
# NOTE: In current version, compatibility mode is enabled by default.  This
# can be changed in module mpigridr.
#
#--------------------------------------------------------------------------- 
# COMPATIBILITY MODE: parameter setting
#
# Following the final "set ... &" line from stdin or parfile, or anywhere
# in parfile, a line it can parse as an old-style param line, e.g.
# 1 1 1 1 0 0 1 0 0 0
# will be treated as such, and those integer params (up to 12) which are:
# idoell idotemp idoweight ibandmode idogaus idodiff ipolmode idosrcpol
# idophase idocompress idorizero idoprint
# will override previously set values of these
#
#--------------------------------------------------------------------------- 
# PARFILES and DATFILES
#--------------------------------------------------------------------------- 
# If not specified as a command-line argument (if that feature is enabled
# on compilation) then can be set as normal:
#
# parfile=parfilename  : after this, open parfile and read remaining 
#                        parameters as if chosen from command-line
#                        NOTE: any set lines in scripts after this may
#                        cause problems (if no datfile used)
#
# datfile=datfilename  : read list of uv data files from this file instead
#                        of prompting from stdin (same as if set as
#                        command-line argument (see above)
#
#--------------------------------------------------------------------------- 
# DATFILES:
#--------------------------------------------------------------------------- 
# These are the lines that would normally be entered when prompted for
# lists of uv-files and scans.  They work the same.
# 
# Input lines are grouped into scans that are gridded together.  If using
# scan modes, then these are from a single DEC scan.  A blank line terminates
# scans.
#
# A second blank line terminates scan input (from datfile or stdin)
#
# Scans normally consist of a sequence of a line with a filename plus a line 
# with weight information, e.g.
#
# filename1
# weightline1
# filename2
# weightline2
# ...
# filenameN
# weightlineN
#
# If the parameter noisefactor (see below) is set, then it will not expect
# or prompt for the weightlines, so then you just give a sequence of files:
#
# filename1
# filename2
# ...
# filenameN
#
# THIS IS THE PREFERRED MODE OF OPERATION (the old mode is for compatibility).
# If you want to override the error scaling factor rather than use the 
# global noise factor, you can provide it after the filename.  If you do so,
# you can also provide a new raoffset to use if in differenced modes, e.g.
# idodiff>0, rather than use the global Roffset.  
#
# filename1 <errscale1 <raoffset1>>
# filename2 <errscale2 <raoffset2>>
# ...
# filenameN <errscaleN <raoffsetN>>
#
# If you do this, it will also not want separate weightlines.
#
#--------------------------------------------------------------------------- 
# COMPATIBILITY MODE: weightlines
#
# <wt_off <ampscale <errscale <raoffset <decoffset>>>>>
#
# where: wt_off    weight scale factor for this field (e.g. in mosaic)
#        ampscale  scale factor of vis amplitudes
#        errscale  scale factor for vis errors (e.g. noise correction)
#        raoffset  RA offset for idodiff>0 (override Roffset)
#        decoffset DEC offset for idodiff>0 (override Doffset, normally 0)
#
# Note that only errscale and raoffset are available on the filename line.
#
# Use Doffset to set a global DEC differencing offset if not in compatibility
# mode.
#
# There is a global ampfactor parameter (see below) but setting this will not 
# turn off compatibility mode.
#
#--------------------------------------------------------------------------- 
# FIXED SIZE PARAMETERS
#
#  USAGE: these cannot be changed using "set key=value"
#         nkeymax        max number of keys for get_keys
#         nsrcfilmax     max number of source files
#         nbandlinesmax  max number of band lines 
#
# These are set in mpiparams.F90 and fixed for use in parameter reading
# (and thus cannot be set themselves).
#
#--------------------------------------------------------------------------- 
# STANDARD CONTROL PARAMETERS
#
# Keys: idoell idotemp idoweight ibandmode idogaus idodiff ipolmode idosrcpol
#       idophase idocompress idorizero idoprint
# Also: idoleak (was part of ipolmode)
# THESE ARE THE STANDARD CONTROL KEYS (previously set on first line)
#  USAGE: idoell 
#                = 0     no ell weighting
#                = 1     (DEFAULT) ell weighting 2pi/l^2 (flat bandpower)
#                > 1     read in cshape arrays
#  USAGE: idotemp
#                > 1     Jy/sr read Falpha (flux units)
#                = 1     (DEFAULT) dT/T (w/Planck correction)
#                < 1     Jy/sr alpha=0.0 (flux units)
#     
#  USAGE: idoweight
#                > 3     1.0 uniform weight (unweighted)
#                = 3     1/sig^2 x K/Jy  (experimental)
#                = 2     1/sig (experimental)
#                = 1     (DEFAULT) 1/sig^2 (default)
#                < 1     1.0 uniform weight (unweighted)
#
#  USAGE: ibandmode 
#                < 0     as -ibandmode, but no S (doestim=.FALSE.) 
#                = 0     default, single bands and file for all matx
#                = 1     (DEFAULT) separate files for S,CN,CSrc,CP,C_XX (NEW 29Jul04)
#                > 1     as 1, but separate files for each C_XX band (N/A yet!)
#
#  USAGE: idogaus
#                > 2     Set Gaussian beam, Rcut = 0.1*idogaus*Ddish
#                = 2     Set Gaussian beam (use Gnorm, GFWHM)
#                = 1     Default Gaussian CBI beam & aacf
#                = 0     (DEFAULT) Default TJP CBI beam & aacf
#                < 0     TJP CBI beam/aacf, Rcut = -0.1*idogaus*Ddish
#
#  USAGE: idodiff
#                > 10    Treat as idodiff-10 but no beam factor in src proj
#                > 4     No differencing
#                = 4     M-T differencing opposite sign
#                = 3     M-(L+T)/2 differencing
#                = 2     Scan subtraction before gridding
#                = 1     Main-Trail differences
#                = 0     (DEFAULT) No scan projection
#         Note - the following options for controlling scan projection are
#         for compatibility.  It is preferred to use idoproj (see below)
#                < 0     Scan projection with abs(idodiff) matrices
#                <-10    No beam in src proj, else as idodiff+10
#         idodiff<0 sets idoproj=abs(idodiff) overwriting previous idoproj
#         (unless idoproj<-1) then sets idodiff=0
#
#  USAGE: ipolmode
#                = 1     full polarization
#                = 0     (DEFAULT) intensity only, grid RR and LL together
#                = -1    intensity only, grid RR only
#                = -2    intensity only, grid LL only
#                < -2    intensity only, grid RR and LL together
#
#  USAGE: idoleak
#                > 0     leakage correction (use std PA sign)
#                = 0     (DEFAULT) no pol leakage correction
#                < 0     leakage correction (use reverse PA sign, debug only)
#
#  USAGE: idosrcpol
#                > 0     pol src projection (only) for first idosrcpol of NS
#                else    (DEFAULT) no pol src projection
#
#  USAGE: idophase
#                > 2     PA factor i*2*theta_v
#                = 2     grid using PA factor -i*2*theta_k, project using 
#                        i*2*(theta_v-theta_k) FOR E/B ESTIMATORS
#                = 1     (DEFAULT) PA factor i*2*theta_v
#                = 0     PA factor i*2*(theta_v-theta_k) (use if applied in 
#                        cbical/cbipol/AIPS) 
#                < 0     as > 0 but with opposite sign (debug mode)
#         NOTE: for CBI use default idophase=1 (produced Q+iU estimators)
#               for CBI E+iB estimators, use idophase=2
# 
#  USAGE: idocompress
#                < 0     as abs(idocompress) but compress identical fields
#                  0     no compression, keep each visibility per field
#                  1     limited compression, compress identical vis each field
#                  2     major compression, allow conjugates for RR,LL,RL<->LR
#                  3     full compression, any antenna pairs
#                > 3     extreme compression, compress RR and LL together
#
#   NOTE: 1 will only compress exactly same visibilities
#         2 will compress opposite conjugations same equiv. poln and antennas
#         3 will compress regardless of antennas
#         4 will compress RR and LL also in additon to 3
#         
#         RL will be compressed into equiavlent LR (and visa versa) if >1
#         Frequencies will always be kept separate
#
#         Compression of files/fields (idocompress<0)
#           will only compress to the latest field so you must put
#           the files from the same field together in the list, otherwise
#           it will be called a new "field"
#
#         Compression and scan gridding
#           scan gridding will probably work for any compression since all
#           scans will be compressed the same way
#           safer if abs(idocompress).LT.1
#          strict scan projection should use no compression
#
#         Compression and leakage
#           for leakage correction, limited to abs(idocompress).LT.3
#           since it needs a and b antennas preserved
#
#  USAGE: idorizero
#                = 1     set off-diag CN,CSrc,CProj,C_XX elements to zero
#                else    (DEFAULT) use correct off-diagonal elements
#         NOTE: for debugging only - CBI use default idorizero=0
# 
#  USAGE: idoprint
#                > 1     even more output(e.g. C(i,j) for all i,j)
#                = 1     more output 
#                = 0     (DEFAULT) some diagnostic output
# 
#--------------------------------------------------------------------------- 
# ARRAY SIZE PARAMETERS
# Max sizes: nbeam nfldmax nsrcmax nsrccor nprojmax
#    USAGE: these set grid and max array sizes
#         nbeam          default size for nbeamgrid (DEFAULT=83)
#         nfldmax	 max number of fields in a scan 
#         nsrcmax        max number of sources to read in
#         nsrccor        max number of source projection matrices
#         nprojmax       max number of scan projection matrices
# 
# NOTE: the defaults for these are set in mpiparams.F90
#
#--------------------------------------------------------------------------- 
# OTHER CONTROL PARAMETERS
# Modes: idoestim idonoise idoproj idosrcs idobands idogrids idopsf
#    USAGE: these control what is computed and written out (0=NO 1=YES)
#           idoestim=1   write estimator vector(s)
#           idonoise=1   calculate noise covariance matrix
#           idosrcs=1    calculate source projection matrices
#           idobands=1   write signal band covariance matrices
#           idogrids=1   calculate grid matrices (necessary for idoband=1)
#
# Scan projection conrol: idoproj
#           idoproj=N    N>0: calculate N scan projection matrices
#                        N=0: no scan projection (regardless of idodiff)
#                        N=-1: mode determined by idodiff (default)
#                        N<-1: scan mode but no matrices
#
#   NOTE: can also be set via idodiff<0 (see above)
#   If idodiff>0 (differencing chosen), the scan projection can also be
#   enabled by explicitly setting idoproj>0 (else it is disabled).  For
#   example, idodiff=2 idoproj=1 subtracts the scan mean and also projects
#   it out.
#
# PSF vector construction: idopsf
#           idopsf=1     write PSF vector for point source at mosaic center
#           idopsf=2     write PSF vector for point source at field centers
#                        (sets all vis to 1 regardless of field position)
#
#--------------------------------------------------------------------------- 
#
# Boot control: ireadboot idumpboot file_boot file_dump
#    USAGE: ireadboot=1   restart from boot file file_boot
#           idumpboot=1   write out intermediate state into file file_dump
#    NOTE: if filename not specified will propt stdin during execution
#
# MFS control: idomfs fqref Falpha
#    USAGE: idomfs=0      (default) grid using usual spectrum (idotemp)
#           idomfs=1      lin-freq MFS grid x ([fch-fqref]/fqref)
#           idomfs=2      log-freq MFS grid x ln(fch/fqref) for each chan
#           fqref=<val>   set ref frequency in GHz (default 31.0)
# 
#           Falpha=<val>  set spectral index for idotemp=2 gridding
#
# Z normalization control: idoznorm
#    USAGE: controls the normalization (s_z_vec) of estimators
#           idoznorm=0    (default) z_i = Sum_k w_k (vis weights only)
#           idoznorm>0    z_i = Sum_k w_k*g_k**|idoznorm| (beam g_k)
#    NOTE: idoznorm=1 will produce estimators equiv to vis (PSF vec will =1)
#
# visibility weighting control: idovnorm
#    USAGE: controls the visibility weighting when gridding to estimators
#           idovnorm=0    (default) w_k (raw vis weights only)
#           idovnorm>0    w_k = w_k / sumviswt
#    NOTE: sumviswt = Sum_k w_k for ALL vis in scan (not just those gridded)
#          THIS WILL APPROXIMATELY GIVE UNIFORM WEIGHTING TO SCANS IN MOSAIC
#          TO AVOID STRIPING IN IMAGES - Not recommended for power-spectrum
#
# Grid mode control: igridmode
#    USAGE: igridmode<0   pseudo-ungridded mode (include beam factor)
#           igridmode=0   pseudo-ungridded mode (grid to nearest est, no beam fac)
#           igridmode=1   (default) use beam grid kernal
#    NOTE: For igridmode<1, will grid visibilities only to the nearest estimator
#          Recommended for single-field data only (with or w/o differencing),
#          as the lack of multiple-estimator gridding will mess up mosaicing.
#
# Grid uv radius
#           ruvgridmin    default or <0.0 ==> 1.0		
#    Will grid to estimator if within allowed uv radius Ddish/Lambda x ruvgridmin
#    NOTE: if igridmode.NE.0 then will cut off at ruvgridmin=1.0 due to beam anyway,
#    so in practice, values <1.0 are the useful ones.
#
#--------------------------------------------------------------------------- 
# PROCESSING: values for processing
# 
# Sky Beam: nbsky file_beamsky
#    USAGE: set size of beamsky array to nbsky, read in from file_beamsky
#           this is the on-sky beam used for source projection
#
# Beamgrid: nbgrid delta_u ugridmax
#    USAGE: nbgrid        set dimension of beam grids (else use nbeam) (int)
#           ugridmax      radius of beamgrid, usually = 2.0*Ddish/wchan(1)
#           delta_u       fine-grid in wavelengths usually set to 
#                           delta_u=umax/kmax where kmax=(nbgrid-3)/2)
#                           for padding (the 3 is for one-cell padding)
#           Ddish         diameter of dish in cm (single dish size for now)
#
# Beam: GFWHM Gnorm Falpha 
#    USAGE: set Gaussian beam parameters, useful only if idogaus=2
#           GFWHM         FWHM of Gaussian beam at 30GHz
#           Gnorm         rescale beam values by this factor (not recommended)
#
# Lattice: s_ellmin s_ellmax s_igrid s_jgrid s_ell_outer s_igrid_2 s_jgrid_2 
#    USAGE: these set the construction of the coarse-grid estimator lattice
#           s_ellmin      inner ell radius in lattice
#           s_ellmax      outer ell radius in lattice
#           s_igrid       number of fine-grid cell per coarse cell in u (int)
#           s_jgrid       number of fine-grid cell per coarse cell in v (int)
#
#           It is possible to place a second zone for gridding at a different
#           coarse grid size:
#
#           s_ell_outer   outer ell radius of second zone
#           s_igrid_2     coarse/fine cell in u for second zone (int)
#           s_jgrid_2     coarse/fine cell in v for second zone (int)
#
#    NOTE: if s_ell_outer > s_ellmax then second zone is outside first zone
#
# Read selection: dochan doant ba_min ba_max ell_min ell_max ra_center dec_center
#    USAGE: dochan  (list of flags for inclusion of channels 1:nchan; DEFAULT: all)
#             e.g.  dochan=all
#                   dochan=T,T,F,T,T,T,T,T,T,T (flag 3rd channel CH3 on CBI)
#
#           doant   (list of flags for inclusion of antennas 1:nant; DEFAULT: all)
#             e.g.  doant=all
#                   doant=T,T,T,F,T,T,T,F,T,T,T,T,T  (flag Rx3 = 4th CBI antenna)
#
#           NOTE: for dochan and doant, if you give a list shorter than nchan or nant
#                 it will set the remainder to T
#
#           ba_min, ba_max     (min,max baselines to include, in cm; DEFAULT: 0,0=all)
#           ell_min, ell_max   (min,max ell to include; DEFAULT: 0,0=all)
#           
#           ra_center, dec_center  (location of mosaic center)
#             e.g.  ra_center=04:13:26.2 dec_center=10:27:57.6
#                   ra_center=center dec_center=center   (use first field center)
#
# Data Handling: Roffset, Doffset, noisefactor, ampfactor
#    USAGE: Roffset       RA switching separation for differencing (idodiff>0)
#           Doffset       DEC switching separation (idodiff>0)
#           noisefactor   scale factor for visibility errors
#           ampfactor     scale factor for visibility amplitudes
#
#    NOTE: these are global values applied for all data files unless overridden
#          for specific files (see above).
#
# Estimators: s_z_cut
#    USAGE: s_z_cut       lower cutoff for estimator weights (Z)
#
#--------------------------------------------------------------------------- 
# FILES: shapes, sources, band output
# 
# Shapes: file_clshape cl_norm cl_col file_eeshape ee_norm ee_col ...
#    USAGE: for temperature or pol product (ee, bb, te, tb, eb)
#
#           file_clshape  name of file to read in for cl (or special code)
#           cl_col        column number from file_clshape to use
#           cl_norm       scale factor or cl value to use (see below)
#
#           similarly for pol:
#
#           file_eeshape, file_bbshape, file_teshape, file_tbshape, file_ebshape
#           ee_norm, bb_norm, te_norm, tb_norm, eb_norm
#           ee_col, bb_col, te_col, tb_col, eb_col
#
#    NOTE: the file is expected to be in free-format, if xx_col is > 1 then expects
#          first column to be ell, if xx_col=1 then expects one per ell each ell
#
#          Typically cmbfast output files are in uK**2, use so cl_norm=1.3467e-13
#
#          xx_col can be given a code instead of filename, for example
#                -1 = do nothing (turn off this polarization)
#                 0 = const c_l with value xx_norm (in DT/T)
#                 1 = flat bandpower with value xx_norm (in DT/T)
#
# Sources: n_srcfil_max addsrc
#    USAGE: addsrc=srcline WHERE srcline is usual source line
#              srcline is filename followed by optional parameter PAR
#              File is source list with free format: 
#                Name RA Dec Freq Flux Err Alpha
#              Default action is to subtract Flux, project Err
#              Filename may be prepended by character to control action:
#                -       = subtract Flux, ignore Err
#                +       = add Flux, project Err
#                &       = ignore Flux, project Err
#                @       = project Flux, ignore Err
#                *       = scale Flux and Err by PAR1, then as default
#                ^       = project Flux*PAR1, subtract Flux*(1-PAR1), ignore Err
#                $       = project with 1, ignore Flux,Err
#     NOTE: in shell scripts these characters usually must be escaped with \
#     Examples:
#           addsrc=srcfile &
#           addsrc=$srcfile  (or in shell script addsrc=\$srcfile)
#           addsrc=*srcfile 1.5
#
# Output: file_output
#    USAGE: file_output=rootname WHERE rootname is prepended to output files
#
# Bands: n_bandnames_max addband
#    USAGE: add another band (or pol for existing band) to compute
#           options:
# 
#           addband=name pol=p NB=NB limit=l1,...,1n 
#                        (n=2 or 2*NB upper/lower limit pairs)
#
#           addband=name pol=p NB=NB bound=b1,...,bn
#                        (n= NB-1, NB, or NB+1 boundaries)
#
#    NOTE: for NB=0 no other lims (use full ell range)
#      Uses rest of line up to end
#      Will name band files as rootname_name_XX where XX is the pol (e.g. TT)
#      For polarization use p=0 (use same limit/bound for all pols) or
#        set each pol separately (use same name)
#      Set n_bandname_max to at least the number of band runs you want
#
#---------------------------------------------------------------------------
# USAGE NOTEs:
#
# To run with different dish size and beam with Gaussian approximation, set
# Ddish=dish dia (cm), GFWHM=beam (arcmin at 30GHz), and use idogaus=2,
# e.g. for CBI2
# idogaus=2 Ddish=140.0 GFWHM=30.0
# or whatever the beam is at 30GHz.
# c.f. CBI1 (the default values): Ddish=90.0 GFWHM=45.1
#
#---------------------------------------------------------------------------
# OUTPUT FILE FORMATS:
#---------------------------------------------------------------------------
# Standard output files: These are Fortran unformatted files
#
# _SVEC     Estimator vector (subroutine write_estim in mpigridr.F90)
#
#      REAL, DIMENSION(nx) :: ugrid, vgrid  ! u,v of estimator centers
#      REAL*8, DIMENSION(nx) ::  zgrid      ! sum of weights each estimator
#      REAL*8, DIMENSION(NV) ::  SVector    ! estimator vector
#      REAL*8 ::  ra_center, dec_center     ! ra,dec of phase center (radians)
#
#      NV=2*nx  ! number of real+imaginary for nx = nslist + nplist estimators
#               ! nslist = # of RR estimators, nplist = # of RL estimators
#
#      WRITE(iout) NV, 2*nslist, 2*nplist
#      WRITE(iout) (SVector(i),i=1,NV)
#      WRITE(iout) (ugrid(i),i=1,nx)
#      WRITE(iout) (vgrid(i),i=1,nx)
#      WRITE(iout) (zgrid(i),i=1,nx)
#      WRITE(iout) ra_center, dec_center
#
#
# _PSF uv psf vector (subroutine write_psf in mpigridr.F90)
#
#  (same format as _SVEC - this is just an estimator vector for a point
#   source at the phase center!)
#  
#
# _NOIS    Noise covariance matrix (subroutine write_noise in mpigridr.F90)
#
#
#      REAL*8, DIMENSION(NV,NV) :: CNoise
#      ! others same as _SVEC 
#      ! NOTE: only lower triangle of CNoise is written as it is Hermitian
#
#      WRITE(iout) NV, 2*nslist, 2*nplist
#      DO ipt = 1, nx
#         nr = 2*ipt-1
#         ni = 2*ipt
#         WRITE(iout) ipt
#         WRITE(iout) (CNoise(nr,j),j=nr,1,-1)
#         WRITE(iout) (CNoise(ni,j),j=ni,1,-1)
#      END DO
#      WRITE(iout) (ugrid(i),i=1,nx)
#      WRITE(iout) (vgrid(i),i=1,nx)
#      WRITE(iout) (zgrid(i),i=1,nx)
#
# _CSRC   Source projection matrix  (subroutine write_csrc in mpigridr.F90)
#
#
#      REAL*8, DIMENSION(NV,NV,NS) :: CSource
#      ! others same as _SVEC 
#      ! NOTE: only lower triangle of CSource is written as it is Hermitian
#      ! NS = # of source covariance matrices
#
#      WRITE(iout) NV, 2*nslist, 2*nplist
#      WRITE(iout) NS
#      DO ipt = 1, nx
#         nr = 2*ipt-1
#         ni = 2*ipt
#         WRITE(iout+myid) ipt
#         DO ism = 1, NS
#            WRITE(iout) (CSource(nr,j,ism),j=nr,1,-1)
#            WRITE(iout) (CSource(ni,j,ism),j=ni,1,-1)
#         ENDDO
#      ENDDO
#      WRITE(iout) (ugrid(i),i=1,nx)
#      WRITE(iout) (vgrid(i),i=1,nx)
#      WRITE(iout) (zgrid(i),i=1,nx)
#
#
# _PROJ   Scan projection matrix  (subroutine write_cproj in mpigridr.F90)
#
#
#      REAL*8, DIMENSION(NV,NV,n_proj) :: CProj
#      ! others same as _SVEC 
#      ! NOTE: only lower triangle of CProj is written as it is Hermitian
#      ! n_proj = # of scan projection matrices
#
#      WRITE(iout) NV, 2*nslist, 2*nplist
#      WRITE(iout) n_proj
#      DO ipt = 1, nx
#         nr = 2*ipt-1
#         ni = 2*ipt
#         WRITE(iout) ipt
#         DO ism = 1, n_proj
#            WRITE(iout) (CProj(nr,j,ism),j=nr,1,-1)
#            WRITE(iout) (CProj(ni,j,ism),j=ni,1,-1)
#         END DO
#      END DO
#      WRITE(iout) (ugrid(i),i=1,nx)
#      WRITE(iout) (vgrid(i),i=1,nx)
#      WRITE(iout) (zgrid(i),i=1,nx)
#
#
# _XX  Band signal covariance matrix  (subroutine write_bands in mpigridr.F90)
#      XX = TT (ipol=1), EE (2), BB (3), EB (4), TE (5), or TB (6)
#
#
#      REAL*8, DIMENSION(NV,NV,NB) :: C_XX
#      ! others same as _SVEC 
#      ! NOTE: only lower triangle of C_XX is written as it is Hermitian
#      ! ipol = polarization id (see above)
#      ! NB = # of bands (for bandpowers) for this ipol
#
#      REAL, DIMENSION(1:NB) :: bandlower, bandupper ! min,max ell each band
#
#      WRITE(iout) NV, 2*nslist, 2*nplist
#      WRITE(iout) ipol, NB
#      WRITE(iout) bandlower(1:NB)
#      WRITE(iout) bandupper(1:NB)
#      DO ipt = 1, nx
#         nr = 2*ipt-1
#         ni = 2*ipt
#         DO k = 1,NB
#            WRITE(iout) ipt
#            WRITE(iout) (C_XX(nr,j,k),j=nr,1,-1)
#            WRITE(iout) (C_XX(ni,j,k),j=ni,1,-1)
#         END DO
#      END DO
#      WRITE(iout) (ugrid(i),i=1,nx)
#      WRITE(iout) (vgrid(i),i=1,nx)
#      WRITE(iout) (zgrid(i),i=1,nx)
#
#
#---------------------------------------------------------------------------
# Dump files: These are Fortran unformatted files also
#
#    the dump files are written in subroutine dumpboot in mpireadmod.f90
#    the dump files are read in subroutine readboot in mpireadmod.f90
#
# Dump files are intended to enable restarting of gridr after gridding
# in order to make different bandpower matrices (without regridding).
# However, it can be useful for other things since the "R-matrices"
# contain all the info relating estimators to uv-plane
#
# The dump/boot files are:
#
#    _Svec.dmp      = intensity estimators (complex)
#    _Spol.dmp      = polarization estimators (complex)
#    _Nvec.dmp      = noise covariance for intensity
#    _Npol.dmp      = noise covariance for polarization
#    _Rvec.dmp      = R-matrix for intensity estimators
#    _Rpol.dmp      = R=matrix for polarization estimators
#    _Leak.dmp      = R=matrix for gridded linear leakage (int. into pol.)
#    _Fsrc.dmp      = source means for subtraction from intensity estimators
#    _Fpol.dmp      = source means for subtraction from polarization estimators
#    _Dsrc_N.dmp    = source covariances for intensity
#    _Dpol_N.dmp    = source covariances for polarization
#    _Proj_N.dmp    = scan projection for intensity
#    _Ppol_N.dmp    = scan projection for polarization
#
# Not all dump/boot files will necessarily be there, depends on gridr mode chosen
#
# See the subroutine readboot in mpireadmod.f90 for contents and formats of these
# files.
#
#