; UVCON ;--------------------------------------------------------------- ;! Generate sample UV coverage given a user defined array layout ;# TASK ANALYSIS UV ;----------------------------------------------------------------------- ;; Copyright (C) 1995-1996, 2000-2003, 2005-2007, 2009 ;; 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 ;----------------------------------------------------------------------- UVCON LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC UVCON Generates UV data for a given array and model INFILE Antenna location file name IN2FILE TSYS and Efficiency BLANK=>INFILE's data are used for TSYS and Efficiency OUTFILE Antenna location file name Positions are in equatorial coordinate system. IN2NAME Model image name (name) The both dimensions of the model must be 2**N pixels IN2CLASS Model image name (class) IN2SEQ 0.0 9999.0 Model image name (seq. #) IN2DISK Model image disk unit # INVERS -1.0 46655.0 CC file version #. OUTNAME Output UV file name (name) OUTCLASS Output UV file name (class) OUTSEQ -1.0 9999.0 Output UV file name (seq. #) OUTDISK 0.0 9.0 Output UV file disk unit #. NMAPS 0.0 4096.0 No. maps to use for model. BCOMP First CLEAN comp to sub. 1 per field. 0 => 1 NCOMP Last CLEAN comp to sub. to use (0 => all) FLUX Lowest CC component used. CMETHOD Modeling method: 'DFT','GRID'; ' '=>DFT CMODEL Model type: 'COMP','IMAG' ' ' => 'COMP' => CC components 'IMAG' => image FACTOR Factor times model fluxes. 0 => 1 SMODEL Source model, 1=flux,2=x,3=y See 'explain'. RASHIFT Shift of the model center relatively of the initial RA=0, per field (asec) DECSHIFT Shift of the model center relatively of the initial declinat., given at APARM(3) per field (asec) APARM Control information: 1: Frequency of chan. 1, GHz 2: Wavelength of ch 1, cm IF both .LE. 0 then wavelength = 0.1 cm 3: Source declination, deg 4: Min hour angle, hours 5: Max hour angle, hours The hour angles are for the given array center 6: Min antenna elevation, deg 7: Integration time, sec 0 => 1.D6 to simmulate snapshot 8: Bandwidth(increment) of the freq. channel, MHz >=0 => it is increment to simulate multi chann. data =0 => Bandwidth = 1MHz <0 => one channel data to simulate multi frequency UV coverage 9: Number of freq. channels 0 => 1 10: Max blockage allowed 0 => 1 no blockage BPARM Control information: 1: Multiplier of the calcul. noise. 0 => 1 -1 => 0 (no noise) 2: Atmosphere noise at zenith in degrees. 3: RMS of pointing error, random among all antennas but constant in time, in arcsec If (BPARM(3).LT.0) then the phase and amplitude errors of each antenna are simulated instead of pointing error. ABS(BPARM(3)) is half range of homogeneously distributed phase, rad BPARM(4) is half range of homogeneously distributed natural LOG of factor to amplitude BPARM(5): 0 => only one (first) clean component is affected by the phase/amp noise 1 => all clean components are affected 4: global pointing error, constant in time for all antennas, in arcsec 5: RMS of pointing error, random among all antennas and in time, in arcsec 6: Type of the primary beam 1 => circular dish with the flat illumination 2 => illumination is 10dB down at the dish edge 3 => illumination is 15dB down at the dish edge The dish diameter is given at the INFILE (antenna 1) 4 => Gaussian beam with given BMAJ, BMIN, BPA in degrees 5 => Gaussian beam with variable BMAJ, BPA depending on the time .GT.0 =>Multiply the model by the primary beam. 0 => Not multiply the model by the primary beam. 7: Time tolerance, in minutes 0 => 1 If the difference of the current and previous time is < the time tolerance, the pointing error or the phase of the antenna or primary beam parameters are not changed 8: Shift the UV data by RASHIFT, DECSHIFT? 0 => yes shift 1 => no shift 9: Range of the primary beam 0 => 2.5 10: If OUTFILE.NE.BLANK then 0 => calculate OUTFILE and exit 1 => calculate OUTFILE and carry out the rest of job CPARM Frequencies of the group(IFs) begins 1: Number of the groups (IFs) 2-10 Frequency of group(IFs) begins in MHz BMAJ 0 FWHM major axis of the Gaussian primary beam, degree See help for the variable primary beam (BPARM(6)=5) BMIN 0 FWHM minor axis of the gaussian primary beam, degree BPA 0 Position angle of Gaussian primary beam, degree DO3DIMAG 1 => use W term calculating visibilities (only if CMETHOD='DFT', and CMODEL ='COMP') 0 => no W term calculating visibilities ---------------------------------------------------------------- UVCON Task: Generates a UV data file from an array geometry given by INFILE. File IN2FILE provides information about elevation dependence of antenna efficiency and system noise. The visibilities will be computed using a model specified by IN2NAME, (either from CC components, or the image itself) or from SMODEL. Gaussian noise will be added according to antenna parameters given in the INFILE. Adverbs: INFILE.....Name of the user-supplied file defining the array configuration and antenna characteristics. IN2FILE....Name of the user-supplied file defining the dependence of the TSYS and Efficiency of each antenna on elevation. These more precise data substitute the TSYS and Efficiency of INFILE data. If IN2FILE.EQ.BLANK then INFILE's data are used for TSYS and Efficiency OUTFILE....Name of the file which have the antenna positions given at equatorial coordinate system. All other antenna information repeats the INFILE. IN2NAME....Model map name (name). Standard defaults. The both dimensions of the model must be 2**N pixels IN2CLASS...Model map name (class). Standard defaults. IN2SEQ.....Model map name (seq. #). 0 => highest. IN2DISK....Disk drive # of model map. 0 => any. INVER......CC file ver. number. 0 => highest. OUTNAME....Output UV file name (name). Standard behavior with default 'UV DATA FILE'. OUTCLASS...Output UV file name (class). Standard defaults. OUTSEQ.....Output UV file name (seq. #). 0 => highest unique. OUTDISK....Disk drive # of output UV file. 0 => highest disk with space for the file. NMAPS......Number of image files to use for model. If more than one file is to be used, the NAME, CLASS, DISK and SEQ of the subsequent image files will be the same as the first file except that the LAST 3 or 4 characters of the CLASS will be an increasing sequence above that in IN2CLASS. Thus, if INCLASS='ICL005', classes 'ICL005' through 'ICLnnn' or 'ICnnnn', where nnn = 5 + NMAPS - 1 will be used. Old names (in which the 4'th character is not a number) are also supported: the last two characters are '01' through 'E7' for fields 2 through 512. In old names, the highest field number allowed is 512; in new names it is 4096. BCOMP......The first clean component to process. One value is specified for each field used. 0 => 1 NCOMP......Number of Clean components to use for the model, one value per field. If all values are zero, then all components in all fields are used. If any value is not zero, then abs(NCOMP(i)) (or fewer depending on FLUX and negativity) components are used for field i, even if NCOMP(i) is zero. If any of the NCOMP is less than 0, then components are only used in each field i up to abs(NCOMP(i)), FLUX, or the first negative whichever comes first. If abs(NCOMP(i)) is greater than the number of components in field i, the actual number is used. For example NCOMP = -1,0 says to use one component from field one unless it is negative or < FLUX and no components from any other field. This would usually not be desirable. NCOMP = -1000000 says to use all components from each field up to the first negative in that field. NCOMP = -200 100 23 0 300 5 says to use no more than 200 components from field 1, 100 from field 2, 23 from field 3, 300 from field 5, 5 from field 6 and none from any other field. Fewer are used if a negative is encountered or the components go below FLUX. FLUX.......Only components > FLUX in absolute value are used in the model. CMETHOD....This determines the method used to compute the model visibility values. 'DFT' uses the direct Fourier transform, this method is the most accurate. 'GRID' does a gridded-FFT interpolation model computation. ' ' => DFT NOTE: data in any sort order may be used by the 'DFT' method but only 'XY' sorted data may be used by the 'GRID' method. CMODEL.....This indicates the type of input model; 'COMP' means that the input model consists of CLEAN components, 'IMAG' indicates that the input model consists of images. If CMODEL is ' ' clean components are used as a model If CMODEL is 'IMAG' image is used as a model IF pointing error is included (BPARM(6) > 0) then CMETHOD and CMODEL are forced to DFT and COMP. FACTOR.....This value will be multiplied times the model 0 => 1. The model are added with the noise. SMODEL.....A single component model to be used instead of a CLEAN components model; if abs (SMODEL) > 0 then use of this model is requested. SMODEL(1) = flux density (Jy) SMODEL(2) = X offset in sky (arcsec) SMODEL(3) = Y offset in sky (arcsec) SMODEL(4) = Model type: 0 => point model 1 => elliptical Gaussian, for which: SMODEL(5) = major axis size (arcsec) SMODEL(6) = minor axis size (arcsec) SMODEL(7) = P. A. of major axis (degrees) 3 (not 2 !!!) => uniform sphere, for which: SMODEL(5) = radius (arcsec) RASHIFT....Shift of the model center relatively of the initial RA=0 per field (asec). The RASHIFT is given for the picture plane. So the shift at RA is RASHIFT/COS(declination) The primary beam points to XREF + RASHIFT(1) where XREF is X coordinate value at the reference pixel DECSHIFT...Shift of the model center relatively of the initial declination, given at APARM(3) per field (asec) The primary beam points to YREF + DECHIFT(1) where YREF is Y coordinate value at the reference pixel These shifts can be used for simulation of the multi field observation (mosaic) APARM......User specified array. APARM(1): Frequency of lowest frequency channel, GHz APARM(2): Wavelength of longest wavelength channel (cm). Only one of these should be specified. (A wavelength of 1 mm is assumed if neither APARM(1) nor APARM(2) is positive.) APARM(3): Source declination, deg APARM(4): Min hour angle, hours APARM(5): Max hour angle, hours The hour angles are for the given array center. The position of the array center (site) is given at the input file. APARM(6): Min antenna elevation, deg APARM(7): Integration time per visibility point, sec 0 => 1.E6. Such a big number should be more of any Hmax-Hmin and therefore the snapshot observation near Hmin will be generated. APARM(8): Bandwidth(Increment) of frequency channel, MHz <0 => one channel data are created with different U,V,W for each frequency. Such data are useful for simulating of multi frequency imaging. BANDW=|APARM(8)| is the bandwidth/ increment of the channel and is used in UVCON to calculate U,V,W and noise. >=0 =>it is frequency increment and the created UV data are AIPS' standard multi channel data. The data can be used for different transformations in AIPS. In particular such data can be used for simulating of smearing effect using AIPS tasks UVAVG for time averaging and AVSPC or SPLAT for frequency averaging. =0 => BANDW = 1MHz APARM(9): Number of freq. channels to simulate different U, V, W using different frequencies. 0 => 1 The frequency of channel 'i' is determined by: FREQ(i) = APARM(1) + (i-1)*APARM(8), i=1,2..APARM(9) APARM(10): Max fractional area blockage of one antenna by any other. 0 => 1. Maximum possible blockage is 1 (the total blockage). Therefore the default (1) allows any blockage. BPARM......User specified array. BPARM(1): Multiplication factor for the noise. 0 => 1 -1 = > 0 (no noise) BPARM(2): Atmosphere noise at zenith, in degrees. It is used for calculation visibilities noise and weights depending on elevation BPARM(3): RMS of pointing error, random among all antennas but constant in time, in arcsec BPARM(4): global pointing error, constant in time for all antennas, in arcsec. This error simulates the possible error of the source coordinates BPARM(5): RMS of pointing error, random among all antennas and in time, in arcsec The total pointing error for the given antenna and time is equal to: BPARM(3) + BPARM(4) + BPARM(5) The pointing error simulation is carried out if the total pointing error exceeds 0.00001 If BPARM(3) is negative then the phase and amplitude errors of each antenna are simulated instead of pointing error. ABS(BPARM(3)) is half range of homogeneously distributed phase, in radians BPARM(4) is half range of homogeneously distributed natural logarithm of factor to amplitude. BPARM(5): 0 => only one (the first) clean component of the model is affected by the phase/amp noise 1 => all clean components of the model are affected. The pointing as well as phase and amplitude error simulation is carried out only if CMETHOD='DFT' and CMODEL='COMP' If not then CMETHOD and CMODEL are forced to have these values. BPARM(6): Type of the primary beam 1 => circular dish with the flat illumination; close to the VLA antenna 2 => illumination goes 10dB down at the dish edge 3 => illumination goes 15dB down at the dish edge The antenna diameter and the wavelength are picked up from the input file and from APARM(1)/APARM(2) 2,3 may correspond to the future ALMA antenna 4 => Gaussian beam with given BMAJ, BMIN, BPA in degrees 5 => Gaussian beam with variable BMAJ, BMIN, BPA depending on the time. BMIN stays constant at this case. BMAJ and BPA are calculated for each time at this case. The primary beam can be variable, if the array element is another array (antenna station). In this case the projection of the antenna station aperture on the source picture plane will be changed depending on the source elevation. So if the beam of the antenna station is circular two dimensional Gaussian at zenith, then it will be elliptical two dimensional Gaussian with the major axis increased at 1/sin(el) times. UVCON calculates elevation and azimuth for each visibility(time) and recalculates BMAJ in BMIN/SIN(EL). BMIN stays without change. The new Gaussian beam is rotated to direct the BMAJ in the calculated azimuth. The variable primary beam simulation is carried out only if CMETHOD='DFT' and CMODEL='COMP' If not then CMETHOD and CMODEL are forced to have these values. 0 => 1 BPARM(7): Time tolerance, in minutes; 0 => 1. If the difference of the current and previous times is less than the time tolerance, the pointing error or the phase/ampl of the given antenna, or primary beam parameters are not changed. By other words: the change of the parameters is carried out every BPARM(7) minutes. BPARM(8): 0 => the UV data are shifted by RASHIFT, DECSHIFT simulating the mosaic observation at the pointing given by RASHIFT, DECSHIFT 1 => the UV data are not shifted by RASHIFT, DECSHIFT. The model image is multiplied by the primary beam pointed at the direction given by RASHIFT, DECSHIFT, but the tangent stays at the given (RA=0, DEC=APARM(3)). This simulates the pseudo mosaic observation. BPARM(9): Range of the primary beam (in one direction) 0 => 2.5 The argument of the function describing the PB is PI*RANGE For the circular dish with flat illumination the first null occurs when the range = 1.2. The program calculates the beam inside of the range and put it to zero outside. Gaussian presentation of the beam corresponds to the function exp(-4ln2*ARG) ARG = (x/bmaj)^2 + (y/bmin)^2 So x=bmaj/2, y=0 gives PRBEAM=0.5 The value ARG=2.5 gives PRBEAM = 2^(-10) ~1E-3 BPARM(10):If OUTFILE.NE.BLANK then 0 => calculate OUTFILE and exit 1 => calculate OUTFILE and carry out the rest of job CPARM......Frequencies of group(IF) begin CPARM(1): Number of the groups (IFs) CPARM(2-10): Frequency of the group(IF) begins, in MHz IF (CPARM(1).NE.0) THEN: The total number of frequencies is CPARM(1)*APARM(9) The frequency values are calculated as: CPARM(IFRGR+1) + (IFRCHA - 1) * APARM(8) where IFRGR group(IF) number IFRCHA channel number at each group BMAJ.......FWHM major axis of the Gaussian primary beam at the level 0.5, degree. BMIN.......FWHM minor axis of the Gaussian primary beam at the level 0.5, degree. BMIN should be given at the case of the time variable primary beam. BPA........Position angle of the Gaussian primary beam, degree BMIN stays constant when the time variable primary beam is simulated (BPARM(6)=5). BMAJ and BPA are calculated for each time at this case. DO3DIMAG...1 => use W term calculating visibilities. Can be used for investigation of the wide field of view problem. Can be used only if CMETHOD='DFT', and CMODEL ='COMP' 0 => no use W term calculating visibilities ---------------------------------------------------------------- UVCON: Task to create UV data corresponding to the given source model with noise. PROGRAMMER: L. Kogan, NRAO, Socorro. DOCUMENTOR: R. Perley, NRAO, Socorro. RELATED PROGRAMS: UVSIM, UVSUB, UVMOD PURPOSE This task is used to generate a u-v database for an interferometric array whose configuration is specified by the user. Visibilities corresponding to a specified model, and Gaussian noise appropriate for the specified antenna characteristics are calculated for each visibility. The output is a standard AIPS u-v data file. This task replaces the old procedure which required use of the AIPS tasks UVSIM, UVSUM, UVMOD and verb PUTHEAD. The array geometry can be specified in four different coordinate systems: earth-centered equatorial, local tangent plane, geodetic, and array-centered equatorial. (See definitions below). SPECIFYING THE ARRAY CONFIGURATION The information defining the array configuration and antenna characteristics is read by UVCON from an auxiliary input file, supplied by the user. This is a free-format text file. One must list, in the following order: Line 1: The number of antennas, Line 2: The site latitude(geodetic), the site longitude, in degrees, The site height relatively the geoid, in meters. Line 3: A multiplicative conversion factor specifying how the antenna coordinates, listed next by the user, can be converted into units of meters; and a second multiplicative conversion factor specifying how the listed antenna diameters can be converted into units of meters. If the antenna location coordinates are given in nanoseconds, the conversion factor is 0.299. The remaining lines specify the antenna location and parameters, with one line for each antenna. Each line is formatted thus: Col. 1: The coordinate system: All are right-handed. Units are in meters, (but see note for Line 3, above). 0 => Equatorial, with X positive towards Greenwich longitude (and latitude = 0), Y to the 'east', and Z to the North Pole. Units in meters, but see Line 3 description above. Warning: VLBA uses opposite direction for Y axis, so you need to change it if you use it. 1 => Local Horizon, with X positive towards east, Y positive towards north, Z positive to local zenith. Units in meters, but see Line 3 description above. Coordinate origin is at the array center. 2 => Geodetic, with coordinates given by geodetic latitude, longitude (positive towards west), (both in degrees) and elevation above the geoid (in meters). 3 => Array Centered Equatorial. The same as '0' but with X positive to Dec = 0 on local meridian, Y positive to east, and Z positive towards NCP. This option is good for VLA Units in meters, but see Line 3 description above. Col. 2: Antenna Coordinate X, as defined above. Col. 3: Antenna Coordinate Y, as defined above. Col. 4: Antenna Coordinate Z, as defined above. Col. 5: Antenna diameter (meters, but see note for Line 3, above). Col. 6: Antenna efficiency (fraction). 0 => 0.5 Col. 7: Antenna system temperature (K) 0 => 50K Col. 8: Number of levels of digitization of signals. 0 => 2 level Col. 9: Put one if the coordinates are given relatively the Earth's center (VLBI case); Put zero in other cases. The antenna diameters, efficiency, noise temperature, and number of levels in the digitizer are used to calculate the noise level for the given visibility. This noise can be multiplied by the factor (BPARM(1)). The factor is 1 (the noise is equal to the calculated one) if BPARM(1) = 0 or 1. Set BPARM(1)=-1 for the noise calculation to be turned off. Dependence of the antenna efficiency and noise temperature on elevation is given at file IN2FILE. Comment line can be added at both INFILE and IN2FILE putting semi column (';') at the first position of the line. Here is a sample file for a six-element array: ; number of array antennas 6 ; latitude, longitude of the antennas 30 20 ; scaling coefficients 1 1 ; IND X Y Z TSYS EFF Dant Nlev 3 499.8614 -1317.9860 -735.2027 10 0.6 50 4 1 -801.3750 -124.9699 1182.1318 20 0.4 50 2 3 -5271.2720 -823.5634 7791.9982 30 0.4 50 2 3 152.7899 -401.2680 -223.3888 40 0.4 60 3 3 -6870.8985 -1072.9210 10148.7829 50 0.4 50 2 3 765.2380 2889.4558 -1108.8724 60 0.4 50 2 The array center is at latitude 30 degrees and longitude 20 degrees to west. Conversion factors for both antennas positions and diameters equal 1, so the relevant values are given in meters. Position of the second antenna is given in the local RH system with Z as local zenith. All other antennas' positions are given in a local equatorial coordinate system. Diameters of the antennas are 10, 20, 30, 40, 50, and 60 meters. The efficiency of the first antenna is 0.6. All other antennas have an efficiency of 0.4. The noise temperature of the fourth antenna is 60 degrees. All other antennas have the noise temperature 50 degrees. The first antenna has four level digitizer (two bits), the fourth one a three level digitizer, and the all other antennas have two level digitizer (1 bit). One must supply the name of the input file via the AIPS adverb INFILE. Examples: INFILE='myarea:test.ant' (Unix) where MYAREA is an environment variable set before starting AIPS. For example: %setenv MYAREA /mnt/myarea/sim (in csh) $export MYAREA=/mnt/myarea/sim (in ksh) There are five ready input files for 4 VLA configurations and VLBA. The five files are under $AIPSTARS and should be called as: INFILE 'AIPSTARS:VLA-A_UVCON' INFILE 'AIPSTARS:VLA-B_UVCON' INFILE 'AIPSTARS:VLA-C_UVCON' INFILE 'AIPSTARS:VLA-D_UVCON' INFILE 'AIPSTARS:VLBA_UVCON' If a user want to change the data of VLA, VLBA configuration, he/she can copy the relevant file(s) to his area, edit it and create his own version. SPECIFYING THE DEPENDENCE of the TSYS and EFFICIENCY on the ELEVATION (IN2FILE) The information defining the antenna noise temperature (TSYS) and efficiency dependence on elevation is read by UVCON from an auxiliary second input file (IN2FILE), supplied by the user. This is a free-format text file, including the four columns. Col.1: Antenna number Col.2: Elevation in degrees. Col.3: TSYS in degrees K Col.4: Efficiency, undimensional. UVCON calculates elevation for the given antenna and evaluates the noise temperature and efficiency interpolating the IN2FILE's data to the given elevation for the given antenna. If IN2FILE .EQ. BLANK or there are no data for an antenna then TSYS and efficiency of the antennas are considered independent on elevation and are picked up from the INFILE. Contribution of the sky noise (at this case) is added depending on elevation (COSEC(ELEV)) considering the zenith atmosphere is identical for all antennas. Here is an example of I2FILE: Here is a sample file for a six-element array: ; ANT ELEV TSYS EFF 1 15.0 70 0.3 2 20.0 65 0.35 3 20.0 65 0.35 4 20.0 65 0.35 1 25.0 60 0.4 2 30.0 52 0.45 3 30.0 50 0.45 4 30.0 50 0.45 1 40.0 40 0.5 2 45.0 45 0.55 3 45.0 45 0.55 4 45.0 45 0.55 1 45.0 40 0.6 2 50.0 35 0.65 3 50.0 35 0.65 4 50.0 35 0.65 If the data for an antenna absent in the file I2FILE then INFILE's data used to calculate noise and efficiency for this antenna. USING UVCON TO SIMULATE EFFECT OF SMEARING AS A RESULT OF AVERAGING IN TIME AND/OR FREQUENCY UVCON prepares the AIPS' standard multi channel UV data for the given set of times and frequencies. Having simulated such UV data the user can simulate the smearing effect using the AIPS tasks UVAVG (time averaging) and AVSPC, SPLAT (frequency averaging). Use APARM(8)>=0 in this case. USING UVCON TO SIMULATE UV DATA FOR THE MULTI FREQUENCY SYNTHESIS. APARM(8) should be negative at this case. UVCON creates the one channel UV data with different U,V,W for each of APARM(9) frequencies which are incremented by |APARM(8)|. Such data can be immediately read for an imaging task (AIPS' task IMAGR for example) to create image based on the multi frequency observations (multi frequency synthesis).