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.