.ec _
.ll 76
.ad b
.in 4

.ti -4
1 Language
.nf

NEW in v1.2.3 (2014-11-11)
==========================

LISSAJOUS /FOCUS     f1 f2 [... f18] [direction]    ! for NIKA
LISSAJOUS /POINTING                                 ! for NIKA
LISSAJOUS /TUNE      xOffsetT     yOffsetT          ! for NIKA
          /TTUNE     tTune                          ! for NIKA

FOCUS     /TUNE      xOffsetT     yOffsetT          ! for NIKA
          /TTUNE     tTune                          ! for NIKA
OTFMAP    /TUNE      xOffsetT     yOffsetT          ! for NIKA
          /TTUNE     tTune                          ! for NIKA
POINTING  /TUNE      xOffsetT     yOffsetT          ! for NIKA
          /TTUNE     tTune                          ! for NIKA

RECEIVER  BOLOMETER  NIKA         pixel             ! for NIKA






SUMMARY OF PAKO\ COMMANDS v1.2.3

Examples how to use HELP:

for detailed HELP on a command:  HELP OTFMAP
                                 HELP OTFM
one subtopic or option:          HELP OTFMAP /NOTF
examples:                        HELP OTFMAP EXAMPLES
all subtopics and options:       HELP OTFMAP *
options in general:              HELP OPTIONS
news about paKo:                 HELP PAKO\ NEWS


NOTE:  <<TBD     ... >>    (To BE DONE) or
       <<        ... >>    flag items that are planned for the NCS, but
                           not yet implemented or propely tested.
                           Observers should not try to use these features
                           without consulting the NCS team.

   setup:
SET & SHOW           set general parameters (project, observer, ...)
CATALOG              select source or line catalogs
SOURCE               specify a source
OFFSETS              specify source offsets
RECEIVER             set up receivers
BACKEND              set up backends

   switching modes (select 1)
SWBEAM               select and set up beam switching
SWFREQUENCY          select and set up frequency switching
SWTOTAL              select total power (no switching)
SWWOBBLER            select and set up wobbler switching

   observing modes (select 1)
CALIBRATE            specify a calibration
FOCUS                specify a focus measurement
POINTING             specify a pointing measurement
TIP                  specify an antenna tipping (a.k.a., "skydip")
TRACK                specify tracking of a single position, e.g., with SWFREQUENCY
ONOFF                specify on-off (a.k.a, "position switching")
OTFMAP               specify an On-The-Fly (OTF) map
LISSAJOUS            specify an On-The-Fly map along a Lissajous curve
VLBI                 specify tracking of a single position for VLBI

   start:
START                start an observation, i.e., send it to the queue

   save:
SAVE                 save parameters to file, i.e., a .pako script

.\"    DIY observing modes (not yet supported)
.\" <<TBD: SUBSCAN              specify an OTF subscan>>
.\" <<TBD: SEGMENT              specify a segment of an OTF subscan>>


.\"          the following 3 lines commented out 2014-11-11
.\"          because of a bug in the HELP system
.\" .ti -4
.\" 2 NEWS
.\" .nf

NEW in v1.2.3 (2014-11-11)
==========================

LISSAJOUS /FOCUS     f1 f2 [... f18] [direction]    ! for NIKA
LISSAJOUS /POINTING                                 ! for NIKA
LISSAJOUS /TUNE      xOffsetT     yOffsetT          ! for NIKA
          /TTUNE     tTune                          ! for NIKA

FOCUS     /TUNE      xOffsetT     yOffsetT          ! for NIKA
          /TTUNE     tTune                          ! for NIKA
OTFMAP    /TUNE      xOffsetT     yOffsetT          ! for NIKA
          /TTUNE     tTune                          ! for NIKA
POINTING  /TUNE      xOffsetT     yOffsetT          ! for NIKA
          /TTUNE     tTune                          ! for NIKA

RECEIVER  BOLOMETER  NIKA         pixel             ! for NIKA


NEW in v1.1.15:
==============

Support for the upgrade of EMIR band E150 to full 2*2*8 GHz LSB+USB 
in both polarizations, and the E330 local oscillator to higher
frequencies (2013-09).

There are NO new commands in v1.1.15


NEW in 1.1.14:
==============

RECEIVER BOLOMETER NIKA          ! Receiver (bolometer) NIKA

SUBSCAN xOffset yOffset  /TUNE                    ! for NIKA
DIY                      /PURPOSE "play my Tune"  ! for NIKA


NEW in 1.1.12:
==============

RECEIVER BOLOMETER GISMO    ! Receiver (bolometer) GISMO

LISSAJOUS                   ! Observing Mode Lissajous for GISMO, i.e.,
                            ! an On-The-Fly map along a Lissajous curve


UPDATED in 1.1.11:
==================

RECEIVER EMIR               ! Receiver EMIR, upgrade of E230 and E330
BACKEND  FTS                ! Fourier Transform Spectrometer
BACKEND  BBC                ! Broad Band Continuum Backend

SET      EMIRcheck          ! limit checking for EMIR
SET      UserLevel          ! 

.\" paKo, v1.1.6
.\" ============
.\" 
.\" UPDATED in v1.1.6: 
.\" 
.\" BACKEND FTS                 ! Fourier Transform Spectrometer
.\" 
.\" 

NEW in v1.1.5: 
=============

BACKEND BBC                 ! Broad  Band Continuum Backend
BACKEND NBC                 ! Narrow Band Continuum Backend


NEW in v1.1.4: 
=============

BACKEND FTS                 ! Fourier Transform Spectrometer                    
SET     EMIRCheck           ! "strict"|"relaxed"|"loose"


NEW in v1.1.1: SUPPORT FOR EMIR
===============================

--> major changes in 

CALIBRATE
BACKEND
RECEIVER

.\" paKo, v1.0.9.4
.\" ==============
.\" 
.\" modifications of some commands FOR MAMBO BOLOMETER OBSERVATIONS, see:
.\" 
.\" OFFSETS ...  /SYSTEM NASMYTH
.\" OFFSETS ...  /SYSTEM NASMYTH /CLEAR
.\" TIP     ...  /TPADDLE
.\" TIP     ...  /SLEW  
.\" 
.\" paKo, v1.0.9
.\" ============
.\" 
.\" paKo, v1.0.8
.\" ============
.\" 
.\" 100 kHz Filterbank is decommissioned (RM, 12.9.2007)
.\" 
.\" paKo, v1.0.7
.\" ============
.\" 
.\" IMPORTANT CHANGE: NEW LOGIC FOR RECEIVER /TEMPLOAD L L
.\" for details, see: 
.\" HELP RECEIVER /TEMPLOAD
.\" 
.\" paKo, v1.0.6.3
.\" ==============
.\" 
.\"    GENERAL:
.\" 
.\" paKo Lock              There is a new lock file mechanism to prevent that 
.\"                        2 instances of pako run in the same working directory.
.\" 
.\" Sequence of Commands   It is now enforced for the purpose of consistency checking and
.\"                        "scan analysis", i.e., for the translation to subsan sequences:
.\" 
.\"                        BACKEND must be specified after RECEIVER.
.\"                        Observing Mode must be specified after Switching Mode.
.\"                        Observing Mode must be specified after SET 2ndRotation.
.\"                        ONOFF must be specified after OFFSETS.
.\" 
.\"                        START will not work without SOURCE, RECEIVER, and BACKEND.
.\" 
.\" Checks                 There are various stricter limit checks and more consistency 
.\"                        checks.
.\" 
.\"    NEW COMMANDS:
.\" 
.\" SET 2ndRotation        set rotation angle for secondary mirror
.\"                        and Wobbling mechamism. This is ONLY for Bolometer
.\"                        with Wobbler Switching and POINTING, FOCUS, 
.\"                        and OTFMAP.
.\" 
.\" SHOW                   now also shows the pako version (revision number and date)
.\"                        and the 2ndRotation.
.\" 
.\" NOTE                   the character / is NOT allowed in source names
.\"                        to avoid confusion with SIC "options" like /VELOCITY
.\" 
.\" 
.\"    NEW OPTIONS:
.\" 
.\" POINTING /DOUBLEBEAM   "double-beam pointing"
.\"                        only for Bolometer and Wobbler switching
.\"                        with 2ndRotation angle = 0.0


-----
NOTE:  <<TBD ... >>    (To BE DONE) or
       <<    ... >>    flag items that are planned for the NCS, but
                       not yet implemented or properly tested.
                       Observers should not try to use these features
                       without consulting the NCS team.

.\"          the following 3 lines commented out 2014-11-11
.\"          because of a bug in the HELP system
.\" .ti -4
.\" 2 HELP
.\" .nf

.\" Examples how to use HELP:
.\" 
.\" for detailed HELP on a command:  HELP OTFMAP
.\"                                  HELP OTFM
.\" one subtopic or option:          HELP OTFMAP /NOTF
.\" examples:                        HELP OTFMAP EXAMPLES
.\" all subtopics and options:       HELP OTFMAP *
.\" options in general:              HELP OPTIONS
.\" news about paKo:                 HELP PAKO\ NEWS
.\" help about paKo HELP:            HELP PAKO\ HELP

.\"  <<< ************************************************************* EMIR ***************

.ti -4
1 BACKEND

.nf
BACKEND  name      nPart resolution bandwidth fShift 
                         receiverBand [polarization subband|sideband]

BACKEND  /CLEAR

