.ec _
.ll 76
.ad b
.in 4
.\"====================================================================
.ti -4
1 Language
.ti +20
ASTRO_\ Language summary

.nf
ATMOSPHERE          : compute atmospheric parameters
CATALOG             : opens a standard source or line catalog
CONVERT             : precess coordinates from an input catalog
CONSTELL            : draws constellation on current plot
FRAME               : define plotting reference system
HORIZON             : plot observability hours of sources and planets
HEADER              : write time parameters on top of plot
OBSERVATORY         : define current observatory
PLANET              : compute planet coordinates
SET parameter value : enter some parameter value
SHOW		    : display variable defined with SET, OBSERVATORY, and TIME
SOURCE              : compute source coordinates and velocities
TIME                : set computation time
UV__TRACKS          : plot interferometer UV tracks
.fi
.\"====================================================================
.ti -4
1 ATMOSPHERE
.ti +4
[ASTRO_\]ATMOSPHERE [INTERPOLATE|MAKE|SAVE] [/PRINT] [/FREQUENCIES
SIGVAR IMAVAR]

Compute atmospheric emission, opacity, system temperatures, etc...,
using input parameters provided by the user. Input parameters are the
following SIC variables:
.nf
   TEMPERATURE      Outside temperature
   ZERO__PRESSURE    Pressure at sea level.
   AIRMASS          Number of air masses
   WATER            Precipitable water vapor
   FORWARD__EFF      Forward efficiency
   GAIN__IMAGE       Receiver gain ratio
   TREC             Receiver temperature
   FREQ__SIG         Signal frequency (in GHz)
   FREQ__IMA         Image frequency (in GHz)
.fi
These variables can be assigned using the SIC command LET.
The additional input variables
.nf
   ALTITUDE         Site altitude
   FREQ__SIG         Signal frequency (in GHz)
   FREQ__IMA         Image frequency (in GHz)
.fi
are modified by the ASTRO OBSERVATORY and LINE commands.
.br
Option /PRINT displays all these inputs.

The output of the command consists in the following variables
.nf
   TRUE__PRESSURE    Local pressure, derived from the site altitude and
                    the sea level pressure by the scale height of 5.5 km.
   TSYS             The system temperature in the signal sideband
   TAU__H2O          The water vapor opacity
   TAU__O2           The dry atmosphere opacity (mostly due to Oxygen,
                    but minor constituents like Ozone may also play a role)
   TAU__TOT          The total opacity: H2O + O2 (+ minor components for
                    new ATM versions)
   EMIS__SIG         The atmospheric emission (Kelvin) in the signal sideband
   EMIS__IMA         The atmospheric emission (Kelvin) in the image sideband
   PATH__SIG         The atmospheric excess optical path length (mm)
                    in the signal sideband
   PATH__IMA         The atmospheric excess optical path length (mm)
                    in the image sideband
   ATM__SIG          The atmosphere temperature in the signal sideband
   ATM__IMA          The atmosphere temperature in the image sideband
   TANT             The antenna temperature
.fi
These variables can then be used to produce plots of atmospheric
transparency, system temperatures, etc. By default, the command
computes the atmospheric parameters for a single pair of signal and
image frequencies. To compute the parameters for a list of
frequencies, use option /FREQUENCIES (see subtopic for details).

ATMOSPHERE INTERPOLATE
.br
will do the same calculations, but interpolating the data from the
binary table (as defined by logical name GAG__ATMOSPHERE). The whole
table is loaded in internal buffers which can be accessed in the
structure ATM%TABLE% for use in procedures.

ATMOSPHERE MAKE filename nf freqmin freqmax
.br
will create the binary table filename.bin for nf frequencies between
freqmin and freqmax (in GHz). See subtopic FORMAT for details about
the binary format used.

ATMOSPHERE SAVE filename
.br
will save inside filename.bin the binary table currently in memory.
This is useful to save with the current machine byte order a table
previously computed on a different machine with a different byte order.
.\"--------------------------------------------------------------------
.ti -4
2 FORMAT

The ATM values are saved in binary files which use an ad-hoc format
(in particular, this is not the Gildas Data Format). They are Fortran
unformatted (binary) files, usually read in direct access mode with
128 words (512 bytes) records. The values are written in the current
machine system (IEEE, EEEI, ...); this system is saved as the very
first word in the file.

The file consists in a succession of tables describing the opacities,
atmospheric emission, and optical length in the space of pressure,
temperature, frequency, water vapor, and airmass. The values in the
tables, and the tables themselves, are written contiguously (no blanks
inserted e.g. no alignment on the records). Here is the exact
sequence:

.nf
Code    C*4  [     ]  System code

Np      I*4  [     ]  Number of pressure values
Nt      I*4  [     ]  Number of temperatures
Nf      I*4  [     ]  Number of frequencies
Nw      I*4  [     ]  Number of precipitable water vapor amounts
Na      I*4  [     ]  Number of airmass values

P[Np]   R*4  [HPa  ]  Pressure values
T[Nt]   R*4  [K    ]  Temperaure values
F[Nf]   R*4  [GHz  ]  Frequencies
W[Nw]   R*4  [mm   ]  Precipitable water vapor amounts
A[Na]   R*4  [     ]  Airmass values

tauox[Nf,Nt,Np]        R*4  [neper] Opacity (dry component)
tauw[Nf,Nt,Np]         R*4  [neper] Opacity (wet component)

Temis[Na,Nw,Nf,Nt,Np]  R*4  [K    ] Atmospheric emission
Path[Na,Nw,Nf,Nt,Np]   R*4  [cm   ] Optical length
.fi
.\"--------------------------------------------------------------------
.ti -4
2 /FREQUENCIES
.ti +4
ATMOSPHERE /FREQUENCIES SignalVar [IntermediateFrequency]

Vectorized version of the ATMOSPHERE command.

