Description

The vpmanager tool serves to set up a list of primary beams or voltage patterns (antenna responses) and then select in detail which of them is used for which observatory. The distinction of several antenna types for a given observatory (heterogeneous arrays) is supported.

Antenna responses can be selected from either internally hard-coded ones, or response-groups defined via an AntennaResponses table, or user-defined analytic primary beams.

Imaging and simulation routines pick up the selected response definitions and instantiate them.

The vpmanager can also create a table with the description of one or more voltage patterns (vp) or primary beams
(pb). There is a mapping between telescope name and the vp or pb description. The vp description table can be read by imager's setvp method, which instantiates the corresponding voltage patterns from the descriptions and applies them to the images.

The vpmanager tool is the CASA Python object which constitutes the user interface to the VPManager C++ class. By default it is named "vp" in casapy.

The VPManager class is implemented as a singleton, i.e. internally there is only one instance at all times. This instance accessed via the static VPManager::Instance() method. It is permanent until casapy is exited and can be reinitialised via the VPManager::reset() method.

The vp tool connects to the single instance of VPManager. All settings the user makes with the tool, have effect immediately and are then used by all parts of CASA which access the VPManager class (i.e. eventually all imaging and simulation routines).

The VPManager instance keeps a simple database of available antenna responses, the {\it vplist}. This list is initialized at the startup of CASA or by calling the reset() method of the class. In the vp tool, the reset call can be triggered using

\begin{verbatim}
vp.reset()
\end{verbatim}

In order to support heterogeneous interferometer arrays, VPManager permits the use of {\it antenna types} in addition to observatory or {\it telescope} names.

For defining a simple response which is only spatially scaled by frequency but otherwise constant, a simple call to the vp tool is sufficient, e.g.:

\begin{verbatim}
vp.setpbairy(telescope='ALMA',
dishdiam='12.0m',
blockagediam='0.75m',
maxrad='1.784deg',
reffreq='1.0GHz',
dopb=True)
\end{verbatim}

This will create a new entry in the vplist for an analytic Airy disk antenna response and make it the default response for telescope "ALMA". Subsequent requests to VPManager for a ALMA antenna response will get this Airy disk.

If whole {\it response systems} are to be defined for a given telescope, the use of an {\it AntennaResponses table} is possible. Such a table can be set up using the vp tool method

{\tt createantresp()}

and then connected to a telescope using a command like

\begin{verbatim}
vp.setpbantresptable(telescope='ALMA',
antresppath=casa['dirs']['data']
+'/alma/responses/AntennaResponses-ALMA-RT',
dopb=True)
\end{verbatim}

where the value of the {\tt antresppath} parameter indicates the path to the AntennaResponses table. Subsequent requests for ALMA antenna responses to VPManager will start a search in the indicated AntennaResponses table for responses matching given parameters. Presently supported search parameters in VPManager::getvp() and vp.getvp() are:

\begin{itemize}
\item antenna type
\item observation time (used for versioning and for reference frame transformations)
\item frequency (as a Measure, the reference frame is respected)
\item observing direction (to support elevation and azimuth dependent responses)
\end{itemize}

An example of a call to vp.getvp() is

\begin{verbatim}
myrecord = vp.getvp(telescope='ALMA',
antennatype = 'DV',
obstime = '2009/07/24/10:00:00',
freq = 'TOPO 100GHz',
obsdirection = 'AZEL 30deg 60deg')
\end{verbatim}

If the default antenna response for the given telescope is not defined via an AntennaResponses table, the observation parameters {\tt obstime}, {\tt freq}, and {\tt obsdirection} are not needed and can be omitted. The parameter {\tt antennatype} defaults to empty string. So if no antenna types are distinguished for the given telescope, the simplest call to getvp becomes

\begin{verbatim}
myrecord = vp.getvp(telescope='HATCREEK')
\end{verbatim}

During initialization, VPManager will look for entries in the column "AntennaResponses" of the CASA "Observatories" table. If there are non-blank entries, the string found will be interpreted as the path to the default AntennaResponses table for the given telescope.

Note that the casacore AntennaResponses C++ class (which is used by VPManager to administrate the AntennaResponses tables) also supports the additional search parameters "receiver type" and "beam number". A general interface to the response file name search is available through the vp.getrespimagename() method. But presently this accesses only AntennaResponse tables which are entered as the default table in the Observatories table.

Generally, the vp tool methods provide functionality: to set up new analytic antenna responses, select which antenna responses from the vplist to use for which telescope and antenna type, access the contents of the vplist, create and access an AntennaResponses table, create a voltage pattern table.