12.6 Adding your own tasks to AIPS

This Section is a brief guide for the user who wants to modify an existing task in AIPS or to write a new task. While it is difficult to write an AIPS task from scratch, AIPS contains several template tasks that are designed to hide most of the work from the “occasional” programmer. Anyone familiar with FORTRAN and a little of the system services of their local computer should be able to add convenient tasks to their local version of AIPS with a little practice and patience. The growing use of binary installations makes this more difficult since local sites are unlikely to have the relevant compilers.

12.6.1 Initial choices to make

The simplest way to write an AIPS task is to modify one of the four template tasks, TAFFY, CANDY, FUDGE or UVFIL. These tasks handle the AIPS I/O, contain extensive documentation, need to be modified in only a few well-defined places, and can be easily interfaced to user subroutines. They are limited in their ability to handle many input and output images, however, and generally operate on one image row or one visibility point at a time. Softening of these limitations will be discussed in 12.6.5.

TAFFY — This template task reads an existing image in AIPS line by line, modifies the line of data as desired and then creates and writes the modified image in AIPS. This template task might, for example, be used to blank pixels in an input image in some specified manner.

CANDY — This task is similar to TAFFY except the input data are contained in an auxiliary file which is FORTRAN readable and outside AIPS. The task can transfer an image in any reasonable format outside AIPS into the AIPS data structure.

FUDGE — This template task reads an existing AIPS uv database optionally applying calibration, editing, and data selection, modifies the results point by point, and then creates and writes this modified output uv database in the AIPS catalog. This template task might, for example, be used to modify a uv data base for which the time parameter has been incorrectly written.

UVFIL — This task is similar to FUDGE without calibration and editing, except that the input uv data are contained in one or two auxiliary files, which are FORTRAN readable and outside AIPS. The task is useful for translating visibility data in an arbitrary format into an AIPS cataloged uv data set, or for computing a uv data set from model sources.

If you wish to make a minor change in an existing AIPS task, it will be simpler to copy the AIPS task itself and modify it as needed. For example, if you wanted to add a option in COMB to combine two input images in a new way to obtain a resultant image, it would be better to start with COMB itself than with one of the templates. However, non-trivial changes to major tasks will require a careful look at the code, which is generally well documented and segmented.

Changes to tasks that make plots and/or use the TV and other graphics devices can be tricky, but are useful sometimes. Changes to imaging and deconvolution software should not be attempted unless the changes are almost trivial. Modifying existing verbs or creating new ones require you to find which AUxx.FOR routine is involved and then require the entire AIPS program to be relinked. Going AIPS describes some of the considerations. The new pseudoverbs VERB and PSEUDOVB allow you to update your AIPS vocabulary using your own procedure rather than by changing the supplied vocabulary files and executing POPSGN as described in Going AIPS. In all cases, do not put your modified code into the standard AIPS code areas unless your local AIPS Manager agrees and has made a backup copy of the original code and executables. Such modified files may well disturb the AIPS updates done by the so-called “Midnight Job.”

12.6.2 Getting started

Even if you have special privileges in AIPS, it is wise to generate and link new code in your own user directory rather than in your installation’s designated local AIPS directory. After the code has been written and tested, check with your local AIPS Manager about installing it in a public area. Decide which template task or other AIPS task you want to modify, then follow these instructions after logging into your private area.

Under Unix

% source /AIPS/LOGIN.CSH  C R

to get the basic AIPS system logicals under a c-shell, or


to get the basic AIPS system logicals under a korn, bourne, or bash shell. (These assume that your AIPS system home directory is called /AIPS).

% $CDTST (or $CDNEW)  C R

to set up the logical assignments for programming.


to locate the task called TASK.


to create a file of linking information for a task found in area AREA, e.g.APLPGM for TAFFY, APGNOT for FUDGE, CANDY and UVFIL, YPGM for IMEAN, etc.


to copy code for TASK into your area and to give it a new name (5 letters).


to copy and rename the inputs/help file for the task.