In this case, the input parameters are identical to the non-vectorized
form (in particular, they are still scalar) except FREQ__SIG and
FREQ__IMA which are ignored. The list of signal frequencies is read
instead from the first variable passed to the option. It can be scalar
or vector.

If an intermediate frequency is also provided, a list of image
frequencies is derived from the signal frequencies, symetric with
respect to the IF. If the IF is absent, image frequencies are defined
identical to the signal frequencies, but still used in the ATM
computation (in particular this gives a decent continuum estimation if
GAIN__IMAGE is non zero). Set GAIN__IMAGE to zero to remove any image
contribution.

The atmospheric excess optical path length is NOT computed by this
option. Frequencies are all expected in GHz.

In return, the command stores vectorized products in the following
user-defined variables:
.nf
  ATM%TSYS
  ATM%TAU__H2O
  ATM%TAU__O2
  ATM%TAU__TOT
  ATM%EMIS__SIG
  ATM%EMIS__IMA
  ATM%PATH__SIG
  ATM%PATH__IMA
  ATM%ATM__SIG
  ATM%ATM__IMA
  ATM%TANT
  ATM%IER         ! Error status for each frequency
.fi
Their dimensions match the input frequency lists.
.\"====================================================================
.ti -4
1 CATALOG
.ti +4
[ASTRO_\]CATALOG name [/VELETA] [/ALTERNATE] [/SOURCE] [/LINE]

Open the catalog file specified by 'name'. It can be a source
catalog (if /SOURCE or /ALTERNATE is present, or if the extension is .sou, or by
default if none is present), or a line catalog (if /LINE option, or
if the extension is .lin).

See HELP CATALOG FORMAT for a description of the source catalogs
content. The directory GAG__DEMO: contains two examples of source
catalogs, sample.sou and phase.sou (an incomplete list of Plateau
de Bure phase calibrators). The file GAG__DATA:phase-pdb.sou
contains a more complete list of Plateau de Bure phase calibrators.

The line catalog can be used to draw the position of known spectral
lines when plotting the frequency coverage of EMIR, NOEMA or ALMA.
See HELP CATALOG /LINE for details.

CATALOG with no arguments will display the catalogs currently opened.
.\"--------------------------------------------------------------------
.ti -4
2 /ALTERNATE
.ti +4
This option will open the specified source catalog as a second
catalog, only accessible through the "/ALTERNATE" options of commands
SOURCE, HORIZON, and CONVERT. For instance, a catalog containing
calibration or pointing sources may be opened as an Alternate Source 
catalog,
while the objects to study are kept in the Current catalog, enabling
easy switching between the two kinds of objects.

.\"--------------------------------------------------------------------
.ti -4
2 /LINE
.ti +4
[ASTRO_\]CATALOG Name /LINE

Indicate we are specifying the line catalog.


The line catalog can be used to draw the position of known spectral
lines when plotting the frequency coverage of EMIR (commands
PICO\EMIR,BACKEND) and NOEMA (commands
NOEMA_\TUNING,BASEBAND,SPW,PLOT). 

To do so one should first use "SET LINES ON" (see HELP SET LINES 
for details).  GILDAS provides an internal line catalog 
(GAG__DATA:molecules.dat) used as a default. 

The line catalog format is:
.nf
  Freq(In GHz) 'LineName' 
  230.538	     'CO (2-1)'	
.nf

Lines starting with "!" are regarded as comments and are ignored.

.fi
.\"--------------------------------------------------------------------
.ti -4
2 /SOURCE
.ti +4

Indicate we are specifying the source catalog

.\"--------------------------------------------------------------------
.ti -4
2 /VELETA
.ti +4
This option will open the catalog file 'name'.CAT, assuming it follows the
format of OBSINP catalogs in use on the 30m Radiotelescope of IRAM instead
of the default GILDAS format (see HELP CATALOG FORMAT).  

A file
_'name'.SOU will be created in the current directory in the Plateau de Bure
format, so that this option needs to be specified ONLY ONCE for each
catalog. Fancy keywords in the catalog such as SL0P, SB0P ... are not supported.

.\"--------------------------------------------------------------------
.ti -4
2 FORMAT
.ti +4

In the ASTRO source catalog format each source uses one line of the catalog
file.  Each line should contain the following consecutive keywords
(some may be omitted):
.nf
 1) 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
    ( | ) with no embedded spaces, e.g.: B0415+379|3C111. Each name must
    have at most 12 characters.
 2) Coordinate system: 2 characters, optional, may be:
      EQ for equatorial coordinates. If "EQ" is given explicitely,
                             then the Equinox value is mandatory.
      GA for Galactic II coordinates.
      EC for J2000 Ecliptic coordinates
      HO for horizontal coordinates
      DA for equatorial, present-day coordinates.
 3) Equinox: needed for equatorial coordinates after "EQ" keyword.
 4) Longitude-like coordinate: in degrees, except for EQ and DA where it
    should be in hours. Format is
          hh:mm:ss.sss[,first[,second]]
    where
          "hh:mm:ss.sss" is a generalized sexagesimal format
            (hh:mm:ss.sss or dd.ddd or hh:mm.mmm)
          "first" is an (optional) first order time derivative
          "second" is an (optional) second order time derivative
 5) Latitude-like coordinate: in degrees, same format as above.

 The following OPTIONAL keywords can also be included, and may be listed in
 any order:

 A) a "Velocity" keyword
     Velocity Value
        where "Velocity" is an alphabetic code, equal to "LSR", "HELIO", 
	or "EARTH". HELIO actually means: referred to the Solar System
        barycenter. Value is the velocity in km/second, in the corresponding
        reference frame. Default is zero.
 A') the "REDSHIFT" keyword   
     Redshift Value
	Value is the redshift value.
	The user may provide a redshift OR a velocity, not both.
 B) an "Intensity" keyword
     FLUX  Value [Index]
         Value is the flux in Jy. Index is an optional spectral index
     Mx  Value
         Value is the magnitude, Unknown values can be coded 99.99
         Mx can be MAGNITUDE, or x is one of V,R,I,J,H,K,L,M,N to indicate
         the visual band
 C) a "Project" keyword
     PROJECT Project_ID
        to specify a project identification (a string without spaces)
 D) an "hour" keyword to indicate the validation hour for the coordinates
    (which is useful when time  derivatives are given), specified by
     HOUR Value
 E) A "Parallax" keyword
     PARALLAX Value
          Value is in arcsec.