Alternative short syntax (only for the backends shown here!):
BACKEND  BBC   nPart           /REC receiverBand [polarization sideband]
BACKEND  NBC   nPart           /REC receiverBand [polarization subband]
BACKEND  4MHz  nPart           /REC receiverBand [polarization subband]
BACKEND  WILMA nPart           /REC receiverBand [polarization subband]
BACKEND  FTS   nPart           /REC receiverBand [polarization subband]
BACKEND  FTS   nPart /FINE     /REC receiverBand [polarization subband]

Set up backends for heterodyne receivers.

Character :: name           ! name of backend
Integer   :: nPart          ! (logical) number of backend part
Real      :: resolution     ! [MHz]
Real      :: bandwidth      ! [MHz]
Real      :: fShift         ! frequency shift [MHz]
Character :: receiverBand   ! receiver band      to connect to backend part 
Character :: polarization   ! EMIR: polarization to connect to backend part 
Character :: subband        ! EMIR: subband      to connect to backend part 
Character :: sideband       ! EMIR: sideband     to connect to backend part 

Choices for (backend) name are:
BBC                         ! Broad  Band Continuum Backend
NBC                         ! Narrow Band Continuum Backend 
4MHz                        ! filter spectrometers with fixed resolution 
WILMA                       ! autocorrelation spectrometers
FTS                         ! Fourier Transform Spectrometer
VESPA                       ! autocorrelator with variable resolution


Choices for receiverBand are (compare RECEIVER command):
E090 E150 E230 E330 HERA1 HERA2

Choices for polarization are (for EMIR; compare RECEIVER command):
Horizontal Vertical

.so nroffSoSubtopics/subbandSideband.nroff

fShift can be used to shift (offset) the backend band within the
receiver band; this only applies to some backends, in particular
VESPA. For VESPA, the range for fShift is much smaller than the 4GHz
subbands of EMIR. For wide-bandwidth backends, fShift is fixed,
corresponding to the frequency pattern of the EMIR subbands and
backend bands. See EMIR and backend documentation.

/CLEAR completely clears the backend setup.

If option /CLEAR is present, all other parameters and options are ignored.

.so nroffSoSubtopics/subbandIFcables.nroff

NOTES: 
- for some backends the resolution and/or bandwidth are fixed and the
  short syntax can be used. (The full syntax is supported for all backends).
- for VESPA always use the full syntax!
- after changing the receiver configuration: BACKEND /CLEAR is recommended 
  followed by the backend setup for the new receivers; without that it is
  possible that pako will not accept BACKEND commands because of unresolved 
  conflicts between the RECEIVER and BACKEND setups.
- However, the backend command will automatically try to disconnect
  backends that were connected to receiver (sub)bands that are not 
  connected anymore.

.\" .so nroffSoSubtopics/backendBBC.nroff
.\"
.\" .so nroffSoSubtopics/backend4MHz.nroff
.\" 
.\" .so nroffSoSubtopics/backend1MHz.nroff
.\" 
.\" .so nroffSoSubtopics/backendVESPA.nroff
.\" 
.\" .so nroffSoSubtopics/backendWILMA.nroff

.\"  commented out: 
.\" .so nroffSoOptions/optionDefaults.nroff
.\" .so nroffSoOptions/optionClear.nroff
.\" .so nroffSoOptions/optionConnect.nroff
.\" .so nroffSoOptions/optionDisconnect.nroff
.\" .so nroffSoOptions/optionMode.nroff
.\" .so nroffSoOptions/optionPercentage.nroff
.\" .so nroffSoOptions/optionBackendReceiver.nroff
.\" .so nroffSoExamples/pakoExamplesBackend.nroff

.ti -4
2 BBC
.so nroffSoSubtopics/backendBBC.nroff

.ti -4
2 FTS
.so nroffSoSubtopics/backendFTS.nroff

.\" .ti -4
.\" 2 4MHZ
.\" .so nroffSoSubtopics/backend4MHz.nroff
.\" .ti -4
.\" 2 1MHZ
.\" .so nroffSoSubtopics/backend1MHz.nroff
.\" .ti -4
.\" 2 VESPA
.\" .so nroffSoSubtopics/backendVESPA.nroff
.\" .ti -4
.\" 2 WILMA
.\" .so nroffSoSubtopics/backendWILMA.nroff

.ti -4
2 /DEFAULTS
.\" .so nroffSoOptions/optionDefaults.nroff

.nf
/DEFAULTS  [yes|no]

Set default values.

If EMIR sub bands have been selected with the RECEIVER command, 
this option has a special function for some Backends:

BACKEND BBC       /Defaults     connects one BBC  part to each
                                sideband (!) of each selected EMIR band
                                (up to 8)

BACKEND NBC       /Defaults     connects one NBC  part to each
                                selected EMIR sub band (up to 4)

BACKEND 4MHZ      /Defaults     connects one 4MHz part to each of 
                                the 1st and 2nd selected EMIR sub band

BACKEND WILMA     /Defaults     connects one WILMA part to each
                                selected EMIR sub band (up to 4)

BACKEND FTS       /Defaults     connects one FTS part in "wide" bandwidth 
                                to each EMIR sub band (up to 4) selected
                                for IF cables 1 to 4, and additionally
                                one part to each of the available Outer
                                subbands (up to 4) on IF cables 5 to 8
                                
BACKEND FTS /Fine /Defaults     connects one FTS part in "fine" resolution 
                                to each EMIR sub band (up to 4) selected
                                for IF cables 1 to 4, and additionally
                                one part to each of the available Outer
                                subbands (up to 4) on IF cables 5 to 8
.fi

.ti -4
2 /CLEAR
.so nroffSoOptions/optionClear.nroff

.nf
After changing the receiver configuration: BACKEND /CLEAR is recommended 
followed by the backend setup for the new receivers; without that it is
possible that pako will not accept BACKEND commands because of unresolved 
conflicts between the RECEIVER and BACKEND setups.
.fi

.ti -4
2 /CONNECT
.so nroffSoOptions/optionConnect.nroff

--> DEPRECATED. PROTECTED (needs SET userLevel)

.ti -4
2 /DISCONNECT
.so nroffSoOptions/optionDisconnect.nroff

-->  DEPRECATED. PROTECTED (needs SET userLevel)

.ti -4
2 /FINE
.so nroffSoOptions/optionFine.nroff

.ti -4
2 /MODE
.so nroffSoOptions/optionMode.nroff

.ti -4
2 /LINENAME
.\" .so nroffSoOptions/optionLineName.nroff

.nf

/LINENAME lineName

Character :: lineName          ! name of line. don't use @ < >

--> OPTION OF BACKEND COMMAND FOR USE WITH EMIR

This allows to set a "line" name for each backend part. 

If a line name is set for a backend part, it will be used in the CLASS
header of the spectrum from that backend part.

If no line name is set for a backend part (default), the line name
from the corresponding RECEIVER band will be used in the CLASS header.

This is an optional convenience feature to make it easier to identify
spectra by appropriate names, in particular in cases where several
different lines are observed simultaneously with the same receiver
band.

This is only a name or label, and has no influence on any frequencies
or other control parameters.

.ti -4
2 /PERCENTAGE
.so nroffSoOptions/optionPercentage.nroff

.ti -4
2 /RECEIVER
.\" .so nroffSoOptions/optionBackendReceiver.nroff
.nf
/RECEIVER receiverBand [polarization subband|sideband]

Character :: receiverBand   ! receiver band      to connect to backend part 
Character :: polarization   ! EMIR: polarization to connect to backend part 
Character :: subband        ! EMIR: subband      to connect to backend part 
Character :: sideband       ! EMIR: sideband     to connect to backend part 

Choices for receiverBand are (compare RECEIVER command):
E090 E150 E230 E330 HERA1 HERA2

Choices for polarization are (for EMIR; compare RECEIVER command):
Horizontal Vertical

.so nroffSoSubtopics/subbandSideband.nroff

.fi  
.ti -4
2 EXAMPLES
.nf
.so nroffSoExamples/pakoExamplesBackend.nroff

.\"  >>> ************************************************************* EMIR ***************
.\"  <<< ************************************************************* EMIR ***************

.ti -4
1 CALIBRATE

.nf

CALIBRATE (no parameters)

Specify a calibration measurement with the heterodyne receivers,
normally with subscans "SAC": Sky -- Ambient temperature load -- Cold load

NOTE: CALIBRATE is always and automatically done with switching mode "total power"
and the time per phase is adjusted to be in the range 0.1 to 0.5 [sec]

.\" .so nroffSoOptions/optionDefaults.nroff
.\" .so nroffSoOptions/optionAmbient.nroff
.\" .so nroffSoOptions/optionCold.nroff
.\" .so nroffSoOptions/optionCalGainImage.nroff
.\" .so nroffSoOptions/optionGrid.nroff
.so nroffSoOptions/optionSky.nroff
.\" .so nroffSoOptions/optionSystem.nroff
.\" .so nroffSoOptions/optionTcalibrate.nroff
.\" .so nroffSoExamples/pakoExamplesCalibrate.nroff

.ti -4
2 /DEFAULTS
.so nroffSoOptions/optionDefaults.nroff
.ti -4
2 /AMBIENT
.so nroffSoOptions/optionAmbient.nroff
.ti -4
2 /COLD
.so nroffSoOptions/optionCold.nroff
.ti -4
2 /GAINIMAGE
.\" .so nroffSoOptions/optionCalGainImage.nroff

