\documentclass[11pt]{book} 
\include{gildas-def} % GILDAS specific definitions

\makeindex{}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{document}

\frontmatter{} %

\begin{center}
  \huge{}
  \textbf{ASTRO} \\[2\bigskipamount]
  \Large{}
  A \gildas{} software\\[\bigskipamount]
  Jan. 24th, 2018\\[\bigskipamount]
  \large{}
  Questions? Comments? Bug reports? Mail to: \texttt{gildas@iram.fr}\\[2\bigskipamount]
  The \gildas{} team welcomes an acknowledgment in publications\\
  using \gildas{} software to reduce and/or analyze data.\\
  Please use the following reference in your publications:\\
  \texttt{http://www.iram.fr/IRAMFR/GILDAS}\\[2\bigskipamount]
\end{center}

\begin{description}
\item[Documentation] \mbox{}\\
  \credit{J.Boissier$^{1}$}{F.~Gueth$^{1}$}{R.~Lucas}
\item[Software] \mbox{}\\
  \credit{J.Boissier$^{1}$}{F.~Gueth$^{1}$, J.~Pety$^{1,2}$}{R.~Lucas}
\end{description}
1. IRAM\\
2. Observatoire de Paris

\begin{rawhtml}
  Note: this is the on-line version of the ASTRO Manual.
  A <A HREF="../../pdf/astro.pdf"> PDF version</A>
  is also available.
\end{rawhtml}

\bigskip{} %

Related information is available from:
\begin{latexonly}
  \begin{itemize}
  \item{CLIC: Continuum and Line Interferometric Calibration}
  \item{CLASS: Continuum and Line Analysis Single-dish Software}
  \item{GREG: Graphical Possibilities}
  \item{SIC:  Command Line Interpreter}
  \item{IRAM Plateau de Bure Interferometer: Flux Measurements}
  \end{itemize}
\end{latexonly}
%
\begin{rawhtml}
  <UL>
  <LI> <A HREF="../clic-html/clic.html"> CLIC:</A>  Continuum and Line
  Interferometer Calibration
  <LI> <A HREF="../class-html/class.html"> CLASS:</A> Continuum and Line
  Analysis Single-dish Software
  <LI> <A HREF="../greg-html/greg.html"> GreG:</A> Graphical Possibilities
  <LI> <A HREF="../sic-html/sic.html"> SIC:</A> Command Line Interpreter
  <LI> IRAM Plateau de Bure Interferometer:
  <A HREF="../flux-html/flux.html"> Flux Measurements</A>
  </UL>
\end{rawhtml}

% -----------------------------------------------------------------------------
\newpage
\tableofcontents

\mainmatter{} %

% -----------------------------------------------------------------------------
\newpage
\chapter{Introduction}

This document gives a description of the \astro\ software, developed
to help astronomers to prepare their observations with the IRAM
telescopes. \astro\ stands for ``A Software To pRepare Observations''.

\astro\ includes a series of tools to compute {\bf ephemeris},
typically the position of sources as seen at a given time from a given
location.  These commands are described in
Chapter~\ref{chapter.ephemeris}.  Although they are slighlty biased
towards (sub)millimeter astronomy, specially in the terminology used
for input and output parameters, these commands are generic enough to
be used to plan observations with any instrument.

A number of tools are available to {\bf prepare millimeter-wave
observations} (Chapter~\ref{chapter.millimeter}). Especially,
\astro\ provides an interface to the {\tt ATM} library, that
can be used to model the atmospheric absorption and emission 
at millimeter wavelengths.

\astro\ also includes a number of tools that are {\bf specific to the
  IRAM instruments}, and are aimed at helping astronomers to prepare
observing procedures for the Pico Veleta 30m antenna and the NOEMA
interferometer.  These tools are descrived in
Chapters~\ref{chapter.pico} and~\ref{chapter.noema}.

% widget?
% list of commands?

% -----------------------------------------------------------------------------
\newpage
\chapter{Ephemeris}
\label{chapter.ephemeris}

% -----------------------------------------------------------------------------

\section{Setting observatory and time} 

% -----------------------------------------------------------------------------

\subsection{Setting the observatory}

The results of most commands of \astro\ depend on the observer's
location on Earth. % \footnote{this restriction to Earth-based
% observatories has not been so far a real limitation for potential
% users.}. 
This information is input to the software using the
\com{OBSERVATORY} command: \\

{\tt OBSERVATORY longitude latitude altitude [sunlimit]}\\

where the longitude and latitude are in degrees (with the usual
convention of positive values towards North and East respectively) and
the altitude is in kilometers. The fourth parameter is the radius of
the sun avoidance circle (default is 30 degrees), used to indicate in
plots the sky area that cannot be observed. A number of
observatories are pre-defined and can be selected directly by typing:\\

{\tt OBSERVATORY name} \\

Known observatories are given in Table~\ref{table.obs}. Note, that the
Plateau de Bure sun avoidance limit used to be 45 degrees, but has
been decreased to 35 degrees in July 2009. For the submillimeter and
millimeter facilities within this list, \astro\ also assumes an
antenna diameter, that is used to compute the beam size and thereby
the main beam brightness temperatures of planets (see {\tt PLANET}
command).

When entering only {\tt OBSERVATORY} (without argument), \astro\ will
select the default observatory. The latter is defined by the {\tt
GAG\_ASTRO\_OBS} logical:

\begin{verbatim}
   SIC LOG GAG_ASTRO_OBS PICO      ! define PICO as default observatory 
   OBSERVATORY ALMA                ! select ALMA as observatory
   OBSERVATORY                     ! select PICO as observatory
\end{verbatim}

For IRAM instruments and ALMA, the observatory selection activates
commands to prepare receiver and correlator setups (see related
chapters).  In this frame, the commands OBSERVATORY NOEMA and
OBSERVATORY PDBI (or BURE) select the same position on Earth, sun
limit and dish diameter, but different commands to represent the
different hardware status (PDBI/BURE = up to 2017, NOEMA = as of
2017).

Note that some commands take into account different versions of the hardware.
They are accessible by adding an argument after the observatory name.
For PDBI and NOEMA, versions are identified through years.
For ALMA, versions are identified by cycle number.


{\em Note for experts --} The logical {\tt GAG\_ASTRO\_OBS} is defined
in the {\tt gag.dico.gbl} file in the GILDAS distribution. By default,
it is set to BURE. To override this default, users have to "export
GAG\_OBSERVATORY=ObservatoryName" just before sourcing gildas-env.sh
at the beginning of the compilation procedure. Another possibility to
permanently modify the value of {\tt GAG\_ASTRO\_OBS} is to edit the
{\tt astro-site.astro} procedure (see section~\ref{chap.defaults}).

\begin{table}
\begin{center}
\begin{tabular}{|l|l|c|c|c|c|}
\hline
 Name & Longitude & Latitude & Altitude & Sun avoidance & Antenna \\
       &      &          & (m)      & limit (deg.)  & diameter (m) \\
\hline
NOEMA ( or BURE or PDBI) &  05:54:28.5   & 44:38:02.0   & 2560   & 32 & 15 \\ 
PICOVELETA & -03:23:55.51   & 37:04:06.29   & 2850    &  2 & 30 \\
ALMA & -67:45:11.6   & -23:01:11.7  & 5000    & 0  & 12 \\
APEX & -67:45:32.9   & -23:00:20.8  & 5104    & 0 & 12 \\
ATF  & -107:37:10.02 & 34:04:29.8   & 2135   &  0 & 12 \\
CSO  & -155:28:31.8    & 19:49:20.78     & 4200    & 30 & 10 \\
FCRAO & -72:21:00.0   & 42:23:24.0   & 0    & 0 & 14 \\
JCMT & -155:28:37.2    & 19:49:22.11     & 4111 & 30 & 15 \\
KITTPEAK & -111:36:54    & 31:57:12     & 1938 & 30 & 12 \\
KOSMA & 07:47:02.4    & 45:59:02.4   & 3089 & 30 & 3 \\
NOBEYAMA & 138:28:33.0 & 35:56:30.0 &1350 & 30 & 10 \\
SEST & -70:43:48     & -29:15:24    & 2347 & 60 & 15 \\
SMA  & -155:28:52    & 19:49:33     & 4200 & 30 & 6 \\
SMT (or HHT) & -109:53:28.48 & 32:42:05.8   & 3186 & 30 & 10 \\
YEBES & -03:05:12.71 & 40:31:28.78 & 990 & 2 & 40 \\
&&&&&\\
EFFELSBERG & 06:53:02      & 50:31:29     & 360 & 20  & 100 \\
GBT  & -79:50:23.41    & 38:25:59.24   & 807  & 0 & 100 \\
MEDICINA & 11:38:49 & 44:31:15 & 25 & 30 & \\
VLA  & -107:37:06    & 34:04:42     & 2124 & 0 & 25 \\
&&&&&\\
LASILLA & -70:43:48     & -29:15:24  & 2347 & 60  &  \\
MAUNAKEA & -155:28:18 & 19:46:36 & 4200 & 60 & \\ 
PARANAL (or VLT)  & -70:24:11.642 & -24:37:33.117 & 2636 & 60 & \\ 
IOTA & -110:53:05 & 31:14:11 & 2608 & 60 & \\
PTI  & -116:51:47.88 & 33:21:24.12 & 1687 & 60 & \\
GI2T & 06:55:36 & 43:44:56 & 1270 &  & \\
\hline
\end{tabular}
\end{center}
\caption{Observatories known by the {\tt OBSERVATORY}
command. For interferometer, the coordinates correspond to the array
center.The first part of this table lists the millimeter instruments:
an antenna diameter is defined, to be used to compute angular resolution
and planet brightness temperatures. \label{table.obs}}
\end{table}

% -----------------------------------------------------------------------------

\subsection{Setting the time}

Atfter having set the observatory, it is necessary to define the time at which
ephemeris must be calculated, using the command:\\

{\tt TIME hour date}\\

Formats are ``hh:mm:ss.ss'' and ``jj-mmm-yyyy''.  Entering only {\tt
TIME} will use the current system time and date. By default, time and
date are supposed to be in UTC (Universal Time Coordinated). However,
time may also be entered in:
\begin{itemize}

\item local time, using the option {\tt /ZONE z} where {\tt z} is the
number of hours to be substracted to the local time to convert it to
UTC (example: {\tt /ZONE 2} corresponds to Summer Time in Western Europe).

\item UT1, using the option {\tt /UT1}. The difference between
UTC and UT1 can be modifed using the {\tt SET DUT1 dUT1\_value} command.
As of January 2008, dUT1 is $-$0.3~sec (Bulletin D~98 of IERS). By
construction of UTC, the value of dUT1 is always lower than 1~sec.
The difference is therefore very small for all usual ephemeris
computations.

\item TDT (Terrestrial Dynamical Time), using the option {\tt /TDT}.
The difference between UTC and TDT can be modifed using the {\tt SET
DTDT dTDT\_value} command. Since January 2006, dTDT1 is 65.184~sec
(last introduction of a leap second, Bulletin C~30 of IERS).

\end{itemize}

{\em Definitions --} The definition of the various times used in
astronomy is given in a number of excellent textbooks. To make a quite
complex story short: time standard is the TAI (International Atomic
Time), which is not defined by an astronomical measurement. The TDT
(Terrestrial Dynamic Time) is defined as TDT=TAI$+32.1284$, the offset
being introduced to allow for a continuity with older definitions. UT1
is defined by astronomical measurements of the Earth rotation,
corrected for various effects. UT1 differs from TAI, because of the
irregularity of the Earth rotation period at the millisecond level,
and drifts slowly with time, because of the overall slowing down of
the Earth rotation. UTC is defined as TAI + a certain offset, such
that $|$UTC$-$UT1$| < 1$~sec, i.e.\ UTC is an atomic-based time that
is tracking the astronomical-based time within one second. Since UT1
drifts compared to TAI (and thus UTC), a leap second in UTC may be
introduced on the 1st of January or 1st of June.  Hence, the
difference UTC$-$UT1 is kept $<1$~sec.

% -----------------------------------------------------------------------------

\subsection{Setting defaults}
\label{chap.defaults}

%% Should mention logical astro_site_init

\astro\ comes with a short precedure named {\tt astro-site.astro}, located
in the {\tt pro} directory of your GILDAS installation. This file is
executed at the beginning of each \astro\ session, and is used to set
default values for the time and observatory parameters. 

\begin{verbatim}
  !
  ! Observatory and time initialization
  !
  astro\set dut1 -0.3    ! November 2007 Bulletin D 98 of IERS
  astro\set dtdt 65.184  ! January 2006  Bulletin C 30 of IERS
  !
  astro\observatory      ! Select default observatory
  astro\time           ! Use current system time
  !
  if (observatory.eq."BURE") then
     astro\set azimuth south
     astro\catalog gag_data:phase-pdb
     sic\message i site "Plateau de Bure defaults selected"
  else if (observatory.eq."PICOVELETA") then
     astro\set azimuth north
     sic\message i site "Pico Veleta defaults selected"   
  else
     sic\message i site "No known defaults for this observatory"
  endif
\end{verbatim}

Note the {\tt SET AZIMUTH NORTH|SOUTH} command, which is used to define
the azimuth to be zero in the North or South directions, to conform to
local conventions.

% -----------------------------------------------------------------------------

\subsection{{\tt HEADER} command}

At any time during an \astro\ session, the {\tt HEADER} command can be
used to check the current time and observatory that have been selected.
The output of the command also give sun-related information (sun rise,
sun set, twilight times).

\begin{verbatim}
  UTC :    19-SEP-2007   02:18:59.998
  UT1 :    19-SEP-2007   02:18:59.698    D_UT1 :     -0.300
  TDT :    19-SEP-2007   02:20:05.182    D_TDT :     65.184
  Julian date :          2454362.60
  LST :        02:33:06.1453
  
  OBS :    BURE   05:54:28.500   44:38:02.000
  Alt.:    2.560 km     Sun Avoidance:    45.0 deg.
  
  SunRise/Set :      05:23:47.980   17:37:02.472
  Twilight              Start          End
  Civil :            18:10:55.799   04:49:54.653
  Nautical :         18:45:21.460   04:15:28.992
  Astronomical :     19:20:49.604   03:40:00.848
\end{verbatim}

% -----------------------------------------------------------------------------

\section {Computing source positions}

% -----------------------------------------------------------------------------

\subsection{Source catalogs}
\label{chap.catformat}

\astro\ uses source catalogs, that are selected by the \com{CATALOG
name} command. File extension may be omitted when specifying the file
name, the default is {\tt .sou}. The catalog format is that used at
the Plateau de Bure and Pico Veleta telescopes.

Catalogs in the old {\tt OBSINP} input format, used at the IRAM 30-m
Pico Veleta telescope until 2006, may also be read. The command is
then \comm{CATALOG}{/VELETA}. In that case, the input file (default
extension {\tt .cat}) is read and converted to the standard format; a
file with the same name but extension {\tt .sou} is created in the
current directory.

In the \astro\ catalog format, each source uses one line of the catalog
file.  Each line should contain the following consecutive keywords (some
may be omitted):
\begin{itemize}
\item Source name field:\\
  The source name field is a composite item which can accomodate several
  names for a single source. Names should be separated by a vertical bar
  {\tt |} with no embedded spaces, e.g.:
\begin{verbatim}
B0415+379|3C111
\end{verbatim}
  Each name must have at most 12 characters.
\item Coordinate system: 2 characters, optional. May be:
\begin{itemize}
\item {\tt EQ} for equatorial coordinates. If {\tt EQ} is given
  explicitely, then the next keyword (equinox) is mandatory.
\item {\tt GA} for Galactic II coordinates.
\item {\tt EC} for J2000 Ecliptic coordinates
\item {\tt HO} for horizontal coordinates
\item {\tt DA} for equatorial, present-day coordinates.
\end{itemize}
\item Epoch: needed for equatorial coordinates after {\tt EQ} keyword.
\item Longitude-like coordinate: in degrees, except for EQ and DA where it
  should be in hours. Format is hh:mm:ss.sss or dd.ddd or hh:mm.mmm.
\item Latitude-like coordinate: in degrees, or hours for EQ and DA (same 
format as above).
\item Velocity type: alphabetic code, can be {\tt LSR}, {\tt HELIO} or
  {\tt EARTH}.
\item Velocity: in km/second, in the corresponding reference frame (LSR,
  Heliocentric, or local. Default is zero.
\item Intensity type: Either {\tt FLUX} or {\tt MAGNITUDE} (optional)
\item Intensity: Either the Flux in Jansky or the magnitude (optional).
\item Spectral index (optional).
\end{itemize}

A second catalog (known as the ``{\tt ALTERNATE}''catalog ) may also
be defined, using \com{CATALOG Name /ALTERNATE}. Commands
\com{SOURCE}, \com{HORIZON} and \com{CONVERT} will take sources from
this alternate catalog if used with the {\tt /ALTERNATE} option. This
enables easy switching between two classes of objects: for instance
the project sources in the main catalog, and pointing sources or phase
calibrators in the {\tt ALTERNATE} catalog.\\

{\em Example of catalog:} 

\begin{verbatim}
  IRC+50096               3:22:59.000    47:21:19.00    LS -17.2
  CRL618                  4:39:34.000    36:01:16.00    LS -21.3
  IRC+10216               9:45:14.800    13:30:40.50    LS -27.0
  CIT6                    10:13:11.000   30:49:17.00    LS -1.8
  IRC-10236               10:14:35.000   -14:24:31.00   LS 3.3
  YCVN                    12:42:47.000   45:42:48.00    LS 21.7
  IRC+10420               19:24:26.700   11:15:11.00    LS 75.0
  CRL2688                 21:00:19.900   36:29:45.00    LS -36.0
  NGC7027                 21:05:09.400   42:02:03.00    LS 24.8
  RCAS                    23:55:51.700   51:06:36.00    LS 22.0
  OH26.5+0.6              18:34:52.500   -5:26:37.00    LS 27.0
  OH104.9+2.4             22:17:42.500   59:36:16.00    LS -28.0
  MUCEP88       EQ 1988.5 21:43:09.300   58:43:37.00    LS 0
  ALIRA         EQ 2000.0 18:36:56.200   38:47:01.00    LS 0.
\end{verbatim}

% -----------------------------------------------------------------------------

\subsection{Source selection}

Once a catalog has been defined, a source within this list can be
selected using the {\tt SOURCE name} command.  The {\tt /ALTERNATE}
option will direct the search to the alternate catalog. 

The source coordinates are reduced to current epoch (as defined by the
last \com{TIME} command), and converted to horizontal coordinates
azimuth and elevation relative to the observatory (as defined by the
last \com{OBSERVATORY} command). Precession, nutation, aberration are
taken into account. The motion of the Earth uses the ephemerides from
the Bureau des Longitudes (BDL82). The source horizontal coordinates
are printed on the screen, together with the line--of--sight
components of the velocities of:
\begin{itemize}
\item the source relative to the observer (S/OBS)
\item the source relative to the standard of rest (S/LSR)
\item the standard of rest relative to the Solar System barycenter (LSR/G)
\item and the Solar System barycenter relative to the observer (G/OBS)
\end{itemize}

All velocities are in km/s, counted positively for outwards
motions. After running the {\tt SOURCE} command, a number of {\tt SIC}
gloabal variables are updated and contain \ the source right ascension
(variable {\tt RA}), declination ({\tt DEC}), azimuth ({\tt AZIMUTH})
or elevation ({\tt ELEVATION}). These are global {\tt ASTRO}
variables, used or mnodified by other commands. In addition, a
structure called {\tt astro\%source\%} is created, and contains all
output values of the {\tt SOURCE} command.

{\tt SOURCE} with no arguments will compute positions of all sources
from the current (or alternate) catalog in a row. The {\tt SIC} variables
will contain the position of the last source.

SOURCE /RESET will reset all source related parameters in ASTRO and
remove the ASTRO\%SOURCE structure.

% -----------------------------------------------------------------------------

\subsection{Solar system bodies}

The {\tt PLANET name} command is similar to the {\tt SOURCE} command,
but the object must be a Solar System body. No catalog is used. Known
objects are: SUN, MOON, MERCURY, VENUS, MARS, JUPITER, SATURN, URANUS,
NEPTUNE. {\tt PLANET} with no argument compute positions for all these
objects.

Just like {\tt SOURCE}, the {\tt PLANET} command updated a number of
{\tt ASTRO} global variables ({\tt RA}), {\tt DEC}, {\tt AZIMUTH},
{\tt ELEVATION}). A structure called {\tt astro\%planet\%} is also
created, and contains all output values of the {\tt PLANET}
command. \\

In addition to the position, information is given on the planet's
apparent size and position angle, its brightness temperature and flux
at (sub)millimeter wavelengths, at the current frequency.
\begin{itemize}
\item The observing frequency (in GHz) is updated by modifying the
value of the variable {\tt FREQUENCY}. Default is 100~GHz.
\item The beam of the telescope is computed by \astro, using the
antenna diameter associated to the selected observatory
(Table~\ref{table.obs}). This can however be modified by the user,
by setting the {\tt BEAM} variable to a non-zero value. The read-only
{\tt PRIMBEAM} variable contains the value actually used in the
computation.
\end{itemize}

% -----------------------------------------------------------------------------

\subsection{Precession}

... CONVERT command ...

% -----------------------------------------------------------------------------

\section{Plotting object positions}

In addition to computing positions of sources or planets, \astro\ can
also produce plots of sky areas with the requested source positions 
being indicated. 

\begin{figure}
  \centering \includegraphics[angle=270,width=15cm]{FigFrame1}
  \caption{Example of plot produced by \astro: plotting source
  positions and sun avoidance circle in an horizontal frame.}
  \label{fig.frame.1}
\end{figure}

\begin{figure}
  \centering \includegraphics[angle=270,width=15cm]{FigFrame2}
  \caption{Example of plot produced by \astro: plotting source positions
  in an horizontal frame centered on zenith position.}
  \label{fig.frame.2}
\end{figure}

\begin{figure}
  \centering \includegraphics[angle=270,width=15cm]{FigFrame3}
  \caption{Example of plot produced by \astro: finding phase
  calibrators in the vicinity of NGC7027.}
  \label{fig.frame.3}
\end{figure}


% -----------------------------------------------------------------------------

\subsection{{\tt FRAME} definition}

The plotting frame is defined by the command \com{FRAME}. The frame
may be in Equatorial coordinates (Righ Ascension--Declination) or in
Horizontal coordinates (Azimuth--Elevation, as seen from the seleted
observatory and at the time defined by the {\tt TIME} command). These
twe modes are selected by {\tt FRAME EQ} or {\tt FRAME HO} respectively.

The plotting may be done in rectangular coordinates using {\tt FRAME
HO} or {\tt FRAME EQ}, with no other argument. If other arguments are
given, a stereographic projection is used, which gives a better
representation of the sky (distorsion of shapes is not too serious,
but the scale of the map changes from the center of the projection to
the edges). The projection is defined by its center coordinates and
its size: for instance \\ 
{\tt FRAME EQ ra dec size}\\ 
will use a projection centered in the requested direction, while the size 
parameter, in degrees, specify the plotting range (default is 180 degrees,
i.e.\ a whole hemisphere). Similarly,\\

{\tt FRAME HO az el size} \\

will produce a plot centered at the requested Azimuth and Elevation 
(in degrees). Caution: there are two possible azimuth definitions,
depending on whether the azimuth is set to zero in the North or South
direction. The \com{SET AZIMUTH NORTH|SOUTH} command allows one 
to select one or the other convention. 

Use of SIC variables is allowed to select frames such as\\

{\tt FRAME EQ RA*12/PI DEC*180/PI 45}\\

which selects a frame of size 45 degrees, in equatorial coordinates,
centered on the last computed object position. A few short cuts are
available to produce a number of useful, classical plots:

\begin{itemize}
\item {\tt FRAME HO ZENITH} gives the whole sky above the horizon,
centered on the zenith position. It is equivalent to {\tt FRAME HO 0 90 180}
in the {\tt SET AZIMUTH SOUTH} convention, or {\tt FRAME HO 180 90 180}
in the {\tt SET AZIMUTH NORTH} convention.
\item {\tt FRAME HO SOUTH} gives the visible sky above the
southern horizon. It is equivalent to {\tt FRAME HO 0 60 120}
in the {\tt SET AZIMUTH SOUTH} convention, or {\tt FRAME HO 180 60 120}
in the {\tt SET AZIMUTH NORTH} convention.
\item {\tt FRAME HO NORTH|EAST|WEST} are also possible, to plot 
the visible sky above the north, east, and west horizon respectively.
\end{itemize}

% -----------------------------------------------------------------------------

\subsection{Plotting sun avoidance region}

The {\tt TIME} command already described above also plots the sun
avoidance region. This is not done automatically by {\tt FRAME}, so
that the user can produce time-independant plots. Alternativelly,
entering several {\tt TIME} commands in a row allows to produce plots
with different sun avoidance regions being plotted. {\tt TIME /NODRAW}
can be used to suppress the plotting of the sun avoidance circle.

Finally, the command {\tt HEADER} will label the plot with the times
(LST, UTC) and dates. Again, this is independant from {\tt FRAME}
and {\tt TIME}, so that the user can have a full flexibility to 
define the plot and labels.

% -----------------------------------------------------------------------------

\subsection{Plotting source or planet position}

In addition to computing the coordinates, the commands {\tt SOURCE
/DRAW} and {\tt PLANET /DRAW} will also indicate the position of the
requested source in the current plot (as defined by {\tt
FRAME}). Arguments to the {\tt /DRAW} option may be:
\begin{itemize} 
\item {\tt LINE}, to plot a line from the previously computed position
\item {\tt MARKER}, to plot the current \greg\ marker at the computed 
position (with a size corresponding to the source flux in the catalog,
for the {\tt SOURCE} command).
\item {\tt SYMBOL} to plot the source name ({\tt SOURCE} command) or
the usual planet symbol ({\tt PLANET} command)
\item {\tt FULL}, to combine {\tt MARKER} and {\tt SYMBOL} (the
sourcee name or planet symbol will be offset one marker size above the
computed position).
\end{itemize}

The default argument of {\tt /DRAW} is {\tt SYMBOL}. Another very
useful option of the {\tt SOURCE} command is {\tt SOURCE /FLUX
min\_flux}, that selects only the sources whose flux is larger that
the {\tt min\_flux} value. \\

{\em Examples ---} Below are a few examples of plots produced by the
commands described in this section. A large variety of plots can be
produced, depending on the user's purposes.

The following commands plot the position of the sources in the sky at
03:00 UT on April 1$^{st}$ 2008, together with the position of planets
(Fig.~\ref{fig.frame.1}, only Jupiter is up):
\begin{verbatim}
  CATALOG GAG_DEMO:SAMPLE.SOU           ! define the catalog
  OBSERVATORY BURE                      ! define the observatory
  FRAME HORIZON                         ! plots the whole visible sky
  TIME 03:00 01-APR-2008                ! define the time & plot sun avoidance
  SOURCE /DRAW                          ! draw all sources from catalog
  PEN 1                                 ! select pen 1 (red)
  PLANET /DRAW                          ! draw all planets
  PEN 0                                 ! select pen 0 (black)
  HEADER                                ! label the plot.
\end{verbatim}

The same plot, but seen in a different projection (from zenith
position, see Fig.~\ref{fig.frame.2}), is produced by:
\begin{verbatim}
  CATALOG GAG_DEMO:SAMPLE.SOU           ! define the catalog
  OBSERVATORY BURE                      ! define the observatory
  TIME 03:00 01-APR-2008                ! define the time 
  FRAME HORIZON ZENITH                  ! plots the whole visible sky
  SOURCE /DRAW                          ! draw all sources from catalog
  PLANET /DRAW                          ! and planets (only Jupiter is up)
  HEADER                                ! label the plot.
\end{verbatim}

The following commands sequence plots the phase calibrators close to
NGC~7027 (Fig.~\ref{fig.frame.3}):
\begin{verbatim}
  CATALOG GAG_DEMO:SAMPLE.SOU           ! selects the source catalog
  CATALOG GAG_DEMO:PHASE /ALTERNATE     ! selecs the calibrators catalog
  OBSERVATORY BURE                      ! define he observatory
  TIME 03:00 01-JAN-1990                ! define the time 
  SOURCE NGC7027                        ! get source position
  FRAME EQ RA|PI*12 DEC|PI*180 45       ! frame EQ, centered on source, 
                                        ! 45 degrees in total size
  PEN 1                                 ! red pen
  SOURCE NGC7027 /DRAW                  ! plot source position
  PEN 0                                 ! black pen 
  SOURCE /DRAW /ALTERNATE               ! draw phase calibrators
  HEADER                                ! label the plot
\end{verbatim}

% -----------------------------------------------------------------------------

\subsection {Constellations drawing}

\begin{figure}
  \centering \includegraphics{FigConstell}
  \caption{Plotting northern sky constellations.}
  \label{fig.constell}
\end{figure}

The {\tt CONSTELLATION } command plots the main constellations stars
in the {\tt FRAME} area, using the current pen and marker. The marker
size will scale acrording to the star magnitude. Options are available
to draw lines between stars (to form classical constellation outlines)
or plot the star names. See the corresponding section of language
internal help for details. \\

{\em Example --} Figure~\ref{fig.constell} shows the plot resulting
from the commands:
\begin{verbatim}
  FRAME EQ 12:32:54 75:30:33 180.0  ! an equatorial frame
  GREG\SET MARKER 5 2 1  
  CONSTELLATION /DRAW M L           ! draws the stars and the lines
\end{verbatim}

% -----------------------------------------------------------------------------

\section {Observability bar charts}

\begin{figure}
  \centering \includegraphics[angle=270,width=12cm]{FigHorizon}
  \caption{Plotting an observability chart.}
  \label{fig.horizon}
\end{figure}

A extremely convenient mean of planning observations is to produce a
diagram in which time is used as x--coordinate, and in which an
horizontal bar is drawn for each selected source to indicate the time
period during which the source is up. Such a plot is produced using
the command \com{HORIZON}. One may use all sources in the current
catalog ({\tt HORIZON /SOURCE}), all planets ({\tt HORIZON /PLANET}),
or both. Specific objects may be called by their names using {\tt
HORIZON /SOURCE name1 name2 ...} or {\tt HORIZON /PLANET name1 name2
...}. A source that is presently in the sun avoidance circle is
written within brackets ([]) and in italics (e.g.\ [{\em NGC
2264}]). When a quite long catalog is used, the command {\tt HORIZON
/SOURCE NEXT n} can be used repetitively to obtain plots with only
{\tt n} objects at a time.

{\em Example --} The following commands will plot the observability
hours for the sources of the {\tt sample.sou} catalog on
April~1st$^{st}$ 2008, together with planet Neptun. The output is
presented in Fig.~\ref{fig.horizon}.
\begin{verbatim}
  CATALOG GAG_DEMO:SAMPLE.SOU         ! define the catalog
  OBSERVATORY PICOVELETA              ! ... the observatory
  TIME 12:00 01-APR-2008              ! ... and the time 
  HORIZON /SOURCE /PLANET NEPTUN      ! produce the plot
\end{verbatim}


% -----------------------------------------------------------------------------

\newpage
\chapter{Millimeter-wave observations}
\label{chapter.millimeter}

% -----------------------------------------------------------------------------

\section{Atmospheric effects}

... ATMOSPHERE command ...

% -----------------------------------------------------------------------------

%\section{Frequency coverage of an observation}

%(Sub-)millimeter-wave receivers can be tuned within a certain
%frequency range, and provide for each tuning an output of a few
%gigahertz wide. When planning observations, is is necessary to be able
%to check which molecular lines are present within the output frequency
%range, in order to optimize the central frequency that has been
%selected, and define the appropriate correlator/backend mode. 

%\astro\ offers a collection of commands to perform such preparatory
%work, for the IRAM 30-m antenna, the IRAM Plateau de Bure
%inteferometer, and ALMA. The observatory has to be selected using the
%{\tt OBSERVATORY} command. In all three case, the {\bf receiver}
%tuning is defined using the {\tt LINE} command, but the behaviour of
%the command is slightly different in each case, to match the
%specificities of each instrument. The {\bf correlator} setup can be
%simulated using commands specific to each instrument.  Please read the
%following chapters for a more detailed description of how planning
%observations with these three instruments.

% -----------------------------------------------------------------------------

\newpage
\chapter{Planning observations with the Pico Veleta antenna}
\label{chapter.pico}




% -----------------------------------------------------------------------------

% \section {Sensitivity estimates}

% \astro\ does not include any tool to estimate the sensitivity (or
% required integration time) of an observations performed with the 30~m
% antenna. An detailed webbased tool, that allows one to select the
% receiver and observing mode is available at {\tt http://www.iram.es}.

% -----------------------------------------------------------------------------

 \section {Receiver and correlator setup}

 Since 2016, a set of commands have been developed in ASTRO in order
 to help users when preparing receiver and correlator setups for EMIR
 observations. The commands are: EMIR, BASEBAND, and BACKEND.  

 Note that the generic ASTRO commands CATALOG, SET LINES and SET
 FREQUENCY can be used to optimize the plots produced by EMIR and
 BACKEND.

 The full documentation not yet written but one can refer to the
 internal HELP and to a dedicated tutorial available on the GILDAS web
 page (http://www.iram.fr/IRAMFR/GILDAS/, tutorial section).




% -----------------------------------------------------------------------------

% \subsection {Receiver setup}

% -----------------------------------------------------------------------------

% \subsection {Correlator setup}

% -----------------------------------------------------------------------------

% \subsection{Fine-tuning the plot}

% -----------------------------------------------------------------------------

% \subsection {Producing setups}

% -----------------------------------------------------------------------------

% \section {HERA observations}

% -----------------------------------------------------------------------------

\newpage
\chapter{Planning observations with the NOEMA observatory}
\label{chapter.noema}

% -----------------------------------------------------------------------------
\section{Introduction}
In ASTRO, the observatory name ``NOEMA'' refers to NOEMA after the
delivery of its correlator (PolyFix) in 2017.

Older states of the hardware are available under the PDBI (or BURE)
observatory name. Different version can be set up through command
OBSERVATORY BURE 'pdbi\_year'.

\section{Receiver and correlator setup}


Since February 2017, a set of commands have been developed in ASTRO in
order to help users when preparing receiver and correlator setups for
NOEMA observations. The main commands are: TUNING, BASEBAND, and SPW.
Other useful commands are LIST, RESET, and PLOT to visualize and
manage the configured spectral windows.  The online proposal
management system requires an ASTRO script as input. This script can
be obtained through the PROPOSAL command once the desired hardware
configuration has been reached.

Note that the generic ASTRO commands CATALOG, SET LINES and SET
FREQUENCY can be used to optimize the plots produced by TUNING,
BASEBAND, SPW and PLOT commands.

The full documentation not yet written but one can refer to the
internal HELP and to a dedicated tutorial (including new NOEMA
nomenclature definition) is available on the GILDAS web page
(http://www.iram.fr/IRAMFR/GILDAS/, tutorial section)


\newpage
\chapter{Planning observations with the Plateau de Bure interferometer}
\label{chapter.bure}

% -----------------------------------------------------------------------------
\section{Introduction}
In ASTRO, the name Plateau de Bure interferometer refers to the NOEMA
observatory as it was before the delivery of the NOEMA correlator
(PolyFix) in 2017. The following refers to this state of the hardware
(so-called \emph{new generation)} of receivers installed in 2006 and
NarrowBand + Widex correlator. 

Older states of the hardware are available through the ``OBSERVATORY BURE  PDBI\_YEAR''
 command, where year can be 1995,2000,2006,2013, or 2015. See
internal HELP for details.

\section{Receiver and correlator setup}

The current generation of receivers at the Plateau de Bure is composed
of {\bf four receivers bands}, tuned {\bf SSB}, each of them including
{\bf two polarization channels}. At any given time, only one receiver
is used, but with the two polarizations. Each polarization delivers 4
GHz. The {\bf narrow-band correlator} accepts as input two signals of
1~GHz bandwidth, that can be selected within the $2\times 4$~GHz
delivered by the receiver. A {\bf wide-band correlator}, processing
the whole $2\times 4$~GHz is currently being built. The receivers
bands are as follows:

\begin{center}
\begin{tabular}{lcl}
Band 1 & \phantom{1}80--117 GHz & (3 mm window) \\
Band 2 & 129--174 GHz & (2 mm window) \\
Band 3 & 200--267 GHz & (1.3 mm window) \\
Band 4 & 277--371 GHz & (0.8 mm window) \\
\end{tabular}
\end{center}

To prepare Plateau de Bure observations, \astro\ includes a series 
of commands to simulate the receivers tuning and backend setup.

% -----------------------------------------------------------------------------

\subsection{Receiver setup}

The receiver tuning is selected by the {\tt LINE} command, which has
the same syntax as the corresponding command in the {\tt OBS} software
on Plateau de Bure: \\

{\tt LINE name frequency band lock center harm /RECEIVER\_BAND irec}\\

{\tt name} is a line name, only used to label the plot; {\tt
frequency} is the rest frequency in GHz; {\tt band} should be USB or
LSB; {\tt lock} is LOW or HIGH [optional, default LOW]; {\tt center}
is the IF1 frequency (in MHz) that must correspond to the required
rest frequency [optional, default 6500]; {\tt harm} is the harmonic
number [optional, reserved for experts]. The {\tt /RECEIVER\_BAND}
option is optional, the software will automatically find the 
appropriate receiver band, depending on the rest frequency.

It is highly recommended {\em not} to center the line at 6~GHz. This
is because the correlator will analyse four 1~GHz-wide slices of the 4
GHz bandwidths, and 6 GHz is very precisely at the limit between two
such adjacents quarters (see below). 
% The Doppler correction computed for the last selected object is used
% in the calculations .

The {\tt LINE} command produces a plot of both the LSB and USB frequency
coverage (the non-selected band being in light grey). The four quarters 
that are analyzed by the IF/correlator system are indicated by horizontal
arrows (see Fig.~\ref{fig.line.dsb}). Vertical lines indicate the
positions of the main molecular lines.

\begin{figure}
  \centering \includegraphics[angle=270,width=12cm]{FigLineDsb}
  \caption{Plateau de Bure frequency coverage: ouptut of {\tt LINE
  test 100 LSB}. Both the LSB and USB frequency coverages are
  displaye.}
  \label{fig.line.dsb}
\end{figure}

\begin{figure}
  \centering \includegraphics[angle=270,width=12cm]{FigLineNarrow}
  \caption{Plateau de Bure frequency coverage: ouptut of LINE; NARROW;
  SPECTRAL commands.}
  \label{fig.line.narrow}
\end{figure}

% -----------------------------------------------------------------------------

\subsection{Correlator setup}

The details of the IF processor and narrow-band correlator frequency
plan is presented in another document. In short: the input 4--8~GHz
band is split by the IF processor in four 1~GHz parts, labeled {\bf
Q1, Q2, Q3, Q4}. This processing is done in parallel for both
polarizations. Since the narrow-band correlator accepts only two 1~GHz
input signals, one has to define which part (=which quarter of
which polarization) of the signal is to be sent to the
correlator. The system allows the following choices:
\begin{itemize}
\item first correlator input can only be Q1 HOR, Q2 HOR, Q3 VER, or Q4 VER
\item second correlator input can only be Q1 VER, Q2 VER, Q3 HOR, or Q4 HOR
\end{itemize}
where HOR and VER refers to the two polarizations and Q1...Q4 to the
four quarters of the input 4~GHz signal. Note, that these quarters are
1~GHz wide but are covering only 3.6~GHz in total (due to filters'
edges), hence an overlap between Q1 and Q2 on one side, and Q3 and Q4
an the other side: 
\begin{center}
\begin{tabular}{l}
Q1 = 4.2--5.2~GHz \\ 
Q2 = 5.0--6.0~GHz \\
Q3 = 6.0--7.0~GHz \\
Q4=6.8--7.8~GHz.
\end{tabular}
\end{center}

The command\\

{\tt NARROW\_INPUT Q1|Q2|Q3|Q4 Q1|Q2|Q3|Q4}\\

allows one to select the two entries of the narrow-band
correlator. The polarization is determined from the above list. For
instance, {\tt NARROW\_INPUT Q1 Q2} selects Q1 as the first correlator
entry -- this can only be Q1 HORizontal-- and Q2 as the second
correlator entry -- this can only be Q2 VERtical. Selecting two times
the same quarter (e.g. {\tt NARROW Q2 Q2}) results in both polarization
being observed simultaneously, in the same frequency range.

{\tt NARROW\_INPUT} produces a new plot, where the frequency coverage
of the two selected quarters are displayed. After that step, the {\tt
SPECTRAL} command is used to defined and plot the positions and widths
of each of the 8 units of the correlator. The syntax is:\\

{\tt SPECTRAL iunit bandwidth fcenter /NARROW 1|2}\\

where:
\begin{itemize}
\item {\tt iunit} is the correlator unit number (1 to 8);
\item {\tt bandwidth} is the bandwidth in MHz (20, 40, 80, 160, or 320);
\item {\tt fcenter} is the center frequency (in MHz) of the unit in
         the second IF (in the range 100 to 1100 MHz);
\item the option {\tt /NARROW} is mandatory, to select which entry of
         the correlator the unit is connected to.
\end{itemize}

{\em Example --} Figure~\ref{fig.line.narrow} presents the plot
produced by the command sequence:
\begin{verbatim}
  LINE test 100 LSB 
  NARROW Q3 Q4 
  SPECTRAL 1  80  550 /NARROW 1 
  SPECTRAL 2  80  350 /NARROW 1
  SPECTRAL 3  20  793 /NARROW 1
  SPECTRAL 4  20  700 /NARROW 1
  SPECTRAL 5 320  360 /NARROW 1
  SPECTRAL 6 320  740 /NARROW 1
  SPECTRAL 7 320  540 /NARROW 1
  SPECTRAL 8 320  830 /NARROW 1
\end{verbatim}

% -----------------------------------------------------------------------------

\subsection{Fine-tuning the plot}

The {\tt LINE}, {\tt NARROW}, and {\tt SPECTRAL} commands produce
plots that display the receiver and correlator setup of the
instrument. Those plots can be further modified using the {\tt PLOT}
command, to e.g.:
\begin{itemize}
\item swap from a DSB-like plot (LSB and DSB reprensented) to a NARROW-like
plot (two selected quarters are displayed), using {\tt PLOT DSB|NARROW};
\item zoom on a particular IF region, typically if many lines are
present, using {\tt PLOT /LIMITS min max};
\item introduce a width for the molecular lines displayed ({\tt PLOT
/WIDTH width});
\item plot the location of possible spurious lines ({\tt PLOT /SPURIOUS}).
\end{itemize}

See the on-line help for more details on the input parameters.

% -----------------------------------------------------------------------------

\subsection{Producing setups}

Once the {\tt LINE}, {\tt NARROW}, and {\tt SPECTRAL} commands have been
used to define the tuning of the receiver and backend, the command
{\tt PRINT filename} allows one to write in an output file the
corresponding {\tt OBS} commands. This file can directly be
included in the observing procedure (``setup'' file) to be run
at the Plateau de Bure. 

\begin{verbatim}
  !
  ! Plateau de Bure receiver and backend setup
  ! Written by ASTRO command PRINT on 11-FEB-2008
  !
  ! ----- Receiver -----
  !
  LET RECEIVER 1
  LINE LINE test  100.000000 LSB  LOW  6500.00  57 /RECEIVER 1
  !
  ! ----- IF processor -----
  ! Selected quarters are Q3 VER and Q4 HOR
  !
  NARROW Q3 Q4 /RECEIVER 1
  !
  ! ----- Narrow-band correlator -----
  !
  SPECTRAL 1  80  550.00 /NARROW 1 /RECEIVER 1
  SPECTRAL 2  80  350.00 /NARROW 2 /RECEIVER 1
  SPECTRAL 3  20  793.00 /NARROW 2 /RECEIVER 1
  SPECTRAL 4  20  700.00 /NARROW 2 /RECEIVER 1
  SPECTRAL 5 320  360.00 /NARROW 1 /RECEIVER 1
  SPECTRAL 6 320  740.00 /NARROW 1 /RECEIVER 1
  SPECTRAL 7 320  540.00 /NARROW 2 /RECEIVER 1
  SPECTRAL 8 320  830.00 /NARROW 2 /RECEIVER 1
\end{verbatim}

% -----------------------------------------------------------------------------

\subsection{Old receiver systems}

The above description refers to the ``new generation'' receivers
installed during the winter 2006--2007 (3 and 1.3~mm bands) together
with the new IF processor. The system was completed in 2007--2008 with
the 2~mm band, and should be further developed in the next years
(0.8~mm band, new wide-band correlator). The {\tt LINE} command allows
one to produce plots using the old receiver and backend system, to be
able to check old Plateau de Bure data. The command {\tt SET PDBI
1995|2000|2006} is used to select the status of the instrumentation
in the year:
\begin{itemize}
\item 1995: 3 and 1.3~mm receivers, 500 MHz bandwidth (from IF 100 to 600~MHz).
\item 2000: 3 and 1.3~mm receivers, 580 MHz bandwidth (from IF 100 to 680~MHz).
\item 2006: new generation receivers and new IF processor (this is the default)
\end{itemize}

For the old receivers (1995 and 2000), the {\tt NARROW}, {\tt
SPECTRAL}, and {\tt PLOT} commands are not relevant. Instead, the {\tt
LINE} command has a series of options, the most important one being
{\tt LINE /SPECTRAL iunit bandwidth fcenter} to plot the position and
width of the correlator spectral units (see on-line help for all
options). The plots that are produced are always {\tt DSB}-like. Note
that the doppler correction is of some importance for the old
receivers, because these receivers were (or could be tuned)
DSB. Indeed, doppler tracking is correct only in the signal
sideband. The doppler correction is correct in the image sideband when
the frequency is loaded by {\bf OBS} at the Plateau de Bure, but
subsequent tracking is computed for the signal side band only. The
tracking error in the image side band is 0.04~km/s at 86 GHz, in the
worst case. This is now unrelevant for the current Plateau de Bure
receivers, which are SSB.

% -----------------------------------------------------------------------------

\section {Predicting uv coverage}

.... UV\_TRACK...

%This command {\tt UV\_TRACK} is quite specific to Plateau de Bure, though
%it might in principle be used for other interferometers.

%Give the names of the sstations (e.g. {\tt N05 W12 E24}) occupied by the
%antennas for a given configuration as arguments; the option {\tt /FRAME}
%must be given for the first configuration. Also give the option {\tt /TABLE
%  name} to open a table of UV data, if you want to compute later a
%synthesised beam using \gildas\ task {\tt UV\_MAP}. A plot of UV tracks is
%made in a square box, labelled in meters. A sketch of the interferometer
%with the stations used is also drawn.

% -----------------------------------------------------------------------------

\section {GUI wizards}

The ASTRO window interface includes a submenu ``Pateau de Bure'' that
give acces to a few procedures specific to the Plateau de Bure
interferometer.

\subsection{Sensitivity estimate}

\subsection{Finding calibrators}

% -----------------------------------------------------------------------------

%\newpage
%\chapter{Planning observations with ALMA}
%\label{chapter.alma}

% -----------------------------------------------------------------------------

%\section {Simulating observations}

% -----------------------------------------------------------------------------

%\section {Sensitivity estimates}

% -----------------------------------------------------------------------------

%\section {Receiver and correlator setup}

% -----------------------------------------------------------------------------

% \subsection{Receiver setup}

% -----------------------------------------------------------------------------

% \subsection{Correlator setup}

% -----------------------------------------------------------------------------

\newpage
\chapter{Internal Help}

\section{ASTRO language internal help} 

\input astro-help-astro.tex

% -----------------------------------------------------------------------------
\newpage
\section{PICO language internal help}

Contains commands dedicated to the preparation of EMIR observations.

\input astro-help-pico.tex

\newpage
\section{NOEMA languages internal help}
\subsection{OFFLINE MODE  }
Contains commands dedicated to the preparation of NOEMA observations
after the delivery of PolyFix correlator.

\input astro-help-noemaoffline.tex

\newpage
\subsection{ONLINE MODE  }

\emph{Internal use only}

Contains commands to mimmic OBS session inside ASTRO in order to prepare/check observing procedures or tests 

\input astro-help-noemaonline.tex

\newpage
\section{PDBI and ALMA language internal help}

The PDBI and ALMA languages partially share the same
commands (in particular PLOT).  The commands
are grouped here in the same  section. 
 
\input astro-help-pdbi.tex
%\include{astro-help-pdbi}

%\include{astro-help-pdbi}

\end{document}

% -----------------------------------------------------------------------------

\newpage
\appendix{ASTRO related files}

gag_atmosphere   atm-bure-hpux.bin    ! Atmospheric data
gag_ephemeris    vsop87.bin           ! Ephemerides
gag_constell     constellation.bin    ! Constellations
gag_const_bound  sky.bin              ! Boundaries
astro_stations   astro_stations.dat   ! Interferometer Stations
astro_site_init  astro-site.astro     ! Local astro initialization
gag_molecules    molecules.dat        ! Molecular lines
gag_astro_obs    BURE     ! Default observatory