Any other keyword will be ignored.
.fi

.\"====================================================================
.ti -4
1 CONSTELL
.ti +4
[ASTRO_\]CONSTELL [/DRAW [m] [l] [s]] [/BOUNDARIES]

Plots in the current FRAME with the current FONT, MARKER and PEN, the
constellations, i.e., the main stars of all constellations with a
marker size adequately depending on the magnitude.  The options are:
.nf
 /DRAW [m] [l] [s]
 "m" will cause markers at the star's positions to be plotted
 "l" will cause the constellations outlines to be plotted
 "s" will cause the star's names to be plotted (using current centering and
     character size)
 /BOUNDARIES will draw the constellation boundaries (originally
     constant RA and DEC at 1875 equinox, they are precessed to the
     current equinox).  The current code is quite slow.
.fi

The default is CONSTELL /DRAW m l. This command makes use of the
logical name GAG__CONSTELL which points to a GILDAS Table containing
the stars positions (constellation.bin bydefault) and drawing codes,
and GAG__CONST__BOUND which defines the constellation boundaries (file
sky.bin by default).
.\"====================================================================
.ti -4
1 CONVERT
.ti +4
[ASTRO_\]CONVERT [Catalog__Name] [/ALTERNATE] [/J2000 [Obs__equinox]]
[/PRECESS [New__equinox]] [/GALACTIC] [/FLUX fmin] [/NAME ncname [iname]]
[/INPUT POS|FLUX filename pos]

Change catalog format or equinox.

With the /J2000 and/or /PRECESS option, the command will precess the
current SOU catalog to J2000 system, using the specified equinox for
observation (Obs__equinox, default 1950) and final result
(New__equinox, default 2000). The output catalog is 'Catalog__name'.SOU,
and has the standard format.

/FLUX create a copy of the current catalog with only sources of flux larger
than fmin

/NAME ncname [iname]: reserve ncname characters for names field.  With
iname.gt.0, a standard name (Jhhmmmsddmmm) is created and put in inameth
positions in the list of names.

/INPUT FLUX filename : will take fluxes from filename, which has itself the
format of a catalog (both input catalog and filename are assumed
alphabetically sorted)

/INPUT POSITION filename dpos : will take positions from filename, if
different by more than dpos arc seconds. Filename has itself the format of
a catalog (both input catalog and filename are assumed alphabetically
sorted)

/ALTERNATE option : do the same operation with the Alternate catalog.
.\"====================================================================
.ti -4
1 FRAME
.ti +4
[ASTRO_\]FRAME System [...]

This command specifies the reference frame to be used for plots.
System may be HORIZONTAL or EQUATORIAL (at equinox defined by TIME
command) If no other argument is given, plotting is done in
rectangular coordinates representing Azimuth-Elevation or Right
Ascension-Declination.  If other arguments are given, a Stereographic
projection is used:
.in +4
.ti -2
- FRAME EQUATORIAL Ra Dec Size
.br
the projection will be centered on Ra and Dec (hours - degrees); Size in
degrees specify the plotting range (e.g. 180 for a whole hemisphere = the
default).
.ti -2
- FRAME HORIZONTAL Az El Size
.br
same thing, but Az and El are in degrees.
.ti -2
- FRAME HORIZONTAL Center
.br
will plot a hemisphere in horizontal system, where Center may be ZENITH,
NORTH, EAST, SOUTH or WEST.
.in -4
.\"====================================================================
.ti -4
1 HEADER
.ti +4
[ASTRO_\]HEADER

Write the UTC and LST times on top of the FRAME plot, as well as the
observatory coordinates.

The same information, as well as a couple of other parameters (.eg.
twilight start and end), are listed in the ASTRO terminal. Output
is something like:
.nf
  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
.fi
.\"====================================================================
.ti -4
1 HORIZON
.ti +4
[ASTRO_\]HORIZON h1 h2 ... [/AIRMASS] [/SOURCE ... ] [/PLANET ... ]
[/FLUX Fmin Fmax] [/NIGHT__MARKS] [/ALTERNATE] [/PROJECT] [/ELEVATION]

This command is used to produce plots of LST ranges of observability,
above specified elevations, of sources and planets. An OBSERVATORY and
a TIME must have been selected. The LST axis is drawn on the bottom of
the plot, and UTC on the top . An horizontal line is drawn for the
time period during which the object(s) is(are) visible above elevation
h1; tick marks and labels are provided for elevations h1, h2, ... (in
degrees), or corresponding air masses values (with /AIRMASS
option). Elevation values must be in increasing order, or airmasses in
decreasing order.

Various options are available to control the plot:
.nf
    /SOURCE                  will plot all sources
                             of the current (by default) or alternate
                             (if /ALTERNATE is used) catalog.
    /SOURCE name1 name2 ...  will be restricted to the specified sources
    	    	  	     (sources are searched for in memory
    	    	  	     (after SOURCE command) or in the current
    	    	  	     catalog)
    /SOURCE NEXT n           will plot the next n sources in the current
                             catalog (repeat this command to avoid over-
                             crowded pages)
    /ALTERNATE               with /SOURCE, will use the Alternate catalog
    /FLUX Fmin Fmax          restrict the search to sources with flux in
                             the specified range.

    /PLANET                  will plot on one page all solar-system bodies
    /PLANET name1 name2 ...  will be restricted to the specified bodies

    /NIGHT__MARKS             Plots also the beginning and end of astronomical,
                             nautical and civil twilights, and an estimate of
                             the moon phase and the moon bolometric magnitude.