.nf

 --> NOTE: OBSOLETE WITH CHANGE TO EMIR

.fi

.ti -4
2 /GRID
.\" .so nroffSoOptions/optionGrid.nroff

.nf
/GRID [yes|no]

NOT YET AVAILABLE FOR EMIR

Do a calibration subscan on a grid.  This is a special calibration
option for polarization observations.

Logical   :: doGrid           ! default: true

IMPORTANT NOTE: 
remember to turn this option off again for normal calibrations:
e.g., CALIBRATE /GRID NO or CALIBRATE /DEFAULT.

.fi

.ti -4
2 /SKY
.so nroffSoOptions/optionSky.nroff
.ti -4
2 /SYSTEM
.so nroffSoOptions/optionSystem.nroff
.ti -4
2 /TCALIBRATE
.so nroffSoOptions/optionTcalibrate.nroff

.\" .ti -4
.\" 2 EXAMPLES
.\" .nf
.\" .so nroffSoExamples/pakoExamplesCalibrate.nroff

.\"  >>> ************************************************************* EMIR ***************

.\"  <<< ************************************************************* EMIR ***************

.ti -4
1 CATALOG

.nf

CATALOG [SOURCE|LINE] fileName

Select a source or line catalog.

Character :: kind              ! SOURCE or LINE
Character :: fileName          ! file name

Selects a file with name fileName as source or line catalog.

.so nroffSoSubtopics/sourceCatalog.nroff
.so nroffSoSubtopics/lineCatalog.nroff
.so nroffSoSubtopics/specialCharacters.nroff

.ti -4
2 SOURCE
.so nroffSoSubtopics/sourceCatalog.nroff

.ti -4
2 LINE
.so nroffSoSubtopics/lineCatalog.nroff


.fi

.ti -4
1 DISPLAY

.nf

DISPLAY REDO

Redo (refresh) the text in the display window.

.fi


.ti -4
1 DIYLIST

.nf
DIYLIST

User-defined list of subscans and segments for observing mode "DIY"; 
to define subscans, see HELP SUBSCAN.

NB: this is a protected command (needs privilege).

DIYLIST without any parameters or options:

  - lists defined subscans and segments in the pako window
    (this requires SET LEVEL 2 or lower)
  - in the pakoDisplay shows conditions, e.g., maximum possible elevation
  - plots defined subscans and segments (depending on SET plotStyle)

.ti -4
2 /CLEAR
.so nroffSoOptions/optionClearDIYlist.nroff

.ti -4
2 /PURPOSE
.so nroffSoOptions/optionPurpose.nroff

.fi

.ti -4
1 FOCUS

.nf

FOCUS lengthFocus

Specify a focus measurement.

Real      :: lengthFocus       ! length [mm] of focus scan


The sequence of focus subscans is determined by 
lengthFocus /nSubscans /otfFocus:

 lengthFocus     ! total length [mm] of the focus scan 
 /nSubscans      ! number of focus subscans
 << TD:/otfFocus       ! not yet implemented>>

 focus subscan 1 is at offset  0.0
 focus subscan 2 is at offset  lengthFocus/2
 in case /nSubscans 3:
 focus subscan 3 is at offset -lengthFocus/2
 in case /nSubscans >3:
 focus subscan 3 is at offset  lengthFocus/2
 focus subscan 4 is at offset -lengthFocus/2
 focus subscan 5 is at offset -lengthFocus/2
 focus subscan 6 is at offset  0.0
 (etc.)
 

.\" .so nroffSoOptions/optionDefaults.nroff
.\" .so nroffSoOptions/optionCalibrate.nroff
.\" .so nroffSoOptions/optionFeBe.nroff
.\" .so nroffSoOptions/optionNsubscans.nroff
.\" .so nroffSoOptions/optionTsubscan.nroff
.\" .so nroffSoOptions/optionUpdate.nroff
.\" .so nroffSoExamples/pakoExamplesFocus.nroff

.ti -4
2 /DEFAULTS
.so nroffSoOptions/optionDefaults.nroff
.\" .ti -4
.\" 2 /CALIBRATE
.\" .so nroffSoOptions/optionCalibrate.nroff
.\" .ti -4
.\" 2 /FEBE
.\" .so nroffSoOptions/optionFeBe.nroff
.ti -4
2 /NSUBSCANS
.so nroffSoOptions/optionNsubscans.nroff
.ti -4
2 /TSUBSCAN
.so nroffSoOptions/optionTsubscan.nroff
.\" .ti -4
.\" 2 /UPDATE
.\" .so nroffSoOptions/optionUpdate.nroff
.ti -4
2 /TUNE
.so nroffSoOptions/optionTuneOffsets.nroff
.nf
For FOCUS, the offsets for the tune subscan are in the
"trueHorizontal" system.

.fi
.ti -4
2 /TTUNE
.so nroffSoOptions/optionTtune.nroff

.ti -4
2 EXAMPLES
.nf
.so nroffSoExamples/pakoExamplesFocus.nroff

.ti -4
1 LISSAJOUS

.nf

LISSAJOUS    xAmplitude   yAmplitude
  /CENTER    xCenter      yCenter
  /FREQUENCY frequencyX   frequencyY
  /PHASES    phiX         phiY
  /TOTF      tOtf
  /SYSTEM    system

additionally for NIKA:

  /FOCUS     f1 f2 [... f18] [direction]
  /POINTING  [yes|no] 
  /TUNE      xOffsetT     yOffsetT
  /TTUNE     tTune

Specify an On-The-Fly (OTF) map with a Lissajous curve in 1 subscan.
LISSAJOUS is at this time (2014-11-10) supported only for GISMO and NIKA

Real      :: xAmplitude        ! amplitude for x-offsets
Real      :: yAmplitude        ! amplitude for y-offsets
Real      :: xCenter           ! center x-offset 
Real      :: yCenter           ! center y-offset 
Real      :: frequencyX        ! frequency    [Hz]  for x 
Real      :: frequencyY        ! frequency    [Hz]  for y 
Real      :: phiX              ! phase offset [rad] for x 
Real      :: phiY              ! phase offset [rad] for y 

Real      :: tOtf              ! time [s]
Character :: systemName        ! name of system, one of:
                               ! PROJECTION
                               ! TRUEHORIZON

Real      :: f1 f2 [... f18]   ! focus offset [mm] during each Lissajous curve
Character :: direction         ! direction of focus offsets, one of:
                               ! X 
                               ! Y
                               ! Z 

Real      :: xOffsetT          ! x-offset for tune subscan
Real      :: yOffsetT          ! y-offset for tune subscan
Real      :: tTune             ! time [s] for tune subscan


During a Lissajous OTF segment, the position offsets 
x and y as a function of time t are:

x = xCenter + xAmplitude * SIN(2 Pi frequencyX t + phiX)
y = yCenter + yAmplitude * SIN(2 Pi frequencyY t + phiY)

SIN is the usual sine function, Pi is the number Pi.

xAmplitude yAmplitude xCenter yCenter are in angle units ([arc sec])
frequencyX frequencyY                 are in [Hz]
phiX       phiY                       are in [rad]

Note that the possible frequencies are very low, 
typically 0.01 to 0.15 Hz.

At the start of a Lissajous subscan, paKo will insert a "ramp" along a
straight line, i.e., a linear OTF segment, increasing the count of
segments by 2.  This ramp up starts with speed 0 relative to the
source and joins smoothly with the start position and velocity of the
Lissajous segment.  The purpose is to avoid a sudden acceleration at
the start of the Lissajous segment.  The inserted ramp up
segment and the Lissajous segment become part of the same subscan.

Lissajous curves with large amplitudes or frequencies can reach the
antenna's speed and acceleration limits for tracking.  Lissajous
curves can be executed only for elevations less than a maximum, which
depends on the Lissajous parameters.  For information, this elevation
condition is shown by pako. Even below the limits, during very fast
Lissajous curves the tracking errors will be higher, several arc sec,
than during most other observations.

DO NOT TRY TO OBSERVE LISSAJOUS ABOVE THIS MAXIMUM ELEVATION.

.ti -4
2 /CENTER
.so nroffSoOptions/optionCenter.nroff
.ti -4
2 /FREQUENCY
.so nroffSoOptions/optionFrequency.nroff
.ti -4
2 /PHASES
.so nroffSoOptions/optionPhases.nroff
.ti -4
2 /SYSTEM
.so nroffSoOptions/optionSystem.nroff
.ti -4
2 /TOTF
.so nroffSoOptions/optionTotf.nroff
.ti -4
2 /FOCUS
.so nroffSoOptions/optionFocus.nroff
.ti -4
2 /POINTING
.so nroffSoOptions/optionPointing.nroff
.ti -4
2 /TUNE
.so nroffSoOptions/optionTuneOffsets.nroff
.nf
The offsets for the tune subscan are in the system selected with /SYSTEM.

.fi
.ti -4
2 /TTUNE
.so nroffSoOptions/optionTtune.nroff

.ti -4
1 OFFSETS

.nf

OFFSETS xOffset yOffset

Specify source offsets.

Real      :: xOffset           ! x-offset 
Real      :: yOffset           ! y-offset 

