Basic APECS commands

This page explains in detail the setup of observing projects at APEX through some basic APECS commands. Note that the information on this page is not needed to submit your project details - it is provided only for those who want to know more about APECS.

Frontends and Backends

The available frontends for APEX are listed on the system summary page. Possible receiver options currently include APEX-1 (known to the system as "het230"), APEX-2, LABOCA, FLASH (which is a PI instrument), and a few more.

With the arrival of the XFFTS backend, the setup for heterodyne projects is much simpler than before.

Example 1: LABOCA

frontends(['laboca'])
laboca.backends(['abba'])

Example 2: APEX-1

exec_apecs_script('shfi_commands')
setup_shfi(fename='het230',linename='co(2-1)',sideband='',mode='spec', cats='sys')

Source and line catalogs and selection

Source information and (in case of heterodyne observations) line information can be given as APECS commands or can be stored in catalogs which will be loaded after startup by the APECS system (which is the preferred way). There are system-wide catalogs, with e.g. pointing sources and widely accepted molecular line frequencies, and user catalogs, which include your target sources and special molecular line frequencies.

• Source catalogs

  APEX source catalogs have the suffix .cat. Comment lines (or comment part of source lines) are preceded by a "!" or "#". Empty lines don't have any effect. A source line will contain source name, coordinate system, epoch, RA (h:m:s), Dec (d:m:s), velocity (currently only LSR velocities are supported), and (maybe) comments. Its syntax looks like the following:

  R-And     EQ 2000  00:24:01.939   38:34:37.12   LSR -15.0  !  Pointing source
  

  Currently, the only possible coordinate system is equatorial with equinox J2000.
  Example: APEX-2 line pointing catalog.
  In APECS, the source catalogs are loaded by the sourcecats command, which allows to specify one or more catalogs, e.g.

  sourcecats(['mystars.cat','mygalaxies.cat'])
  

  When one of the loaded catalogs contains the target source, you can select this source by entering the source command with only the source name as parameter:

  source('R-And')
  

• Line catalogs

  APEX line catalogs have the suffix .lin. Each line should contain transition name, frequency, unit, sideband, and (maybe) comments. Its syntax looks like the following:

  CO(3-2)   345.79599    GHz   LSB  !  main isotope
  

  Example: APEX-2 spectral line catalog.
  The syntax to load a line catalog in APECS is very similar to that for source catalogs, and the line selection also is very simple if the line information is contained in one of the loaded line catalogs. It is actually part of the general receiver setup command.

  linecats(['mylines.lin'])
  setup_shfi(fename='het230',linename='MyLine(2-1)',sideband='',mode='spec', cats='user')
  

For projects with just one (or a few) sources it is probably easier to specify all source information using the source command of APECS instead of preparing a source catalog. An example would be:

source(name='R-And',x=('00:24:01.939','hms'),y=('38:34:37.12','dms'),system='eq',epoch=2000.0,velocity=-15.0,frame='LSR')

This command line contains all the information that you could have put into a source catalog.

Observing procedures, patterns, reference positions, offsets, ...

The basic switch mode for heterodyne observations currently is position switching. Other switch modes (wobbler switching and frequency switching) will be implemented in the future. For mapping of extended sources this switch mode can be combined with an on-source raster pattern. In addition, on-the-fly mapping is available, moving the telescope continuously and observing a reference position after each subscan.

• Switch modes and reference positions

  Currently the only available switch modes are total-power observations (e.g. for continuum pointing, switchmode=0) and position switching (switchmode=1), which is the normal switch mode for line observations.
  For position switching, a sky reference position has to be specified. This can be done relative to the source position (in case of point-like or slightly extended sources) or in absolute coordinates (for very extended sources, or if you want the same reference position for various sources).
  Example: Relative reference position at 10 arcmin distance in Azimuth

  reference(x=600.,y=0.,time=0.,on2off=1,mode='rel',system='ho')
  

  If time is set to 0, the ideal OFF-time is calculated automatically for all observing modes. on2off gives the number of ON observations for each OFF observation. This can be set to values larger than 1 if the atmosphere is very stable.
  

• Observing patterns

  There are three basic observing patterns which can be set up. The first one is a simple ON, where the telescope observes a reference position first and then the target position. The only parameter here is the integration time on the ON position, usually 10 - 30 seconds, depending on atmospheric stability.
  This procedure is suited for long-time integration on point-like sources.

  on(time=20)
  

  
  The second procedure is a RASTER, which basically is a series of ON-observations distributed over an area whose geometry is user-defined. It is suited for extended sources. Required parameters are the extend and the step size (i.e. grid) of the RASTER in both dimensions, as well as the coordinate system (equatorial or horizontal ... the latter usually doesn't make much sense).
  The following example will perform a 3x3 raster map around the source position:

  raster(xlen=16.,xstep=8.,ylen=16.,ystep=8.,time=20.,unit='arcsec',direction='x')
  

  If you want to do a RASTER over a very large area, you should consider splitting it up into several smaller RASTERs, in order to perform an atmosphere calibration measurement in between.
  
  As a third observing pattern we offer ON-THE-FLY mapping. The setup is similar to the RASTER. However, the time parameter specifies here not the integration time for one subscan, but rather for one integration (dump). For technical reasons, it should be set to exactly 1 second, e.g.

  otf(xlen100.,xstep=5.,ylen=16.,ystep=8.,time=1.,size_unit='arcsec',direction='x')
  

• Offsets

  Specifying offsets allows you to shift the centre of the desired observing pattern (i.e. the ON-position or the centre of a RASTER) relative to your catalog source position. For example,

  offset(x=20,y=-50,unit='arcsec',system='eq')
  

  will shift the centre of the following observing pattern by 20" in Right Ascension (east) and -50" in Declination (i.e. south).

Example setup and observing macros

We have collected a number of example macros which give you an idea how the projects are set up and observed in practice.

• Example APECS macros

Further information

Full documentation of the APECS CLI can be found in the following document (pdf format):

• APECS User Manual