.fi

For specific Plateau de Bure scheduling purposes, the options /PROJECT
and /ELEVATION can be used to further restrict the search of the sources
in the catalog. In that case, the source catalog must have a number of
additional parameters available for each source (project name,
frequency, priority, minimal elavation,...).
.\"====================================================================
.ti -4
1 OBSERVATORY
.ti +4
[ASTRO_\]OBSERVATORY [longitude latitude altitude [radius]]
.ti +12
 or
.ti +4
[ASTRO_\]OBSERVATORY [Name] [Version] [Mode]

Specify an observatory by giving its geographic coordinates in
degrees, and elevation in km above sea level. Caution: east longitudes
are positive.  The fourth argument is the radius of the Sun avoidance
circle, in degrees (default is 30 degrees).

Example:  OBSERVATORY 44:23:12.0 +45:09:57.9 3.987 30.

A number of observatories are pre-defined and can be selected directly
be typing "OBSERVATORY Name". Type "OBSERVATORY ?" for the list of
known telescopes.

Without argument, the observatory name is translated from the
GAG__ASTRO__OBS logical name.

For NOEMA, PDBI, PICO, and ALMA, a version can be added as argument. This
can be used to select the instrument capabilities, as done by SELECT PDBI|ALMA
command in the past.

For NOEMA, there is only one year possible for the time being
(2017). In ASTRO, the switch to NOEMA observatory name has been placed
at the delivery of the NOEMA backend polyfix.

For PDBI (observatory can be PDBI or BURE), a year must be entered:
1995, 2000, 2006, 2010, 2013, or 2015. They correspond to the upgrades of the
receiver system (1995, 2006, and 2015) and of the correlator (2000, 2010, 2013).

For PICO, the year can be 2016 or 2021. 2021 takes into account the change in frequency coverage in 2021 (outer baseband folding frequency changed)

For ALMA, the cycle number must be entered (0, 1, ...). Any number
larger than the current cycle is equivalent to "OBSERVATORY ALMA FULL"
and points to the full ALMA capabilities.

For NOEMA, PDBI, ALMA, and 30m,  OBSERVATORY also enables some
specific commands to define and visualize receiver and backend
configurations. These commands are gathered together in the dedicated
languages NOEMA\, PDBI\, PICO\ and ALMA\ (see e.g. HELP NOEMA\ for the list
of available commands).


.\"--------------------------------------------------------------------
.ti -4
2 NOEMA
.ti +4
OBSERVATORY NOEMA [Version] [Mode] 

NOEMA has only 1 available version, identified as 2017. It corresponds
to the delivery of the NOEMA correlator PolyFix.

- 2017: NOEMA receivers and Polyfix Backend (1 mode)

Internal use: In the specific case of NOEMA, a mode (ONLINE|OFFLINE)
can also be given.  OFFLINE mode is the default mode, that should be
used by PIs to prepare observations.  ONLINE mode is defined to use
the same syntax as at the observatory, in OBS software (WORK IN PROGRESS).
.\"--------------------------------------------------------------------
.ti -4
2 PDBI
.ti +4
OBSERVATORY PDBI [Year]

Several states of the PDBI hardware implementation can be accessed
using the year in which they were installed:

.nf
 -1995: 3 and 1.3 mm receivers, 500 MHz bandwidth
 -2000: 3 and 1.3 mm receivers, 580 MHz bandwidth
 -2006: new generation receivers (NGR: 4 GHz bandwidth, 2 polar.)
 -2010 NGR +  modifications in the LO system
 -2013 = 2010 + additional slight modification in the LO system
 -2015 = 2013 + Optimized tuning on a LO grid [default]
.fi

.\"--------------------------------------------------------------------
.ti -4
2 ALMA
.ti +4
OBSERVATORY ALMA [Cycle]

For ALMA, a cycle number can be entered (0, 1, ...). Any number
larger than the current cycle is equivalent to "OBSERVATORY ALMA FULL"
and points to the full ALMA capabilities [default].

.\"====================================================================
.ti -4
1 PLANET
.ti +4
[ASTRO_\]PLANET [name] [/DRAW [Arg1 ... ArgN]] [/QUIET] [/BEAM beam]

Compute the coordinates of a Solar System object. Known objects are:
MOON, SUN, MERCURY, VENUS, MARS, JUPITER, SATURN, URANUS, NEPTUNE. If no
name is entered, all objects are selected. The Option /DRAW is used to
plot the object symbol on the screen.

The PLANET command output the planet coordinates (apparent RA,
apparent DEC, Azimuth and Elevation at time of computation) and the
sun distance (with a warning message if this distance os lower than
the telescope limit). PLANET also indicates the geocentric (DE) and
heliocentric (DS) distances of the object (in AU), the apparent minor
and major diameters (Min and Maj in arcsec), the position angle of the
central meridian (PA, east from north, in degrees), the brightness
temperature (TB in K), the flux (S in Jy) at the current frequency,
the frequency (in GHz), the beam (in arcsec), the main beam
temperature (Tmb in K), the associated flux (in Jy) and the planet
size convolved with the telescope beam (size in arcsec).  The
frequency can be entered by updating the variable FREQUENCY (in
GHz). Without the option /BEAM, the beam used is deduced from the
current observatory and frequency. User may override this default by
giving non zero beam size (in arcsec) as an argument of the /BEAM option.

All these parameters are also also written in SIC variables, in the
ASTRO%PLANET% structure. Just enter EXAMINE ASTRO%PLANET% to get a
complete list of these variables. PLANET /QUIET suppresses all the
printouts on the screen.
.\"--------------------------------------------------------------------
.ti -4
2 /DRAW
.ti +4
ASTRO_\PLANET [...] /DRAW [Arg1 ... ArgN]