IMPORTANT NOTE: one should be careful with the OFFSETS command, which
is only used and only needed in a few special situations, e.g., with
Wobbler-switching ONOFF and to set NASMYTH offsets for
focal-plane-array receivers.  The function of OFFSETS is explained in
the paKo user's manual, Section "A Guide to the Perplexed" and, in
more detail, in the Section "NCS Explained", Subsection "Coordinate
Systems, Projections, and Offsets."

For many observations all "offsets" are specified as parameters or
options of the command for the observing mode. 

.\" .so nroffSoOptions/optionDefaults.nroff
.\" .so nroffSoOptions/optionClear.nroff
.so nroffSoOptions/optionSystem.nroff

.ti -4
2 /DEFAULTS
.so nroffSoOptions/optionDefaults.nroff
.ti -4
2 /CLEAR
.so nroffSoOptions/optionClear.nroff
.ti -4
2 /SYSTEM
.so nroffSoOptions/optionSystem.nroff

.fi

.ti -4
1 ONOFF

.nf

ONOFF xOffset yOffset

Specify on-off measurement, a.k.a. "position switching".

Real      :: xOffset           ! x-offset of "on-source" position
Real      :: yOffset           ! y-offset of "on-source" position

Character :: sourceName        ! name of "on-source" position

NOTE: if SWWOBBLER is the selected switching mode, the special option
/SWWOBBLER YES (TRUE) is implied even without specifying it, and the
on-off parameters appropriate for on-off Wobbler switching are set.

.so nroffSoSubtopics/swWobblerOnOff.nroff

.\" .so nroffSoOptions/optionDefaults.nroff
.\" .so nroffSoOptions/optionBalance.nroff
.\" .so nroffSoOptions/optionCalibrate.nroff
.\" .so nroffSoOptions/optionNsubscans.nroff
.so nroffSoOptions/optionReference.nroff
.\" .so nroffSoOptions/optionSymmetric.nroff
.so nroffSoOptions/optionSystem.nroff
.\" .so nroffSoOptions/optionTsubscan.nroff
.\" .so nroffSoExamples/pakoExamplesOnoff.nroff

.ti -4
2 /DEFAULTS
.so nroffSoOptions/optionDefaults.nroff
.\" .ti -4
.\" 2 /BALANCE
.\" .so nroffSoOptions/optionBalance.nroff
.\" .ti -4
.\" 2 /CALIBRATE
.\" .so nroffSoOptions/optionCalibrate.nroff
.ti -4
2 /NSUBSCANS
.so nroffSoOptions/optionNsubscans.nroff
.ti -4
2 /REFERENCE
.so nroffSoOptions/optionReference.nroff
.ti -4
2 /SWWOBBLER
.so nroffSoOptions/optionSwWobbler.nroff
.ti -4
2 /SYMMETRIC
.so nroffSoOptions/optionSymmetric.nroff
.ti -4
2 /SYSTEM
.so nroffSoOptions/optionSystem.nroff
.ti -4
2 /TSUBSCAN
.so nroffSoOptions/optionTsubscan.nroff

.ti -4
2 EXAMPLES
.nf
.so nroffSoExamples/pakoExamplesOnoff.nroff
.so nroffSoExamples/pakoExamplesOnoffSwWobbler.nroff

.ti -4
1 OTFMAP

.nf

OTFMAP xStart yStart xEnd yEnd

Specify an On-The-Fly (OTF) map with linear OTF subscans.

Real      :: xStart            ! x-offset of start of first OTF  subscan
Real      :: yStart            ! y-offset of start of first OTF  subscan
Real      :: xEnd              ! x-offset of end   of first OTF  subscan
Real      :: yEnd              ! y-offset of end   of first OTF  subscan

The sequence of subscans is determined by:
/croLoop /nOtf /reference /step /zigzag

/croLoop     sequence of:
             R off-source Reference
             O on-source OTF
/nOtf        number of OTF subscans
/reference   off-source reference position
/step        step in x and y between OTF subscans
             = translation of one OTF subscans to the next
/zigzag      option to scan back-and-forth

The scan analysis loops through the letter codes in croLoop until nOtf
OTF subscans have been generated, starting with first letter in the
croLoop.
   
   IF THE CROCODE LETTER IS "R" AND /REFERENCE IS TRUE:
   
   1 subscan tracking the fixed off-source reference position
   is generated
   
   IF THE CROCODE LETTER IS "O":
   
   1 linear OTF subscan is generated. 
   - The start and end positions of the first OTF subscan are:
     parameters xStart yStart xEnd yEnd of the OTFMAP command
   - For the second and all following OTF subscans:
     xStart yStart xEnd yEnd of the previous OTF subscan are
     incremented by parameters dx and dy of option /step.
     If /zigzag is true, xStart yStart and xEnd yEnd are
     interchanged.
   
Then the next letter code in the croLoop is considered
in the same way.

If /reference is true, a croCode ending in "R" will ensure that an
off-source reference subscan follows the last OTF subscan.

.\" .so nroffSoOptions/optionDefaults.nroff
.\" .so nroffSoOptions/optionBalance.nroff
.so nroffSoOptions/optionCROloop.nroff
.so nroffSoOptions/optionNotf.nroff
.so nroffSoOptions/optionReference.nroff
.\" .so nroffSoOptions/optionResume.nroff
.so nroffSoOptions/optionStep.nroff
.\" .so nroffSoOptions/optionSpeed.nroff
.so nroffSoOptions/optionSystem.nroff
.\" .so nroffSoOptions/optionTotf.nroff
.\" .so nroffSoOptions/optionTrecord.nroff
.\" .so nroffSoOptions/optionTreference.nroff
.\" .so nroffSoOptions/optionZigzag.nroff
.\" .so nroffSoExamples/pakoExamplesOtfmap.nroff

.ti -4
2 /DEFAULTS
.so nroffSoOptions/optionDefaults.nroff
.\" .ti -4
.\" 2 /BALANCE
.\" .so nroffSoOptions/optionBalance.nroff
.ti -4
2 /CROLOOP
.so nroffSoOptions/optionCROloop.nroff
.ti -4
2 /NOTF
.so nroffSoOptions/optionNotf.nroff
.ti -4
2 /REFERENCE
.so nroffSoOptions/optionReference.nroff
.ti -4
.\" 2 /RESUME
.\" .so nroffSoOptions/optionResume.nroff
.\" .ti -4
2 /STEP
.so nroffSoOptions/optionStep.nroff
.ti -4
2 /SPEED
.so nroffSoOptions/optionSpeed.nroff
.ti -4
2 /SYSTEM
.so nroffSoOptions/optionSystem.nroff
.ti -4
2 /TOTF
.so nroffSoOptions/optionTotf.nroff
.\" .ti -4
.\" 2 /TRECORD
.\" .so nroffSoOptions/optionTrecord.nroff
.ti -4
2 /TREFERENCE
.so nroffSoOptions/optionTreference.nroff
.ti -4
2 /ZIGZAG
.so nroffSoOptions/optionZigzag.nroff
.ti -4
2 /TUNE
.so nroffSoOptions/optionTuneOffsets.nroff
.nf
The offsets for the tune subscan are in the system selected with /SYSTEM.

.fi
.ti -4
2 /TTUNE
.so nroffSoOptions/optionTtune.nroff

.ti -4
2 EXAMPLES
.nf
.so nroffSoExamples/pakoExamplesOtfmap.nroff
.so nroffSoExamples/pakoExamplesOtfmapSwFrequency.nroff


.ti -4
1 POINTING

.nf

POINTING length

Specify a pointing measurement with linear OTF subscans in the
"true-angle" horizontal system, along azimuth and elevation, all
centered on the source.

Real      :: length            ! length (angle) of each subscan

The first subscan is incrementing in azimuth. If the number of OTF
subscans, nOtf, is 2, the second subscan is incrementing in
elevation.  If nOtf > 2, the subscan sequence is: incrementing
azimuth, decrementing azimuth, incrementing elevation, and if nOtf >
3: decrementing elevation, etc.

.\" .so nroffSoOptions/optionDefaults.nroff
.\" .so nroffSoOptions/optionCalibrate.nroff
.\" .so nroffSoOptions/optionDoubleBeam.nroff
.\" .so nroffSoOptions/optionFeBe.nroff
.\" .so nroffSoOptions/optionMore.nroff
.\" .so nroffSoOptions/optionNotf.nroff
.\" .so nroffSoOptions/optionTotf.nroff
.\" .so nroffSoOptions/optionTrecord.nroff
.\" .so nroffSoOptions/optionUpdate.nroff
.\" .so nroffSoExamples/pakoExamplesPointing.nroff

.ti -4
2 /DEFAULTS
.so nroffSoOptions/optionDefaults.nroff
.\" .ti -4
.\" 2 /CALIBRATE
.\" .so nroffSoOptions/optionCalibrate.nroff
.ti -4
2 /DOUBLEBEAM
.so nroffSoOptions/optionDoubleBeam.nroff
.\" .ti -4
.\" 2 /FEBE
.\" .so nroffSoOptions/optionFeBe.nroff
.\" .ti -4
.\" 2 /MORE
.\" .so nroffSoOptions/optionMore.nroff
.ti -4
2 /NOTF
.so nroffSoOptions/optionNotf.nroff
.ti -4
2 /TOTF
.so nroffSoOptions/optionTotf.nroff
.\" .ti -4
.\" 2 /TRECORD
.\" .so nroffSoOptions/optionTrecord.nroff
.\" .ti -4
.\" 2 /UPDATE
.\" .so nroffSoOptions/optionUpdate.nroff
.ti -4
2 /TUNE
.so nroffSoOptions/optionTuneOffsets.nroff
.nf
For POINTING, the offsets for the tune subscan are in the
"trueHorizontal" system.

