simutil

simutil contains numerous utility methods which can assist users in simulations and other activities in CASA, as well as some methods used internally by simobserve and simanalyze.

It is used by import and instantiation, similarly to testhelper and recipes:

Tsys and Noise:

simutil.noisetemp  

Noise temperature and efficiencies can be calculated for several telescopes: ALMA, ACA, EVLA, VLA, and SMA. The inputs for simutil.noisetemp method include: telescope name, frequency as a quantity string "300GHz", dish diameter (optional - knows diameters for arrays above), $\epsilon$ = rms surface accuracy in microns (also optional - this method contains the engineering specification values for each telescope). The outputs produced $\eta_p$ phase efficiency (from Ruze formula), $\eta_s$ spill (main beam) efficiency, $\eta_b$ geometrical blockage efficiency, $\eta_t$ taper efficiency, $\eta_q$ correlator efficiency including quantization, $t_{rx}$  reciever temperature. Where the total antenna efficiency can be calculated from these outputs as such: $\epsilon = \eta_p * \eta_s * \eta_b * \eta_t$

simutil.sensitivity  

This method is used to alculate the noise in an observation, by adding noise to visibilities in exactly the same way as simutil.corrupt (if doimnoise=True), also create a simulated image and measure noise from it. The inputs to calculate sensitivity are: freq = observing frequency eg. "330GHz", bandwidth e.g. "1GHz", etime = exposure time / length of track e.g. "500sec", integration = scan time e.g. "10sec", elevation e.g. "80deg", either antennalist or telescope, diam, and nant must be set. Other optional inputs may be needed if  either antennalist or telescope/diam/nant is required. These inputs include: pwv in mm [default=2.0], telescope e.g. "ALMA", diam e.g. "12m", nant = number of antennas, and antennalist = a simobserve-format antenna configuration filename. Files for many observatories can be found in casa.values()[0]['data']+"/alma/simmos"; doimnoise = actually create an MS and image from it to measure noise method="tsys-atm" see simobserve.thermalnoise for different ways to specify noise.      

Geodesy and Antenna Positions:

simutil.readantenna     

simutil.readantenna is a helper function to read antenna configuration file; example:

Such that observatory, COFA, coordsys, x, y, z, diam and name will be interpreted as header key = value pairs if they contain "=" and begin with #, and as comments otherwise        
To find the observatory name, one can check the known observatories list me.obslist.If an unknown observatory is specified, then one either must use absolute positions (coordsys XYZ,UTM), or specify COFA= lon,lat. coordsys can be XYZ = earth-centered, UTM=easting, northing, alt, or LOC = xoffset, yoffset, height
           
Outputs will be: earth-centered x,y,z, diameter, name, observatory_name, observatory_measure_dictionary

simutil.baselineLengths (configfile)

When given an antenna configuration file, this mehtod will return the zenith baseline lengths.

simutil.approxBeam (configfile,freq)

When given an antenna configuration file and frequency, this method will return the approximate beam size at zenith from the 90th percentile baseline length.

simutil.long2xyz  

This method returns the nominal ITRF (X, Y, Z) coordinates [m] for a point at geodetic latitude and longitude [radians] and elevation [m].  The ITRF frame used is not the official ITRF, just a right-handed Cartesian system with X going through 0 latitude and 0 longitude, and Z going through the north pole.  

simutil.xyz2long         

When given ITRF Earth-centered (X, Y, Z) coordinates [m] for a point, this method returns geodetic latitude and longitude [radians] and elevation [m]. The ITRF frame used is not the official ITRF, just a right-handed Cartesian system with X going through 0 latitude and 0 longitude, and Z going through the north pole. Elevation is measured relative to the closest point to the (latitude, longitude) on the WGS84 reference ellipsoid.

simutil.locxyz2itrf            

