; MODVF
;---------------------------------------------------------------
;! task to create a warped velocity field
;# Task Imaging Modeling 
;-----------------------------------------------------------------------
;;  Copyright (C) 1995
;;  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
;-----------------------------------------------------------------------
;---------------------------------------------------------------
MODVF     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
MODVF:  Task to create a warped velocity field
INFILE                             Input file name (Non-AIPS)
OBJECT                             Source name
IMSIZE                             Output image size (cells)
CELLSIZE                           Cellsize sec.
OUTNAME                            Output image name (name)
OUTCLASS                           Output image name (class)
OUTSEQ           -1.0     9999.0   Output image name (seq. #)
OUTDISK           0.0        9.0   Output image disk unit #.
APARM                              User supplied array
XINC                               Width of rings in arcsec.
----------------------------------------------------------------
MODVF
Adverbs:
  INFILE.....A file external to the AIPS system from which the
             rotation curve and warping data is read.
  OBJECT.....Object name.
  IMSIZE.....Desired image size in cells.
  CELLSIZE...Desired cell spacing in arcsec.
  OUTNAME....Output image name (name).     Standard behavior
             with default = 'MODVF MAP'.
  OUTCLASS...Output image name (class).    Standard defaults.
  OUTSEQ.....Output image name (seq. #).   0 => highest unique.
  OUTDISK....Disk drive # of output image. 0 => highest number
             with sufficient space.
  APARM......(1),(2): kinematical centre in pixels; (3),(4):
             position angle major axis and inclination of
             reference disk. (5) Systemic velocity
  XINC.......Width of each ring in arcsec
----------------------------------------------------------------
MODVF:  Task which creates a warped velocity field.
DOCUMENTOR: Gustaaf van Moorsel, NRAO.
RELATED PROGRAMS: GAL

                          PURPOSE

MODVF creates a modeled galaxy velocity field based on information in
APARM and in the external file specified by INFILE. In APARM the user
specifies basic parameters of the reference disk, i.e.  the disk of
radius R within which no warping takes place. INFILE contains the
necessary information about the rotation curve and possible warping
beyond R. In contrast to earlier modeling tasks, the warp is not
specified by variations in position angle and inclination. Though
these parameters are easily observable, they are very specific to the
position of the observer with respect to the galaxy. Instead, MODVF
uses two angles which are more meaningful: 1) the warp angle, which is
the angle between the angular momentum vector and the reference disk,
and 2) the twisting angle of the warp. For a more extensive discussion
and explanation see Christodolou et al. (1993).

MODVF divides the actual warped galaxy in cells, the size of which are
specified by XINC. Each of these cells are projected on the plane of
the sky as seen by the observer. Two things may go wrong using this
approach:

1 - certain pixels do not receive a value; there is no cell in the
galaxy which projects on such a pixel. The remedy is to choose XINC
sufficiently small: one-half the pixel size is recommended, but in
strongly warped systems XINC may have to be chosen even smaller, and
MODVF takes longer to execute.

2 - certain pixels receive more than one value; several cells in the
galaxy end up projected on the same pixel. In this case MODVF will
average the contributions of these cells. This is OK if the cells are
adjacent in the galaxy as well. Things go wrong if cells from quite
different locations in the galaxy end up in the same pixel. This can
happen whan the warp is so strong that the galaxy 'folds' and we see
several portions of the disk in the line of sight. Averaging then is
clearly the wrong thing to do, and the user should always be aware of
this danger.

A closer look at some of the adverbs:

INFILE

INFILE contains all the information about the warp and the rotation
curve. Each line in INFILE describes one ring in the galaxy. The first
item on the line is the radius in arcsec, the second item the velocity
in km/s, the third item the warp angle in degrees, and the fourth item
the twisting angle in degrees. A simplified INFILE could look like
this:

20  132 0 0
40  152 0 0
60  172 0 0
80  192 0 0
100 212 0 0
120 212 5 0
140 212 10 5
180 212 15 10

The rotation curve becomes flat at radius 100". At radius 120", the
ring tilts 5" out of the plane of the reference disk (which is the
disk up to 100"), and in subsequent rings it tilts further by the same
amount.  In ring 140", the azimuth of the warp angle as measured in
the reference disk is displaced by 5 degrees with respect to the
previous ring. At 160" it is twisted by yet another 5 degrees for a
total of 10 degrees.

Clearly INFILE can be adapted in a way to reflect any warp model, e.g.
linear increases in the two angles beyond a certain radius (as in the
above example).

IMSIZE, CELLSIZE

As in many other tasks, IMSIZE and CELLSIZE define the size of the
output image in pixels, and the pixel increment in arcsec.

APARM

APARM is used to 'place' the reference disk in space. APARM(1) and (2)
define the pixel coordinates of the kinematical center, (3) and (4)
define the position angle of the major axis and the inclination of the
galactic plane, and (5) specifies the velocity in km/s. Note that
these definitions agree with the ones in GAL.

XINC

XINC specifies how the galaxy is divided up in cells. The galaxy is
divided in many rings of width XINC arcsec (note: these rings are not
the same as the ones specified in INFILE), and every ring is divided
up in small segments which are as 'square' as possible. A too coarse
XINC leads to 'blank' or 'black' spots in the output image. A too fine
XINC does no harm apart from increasing the execution time.


Reference:

Christodolou, D.M., Tohline, J.E., and Steiman-Cameron, T.Y.,
"Modeling of Warps in HI disks", 1993, Ap.J. 416, 74.