.fi
.ti -4
2 /TTUNE
.so nroffSoOptions/optionTtune.nroff

.ti -4
2 EXAMPLES
.nf
.so nroffSoExamples/pakoExamplesPointing.nroff


.\"  <<< ************************************************************* EMIR ***************




.ti -4
1 RECEIVER

.nf

RECEIVER              receiverBand    lineName [frequency SB]
RECEIVER BOLOMETER    bolometerName   [pixel]

Specify selection and setup for receivers.  

The first form is for heterodyne receivers, 
the second form for bolometers.

Heterodyne:
===========

Character    :: receiverBand      ! name of receiver band to connect
Character*12 :: lineName          ! name of line. don't use @ < >
Real         :: frequency         ! [GHz]
Character    :: SB                ! sideband or subband
                                  ! choices for HERA: LSB USB
                                  ! choices for EMIR: LO LI UI UO

Choices for receiverBand are:
E090 E150 E230 E330 HERA1 HERA2

lineName is limited to 12 characters.

.so nroffSoSubtopics/specialCharacters.nroff
.nf

E090 E150 E230 E330 are the 4 EMIR (Eight MIxer Receiver) bands, 
HERA1 and HERA2     are the 2 parts of HERA (HEterodyne Receiver Array).

If only receiverBand and lineName are specified, we try to read the
frequency and sideband/subband from the line catalog specified with:
CATALOG LINE fileName.

The local oscillator for the receiverBand will be set so that the
frequency (corrected for the Doppler shift) will be in the requested
sideband/subband SB.  See receiver documentation for the exact values
of the IF.

.so nroffSoSubtopics/subbandIFcables.nroff

Bolometer:
==========

.so nroffSoSubtopics/receiverBolometer.nroff


.\" .so nroffSoOptions/optionDefaults.nroff
.\" .so nroffSoOptions/optionClear.nroff
.\" .so nroffSoOptions/optionConnect.nroff
.\" .so nroffSoOptions/optionDerotator.nroff
.\" .so nroffSoOptions/optionDisconnect.nroff
.\" .so nroffSoOptions/optionDoppler.nroff
.\" .so nroffSoOptions/optionEfficiency.nroff
.\" .so nroffSoOptions/optionGainImage.nroff
.\" .so nroffSoOptions/optionScale.nroff
.\" .so nroffSoOptions/optionTempLoad.nroff
.\" .so nroffSoOptions/optionWidth.nroff
.\" .so nroffSoExamples/pakoExamplesReceiver.nroff

.ti -4
2 /DEFAULTS
.so nroffSoOptions/optionDefaults.nroff
.ti -4
2 /CLEAR
.so nroffSoOptions/optionClear.nroff
.ti -4
2 /CONNECT
.so nroffSoOptions/optionConnect.nroff

 --> DEPRECATED. PROTECTED (needs SET userLevel)

.ti -4
2 /DEROTATOR
.so nroffSoOptions/optionDerotator.nroff
.ti -4
2 /DISCONNECT
.so nroffSoOptions/optionDisconnect.nroff

 --> DEPRECATED. PROTECTED (needs SET userLevel)

.ti -4
2 /DOPPLER
.so nroffSoOptions/optionDoppler.nroff

.ti -4
2 /EFFICIENCY
.so nroffSoOptions/optionEfficiency.nroff

.\" .ti -4
.\" 2 /FOFFSET
.\" .\" .so nroffSoOptions/optionFoffset.nroff
.\" 
.\" .nf
.\" /FOFFSET fOffset
.\" 
.\" Real      :: fOffset         !  frequency offset [GHz]
.\" 
.\" .fi

.ti -4
2 /GAINIMAGE
.\" .so nroffSoOptions/optionGainImage.nroff

.nf
/GAINIMAGE gainImage [dB]

Specify the gain ratio of image to signal sidebands.

Real      :: gainImage         ! 

If "dB" is added after the value, the ratio is assumed to be in dB,
otherwise a decimal fraction.

--> A standard value for EMIR is -13 db, for HERA -10 db.

.fi

.ti -4
2 /HORIZONTAL
.so nroffSoOptions/optionHorizontal.nroff

.ti -4
2 /SCALE
.so nroffSoOptions/optionScale.nroff

.fi

.ti -4
2 /TEMPLOAD
.\" .so nroffSoOptions/optionTempLoad.nroff

.nf
/TEMPLOAD tempColdLoad tempAmbientLoad
/TEMPLOAD L[OOKUP]     L[OOKUP]
/TEMPLOAD *            ...

Set effective temperatures for the calibration loads at cold and ambient
temperature.

Real      :: tempColdLoad      !
Real      :: tempAmbientLoad   !

NEW LOGIC FOR SINGLE-PIXEL SIS RECEIVERS (FROM SUMMER 2007, paKo v1.0.7)

If a numerical value is entered for tempColdLoad or tempAmbientLoad,
that value is used for calibration calculations.

Instead of specifying a value one may enter the string L(OOKUP) for
tempColdLoad and/or tempAmbientLoad.  This is shown in the pakoDisplay
by the letter "L" instead of a number.

In this case, during the execution of the observations, the NCS will
use measured values for the corresponding load temperature(s).

A * can be substituted for tempColdLoad, which means to leave the
value for tempColdLoad unchanged from the previous RECEIVER command.

NOTE: FOR HERA 
measured values are always used during the execution of the
observations. This is the same logic as in older versions of paKo/NCS.

.fi

.ti -4
2 /VERTICAL
.so nroffSoOptions/optionVertical.nroff

.ti -4
2 /WIDTH
.\" .so nroffSoOptions/optionWidth.nroff

.nf
/WIDTH width

Select receiver setup for WIDE or NARROW bandwidth mode.

Character :: width             ! width. choices: WIDE|NARROW

NOTE: Option /WIDTH NARROW changes the (local oscillator) setup of
receivers HERA1 HERA2 in such a way that a line in the center of the
receiver bandwidth appears in the center of the bands of VESPA.

Spectrometers with 1GHz or more bandwidth normally require /WIDTH WIDE.

 --> NOTE: THIS OPTION DOES NOT APPLY TO EMIR!

.fi

.ti -4
2 BOLOMETER
.nf
.so nroffSoSubtopics/receiverBolometer.nroff

.ti -4
2 EXAMPLES
.nf
.so nroffSoExamples/pakoExamplesReceiver.nroff

.\"  >>> ************************************************************* EMIR ***************


.ti -4
1 SAVE 

.nf

SAVE [commandToSave]
SAVE ALL [CORRECTIONS]
SAVE SET [CORRECTIONS]
SAVE SWITCHING

Save parameters and options of a command in the form of a valid .pako
script.

Character :: commandToSave     ! command to save

If commandToSave is not specified, the last selected observing mode is
saved.

SAVE ALL saves (nearly) all current setup parameters, as well as the
current switching and observing modes, to file all.pako, or to a
different file specified with /FILE.

NOTE: SAVE ALL and SAVE SET save the pointing and focus corrections
only if they are used in the form 
SAVE ALL C[ORRECTIONS]
SAVE SET C[ORRECTIONS]