% setenv MYAIPS ‘pwd‘  C R

to define MYAIPS (must be uppercase) as your disk area for AIPS programs, or

% export MYAIPS=‘pwd‘  C R

to define the MYAIPS environment variable under korn, bash, and bourne shells.

12.6.3 Initial check of code and procedures

Before modifying the task in any way, it is wise to compile, link and execute the unchanged task to check that the original code is sound and that all of the AIPS logical assignments have been properly set. The duplicated AIPS task should run identically to the original; the template tasks are set up to duplicate the input data set with no changes and default parameters. In this way errors or other problems associated with the generation of new tasks can be found and corrected before getting into the quagmire of bugs that you are about to add. Note that CANDY and UVFIL require external data files and are therefore not so easily checked.

One change is needed in the FORTRAN program before checking. In the main program, about 60 lines down, there is a data statement which identifies the task.


Change this to


The maximum number of characters in a task name is five and the DATA statement must be in the above form. There is no need to change the help file yet, as long as it is named NTASK.HLP.

To compile and link the task, type:


To compile the task for debugging, add the DEBUG NOOPT options to the COMLNK line. There should be no error messages and no significant warnings.

After successful compilation and linking, try executing the task. Under Unix, stay logged in to your area. To initiate the AIPS program, type:

% aips  C R


% aips debug  C R

to use the debugger (e.g.dbx) on tasks compiled with the DEBUG option. You will have to tell the procedure which debugger you want and that you do not want to start AIPS itself under that debugger.

Your AIPS Manager may have to make some arrangements for you to activate AIPS from your login. Once you have started AIPS, type


to specify the location of inputs and help information and of the task executable.

Set up the input parameters, then

> INP  C R

to review the input parameters. You should be told AIPS 1: Found in Version=MYAIPS at the start of the inputs display. If not, there is something wrong with the logical or task name or the location of the inputs/help file.

> GO  C R

to run the task. The Found line should appear again.

12.6.4 Modifying an AIPS task

If you are modifying an existing task, the only ground rules are to read the task carefully and note the locations where changes must be made. Unlike the template tasks which are organized so that additional code need be inserted in only one or two places, an AIPS task may need revisions in a variety of places. Some guidelines are:

  1. Change the data statement DATA PRGM near the beginning of the program and the PROGRAM statement at the very beginning, if you have not already done this.
  2. Make changes in the introductory text which describes the task. This is particularly important if you are adding or removing adverbs.
  3. The subroutine GTPARM obtains the adverb values from the input table in order. If you add or subtract adverbs, change INPRMS, the amount of input information. Be careful in the translation of the adverbs, which are usually listed in a COMMON named /INPARM/.
  4. Change code as desired. Try to modify HIstory file entries as well.
  5. Liberally sprinkle PRINT statements in crucial places to help debug the program. If much of the new code can be put in a subroutine, write and debug the subroutine outside AIPS. Then, add it to the task.
  6. Revise the file NTASK.HLP. At least, change all references to TASK to NTASK! If there are any changes in the adverb list, look at these changes carefully. Further changes in the HELP and EXPLAIN portions of the file may be needed to document your work for for others and for yourself at a later date.
  7. Compile and link the modified task following the instructions in the previous section. When it compiles and links without errors, try it out in AIPS.

12.6.5 Modifying an AIPS template task.

The template tasks are:

  1. TAFFY — modifies an existing image file and writes a new image.
  2. CANDY — writes a new image. Input data from outside AIPS.
  3. FUDGE — modifies an existing uv database and writes a new database.
  4. UVFIL — writes a new uv database taking input data from outside AIPS.

These tasks are described in detail in Chapter 2 of Going AIPS. The template tasks and the code for each are extensively documented there, so only the major points are discussed here.