Arguments to PLANET /DRAW may be:
.in +6
.ti -4
LINE
.br
Draw a line from the previously computed position (SOURCE or PLANET)
.ti -4
MARKER
.br
Draw a marker (GreG style defined by GREG\SET MARKER) at the computed
position
.ti -4
SYMBOL
.br
Draw the planet symbol at the computed position.
.ti -4
FULL
.br
Combine MARKER and SYMBOL (the name will be offset one marker size
above the computed position).
.ti -4
BOX
.br
Draw a box around the symbol plotted by SYMBOL (suited for SYMBOL, not
FULL).
.in -6

Default is SYMBOL. If several arguments are given they will be used in
sequence.
.\"====================================================================
.ti -4
1 SET
.ti +4
[ASTRO_\]SET parameter value

Enter a value for a parameter. Valid parameters are :
.in +4
.ti -2
- SET ATM VersionYear (1995, 2003 or 2009)
.ti -2
- AZIMUTH   North|South
.ti -2
- DUT1  Value (in seconds)
.ti -2
- DTDT  Value (in seconds)
.ti -2
- SET FREQUENCY MainAxis SecondAxis
.ti -2
- SET LINES [ON|OFF|Profile Width]
.ti -2
- SET NAME Argument
.in -4
See subtopic for details
.\"--------------------------------------------------------------------
.ti -4
2 ATM
.ti +4
[ASTRO_\]SET ATM Version

Set the ATM version to be used by the ATMOSPHERE command.  Choices
are:
.in +2
.ti -2
-_ OLD or 1985 select the old ATM model, in use at IRAM since circa
1985.
.ti -2
-_ 2003 select the 2003 version of the ATM model, developed by Juan
Pardo in ISM in Madrid. For this, the corresponding ATM library must
be available on your system.
.ti -2
-_ NEW or 2009 select the 2009 ATM model, developed by Juan Pardo in
ISM in Madrid. For this, the ATM library must have been compiled
together with Gildas (implicit if a C++ compiler was found).
.in -2

Default is 2009. You have to switch explicitly to 1985 or 2003 if the
2009 version is not available on your system.
.\"--------------------------------------------------------------------
.ti -4
2 AZIMUTH
.ti +4
[ASTRO_\]SET AZIMUTH North|South

  Indicate where is the Zero of Azimuth. This depends on the
  Observatory.

.ti -4 
2 DUT1
.ti +4
[ASTRO_\]SET DUT1  Value

  Set the value of (UT1-UTC) in seconds of time for the ephemeris.
  It should be taken from the IERS.

.ti -4 
2 DTDT
.ti +4
[ASTRO_\]SET DTDT  Value

  Set the value of (TDT-UTC) in seconds of time for the ephemeris.
  It should be taken from the IERS.


.ti -4
2 FREQUENCY
.ti +4 
  [ASTRO_\]SET FREQUENCY [MainAxis SecondAxis]

Define the main and secondary frequency frames of the current session
for EMIR and NOEMA receiver and backend frequency coverages.  The
lower axis of the plots is always in the main frequency frame, while
the upper axis displays the secondary frame.
Possible frames are:
.br
.ti +2
REST,LSR,RF for the main frame and
.br
.ti +2
REST,LSR,RF,IF1,IF2,IMREST,IMLSR,IMRF,CHUNK,NULL (i.e. nothing drawn) for
the secondary frame. 
When CHUNK is chosen, the chunk numbers are indicated in the upper axis.

SET FREQUENCY DEFAULTS comes back to the default (main='REST', second
axis='NULL').  Note that the main frequency frame defines not only 
the lower axis of the plot but also the frame in which input and 
output frequencies are given.

With no arguments, SET FREQUENCY displays the current
content of the axis.

.ti -4
2 LINES
.ti +4
ASTRO_\SET LINES ON|OFF 
.ti +4 
or
.ti +4
ASTRO_\SET LINES Shape Width 

Define if and how molecular lines will be drawn on frequency coverage
plots (commands PICO_\EMIR,BACKEND for 30m and
NOEMA_\TUNING,BASEBAND,SPW for NOEMA).

.in +2
.ti -2
-_ ON|OFF: to switch ON or OFF the drawing of the lines
.ti -2
-_ BOXCAR|GAUSS|MARKER Width: to choose the profile of the drawn
molecular lines. Marker (the default profile) is a simple vertical
line. The width (respectively FWHM) of the boxcar (resp. gaussian)
profile must be provided as 3rd argument (in MHz).
.in -2

The lines are taken from the line catalog that can be defined with the
command CATALOG /LINE.

.ti -4
2 NAME
.ti +4
[ASTRO_\]SET NAME Argument 

.br
Define the naming convention for listing sources from the catalog.  Sources
in the catalog may have several names (see HELP CATALOG Format). 
This command define which name
should be printed in commands SOURCE and HORIZON. Argument can be
.in +4
.br
*   to print the name of the source which has been searched for
.br
ALL to print all the possible names of the source
.br
1,2,3 etc... to print the first, second, third, etc.. possible
names of the source
.in -4
.\"====================================================================
.ti -4
1 SHOW
.ti +4
[ASTRO_\]SHOW [PARAMETER]

Display the value of ASTRO parameters defined by SET, OBSERVATORY and
TIME commands. Valid parameters are :

.in +4
.ti -2
- ATM: current version of atm
.ti -2
- AZIMUTH: current 0 azimuth  (North|South) 
.ti -2
- DUT1:  Value (in seconds)
.ti -2
- DTDT:  Value (in seconds)
.ti -2
- FREQUENCY: current Main and Secondary axes for frequency plots
.ti -2
- LINES: display how molecular lines are drawn on frequency plots
.ti -2
- NAME: display which source name will be drawn (if multiple names) 
.ti -2
- OBSERVATORY: current observatory coordinates and characteristics
.ti -2
- TIME: current system time (as defined by TIME command)
.ti -2
- ALL: display all parameters
.in -4
.\"====================================================================
.ti -4
1 SOURCE
.ti +4
[ASTRO_\]SOURCE [name [...]] [/DRAW [Arg1 ... ArgN]] [/ALTERNATE]
[/SUN] [/FLUX Fmin Fmax] [/RESET] [/DOPPLER] [/CURSOR]
.br
[ASTRO_\]SOURCE /VARIABLE VarName [/ALTERNATE] [/FLUX Fmin Fmax]