(Normally SAVE ALL and SAVE SET are meant to generate paKo scripts
that can be used to re-produce the setup at a later time, when one
probably wants to use different corrections. On the other hand the
idiomatic usage: SAVE ALL C /FILE LAST allows to save "really
everything" in order to recover it with @ LAST)

SAVE SWITCHING saves the currently selected switching mode (total
power, beam, frequency, wobbler), to file switching.pako, or to a
different file specified with /FILE.

NOTE: the parameters of "unused" (unselected) hardware, switching
modes, and observing modes are never saved.

.\" .so nroffSoOptions/optionAppend.nroff
.\" .so nroffSoOptions/optionFile.nroff
.\" .so nroffSoExamples/pakoExamplesSave.nroff

.ti -4
2 /APPEND
.so nroffSoOptions/optionAppend.nroff
.ti -4
2 /FILE
.so nroffSoOptions/optionFile.nroff
.ti -4
2 EXAMPLES
.nf
.so nroffSoExamples/pakoExamplesSave.nroff



.\"  <<< ************************************************************* EMIR ***************


.ti -4
1 SET

.nf

SET keyword   value [value* ...]

Set values for some general parameters.

Character               ::  keyword
Character|Integer|Real  ::  value*

Keywords    Type of Value(s)
========    ================

Level       Integer [Integer]  ! minumum value(s) for warning and error messages
Project     Character(len=24)  ! project ID
PI          Character(len=24)  ! PI. Don't use & < >
Observer    Character(len=24)  ! Observer(s). Don't use & < >
Operator    Character(len=24)  ! Telescope operator(s). Don't use & < >

Pointing    Real Real          ! Pointing corrections [arc sec]
Focus       Real               ! Focus correction [mm]
Topology    Character(len=24)  ! Topology for the overlapping azimuth range
2ndRotation Real               ! Rotation angle for Secondary and Wobbler

Comment     Character(len=128) ! Purpose. Don't use & < >
Purpose     Character(len=24)  ! Purpose. Don't use & < >

EMIRcheck   Character          ! "strict"|"relaxed"|"loose" 

doSubmit    Logical            ! turn submission of jobs to queue on or off

.so nroffSoSubtopics/specialCharacters.nroff

In order to include blank characters in a value of type Character, the
complete value should be included in " ", see example: SET Observer
below.

Only a few of these parameters are shown in the Display.  Use command
SHOW to list (nearly) all of them.

.fi

.\" .so nroffSoSubtopics/setDoSubmit.nroff
.\" .so nroffSoSubtopics/setFocus.nroff
.\" .so nroffSoSubtopics/setLevel.nroff
.\" .so nroffSoSubtopics/setPointing.nroff
.\" .so nroffSoSubtopics/set2ndRotation.nroff
.\" .so nroffSoSubtopics/setTopology.nroff
.\" .nf
.\" .so nroffSoExamples/pakoExamplesSet.nroff

.ti -4
2 COMMENT
.so nroffSoSubtopics/setComment.nroff
.ti -4
2 DOSUBMIT
.so nroffSoSubtopics/setDoSubmit.nroff
.ti -4
2 FOCUS
.so nroffSoSubtopics/setFocus.nroff
.ti -4
2 LEVEL
.so nroffSoSubtopics/setLevel.nroff
.ti -4
2 POINTING
.so nroffSoSubtopics/setPointing.nroff
.ti -4
2 PURPOSE
.so nroffSoSubtopics/setPurpose.nroff
.ti -4
2 2NDROTATION
.so nroffSoSubtopics/set2ndRotation.nroff
.ti -4
2 TOPOLOGY
.so nroffSoSubtopics/setTopology.nroff

.ti -4
2 EMIRCHECK

.nf

SET EMIRcheck emirCheck

emirCheck  Character         ! 

Choices for emirCheck are:

"strict"|"relaxed"|"loose"

Make the checking of frequency limits less than strict. This allows
to command frequencies that are completely outside the designed and
tested range of the receiver bands.

The standard and recommended limit checking corresponds to "strict".

THIS MUST BE USED CAREFULLY AND ONLY IN CONSULTATION WITH STAFF
ASTRONOMERS OR ENGINEERS.  

.fi

.ti -4
2 LIMITCHECK

.nf

SET LIMITCHECK limitCheck

limitCheck  Character(len=24) ! 

Choices for limitCheck are:

"strict"|"relaxed"|"loose"

Make the checking of some limits less than strict. 

The standard and recommended limit checking corresponds to "strict".

THIS MUST BE USED CAREFULLY AND ONLY IN CONSULTATION WITH STAFF
ASTRONOMERS OR ENGINEERS.  

NB: this is a protected command (needs privilege).

.fi

.ti -4
2 USERLEVEL

.nf

SET USERLEVEL userLevel

userLevel  Character(len=24) ! 

Choices for userLevel are:

"beginner"|"normal"|"experienced"

Sets level of user's experience with paKo and the NCS.  Some features,
that require special care, are only available if userLevel is set to a
higher level.

.fi

.ti -4
2 EXAMPLES
.nf
.so nroffSoExamples/pakoExamplesSet.nroff
.so nroffSoExamples/pakoExamplesSet2.nroff

.\"  >>> ************************************************************* EMIR ***************


.ti -4
1 SHOW

.nf

  SHOW

  List all parameters that can be set with command SET,
  as well as their current values.

.ti -4
1 SOURCE

.nf
SOURCE sourceName 
       [[systemName epoch] lambda beta
          [referenceFrame velocity     ] ]
SOURCE Body sourceName 
            perihelionEpoch ascendingNode      argumentOfPerihelion 
            inclination     perihelionDistance eccentricity

Select a source from the source catalog or specify source parameters
directly on command the line.

Character*12  :: sourceName            ! don't use: & < > ( ) /
Character     :: systemName            ! 
[C]Real       :: epoch                 ! in units [years]
                                       ! NOTE: epoch should be J2000.0
Coordinate    :: lambda                ! longitude
Coordinate    :: beta                  ! latitude
Character     :: referenceFrame        ! reference system for velocity
Real          :: velocity              ! in units [km/s]

IMPORTANT NOTES:

sourceName is limited to 12 characters.

So far only Equatorial J2000.0 coordinates are well tested.
<<TBD:
Observations of the Sun and near the Sun are not yet supported.
>>

.so nroffSoSubtopics/specialCharacters.nroff
.so nroffSoSubtopics/doppler.nroff

.nf

The second form accepts 6 Real arguments to specify the orbital
elements of a solar system body:
Body                                ! special keyword -- exactly like this!
Real       :: perihelionEpoch       ! Julian Date [d]
Real       :: ascendingNode         ! [deg]
Real       :: argumentOfPerihelion  ! [deg]
Real       :: inclination           ! [deg]
Real       :: perihelionDistance    ! [deg]
Real       :: eccentricity          ! 

If only sourceName is specified, we try to read the other parameters
from the source catalog specified with CATALOG SOURCE fileName. The
sourceName in the command must match a source name in the source
catalog with all characters (no minimum match), but the case is
ignored for the matching. Example: SOURCE w3oh matches W3OH in the
source catalog, but SOURCE w3o does not!

The option: /VELOCITY systemVelocity velocity overrides the values in
the catalog.

Epoch can optionally start with a 1-character code "J" or "B" to
distinguish between "J" and "B" epochs/ equatorial coordinates.  (If
this code letter is not present, "J" is implied!).

The coordinates are specified in astronomical sexagesimal format:
with : as field separator, i.e.:

 hh:mm:ss.ss 
ddd:'':"".""

Examples:
 12:34:56.78 for  12 hours,   34 minutes,     56.78 seconds 
123:45:67.89 for 123 degrees, 45 arc minutes, 67.89 arc seconds

For systemName: equatorial and haDec, the longitude, lambda, is
assumed to be in hours; for all other systems it is assumed to be in
degrees.  Latitude, beta, is always in degrees.

Choices for systemName:
"equatorial"         
"horizontal"           

<<TBD: not yet supported:   >>
<<TBD: "galactic"           >>
<<TBD: "apparentEquatorial" >>
<<TBD: "ecliptic"           >>
<<TBD: "apparentEcliptic"   >>
<<TBD: "haDec "             >>

Choices for referenceFrame:
"LSR"                 
"barycentric"
"heliocentric"

<<TBD: not yet supported:    >>
<<TBD: "3K"                  >>
<<TBD: "galactocentric"      >>
<<TBD: "body"                >>
<<TBD: "geocentric"          >>
<<TBD: "topocentric"         >>
<<TBD: "null"                >>

Planets' names are accepted as a special case, if sourceName is one of:
"Mercury"
"Venus"  
"Mars"   
"Jupiter"
"Saturn" 
"Uranus" 
"Neptune"
"Pluto"  

Satellites' (moons') names are accepted, if sourceName is one of:
"Phobos"    
"Deimos"    
"Io"       
"Europa"    
"Ganymede"  
"Callisto"  
"Mimas"    
"Enceladus" 
"Tethys"    
"Dione"     
"Rhea"      
"Titan"     
"Hyperion"  
"Iapetus"   
"Miranda"  
"Ariel"     
"Umbriel"   
"Titania"   
"Oberon"    
"Gabriel"   
"Moon"     

.\" .so nroffSoOptions/optionCatalog.nroff
.\" .so nroffSoOptions/optionGrep.nroff
.\" .so nroffSoOptions/optionVelocity.nroff
.\" .so nroffSoExamples/pakoExamplesSource.nroff

.ti -4
2 /CATALOG
.so nroffSoOptions/optionCatalog.nroff
.ti -4
2 /GREP
.so nroffSoOptions/optionGrep.nroff
.ti -4
2 /VELOCITY
.so nroffSoOptions/optionVelocity.nroff

.ti -4
2 EXAMPLES
.nf
.so nroffSoExamples/pakoExamplesSource.nroff


.ti -4
1 START 

.nf

START

Start an observation, i.e., translate its specification to XML
and submit it to the observing queue. 

Observing jobs are sent to the observing queue only if the observer has 
SET DOSUBMIT YES
in paKo (see command SET DOSUBMIT) and if the operator has selected
the current project to be the "current observing queue".

IMPORTANT NOTE: to avoid any possible confusion, in each project
account at the 30-m telescope, only 1 running instance of Pako should
have SET DOSUBMIT YES!

Example:

SOURCE ...
OTFMAP ...
START              ! will start and OTF map

.fi


.ti -4
1 SUBSCAN

.nf
SUBSCAN xOffset    yOffset
SUBSCAN xStart     yStart     xEnd       yEnd
SUBSCAN xAmplitude yAmplitude frequencyX frequencyY xCenter yCenter phiX phiY

NB: this is a protected command (needs privilege).

Add to user-defined list of subscans and segments for observing mode "DIY"; 
compare command DIY. The subscan command has the 3 main variants above,
depending on the number of parameters:

2 --> Track subscan with fixed offsets
4 --> Linear OTF segment (subscan)
8 --> Lissajous OTF segment (subscan), IMPORTANT: SEE NOTE BELOW

Option /TYPE allows to enforce that the command is interpreted for one
the 3 different types, independant of the number of parameters.

Option /TUNE allows to specify that a Track subscan will be used to "tune"
an instrument, e.g., NIKA.

Real :: xOffset     ! x offset fixed-position TRACK subscan
Real :: yOffset     ! y offset fixed-position TRACK subscan

