; BSMAP
;---------------------------------------------------------------
;! images weak sources with closure phases
;# Task Imaging
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 2008, 2019
;;  Associated Universities, Inc. Washington DC, USA.
;;
;;  This program is free software; you can redistribute it and/or
;;  modify it under the terms of the GNU General Public License as
;;  published by the Free Software Foundation; either version 2 of
;;  the License, or (at your option) any later version.
;;
;;  This program is distributed in the hope that it will be useful,
;;  but WITHOUT ANY WARRANTY; without even the implied warranty of
;;  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;;  GNU General Public License for more details.
;;
;;  You should have received a copy of the GNU General Public
;;  License along with this program; if not, write to the Free
;;  Software Foundation, Inc., 675 Massachusetts Ave, Cambridge,
;;  MA 02139, USA.
;;
;;  Correspondence concerning AIPS should be addressed as follows:
;;         Internet email: aipsmail@nrao.edu.
;;         Postal address: AIPS Project Office
;;                         National Radio Astronomy Observatory
;;                         520 Edgemont Road
;;                         Charlottesville, VA 22903-2475 USA
;-----------------------------------------------------------------------
BSMAP     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
BSMAP     Task for Bi-Spectrum imaging of simple, weak objects
INNAME                             Input UV file name (name)
INCLASS                            Input UV file name (class)
INSEQ             0.0     9999.0   Input UV file name (seq. #)
INDISK            0.0        9.0   Input UV file disk unit #
OUTNAME                            Output image name (name)
OUTSEQ           -1.0     9999.0   Output image name (seq. #)
OUTDISK           0.0        9.0   Output image disk unit #.
IMSIZE            3.0       21.0   Image size
CELLSIZE      0.00001              Cell size in arcseconds
ERROR             0.0              Error per weight in uv data
UVWT                               Weighting 'UN' => uniform,
                                      else natural
DETIME            0.0              Vector averaging time (mins)
----------------------------------------------------------------
BSMAP
Task:  This will perform bi-spectrum imaging of weak objects
       for which self-cal is required but not possible. It
       replaces the combination of CALIB and IMAGR.

       NOTE: this task does NOT apply flagging or calibration tables
       to the input UV data.  Run SPLIT first if that operation is
       desired.
Adverbs:
  INNAME.....Input UV file name (name).      Standard defaults.
                The sort order must be 'TB'.
  INCLASS....Input UV file name (class).     Standard defaults.
  INSEQ......Input UV file name (seq. #).    0 => highest.
  INDISK.....Disk drive # of input UV file.  0 => any.
  OUTNAME....Output image file name (name).  Standard defaults.
  OUTCLASS...Output image file name (class). Standard defaults.
  OUTSEQ.....Output image file name (seq. #). 0 => highest
                unique.
  OUTDISK....Disk drive # of output image file. 0 => highest
                with space for the file.
  IMSIZE.....Sizes of output images in pixels
  CELLSIZE...Cell sizes of output images in arcseconds
  ERROR......Error per weight in uv data in Jy
  UVWT.......Weighting 'UN' => uniform, else natural
  DETIME.....Vector averaging time for input visibilities (min)
             0 = > 1/6 minute.
----------------------------------------------------------------
Task: BSMAP
Purpose: Bi-Spectrum imaging of simple, weak objects
Programmer: T.J. Cornwell
Documentor: T.J. Cornwell
Date of Documentation: 8 Jul 1986
Version: 15OCT86
Related Programs: None

INTRODUCTION:
	BSMAP will image simple objects which are too weak for
self-calibration. Generally, this means objects for which the
visibility is comparable or less than the noise in an
atmospheric coherence time. BSMAP does not attempt to estimate
the atmospheric phase error at each antenna, instead it
averages the Bi-Spectrum (hence the name), onto a very coarse
grid. The bi-spectrum is a function of two pairs of (u,v)
coordinates and is the triple product of three visibilities
around a loop of three antennas specified by the coordinates.
The phase part is just the closure phase, which self-calibration
exploits. BSMAP is then just a smart way of averaging the
closure phase for many atmospheric coherence times to build up
signal to noise.  The Bi-Spectrum data is analyzed in two ways:
        1. The complete Bi-Spectrum is averaged to find the best
estimate of the flux of any point source present. This is more
sensitive than the second method, in which an image is formed.

	2. After the averaged bi-spectrum is formed from the
data, the corresponding visibility function is found by a
least-squares fit. This visibility function is then inverted to

form an image. A beam is also output. Only very small images
can be supported at the moment, but this may change sometime.
The image classes are 'BSMAP' and 'BSBEAM' respectively.
Sometimes this fit will fail; this is a very good indication
that either no source is present or that it really is buried in
the noise.
	The gridding used is simple cell-summing so don't
expect the dynamic range to be great. About a few hundred
to one for a 21**2 pixel image and 20,000 visibilities is

reasonable. Noise will probably kick in before this limit
anyway.
******* Note that all positional information is lost *******.
Unlike ASCAL, BSMAP has no input positional reference frame
to refer to. Roughly speaking the centriod of emission is
shifted to the center of the field.

        The resulting map and beam can be cleaned using APCLN.
Use LGEOM to expand the images to, say 64**2 pixels, and then
use APCLN. Remember to restrict the box to less than half the
BSMAP image size e.g. for 21*21 BSMAP images you can only CLEAN
a 10*10 box!

IMSIZE:
	BSMAP can only estimate very small images at the moment.
The gridding of the data is related to the image size: smaller
images cause more averaging of the bi-spectrum and thus, in
marginal cases, image size can be traded off against SNR.
	The current limit in image size is =< 21**2 pixels
split between the two axes.

CELLSIZE:
	In view of the poor SNR of most data which will be
passed through BSMAP, fairly coarse grids can be used, say
2 pixels per beam. BSMAP will tell you how many points fall
off the edge of the grid so you could adjust to keep this
small.

UVWT:
        The final image and beam can be naturally or uniformly
weighted. Natural weighting is the default, and is, of course,
recommended for weak sources.

DETIME:
        The input visibilities can be averaged coherently before
forming the bi-spectrum. This will help the SNR considerably.
DETIME must be less than the atmospheric coherence time!

ERROR:
        ERROR is the expected noise per weight per complex
correlator. It is not really very critical so the default of
25 mJy per weight will probably do for most VLA data except
1.3cm.

COMMENTS:
	This is an extremely experimental task. Please
talk to Tim Cornwell about any problems you encounter.

RUNNING TIME:
	Currently about 15 minutes of CPU time for about
200,000 visibilities. This may seem a lot but remember:
BSMAP replaces several passes of (CAL, IMAGR)
Large amounts of core are used. For large images on a VAX some
paging will undoubtedly occur. 15*15 pixel images require about
1000 pages working set.