Compute the coordinates of a source from the current catalog (or the
alternate catalog, if the option /ALTERNATE is used). If no name is
specified, all sources of the catalog are selected. Source
coordinates may also be directly specified in the command line, in the
same format as the catalog file. The /DRAW option is used to draw the
source name on the plot at its current position (Azimuth, Elevation).

The source coordinates (azimuth and elevation at time of
computation) are printed on the screen, as well as the line-of-sight
components of the following velocities:
.in +4
.ti -2
- V(S/OBS)
.br
Source (S) relative to Observatory
.ti -2
- V(S/LSR)
.br
Source (S) relative to Local Standard of Rest. This is the LSR velocity
furnished by the observer as part of the source coordinates.
.ti -2
- V(LSR/G)
.br
Local Standard of Rest relative to Solar System Barycenter (G)
.ti -2
- V(G/OBS)
.br
Solar System Barycenter (G) relative to the Observatory
.in -4
All velocities are in km/s, positive if the distance is increasing. With
the above convention, V(S/OBS) = V(S/LSR)+V(LSR/G)+V(G/OBS). Coordinates,
velocities, and redshift are written in SIC variables, in the ASTRO%SOURCE% structure (just
type EXAMINE ASTRO%SOURCE% to get the complete list).

The output of the SOURCE command can be modified with the following
options: SOURCE /SUN will also list the sun avoidance limits; SOURCE
/PRINT suppresses the printing of Azimuth, Elevation, and the velocities
and prints the source properties as in catalog; SOURCE /QUIET suppresses
all printout (useful to avoid too many messages on the screen in e.g. a
loop on many sources).

SOURCE /FLUX Fmin Fmax will select only sources with flux densities in
the specified range. Marker sizes will be proportional to the
(logarithm of the) flux. This is useful to, e.g., filter a list of
potential calibrators.

SOURCE /RESET will nullify all internal source parameters and remove
the ASTRO%SOURCE%VARIABLE.
.\"--------------------------------------------------------------------
.ti -4
2 /DRAW
.ti +4
ASTRO_\SOURCE [...] /DRAW [Arg1 ... ArgN]

Arguments to SOURCE /DRAW may be:
.in +6
.ti -4
LINE
.br
Draw a line from the previously computed position (SOURCE or PLANET)
.ti -4
MARKER
.br
Draw a marker (GreG style defined by GREG\SET MARKER) at the computed
position
.ti -4
SYMBOL
.br
Draw the source name in capitals at the computed position.
.ti -4
FULL
.br
Combine MARKER and SYMBOL (the name will be offset one marker size
above the computed position).
.ti -4
BOX
.br
Draw a box around the name plotted by SYMBOL (suited for SYMBOL, not
FULL).
.in -6

Default is SYMBOL. If several arguments are given they will be used in
sequence.
.\"--------------------------------------------------------------------
.ti -4
2 /VARIABLE
.ti +4
[ASTRO_\]SOURCE /VARIABLE VarName [/ALTERNATE] [/FLUX Fmin Fmax]

Load (a subset of) the (alternate) source file in a user structure
(the structure will be global, and created if needed). /FLUX can be
used to select a range of fluxes. In return, the user structure
contains:

.nf
  S%N                 number of lines read and selected
  S%NAME[S%N]         source name (or names, appended with |)
  S%SYSTEM[S%N]       coordinate system
  S%EQUINOX[S%N]      equinox if coordinate system is Equatorial
  S%LAMBDA[S%N]       lambda coordinate (radians)
  S%BETA[S%N]         beta coordinate (radians)
  S%VTYPE[S%N]        velocity type
  S%VELOCITY[S%N]     velocity value
  S%REDSHIFT[S%N]     redshift value
  S%ITYPE[S%N]        intensity type (FLux, MAgnitude)
  S%INTENSITY[S%N]    intensity value
  S%SPINDEX[S%N]      spectral index
  S%MAGNITUDE[9,S%N]  9 magnitudes per source (see HELP CATALOG FORMAT)
.fi

According to the current ASTRO_\SET NAME tuning, the variable
S%NAME[i] may contain one or all variant names of the source.

Note that in order to see any change in the source file(s) (new file
name, updated file contents), the structure should be reloaded by
calling again this command.
.\"--------------------------------------------------------------------
.ti -4
2 /DOPPLER
.ti +4
[ASTRO_\]SOURCE /DOPPLER Type Value