Real :: xStart      ! x offset start  of linear OTF  segment
Real :: yStart      ! y offset start  of linear OTF  segment
Real :: xEnd        ! x offset end    of linear OTF  segment
Real :: yEnd        ! y offset end    of linear OTF  segment

Real :: xAmplitude  ! x amplitude              Lissajous OTF segment
Real :: yAmplitude  ! y amplitude              Lissajous OTF segment
Real :: frequencyX  ! frequency    [Hz]  for x Lissajous OTF segment
Real :: frequencyY  ! frequency    [Hz]  for y Lissajous OTF segment
Real :: xCenter     ! x center                 Lissajous OTF segment
Real :: yCenter     ! y center                 Lissajous OTF segment
Real :: phiX        ! phase offset [rad] for x Lissajous OTF segment
Real :: phiY        ! phase offset [rad] for y Lissajous OTF segment

If an asterisk * appears in place of any parameter, the value will
remain unchanged from the last valid SUBSCAN command.

NOTES: pako will make its best effort to "guess" the values for
unspecified parameters based on the values of its internal variables
after the previous valid SUBSCAN command.
Each time a SUBSCAN is accepted without error message, a subscan is
added to the list; even if the command is only "SUBSCAN" by itself!
Be careful that a parameter in the command line can refer to different
variables depending on the type of the segment/subscan, e.g., the 1st
parameter can refer to xOffset, xStart, or xAmplitude.
These features should be used with special care, e.g., to experiment
with the DIYLIST and SUBSCAN commands.
It is recommended to collect all SUBSCAN commands in a paKo script and
explicitly specify all parameters for each subscan!

Before START of a DIY subscanlist, you can enter DIYLIST to review
pako's I-DIY messages listing the subscan currently defined (this
requires SET LEVEL 2 or lower), e.g.:
PAKO> set level 2
PAKO> diy
I-DIY,  segments #: 1 to 3
I-DIY,  1 track on at -400.0 -300.0 arcsec projection 10.0 s
I-DIY,  2 onTheFly -300.0 -200.0 to 330.0 220.0 arcsec projection 66.0 s
I-DIY,  3 track on at 440.0 330.0 arcsec projection 10.0 s


IMPORTANT: LISSAJOUS OTF

During a Lissajous OTF segment, the position offsets 
x and y as a function of time t are:

x = xCenter + xAmplitude * SIN(2 Pi frequencyX t + phiX)
y = yCenter + yAmplitude * SIN(2 Pi frequencyY t + phiY)

SIN is the usual sine function, Pi is the number Pi.

xAmplitude yAmplitude xCenter yCenter are in angle units ([arc sec])
frequencyX frequencyY                 are in [Hz]
phiX       phiY                       are in [rad]

Note that the possible frequencies are very low, 
typically 0.01 to 0.15 Hz.

At the start of a Lissajous subscan, paKo will insert a "ramp" along a
straight line, i.e., a linear OTF segment, increasing the count of
segments by 2.  This ramp up starts with speed 0 relative to the
source and joins smoothly with the start position and velocity of the
Lissajous segment.  The purpose is to avoid a sudden aceleration at
the start of the Lissajous segment.  Command DIY lists this inserted
OTF segment as well as the Lisssajous segment.  The inserted ramp up
segment and the Lissajous segment become part of the same subscan.

Lissajous curves with large amplitudes or frequencies can reach the
antenna's speed and acceleration limits for tracking.  Lissajous
curves can be executed only for elevations less than a maximum, which
depends on the Lissajous parameters.  For information, this elevation
condition is shown by pako. Even below the limits, during very fast
Lissajous curves the tracking errors will be higher, several arc sec,
than during most other observations.

DO NOT TRY TO OBSERVE LISSAJOUS ABOVE THIS MAXIMUM ELEVATION.

.fi

.ti -4
2 /CROFLAG
.so nroffSoOptions/optionCROflag.nroff

.ti -4
2 /RAMP
.so nroffSoOptions/optionRamp.nroff

.ti -4
2 /SYSTEM
.so nroffSoOptions/optionSystemSubscan.nroff

.ti -4
2 /TOTF
.so nroffSoOptions/optionTotf.nroff
NOTE: this applies to linear and Lissajous OTF subscan segments

.ti -4
2 /TSUBSCAN
.so nroffSoOptions/optionTsubscan.nroff
NOTE: this applies to Track subscans

.ti -4
2 /TUNE
.so nroffSoOptions/optionTune.nroff

NOTE: this applies to Track subscans. If a valid specification of a
TRACK subscan is entered without the option /TUNE, "no" is implied.

.ti -4
2 /TYPE
.so nroffSoOptions/optionSubscanType.nroff

.ti -4
1 SWBEAM

.nf

SWBEAM (no parameters)

Select beam switching, i.e., switching between 2 positions on the sky
using the rotating beam-switch chopper wheel. This mode is usually
only used for POINTING and FOCUS with the heterodyne receivers.

.ti -4
1 SWFREQUENCY

.nf

SWFREQUENCY fOffset1 [fOffset2] 

Select and set up frequency switching (FS).

Real      :: fOffset1          ! 1st frequency offset [MHz]
Real      :: fOffset2          ! 2nd frequency offset [MHz]

fOffset2 should be set to be = -fOffset1 (symmetric FS).
This is done by default, if only fOffset1 is specified.
(Note that then ABS(fOffset1) = FS amplitude = 1/2 FS throw).
FS  with fOffset2 not equal -fOffset1 is experimental.

/RECEIVER allows to set fOffset1 and fOffset2 for each connected
receiver differently.

Parameters of other options are always the same for all receivers.

Limits for fOffset1 and fOffset2 are:

  -9 to  +9   with the 3 mm receivers /bands
 -18 to +18   with the 2 mm receivers /bands
 -27 to +27   with the 1 mm receivers /bands


IMPORTANT NOTES about use of Frequency Switching (FS)

Frequency Switching (FS) can be very powerful and efficient for some
projects, e. g., mapping of narrow spectral lines in cold dark clouds
outside the plane of the Milky Way.  However, before deciding to use
frequency switching one should consider some potential drawbacks:

The target lines should be narrow enough so that line signals from the
2 phases of the switching cycle are well separated.  

The spectral baseline will generally be less flat than in other
switching modes.

Some spectral lines are also emitted in the earth's mesosphere, e.g.,
the mesopheric lines from (12)CO are rather strong, typically several
[K], and they will be seen in FS spectra taken toward astronomical
sources with a low Doppler shift. The mesospheric lines will appear at
a frequency and velocity that correspond to the rest frame of the
athmosphere, i. e., to good approximation, the observatory.  If,
e. g., you observe using Doppler corrections for the LSR scale, the
mesospheric lines will appear in the spectra at -1 * the velocity of
the Local Standard of Rest relative to the observatory.

Care must be taken that mesospheric lines are not confused with the
lines from the astronomical source, which will appear in the spectrum
at the velocity of the source relative to the LSR.  The ASTRO software
can calculate the velocity of the LSR relative to the observatory for
any source and time.  During observations, this velocity is also
displayed on one of the NCS monitoring windows.

When observing sources near the plane of the Milky Way, line emission
from clouds at other velocities than the target source, e. g., other
spiral arms, can cause confusion.

In case of any doubt, there is a special report on FS that gives more
advice!

.\" .so nroffSoOptions/optionDefaults.nroff
.\" .so nroffSoOptions/optionReceiver.nroff
.\" .so nroffSoOptions/optionTphase.nroff
.\" .so nroffSoExamples/pakoExamplesSwFrequency.nroff

.ti -4
2 /DEFAULTS
.so nroffSoOptions/optionDefaults.nroff
.ti -4
2 /RECEIVER
.so nroffSoOptions/optionReceiver.nroff
.ti -4
2 /TPHASE
.so nroffSoOptions/optionTphase.nroff
.ti -4

2 EXAMPLES
.nf
.so nroffSoExamples/pakoExamplesSwf.nroff


.ti -4
1 SWTOTAL 

.nf

SWTOTAL  (no parameters)             

Select total power, i.e., neither beam, frequency, nor wobbler
switching. Typically used with OTFMAP with off-source references or
ONOFF "position switching".

.\" .so nroffSoOptions/optionDefaults.nroff
.\" .so nroffSoOptions/optionTphase.nroff

.fi

.ti -4
2 /DEFAULTS
.so nroffSoOptions/optionDefaults.nroff
.ti -4
2 /TPHASE
.so nroffSoOptions/optionTphase.nroff

.ti -4
1 SWWOBBLER

.nf

SWWOBBLER wOffset1 [wOffset2]

Select and set up wobbler switching using the wobbling secondary
mirror to switch between 2 positions on the sky.  This is typically
used with the observing modes POINTING, FOCUS, ONOFF, or --with the
bolometer-- OTFMAP. 

Real      :: wOffset1          ! 1st wobbler offset (1/2 "throw")
Real      :: wOffset2          ! 2nd wobbler offset = -wOffset1

IMPORTANT NOTE: Observers must inform the operator if they want to use
this feature.