TAFFY reads a selected subset of an image, one row at a time, to a user interface subroutine DIDDLE. An output image is created, cataloged and filled with values calculated in DIDDLE (or attached subroutines). The dimensionality of the output image need not be the same as the input image.

  1. If the output image has identical dimensions to the input image, and an output image row can be generated from each input image row, then TAFFY is relatively straight-forward to use and the accompanying documentation should suffice.
  2. TAFFY has the option of deferring the writing of an output row until some number of input rows have been read. This would allow the output to depend on some function of several, or even all, input rows. Examples would include smoothing in x and y and other sorts of spatial filtering.
  3. It is possible to handle several input images and several output images with TAFFY by using multi-dimensional images and the axis transposing task, TRANS. Suppose you want to calculate the spectral index from a set of four images. First, use FQCUBE to put the four images into one data cube. (FQUBE lets you avoid re-defining the frequency axis as MCUBE would require.) Then, transpose the cube so that the frequency axis is first with right ascension and declination as the second and third axes. Use this image as the input to TAFFY and use CPARM to specify the frequency values. Each input row will then be the intensity at a pixel for the four frequencies — from which the spectral index and other parameters can be calculated. The output dimension can be specified arbitrarily. For example, you might want to write out the spectral index, the error, the curvature and the flux intercept at some fiducial frequency. When the task has completed, transpose the output cube so that the celestial coordinates are again the first two axes and the spectral index and friends are the third axis.
  4. Subroutine NEWHED may be modified to require certain axis types, operation codes, etc. It must be used to change the output image dimensions if they are not to be the same as the input. An option to omit from the output image the first input axis is available and must be selected in NEWHED.
  5. If you can write and debug outside AIPS any subroutines that DIDDLE will call in calculating the output image, you may speed up the debugging of your algorithms.

CANDY lets you create an image one row at a time. Input information is obtained through a file which is external to AIPS.

  1. Subroutine NEWHED shows an example of how the external file may be defined and how it can be used. The first few records of the external file should contain information for defining the header of the output image and updating the appropriate catalog blocks. The pointers to the AIPS catalog are given in Chapter 5 of Going AIPS.
  2. The subroutine MAKMAP reads further records from the external file until a full row of the output image is obtained.
  3. Many adverbs are built into CANDY. If you need more or wish to change them, read the information at the beginning of subroutine CANIN.

FUDGE reads an existing uv database point by point and creates a new uv database with the modified data. It can easily be used to make simple changes in a uv database; for example, if the u, v, or w terms are to be recalculated, if all phases are to be changed in sign, etc.

  1. If the output data set has different dimensions than the input data set (e.g., by combining several spectral-line channels), changes must be made in the subroutine FUDGIN.
  2. To combine several input data points, use the task UVSRT to put the data points adjacent in the file.
  3. If you wish to calculate quantities from an input uv data set without creating an output file, use this task. In the subroutine DIDDLE set IRET = -1 to avoid writing an the output uv data set.

UVFIL reads input from one or two FORTRAN-readable files which are outside AIPS to create, catalog, and fill a uv database into AIPS. This task is useful for transcribing uv data in an arbitrary format into an AIPS database.

  1. The task code has copious notes to help the user. The first auxiliary file should contain header information about the observations and the telescopes. This file is read in the subroutine NEWHED.
  2. The second auxiliary file contains the actual uv data in some format and it is converted into an AIPS uv database, point by point, in the subroutine FIDDLE. The comments are extensive and an example is given in the code.

12.6.6 Further remarks

  1. Try to use the AIPS coding standards as described in Going AIPS. This will make your code more readable and more portable. It will also save other AIPS programmers lots of work if your new task comes into general use.
  2. Declare all variables that you use.
  3. While debugging, use the FORTRAN PRINT *, ... statement in your code to obtain temporary output on your terminal during execution. If you want more permanent output, use the AIPS message file facilities with the appropriate message level (4 is recommended for information, 6 for warnings, 8 for errors).
  4. You may use a debugger (such as dbx) on AIPS tasks by specifying DEBUG to the COMLNK and aips procedures. Inside AIPS, set the “hidden” adverb SETDEBUG to 0 for normal operation and to 20 to run tasks with your specified debugger.