Can be used to be abe to take into account LSR velocities or redshift
in the frequency coverage computations (NOEMA and PICOVELETA) without
defining a full source (i.e. coordinates, V(LSR/G) and V(G/OBS)
velocities are not computed.  In that case V(SOU/OBS)=V(S/LSR).

.nf
Type can be REDSHIFT or LSR
Value is the value (real) in the corresponding type of doppler.
.fi

.\"--------------------------------------------------------------------
.ti -4
2 /CURSOR
.ti +4
[ASTRO_\]SOURCE /CURSOR

Trigger the interactive cursor on the plot. When the user clic on a
position the information about the closest source are displayed in the
terminal.

.\"====================================================================
.ti -4
1 TIME
.ti +4
 [ASTRO_\]TIME [time [date]] [/ZONE Z] [/UT1] [/TDT] [/NODRAW]

Specify the time-date of computation. Time is normally understood as
UTC; options /UT1 and /TDT may be used to change this to UT1 or
TDT. The time format is HH:MM:SS.SSS, and the date format is
DD-MMM-YYYY. Time and date may be absent or replaced by an asterisk
(*), which defaults to current system time.  Local civil time may be
input instead of UTC, with the option /ZONE z, where z is the
difference in hours between UTC and local civil time (use /ZONE 2
in western Europe in Summer, 1 in winter).

By default, if the sun is visible, a Sun Avoidance Circle (see HELP
OBSERVATORY) is plotted. It can be suppressed using the /NODRAW option.
Use HEADER to examine the value of the Sun Avoidance Circle.
.\"====================================================================
.ti -4
1 UV__TRACKS
.ti +4
[ASTRO_\]UV__TRACKS station1 station2 [station3 [...]]
[/FRAME [size]]  [/HORIZON Elmin] [/HOUR__ANGLE Hmin [Hmax]]
[/INTEGRATION t] [/STATIONS ALL|list] [/TABLE [Name]]
[/WEIGHT Mode] [/SIZE [Size1] [NantSize1]  [Size2] [NantSize2] ...]
[/OFFSET offset]

Plot interferometer UV coverage as observed with the interferometer.
The default is for NOEMA, but the command is more general and can be
used with any array, especially ALMA or SMA.

Station coordinates are searched for in the file defined by the
ASTRO__STATIONS logical variable. The default file contains NOEMA
stations. It can be customized using the SIC LOG ASTRO_STATIONS
YouFile command.

Some configuration files for NOEMA, ALMA, and SMA are distributed with
gildas and can be used as ASTRO__STATIONS files combined with 
UV__TRACKS ALL to avoid typing a lot of station names 
(see HELP UV__TRACKS NOEMA|ALMA|SMA)


Stations should be referred to by a mnemonic (e.g. E003, W000 ...)
given as arguments of UV__TRACKS.  Note that with the contruction of
the NOEMA track extension the mnemonic names changed from
[E,N,W]+2digits for the station number to [E,N,W]+3digits for the
station number.  Old names are still accepted during a transition
period.

The size of the antennas can be specified with the /SIZE option.

The /STATIONS option allows to use the ranks of the stations in the
file rather than the mnemonic names.

The coordinates of the most recently selected SOURCE or PLANET are
considered. The frequency of the simulated observation is read from
the Sic FREQUENCY variable (which is also set by LET FREQUENCY command).

UV__TRACKS can be used iteratively, to simulate the observations of
several configurations. Option /FRAME indicate the start of a
new observations: if not present, configurations are being
stacked on the current UV coverage. The user may select another color
pen to distringuish between the various coverages. A sketch of the
interferometer described by ASTRO__STATIONS is also drawn, and the
selected stations/antennas are highlighted.
.\"--------------------------------------------------------------------
.ti -4
2 NOEMA
.ti +4

---- Using UV__TRACKS with NOEMA configuration files ----

UV__TRACKS can be used to simulate NOEMA observations using NOEMA
configuration files. The sequence should be:

.nf
SIC LOG astro__stations noema-10[a,c,d].cfg
UV__TRACKS all [...options...]
.fi

The logical astro__stations must point to a configuration file of
NOEMA. They are distributed with GILDAS and are called
"noema-[10,11,12][a,c,d].cfg". Then "uv__track all" means all stations will be
used.
.\"--------------------------------------------------------------------
.ti -4
2 SMA
.ti +4

---- Using UV__TRACKS with SMA configuration files ----

UV__TRACKS can be used to simulate SMA observations using SMA
configuration files. The sequence should be:

.nf
SIC LOG astro__stations sma-CONFIG.cfg
UV__TRACKS all [...options...]
.fi

The logical astro__stations must point to a configuration file of
SMA. Four configuration files are distributed with GILDAS:

.nf
sma-sub.cfg: for sub compact configuration (note that in this configuration 
	     the SMA cannot observe sources at elevations lower than 31.3deg)
sma-com.cfg: for compact configuration
sma-ext.cfg: for extended configuration
sma-vex.cfg: for extended configuration
.fi

Then "uv__track all" means all stations in the chosen file will be used.

A catalog of all the SMA pads is also distributed with gildas. The
pads are identified through their numbers (1 to 26, where 25 and 26 are
JCMT and CSO positions). Any SMA configuration can be simulated with a
typical sequence of command:

.nf
OBSERVATORY SMA
SIC LOG astro__stations sma-stations.cfg
UV__TRACKS 1 4 7 9 /FRAME [...]
.fi
.\"--------------------------------------------------------------------
.ti -4
2 ALMA__ACA
.ti +4

---- Using UV__TRACKS for ALMA ----

UV__TRACKS can be used to simulate ALMA observations, using the
/TABLE and /FRAME options to create tables with one or
several configurations. To do so, the command sequence must be

.nf
OBSERVATORY alma
SIC LOG astro__stations "alma-current.cfg"
UV__TRACKS all [...options...]
.fi

The logical astro__stations must point to a configuration file of
ALMA.  They distributed with GILDAS and the currently offered
configurations are named "alma-current-"'J'".cfg" and
"aca-current.cfg" where J is the configuration number.  All the
versions of previous ALMA configuration files are distributed under
the names "alma-cycle"'I'"-"'J'".cfg" and "aca-cycle"'I'".cfg", where
I is the cycle number.  Note that when the configuration of several
cycles are identical we keep only the files of the first cycle in
which they were offered.  Then "uv__tracks all" means all stations
will be used.

For ACA, it is better to enter "observatory aca" - coordinates are the
same, but this will make sure the proper antenna diameter is used in
the computation of shadowing.
.\"--------------------------------------------------------------------
.ti -4
2 /FRAME
.ti +4
[ASTRO_\]UV__TRACKS ... /FRAME [size]
[/HOUR__ANGLE Hmin [Hmax]] [/TABLE [Name]] [/HORIZON Elmin]
[/INTEGRATION t] [/STATIONS ALL|list] [/WEIGHT Mode]

Option /FRAME [size] should be used to start a
new UV coverage. It clears the plot, draws the box, and open a new
table if /TABLE is present. 'size' is the maximum UV spacing plotted,
in meters (default 800 m). Subsequent call to the command (without
/FRAME) adds the new configurations.
.\"--------------------------------------------------------------------
.ti -4
2 /HORIZON
.ti +4
[ASTRO_\]UV__TRACKS ...  /HORIZON Elmin
[/FRAME [size]] [/HOUR__ANGLE Hmin [Hmax]] [/TABLE [Name]]
[/INTEGRATION t] [/STATIONS ALL|list] [/WEIGHT Mode]

Option /HORIZON specifies a minimum elevation (in degrees)
for the source.
.\"--------------------------------------------------------------------
.ti -4
2 /HOUR__ANGLE
.ti +4

[ASTRO_\]UV__TRACKS ...  /HOUR__ANGLE Hmin Hmax
[/FRAME [size]] [/TABLE [Name]]  [/HORIZON Elmin]
[/INTEGRATION t] [/STATIONS ALL|list] [/WEIGHT Mode]

Option /HOUR__ANGLE can be used to limit the hour
angle coverage. Default is from source rise (above the minimum
elevation) to source setup; Hmin and Hmax are in hours.
.\"--------------------------------------------------------------------
.ti -4
2 /INTEGRATION
.ti +4
[ASTRO_\]UV__TRACKS ... /INTEGRATION Tint
[/FRAME [size]] [/HOUR__ANGLE Hmin [Hmax]] [/TABLE [Name]]
[/HORIZON Elmin]  [/STATIONS ALL|list] [/WEIGHT Mode]

Set the time interval (Tint, in minutes) between points in the UV plane.
Default is 15 minutes per point, enough for a quick look, but insufficient
for proper UV coverage on long baselines. Caution: currently there
may be a max of 3000 points between HA__MIN and HA__MAX).
.\"--------------------------------------------------------------------
.ti -4
2 /STATIONS
.ti +4
[ASTRO_\]UV__TRACKS /STATIONS ALL|list
[/FRAME [size]] [/HOUR__ANGLE Hmin [Hmax]] [/TABLE [Name]]
[/HORIZON Elmin] [/INTEGRATION t]  [/WEIGHT Mode]


