AIPS HELP file for UVCON in 31DEC24
As of Sat Apr 20 1:00:16 2024
UVCON: Generates UV data for a given array and model
INPUTS
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 -> ANY 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
HELP SECTION
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
EXPLAIN SECTION
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:
6
30 20
1 1
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:
percentsetenv 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:
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).