VLBMEM VLBMEM, written by Steve Gull, is a program for making an image from visibility data in a Merge-format file using the maximum entropy method. In order to run the program outside the Caltech astronomy department, you need a license from Maximum Entropy Data Consultants Ltd. VLBMEM only handles the gridding, Fourier transform, and MEM deconvolution of a visibility dataset. Gridding is done using natural weighting. VLBMEM does not do any (self-) calibration. A "hybrid mapping cycle" can, however, be set up by alternating VLBMEM with VAMPHI, a modified version of the Caltech self-calibration program AMPHI. Input and Output A log is kept in VLBMEM.LOG. This file is created or OVERWRITTEN every time you start VLBMEM (not for every iteration). VLBMEM uses as its input either: (a) Caltech Merge format visibilities, filename specified by the user; or (b) A workfile called VLBMEM.WRK which allows starting up the program from a partly finished run. VLBMEM will AUTOMATICALLY OVERWRITE VLBMEM.WRK each time control is given back to the user. That is, at the end of PAUSE number of iterations. This allows restarts after a crash. VLBMEM optionally produces the following output maps: (b) The dirty map, created or OVERWRITTEN in file DMAP.DAT. Use command DM. (c) The dirty beam, created or OVERWRITTEN in file DBEAM.DAT. Use command DB. (d) The dirty residual map, created or OVERWRITTEN in file DRESID.DAT. Use command DR. (e) The MEM map, created or OVERWRITTEN in file VLBMEM.DAT. Use command SAV. These maps are all in FITS format. The dirty map and beam are not changed by iterating within VLBMEM, while the dirty residuals and the MEM map are. VLBMEM optionally produces the following output visibility file: (f) The "mock data", created or OVERWRITTEN in file MKDATA.DAT. Use command MK. These mock data are the Fourier transform of the MEM map, sampled at the (u,v) coordinates of the input visibility dataset. They can be viewed by comparing them to the original data in program VPLOT, and they can serve as input for self-calibration, in program VAMPHI. Running VLBMEM To run VLBMEM, use command "vlbmem" (lower case in Unix). You will be asked whether you are starting a new run (option 0) or restarting an old run (option 1). In the latter case, beware that VLBMEM will start overwriting your VLBMEM.WRK as soon as you begin to iterate. Make a copy of it if you foresee coming back to this stage. For a new run, you must specify the Merge file, the desired size of the output MEM map in pixels, and the size of each pixel in mas. These cannot be changed in later iterations. VLBMEM Page 2 The maps need not be square, but the size must be a power of 2. The program has been tested up to 1024*1024, but you are encouraged to stick to 512*512 or smaller. The Fourier Transforms are done on double-sized grids, i.e., the dirty map and beam use 4 times as much space as the final map. The pixels must be square; you input one value. If you enter 0, VLBMEM will select a pixel size which generates an oversampling factor of 3. When producing the "final map, to be published", use a higher oversampling. All other steering is done from a command interpreter, prompt VLBMEM>. Type HELP for a full list of commands. Some are not very interesting (LEV), or potentially dangerous (TRQ). These are meant for debugging. Commands are entered one on each line. For commands which need a numerical value (PAUSE, METHOD, see below), one needs to enter the command first, and then its value on the next line. You can request output files (commands DM, DB, DR, SAV, MK), as discussed above. You may want to see the dirty map (DM) and beam (DB) once, to convince yourself that you choose the right map and pixel size. You will definitely want to see the MEM map (SAV) every time you exit the program, and probably the mock data (MK) as well. The program will normally wait for further commands after every iteration. To allow multiple iterations without waiting, enter the command PAUSE, then enter the number of iterations on the next line. When starting a new run, it is probably convenient to set PAUSE between 5 and 10, and then to reduce it, perhaps first to 3, then to 1, as VLBMEM starts converging. METHOD allows switching between various control schemes. Option 0 (Historic MEM) is the fastest (by a factor of 2 or 3), because it omits calculation of error diagnostics. It follows the same trajectory from the flat model map to the final MEM map as the more sophisticated schemes, but you cannot obtain error estimates on your map. Option 0 is quite appropriate for the bulk of the work, e.g., when your data are not yet properly self-calibrated, in which case you will not run VLBMEM to completion. The historic scheme has reached convergence when Chi-squared is equal to the number of visibility data points. For your "publishable map", use METHOD 1 or 2, called Classic MEM. These schemes use the error bars of the input visibilities to determine convergence and errors in the map. METHOD 1 assumes that your errors are correct. METHOD 2 allows one scale factor on all error bars, i.e., the error bars you give determine the relative weight of the data points, but their overall significance will vary. Use of METHOD 2 allows VLBMEM more freedom to shape the MEM map in the way the algorithm thinks is warranted by the data. If you are very sure of your error bars, stick to METHOD 1. Option 3 is not recommended except for experts (see Nick Weir). Give command ITER to perform iterations of MEM. The current value of PAUSE determines how many iterations are done before stopping. VLBMEM Page 3 FLUX is used to find the flux of a box-shaped feature on the map, and its error bar. This can only be done after at least 1 iteration of METHOD 1 or 2. You will be prompted for the bottom and top corners of the box, in pixels. Commands EX and Q will stop a run of VLBMEM. The program tries to keep VLBMEM.WRK up to date, so one can always restart. However, exiting effectively sets the convergence process back by one iteration along the path. Remember that you usually want to write the current MEM map, and its associated mock data, to disk before you exit (SAV and MK). Monitoring and Strategy A can of worms! If you care to know it all, read the complete MEMSYS manual and then phone up Steve Gull for advice on your particular problem. If you are running on only partly self-calibrated data, stick to METHOD 0, and don't continue for too many iterations. VLBMEM starts from a model map, which, at present, is flat and contains a total flux of 1 Jy. This will be more flexible one day. An important part of this flexibility will be windowing: any part of the model map set to 0 would be windowed out. Because of its model map start, VLBMEM spends the first few iterations hopelessly far away from the visibility amplitudes of your data. A display of the mock data fit after only a few iterations typically shows reasonable phase agreement, but terrible amplitude agreement. The most important diagnostic printed after every iteration is OMEGA. It is related to CHISQ (also printed) as: OMEGA = NDATA / CHISQ After the initial few (2-3) iterations, OMEGA should be converging to 1 as CHISQ drops down. Note that NDATA is not the number of data points, but the number of good data points. This is determined by the current fit to the data, given the error bars of the visibilities. Beware that NDATA will change during iterations in METHOD 2. CHISQ will only drop slowly at first, but after a number of iterations (10 ??), VLBMEM starts to get close to an acceptable solution, and CHISQ starts to fall rapidly (OMEGA will rise rapidly). You have then reached the point to bring PAUSE down to 1, so you can study the diagnostic numbers for every new iteration before deciding to proceed. This is especially important since each iteration will start to take longer and longer, as more time is spent transforming between image and data space in internal loops. The cumulative number of transforms is printed at the end of each iteration (TRANS). The minimum is 2 per iterate, and a maximum of 80 has been imposed to insure that the user gets a chance to intervene eventually. At this stage (10-25 iterations ???), you should stop if you are self-calibrating the data. You should find your own balance between over-iterating, and not iterating far enough. It is worthwhile to continue until OMEGA is really rising fast, but you then do not wish to wait around for many of the later time consuming iterations, unless you are aiming for a final map. It is of course helpful to look at the MEM map, and at how the mock data fit the original data. VLBMEM Page 4 If you are producing a final map, switch to METHOD 2 (or 1, if you are sure of your error bars) when OMEGA starts to rise fast. The official convergence criterion is OMEGA=1. Note that the program does not automatically stop there. In fact, OMEGA will occasionally overshoot, and then come back. This is supposed to be a damped oscillation. Do not worry, unless OMEGA > 2. It is up to you how close to OMEGA=1 you want to end up. Preliminary experience shows that you should not worry about it for endless iterations. Remember, after all, that "Classic MEM" should strictly only be used to find FLUXES of features AND THEIR UNCERTAINTIES. These numbers are available at any stage of METHOD 1 and 2, only, the uncertainties are smallest at OMEGA=1. Display of Maps The maps are standard FITS images, and can be displayed with program MAPPLOT or other image-display packages (AIPS, FIGARO, etc.). Display of Visibilities Program VPLOT overplots the input visibility data (shown as green error bars on a TV screen) and the output mock data of VLBMEM (shown as a red connecting line on a TV screen). Specify MOCKDATA=MKDATA.DAT in VPLOT. The mock data file stores the name of the input Merge file; you do not have to specify the latter. You may instead specify another Merge file, but the (u,v) coverage must be identical. See the help file for VPLOT for more information. Self-calibration The image produced by VLBMEM can be used as an input model for self-calibration in program VAMPHI, a derivative of AMPHI. Instead of a delta component model file, VAMPHI reads the mock data file produced by AMPHI, i.e., the transform of the MEM map, sampled at the coordinates of the (u,v) dataset. Since the mock data file stores the name of the input Merge file, you do not specify it separately. As in ordinary hybrid mapping, phase self-calibration should probably precede amplitude self-calibration. Bugs 1. The input model map for VLBMEM should be user-composable: optional windows and explicit setting of the flux level (as zerospacing parameter, or read in from the Merge file). 2. Windows should preferably be set using an older version of the map on the TV screen. VLBMEM Page 5 3. Parameter input and steering commands should use the KEYIN system. 4. The input and and output files need to become parameters for the user to set, rather than being fixed names. 5. VAMPHI: Might still have a bug in it which produces occasional wildly wrong data points in the output Merge file. History This version of VLBMEM was written by Steve Gull in December 1989, with help from Nick Weir and Tim Pearson. It completely replaces an earlier version that had major flaws in gridding and degridding. The program incorporates the proprietary MEMSYS3 package by Maximum Entropy Data Consultants Ltd. This help file is based on a description written by Rene Vermeulen.