Option /STATIONS enable to access stations by their rank number in the
ASTRO__STATIONS file, rather by their mnemonic. ALL means 'take all
stations'. Switching between files describing interferometer
stations can be done inside ASTRO by redefining the ASTRO__STATIONS
logical variable using the command
.br
SIC LOG ASTRO__STATIONS "path/to/the/desired/file"
.br
.br
The NOEMA stations are described in the file GAG__DATA:astro__stations.dat

.\"--------------------------------------------------------------------
.ti -4
2 /TABLE
.ti +4
[ASTRO_\]UV__TRACKS ... /TABLE [Name [/FRAME Size]]
[/HOUR__ANGLE Hmin [Hmax]] [/HORIZON Elmin]
[/INTEGRATION t] [/STATIONS ALL|list] [/WEIGHT Mode]

Option /TABLE can be used to write the sampling function (UV coverage)
in a UV table for further processing such as producing beams using the
task UV__MAP. Name should be specified only if option /FRAME has been
used, to initialize the table. Subsequent call to the UV__TRACKS command
will append the new observation to this table. The visibilities written
in the UV table are constant, as if a point source were observed
(real part = 1, imaginary part = 0).
.\"--------------------------------------------------------------------
.ti -4
2 /WEIGHT
.ti +4
[ASTRO_\]UV__TRACKS ... /WEIGHT Mode [JyPerK Bandwidth]
/TABLE [Name [/FRAME Size]] [/HOUR__ANGLE Hmin [Hmax]] [/HORIZON Elmin]
[/INTEGRATION t] [/STATIONS ALL|list]

In the output UV table, the weight is by default constant,
equal to 1. This can be modified using the /WEIGHT Mode option. Mode
can be UNIFORM (constant weight), AIRMASS (weight proportional
to airmass^-2, i.e. to sin(elevation)^2) or FULL.

With the option /WEIGHT FULL the weights are computed from the
system temperature, derived from the frequency and receiver temperature.
This option requires two additional arguments to specify the antenna
gain (conversion from Jy to K, about 30 for ALMA below 350 GHz,
between 22 and 35, depending on the frequency for NOEMA) and the
channel width (in MHz). The frequency is derived from variable FREQUENCY.
If FREQUENCY is equal to FREQ__SIG, the image frequency defined
by FREQ__IMA and sideband gain ration (GAIN__IMAGE) are also used
as in the ATM command.  Else, GAIN__IMAGE is set to zero.
.\"--------------------------------------------------------------------
.ti -4
2 /SIZE
.ti +4
[ASTRO_\]UV__TRACKS ... /SIZE Size1 [NAntSize] [Size2 NAntSize2] [...]

The size of the antennas can be customized with the /SIZE option.
With a single argument all the antennas are supposed to have the same
size.  Arrays with different antenna sizes can be defined using
several pairs of arguments. The first argument should be a size (in m)
and the second the number of antennas of this size in the array. The
sizes are attributed to the antenna in the order they are written in
the command line.

For known observatories (NOEMA, ALMA, ACA,...) the size of the antenna
is already known, the /SIZE option can be used to use a different size.

The size of the antenna is used to compute antenna shadowing.

.\"--------------------------------------------------------------------
.ti -4
2 /OFFSET
.ti +4
[ASTRO_\]UV__TRACKS ... /OFFSET Offset

The /OFFSET option is ment to deal with the limitations of
observatories using fixed delay lines. The value should be entered in m.
Does not apply to radio interferometer.

.\"====================================================================
.ti -4
1 UV__DOPPLER
.ti +4

UV__DOPPLER  Observatory  UV__TableIn [UV__TableOut [Mode]]

Compute the Doppler parameter and correct the output table
for this. The correction can be applied to the U,V lengths,
or stored as a Doppler column for further use.

 !!! HIGHLY EXPERIMENTAL - Subject to change without notice !!!
.\"====================================================================
.ti -4
1 ENDOFHELP