There is a relation between the maximum allowed Wobbler throw and the
minimum time per phase: for large throws the switching must be slow,
i.e., time per phase must be large.  For /timePhase 1 [sec] or longer,
any wobbler throw is allowed up to the maximum of 240 ["].

Posssible combinations are, e. g.:

wOffset1   throw  timePhase 
   -22"      44"    0.25 sec
   -22"      44"    1.0  sec
  -120"     240"    1.0  sec
  -120"     240"    2.0  sec

Note that for OTFMAPs with Wobbler switching, special restoration
algorithms are needed to recover an image of the source brightness
distribution. These are available, e. g., in the MOPSIC software.

.so nroffSoSubtopics/swWobblerOnOff.nroff

.\" .so nroffSoOptions/optionDefaults.nroff
.\" .so nroffSoOptions/optionTphase.nroff

.ti -4
2 /DEFAULTS
.so nroffSoOptions/optionDefaults.nroff
.ti -4
2 /TPHASE
.so nroffSoOptions/optionTphase.nroff

.ti -4
1 TIP

.nf

TIP [azimuth]

Specify an antenna tipping (a.k.a., "skydip").

Real      :: azimuth           ! azimuth of tip

If azimuth is not specified, the current azimuth of the telescope is
used.

NOTE: 
TIP is always and automatically done with switching mode "total power"
and for bolometer observations the time per phase is fixed at 0.5 [sec]

.\" .so nroffSoOptions/optionDefaults.nroff
.\" .so nroffSoOptions/optionAirmass.nroff
.\" .so nroffSoOptions/optionSlew.nroff
.\" .so nroffSoOptions/optionTsubscan.nroff

.ti -4
2 /DEFAULTS
.so nroffSoOptions/optionDefaults.nroff
.ti -4
2 /AIRMASS
.so nroffSoOptions/optionAirmass.nroff
.\" .ti -4
.\" 2 /SLEW
.\" .so nroffSoOptions/optionSlew.nroff
.ti -4
2 /TSUBSCAN
.so nroffSoOptions/optionTsubscan.nroff

.fi

.ti -4
1 TRACK

.nf

TRACK xOffset yOffset

specify tracking of a single position

Real      :: xOffset           ! x-offset of "on-source" position
Real      :: yOffset           ! y-offset of "on-source" position

NOTES:
TRACK is normally used for observations with frequency switching
(SWFREQUENCY); also for some special observations, e.g., of pulsars.
There is a built-in limit to the time per subscan, currently (2006-07)
it is 3600 seconds (1 hour).  If for special purposes one needs to
track a source for a longer time, this can easily be done by using
several subscans.

.\" .so nroffSoOptions/optionDefaults.nroff
.\" .so nroffSoOptions/optionSystem.nroff
.\" .so nroffSoOptions/optionNsubscans.nroff
.\" .so nroffSoOptions/optionTsubscan.nroff
.\" .so nroffSoExamples/pakoExamplesTrack.nroff

.ti -4
2 /DEFAULTS
.so nroffSoOptions/optionDefaults.nroff
.ti -4
2 /SYSTEM
.so nroffSoOptions/optionSystem.nroff
.ti -4
2 /NSUBSCANS
.so nroffSoOptions/optionNsubscans.nroff
.ti -4
2 /TSUBSCAN
.so nroffSoOptions/optionTsubscan.nroff

.ti -4
2 EXAMPLES
.nf
.so nroffSoExamples/pakoExamplesTrack.nroff


.ti -4
1 VLBI

.nf

VLBI

Track a single position for VLBI.

This observing mode must not be used for other (non-VLBI) observations.

Some special behaviours are asscociated with the observing mode VLBI:
 - The scan has only one subscan on the (fixed) source position.
 - This subscan will be executed for up to 1 hour.
   In practice it is ended, when the START command is executed for the
   next observation, e.g., when a new VLBI scan, or a POINTING or FOCUS
   is started.
 - Normally, the VLBI field system sends the commands
   SOURCE ...
   VLBI
   START
   directly to paKo, which is running in a special terminal window.  The
   field system sends these commands for the next scan (immediately)
   after the VLBI data recording for the current VLBI target source 
   (for the currant scan) is finished.

.ti -4
1 OPTIONS

.nf

SUMMARY OF OPTIONS FOR PAKO\ COMMANDS: 

(For help on commands say HELP PAKO\ )

For details say, e.g.,  HELP OPTIONS /CROLOOP
                   or:  HELP OP      /CRO

To see if a command has a particular option, see the end of the
HELP for this command.

.ti -4
2 /AIRMASS
.so nroffSoOptions/optionAirmass.nroff
.ti -4
2 /AMBIENT
.so nroffSoOptions/optionAmbient.nroff
.ti -4
2 /APPEND
.so nroffSoOptions/optionAppend.nroff
.\" .ti -4
.\" 2 /BALANCE
.\" .so nroffSoOptions/optionBalance.nroff
.\" .ti -4
.\" 2 /CALIBRATE
.\" .so nroffSoOptions/optionCalibrate.nroff
.ti -4
2 /CLEAR
.so nroffSoOptions/optionClear.nroff
.ti -4
2 /COLD
.so nroffSoOptions/optionCold.nroff
.ti -4
2 /CONNECT
.so nroffSoOptions/optionConnect.nroff
.ti -4
2 /CROLOOP
.so nroffSoOptions/optionCROloop.nroff
.ti -4
2 /DEFAULTS
.so nroffSoOptions/optionDefaults.nroff
.ti -4
2 /DEROTATOR
.so nroffSoOptions/optionDerotator.nroff
.ti -4
2 /DISCONNECT
.so nroffSoOptions/optionDisconnect.nroff
.ti -4
2 /DOPPLER
.so nroffSoOptions/optionDoppler.nroff
.ti -4
2 /DOUBLEBEAM
.so nroffSoOptions/optionDoubleBeam.nroff
.ti -4
2 /EFFICIENCY
.so nroffSoOptions/optionEfficiency.nroff
.\" .ti -4
.\" 2 /FEBE
.\" .so nroffSoOptions/optionFeBe.nroff
.ti -4
2 /FILE
.so nroffSoOptions/optionFile.nroff
.ti -4
2 /FINE
.so nroffSoOptions/optionFine.nroff
.ti -4
2 /FOCUS
.so nroffSoOptions/optionFocus.nroff
.ti -4
2 /GAINIMAGE
.so nroffSoOptions/optionGainImage.nroff
.ti -4
2 /GREP
.so nroffSoOptions/optionGrep.nroff
.ti -4
2 /GRID
.so nroffSoOptions/optionGrid.nroff
.ti -4
2 /HORIZONTAL
.so nroffSoOptions/optionHorizontal.nroff
.ti -4
2 /MODE
.so nroffSoOptions/optionMode.nroff
.\" .ti -4
.\" 2 /MORE
.\" .so nroffSoOptions/optionMore.nroff
.ti -4
2 /NOTF
.so nroffSoOptions/optionNotf.nroff
.ti -4
2 /NSUBSCANS
.so nroffSoOptions/optionNsubscans.nroff
.ti -4
2 /PERCENTAGE
.so nroffSoOptions/optionPercentage.nroff
.ti -4
2 /POINTING
.so nroffSoOptions/optionPointing.nroff
.ti -4
2 /RECEIVER
.so nroffSoOptions/optionReceiver.nroff
.ti -4
2 /REFERENCE
.so nroffSoOptions/optionReference.nroff
.\" .ti -4
.\" 2 /RESUME
.\" .so nroffSoOptions/optionResume.nroff
.ti -4
2 /SCALE
.so nroffSoOptions/optionScale.nroff
.ti -4
2 /SKY
.so nroffSoOptions/optionSky.nroff
.\" .ti -4
.\" 2 /SLEW
.\" .so nroffSoOptions/optionSlew.nroff
.ti -4
2 /SPEED
.so nroffSoOptions/optionSpeed.nroff
.ti -4
2 /STEP
.so nroffSoOptions/optionStep.nroff
.ti -4
2 /SWWOBBLER
.so nroffSoOptions/optionSwWobbler.nroff
.ti -4
2 /SYMMETRIC
.so nroffSoOptions/optionSymmetric.nroff
.ti -4
2 /SYSTEM
.so nroffSoOptions/optionSystem.nroff
.ti -4
2 /TCALIBRATE
.so nroffSoOptions/optionTcalibrate.nroff
.ti -4
2 /TOTF
.so nroffSoOptions/optionTotf.nroff
.ti -4
2 /TPHASE
.so nroffSoOptions/optionTphase.nroff
.\" .ti -4
.\" 2 /TRECORD
.\" .so nroffSoOptions/optionTrecord.nroff
.ti -4
2 /TREFERENCE
.so nroffSoOptions/optionTreference.nroff
.ti -4
2 /TSUBSCAN
.so nroffSoOptions/optionTsubscan.nroff
.ti -4
2 /TEMPLOAD
.so nroffSoOptions/optionTempLoad.nroff
.\" .ti -4
.\" 2 /UPDATE
.\" .so nroffSoOptions/optionUpdate.nroff
.ti -4
2 /TUNE
.so nroffSoOptions/optionTuneOffsets.nroff
.nf
.ti -4
2 /TTUNE
.so nroffSoOptions/optionTtune.nroff
.ti -4
2 /VELOCITY
.so nroffSoOptions/optionVelocity.nroff
.ti -4
2 /VERTICAL
.so nroffSoOptions/optionVertical.nroff
.ti -4
2 /WIDTH
.so nroffSoOptions/optionWidth.nroff
.ti -4
2 /ZIGZAG
.so nroffSoOptions/optionZigzag.nroff

.ti -4
1 ENDOFHELP