This method returns the nominal ITRF (X, Y, Z) coordinates [m] for a point at  "local" (x, y, z) [m] measured at geodetic latitude lat and longitude longitude (degrees) and altitude of the reference point of alt. The ITRF frame used is not the official ITRF, just a right-handed Cartesian system with X going through 0 latitude and 0 longitude, and Z going through the north pole.  The "local" (x, y, z) are measured relative to the closest point to (lat, longitude) on the WGS84 reference ellipsoid, with z normal to the ellipsoid and y pointing north.

simtuil.itrf2loc            

Given Earth-centered ITRF (X, Y, Z) coordinates [m] and the Earth-centered coords of the center of array, this method returns local (x, y, z) [m] relative to the center of the array,  oriented with x and y tangent to the closest point at the COFA (latitude, longitude) on the WGS84 reference ellipsoid, with z normal to the ellipsoid and y pointing north.

simutil.itrf2locname           

Given Earth-centered ITRF (X, Y, Z) coordinates [m] and the name of an known array (see me.obslist()), the mehthod simutil.itrf2locname returns local (x, y, z) [m] relative to the center of the array, oriented with x and y tangent to the closest point at the COFA (latitude, longitude) on the WGS84 reference ellipsoid, with z normal to the ellipsoid and y pointing north.

simutil.utm2xyz          

This method returns the nominal ITRF (X, Y, Z) coordinates [m] for a point at  UTM easting, northing, elevation [m], and zone of a given datum (e.g. 'WGS84') and north/south flag ("N" or "S"). The ITRF frame used is not the official ITRF, just a right-handed Cartesian system with X going through 0 latitude and 0 longitude, and Z going through the north pole.  

simutil.utm2long         

The method simutil.utm2long converts universal transverse meractor coordinates to gps longitude and latitude (in radians)

Pointing and Directions:

simutil.calc_pointings2

This method is used to calculate mosaic pointings to cover a region. This returns a hexagonally packed list of pointings separated by parameter spacing and fitting inside an area specified by direction and mapsize.  Also returns the number of pointings.  The hexagonal packing starts with a horizontal row centered on direction, and the other rows alternate being horizontally offset by a half spacing. 

simutil.read_pointings (filename)

The method simutil.calc_pointings will read a mosaic pointing file. The input file (ASCII) should contain at least 3 fields separated by a space which specify positions with epoch, ra and dec (in dms or hms). The optional field, time, shoud be a list of decimal numbers which specifies integration time at each position in second. The lines which start with '#' are ignored and can be used as comment lines. Example of a file:
       

 

simutil.write_pointings (filename,pointings)

This method will write a list of pointings out to a file. The optional parameter time can be an array of integration times.

Utility

simutil.statim (imagename)

This method will plot an image and calculate its statistics.  optional parameters:  plot [default True], disprange [low and high values for pl.imshow], bar [show colorbar, default=True], showstats [show stats on the image, default=True]

simutil.plotants (x,y,z,d,padname)  

An alternate antenna/config plotting routine, that takes arrays of x,y=local offsets, z=altitude, d=diameter, and padname.  This method routine either plots points or if the array is compact enough to see the diameters, to actual scaled size of the dishes.

simutil.modifymodel (inimage, outimage, inbright,indirection,incell,incenter,inwidth,innchan,flatimage=False)

simutil.modifymodel is a method that onverts inimage to outimage.  Outimage is CASA-canonical 4D with axes in space, stokes, spectral order, which the Toolkit requires (e.g. sm.predict).  Values that are absent in the input, or that the user wishes to override, can be input as quantity strings with the in* parameters. e.g. inbright="4Jy/pixel" will scale outimage to have 4Jy/pixel peak, incell="0.2arcsec" will set the cell size in outimage to 0.2arcsec. The flatimage parameter allows one to also generate a flat (2D, integrated intensity) image from inimage, which can be useful for display purposes.

simutil.convimage (modelflat, outflat)

Given a (2D) model image, this method will regrid it to the scale of the outflat image, and convolve it to the beam of the outflat image.  This is useful to compare a skymodel with a simulated output image.