; DTSIM
;---------------------------------------------------------------
;! Generate fake UV data
;# Task Calibration VLBI
;-----------------------------------------------------------------------
;;  Copyright (C) 1995-1998, 2012, 2018
;;  Associated Universities, Inc. Washington DC, USA.
;;
;;  This program is free software; you can redistribute it and/or
;;  modify it under the terms of the GNU General Public License as
;;  published by the Free Software Foundation; either version 2 of
;;  the License, or (at your option) any later version.
;;
;;  This program is distributed in the hope that it will be useful,
;;  but WITHOUT ANY WARRANTY; without even the implied warranty of
;;  MERCHDTSIMILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;;  GNU General Public License for more details.
;;
;;  You should have received a copy of the GNU General Public
;;  License along with this program; if not, write to the Free
;;  Software Foundation, Inc., 675 Massachusetts Ave, Cambridge,
;;  MA 02139, USA.
;;
;;  Correspondence concerning AIPS should be addressed as follows:
;;         Internet email: aipsmail@nrao.edu.
;;         Postal address: AIPS Project Office
;;                         National Radio Astronomy Observatory
;;                         520 Edgemont Road
;;                         Charlottesville, VA 22903-2475 USA
;-----------------------------------------------------------------------
;---------------------------------------------------------------
DTSIM     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
DTSIM     Task to generate fake UV data
OUTNAME                            Output UV file name (name)
OUTCLASS                           Output UV file name (class)
OUTSEQ            0.0     9999.0   Output UV file name (seq. #)
OUTDISK           0.0        9.0   Output UV file disk unit #
INFILE                             Parameter file name.
PRTLEV                             Print level (0=>none;
                                   1=> echo text file)
DPARM             0.0              Default year, month, day
                                   (4) > 0 leave parallactic
                                       angle in the data
FPARM             0.0              default GAIN(ifnum) in Jy/K
VPARM             0.0              default TSYS(ifnum) in K
----------------------------------------------------------------
DTSIM
Task:  This task will generate fake uv-data for the primary
       purpose of testing AIPS tasks. It is used in conjunction
       with task DTCHK, which measures the degree of compliance
       with the expected test result.

Adverbs:
  OUTNAME....Output UV file name (name).      Standard defaults.
  OUTCLASS...Output UV file name (class).     Standard defaults.
  OUTSEQ.....Output UV file name (seq. #).    0 => highest.
  OUTDISK....Disk drive # of output UV file.  0 => any.
  INFILE.....External text file containing data simulation
             parameters in KEYIN format.
  PRTLEV.....Print level (>0: echo external parameter file
             on input.
  DPARM......Default values for (1) year, (2) month, (3) day used in
             the schedual, flag, and bandpass sections.
             (4) The visibilities as computed take into account the
             difference and sum of the parallactic angles.  This means
             the RR and LL for a point source at the origin will have
             opposite phases due to the difference in parallactic
             angle for the two antennas.  By default, this is taken
             out.  > 0 => leave it in (and let CLCOR deal with it).
  FPARM......Default values for the GAIN (Jy/K) in the CAL_ERR
             section, one value per IF.  IFS > 30 use FPARM(30).
  VPARM......Default values for the TSYS (K) in the CAL_ERR
             section, one value per IF.  IFS > 30 use VPARM(30).
-----------------------------------------------------------------
DTSIM:  Task to generate fake uv-data
Documentor: A. Kemball, Eric W. Greisen
Related Programs: DTCHK

                            OVERVIEW

 This task will generate fake uv-data for the primary purpose of
testing AIPS tasks. It is used in conjunction with task DTCHK,
which measures the degree of compliance with the expected test
result. The input parameters defining the simulated dataset are
provided in the form of an external text file in KEYIN format.
This file is used by DTCHK in checking test compliance. DTSIM
can be used alone, however, to generate datasets containing
simulated data for other purposes.

                         PARAMETER FILE

 The format of the parameter file consists of several different
groups, which are defined below:

 ANTENNA TABLES
 ==============
   The attached antenna tables are defined in the following format:

 AN_TABLE VER = n /       (* defines AN table version number *)
   KEY                    (* required to use the next 3, do once
                             before any STATION *)
   CAL_ERR                (* copy feed cal. err. to the AN table *)
   POLTYPE = 'xxxx'       (* set polzn. POLTYPE keyword; known are
                             'APPROX', 'ORI-ELP', 'X-Y LIN', 'VLBI' *)
   ARRNAM = 'array' /     (* defines AN keyword ARRNAM; eg 'VLBA' *)

   STATION = 'name'       (* station name (up to 8 characters) *)
   LONG = hh:mm:ss        (* station longitude and latitude *)
   LAT = dd:mm:ss
   MNT = 'AZEL' or 'HADC' (* az-el is default, equatorial or
         or 'ORB' or         orbiting or Nasmyth right or left *)
         'NASR', NASL'
   NO = n                 (* antenna number in AN table *)
   ELEV = x               (* station elevation in (m) *)
   ORBPARM = 6*x /        (* orbital parameters (six) *)
   CARTPOS= X, Y, Z       (* XYZ earth-centered coordinates in a
                             right-handed system with Z towards
                             North, X through Greenwich, and Y
                             through Europe, ***THIS MAY BE SPECIFIED
                             IN PLACE OF LONG, LAT, ELEV*** *)

   Multiple STATION records can be defined for any given AN table.

   END /                  (* end of station records *)
 STATION = 'SPEC_NAM' /   (* alternate format for specifying station
                             information, SPEC_NAM is chosen from the
                             following list:
                             VLBA_xx  : xx = BR, FD, HN, KP, LA, MK,
                                             NL, OV, PT, SC
                                             GB, AR, EB, Y, Y1
                             ALL_VLBA : all 10 VLBA antennas
                             ALL_HSA  : all 10 VLBA, GB, AR, EB, Y
                             VLA_Yx    : x = A, B, C, D arrays
                             VLA_na    : n = 1, 2, 3, 4, 5, 6, 7, 8,
                                             9, 10, 12, 14, 16, 18,
                                             20, 24, 28, 32, 36, 40,
                                             48, 56, 64, 72 pad pos.
                                         a = N, W, E arms
                             *** NOTE that specifying VLA_YA and
                                 VLA_YB will specify some common
                                 antennas -this could cause problems-
                                 it would be advisable to specify the
                                 antennas individually in this case.
                             Other alternate formats can be added by
                             request *)


 SOURCE TABLE
 ============
   The source table is defined as follows:

 SU_TABLE /
   SU_ID = n              (* source ID *)
   NAME = 'name'          (* source name (16 characters) *)
   REST_FQ = Nif * x      (* rest freq. for each IF in MHz *)
   LSR_VEL = Nif * x      (* LSR vel. for each IF in km/s *)
   RAEPO = hh:mm:ss       (* RA at epoch *)
   DECEPO = dd:mm:ss      (* DEC at epoch *)
   EPOCH = nnnn /         (* epoch, e.g. 2000 is default *)

   Multiple source records can be specified for the SU table.

   END /                  (* end of source records *)

 FREQUENCY TABLE
 ===============
   The frequency table is defined as follows:

 FQ_TABLE /
   FQID = n               (* frequency ID *)
   FREQ = Nif * x         (* freq. for each IF in MHz *)
   TOTBW = Nif * x        (* bandwidth for each IF in MHz *)
   CHANBW = Nif * x       (* channel BW for each IF in MHz *)
   SIDE = Nif * {0|1} /   (* sideband (0=LSB; 1=USB) per IF
                             1 is default *)

   Multiple FQ ID records can be specified for the FQ table.

   END /                  (* end of FQ ID records *)

 CATALOG HEADER
 ==============
   The catalog header, which defines the overall structure of the
 AIPS uv-data file, is specified as follows:

 CAT_HDR
   REF_FREQ = x           (* reference freq. in MHz *)
   REST_FQ = x            (* rest frequency in MHz *)
   NO_IF = n              (* number of AIPS IF channels *)
   NO_CHAN = n            (* number of freq. channels per IF *)
   STOKES = 4*{'RR'|'LL'|'RL'|'LR'}
                          (* Stokes parameters defined in the file *)
   REF_DATE = 'dd/mm/yy'  (* reference date *)
      or  'yyyymmdd'
   COMPRESS               (* if present, then compress output data;
                             this option not yet implemented *)
   /                      (* end of catalog header parameters *)

 CALIBRATION ERRORS
 ==================
   Calibration errors for each antenna, IF=n and polarization
   p = {R,L} are  specified as follows:

    [A constant rather than time variable value may be had for cheb
     functions by setting the amplitude to 0 and the offset to the
     desired constant number.  A Tsys is needed even if constant.]

 CAL_ERR  LINPOL /        (* LINPOL selects linearized polzn.
                             errors - otherwise 2nd order is used *)
   STATION = 'name'       (* REQUIRED define which antenna *)
   FQID = n               (* define FQID for this calibration error
                             record - default 1 *)

   BP_np = {1, bwth, cheb, phs, norm, v_1, v_2, v_3, v_4 }
           (* bandpass error (type 1), where
              bwth = Butterworth order for ampl. response
              cheb = Chebyshev order for phase response
              phs  = Phase response ampl. (deg.)
              norm = {0 => no normalization; 1 => normalize}
              v_j  = variability parameters (set to zero
                          for no variability)
           or, *)
           {2, frac, time}
           (* bandpass error (type 2), where
              phs  = phase/ampl. slope across band (0..1)
              time = phase/ampl. slope in time (0..1) *)

   DELA_np = 1, cheb, range, delay, offset
             (* delay errors, where
                cheb   = Chebyshev order for delay error poly.
                range  = Period in days for delay poly. from UT 0
                delay  = Delay error poly. ampl. (ns)
                offset = Polynomial offset (ns) *)

   PHAS_np = 1, cheb, range, phs, offset
             (* phase errors where,
                cheb   = Chebyshev order of phase error poly.
                range  = Period in days for phase poly. from UT 0
                phs    = Phase error poly. ampl. (deg)
                offset = Polynomial offset (deg) *)

   FEED_np = 1, ampl, phas
             (* polarization D-terms, where:
                ampl = D-term amplitude
                phas = D-term phase (deg.) *)

   GAIN_np = 1, gval
             (* gain, where
                gval = point source sensitivity (Jy/K)
                may be defaulted with FPARM(n) > 0 *)

   TSYS_np = 1, cheb, range, tval, offset

             (* Tsys, where
                cheb   = Chebyshev order of Tsys poly.
                range  = Period in days of Tsys poly from UT 0
                tval   = Amplitude of Tsys polynomial
                offset = Polynomial offset
                default with VPARM(n) > 0 is
                TSYS_n* = 1, 2, 1, 0, VPARM(n)  *)

   GERR_np = 1, cheb, range, amperr, offset
             (* multiplicative gain error, where
                cheb   = Chebyshev order of gain error poly.
                range  = Period in days for err. poly. from UT 0
                amperr = Gain error poly. ampl.
                offset = Gain error offset *)

   /         (* end of calibration record for this STATION
                and FQID *)

   Multiple records can be defined for each STATION and FQID
   combination.

  END /      (* end of the calibration error group *)

 SOURCE MODEL
 ============
   The source model data are specified as follows:

 SU_MODEL /
   SOURCE = 'name'            (* source name REQUIRED *)
   TYPE = {1, ra, dec, I, Q, U, V}
          (* point source, where
           ra  = RA offset (asec)
           dec = DEC offset (asec)
           I, Q, U, V = flux density (Jy) *)

          {2, ra, dec, pa, maj, min, I, Q, U, V}
          (* Gaussian component, where
           ra  = RA offset (asec)
           dec = DEC offset (asec)
           pa  = position angle (deg)
           maj = major axis (asec)
           min = minor axis (asec)
           I, Q, U, V = flux density (Jy) *)
    /      (* end of this source model *)

    Multiple source models can be defined.

    END /  (* end of the source model data *)

 SCHEDULE RECORDS
 ================
   The fake data are specified via schedule records not unlike those
 accepted by SCHED. The format is given below:

 SCHEDULE /
   DAY = n MONTH = n YEAR = nnnn    (* day, month and year REQUIRED
                                       may be init with DPARM, each
                                       new record defaults to those
                                       of the previous *)
   START = hh:mm:ss                 (* start of scan *)
   STOP = hh:mm:ss                  (* end of scan *)
   SOURCE = 'name'                  (* source name *)
   SUBA = n                         (* subarray number 1=default *)
   FQID = n                         (* frequency ID 1=default *)
   SELECT = +stat or -stat          (* select (+) or de-select all
                                       baselines to a given station *)
   TINT = x /                       (* integration time (sec)
                                       1.0 = default *)

   Multiple schedule records can be defined.

   END /                            (* end of schedule *)

FLAG RECORDS
============
   Pieces of the fake data may be marked as flagged or even omitted by
entering flagging records as

FLAG /
   DAY = n MONTH = n YEAR = nnnn    (* day, month and year REQUIRED
                                       may be init with DPARM, each
                                       new record defaults to those
                                       of the previous *)
   START = hh:mm:ss       (* start of flag interval *)
   STOP = hh:mm:ss        (* end of flag interval *)
   SOURCE = 'name'        (* source name or 'ALL' *)
   SUBA = n               (* subarray number, default = 0 => all *)
   FQID = n               (* frequency ID, default = 0 => all *)
   BIF = n                (* start IF, default 0 => 1 *)
   EIF = n                (* end IF, default 0 => max *)
   BCHAN = n              (* start channel, default 0 => 1 *)
   ECHAN = n              (* end channel, default 0 => max *)
   ANT_1 = 'antenna_1'    (* antenna 1 name or 'ALL';REQUIRED *)
   ANT_2 = 'antenna_1'    (* antenna 2 name or 'ALL'; REQUIRED *)
   PFLAG = 'xxxx' /       (* polarization selection, x = 0 (no) or 1
                            (yes), e.g., '1011' flags RR, RL, LR *)

   Multiple flag records can be defined.

   END /                  (* end of flag *)

BP_TABLE RECORDS
================
     If the CAL_ERR BP option has been used, then one can construct a
bandpass table to match.

BP_TABLE /

   KEY                    (* required to use the next 3, do once
                             before any STATION *)
   NANT = N               (* Number of antennas in the BP table *)
   BPTYPE = 'x'           (* 'CHEBSHEV' for polynomial bandpass,
                             ' ' for normal bandpass *)
   NUMSHF = n /           (* n=1 cross-power, n=2 total-power,
                             else unknown origin of BP solutions *)

   STATION = 'name'       (* station name (up to 8 characters)
                             REQUIRED *)
   DAY = n MONTH = n YEAR = nnnn    (* day, month and year REQUIRED
                                       may be init with DPARM, each
                                       new record defaults to those
                                       of the previous *)
   SUBA = n               (* subarray number, default = 0 => all   *)
   FQID = n               (* frequency ID, default = 0 => all   *)
   START = hh:mm:ss       (* start of scan *)
   STOP = hh:mm:ss        (* end of scan *)
   TINT = t               (* integration time of each entry, seconds *)
   INTERV = Dt            (* spacing of BP solutions in time, minutes
                             *)
   CAL_ERR                (* Use CAL_ERR values, else null BP (1,0) * )
   AC                     (* Auto-correlation data produced the
                             bandpass solution *)
   XC                     (* Cross-correlation data produced the
                             bandpass solution (default) *)
   FLAGPOL = Nif * i      (* Polarization number to be flagged 1 or 2,
                             <= Nif values *)
   FLAGIF = Nif * j       (* Corresponding IF number to be flagged,
                             <= Nif values *)
   FLAGCHAN = Nif * c1,c2 (* Corresponding range of spectral channels
                             to be flagged, <= Nif pairs of values *)
   /

   Multiple BP records can be defined.

   END /                  (* end of BP table *)





EXAMPLE INPUT FILE
==================
   An example input file is given below:

Adverbs:

DPARM      2010          11        Default year, month, day
             11        *rest 0
FPARM         5           5        default GAIN(ifnum) in Jy/K
           *rest 0
VPARM        45          55        default TSYS(ifnum) in K
           *rest 0

And the INFILE:
!----------------------------------------------------------------------
!
! EVLA example
!
AN_TABLE VER=1 /
   KEY
      ARRNAM = 'EVLA' /
   STATION = 'VLA_YC' /
END /
!
! FQ table data
!
FQ_TABLE /
   FQID = 1
   FREQ   = 4988.0, 5244.0
   TOTBW  = 128., 128.0
   CHANBW = 8.0, 8.0 /
END /
!
! SU table data
!
SU_TABLE /
   SU_ID = 1
   NAME = '3C286'
   RAEPO = 13:31:08.29
   DECEPO = 30:30:32.96 /
   SU_ID = 2
   NAME = 'Target'
   RAEPO = 13:18:08.29
   DECEPO = 55:30:32.96 /
END /
!
! Catalog header
!
CAT_HDR /
   REF_FREQ = 4988.0
   NO_IF = 2
   NO_CHAN = 16
   STOKES = 'RR', 'LL', 'RL', 'LR'
   REF_DATE = '20101111'/
!
! Calibration errors: N arm less sensitive IF 1
!
CAL_ERR /
   STATION = 'VLA_2N'    FQID = 1
      GAIN_1R = 1, 7
      GAIN_1L = 1, 7 /
   STATION = 'VLA_4N'    FQID = 1
      GAIN_1R = 1, 7
      GAIN_1L = 1, 7 /
   STATION = 'VLA_6N'    FQID = 1
      GAIN_1R = 1, 7
      GAIN_1L = 1, 7 /
   STATION = 'VLA_8N'    FQID = 1
      GAIN_1R = 1, 7
      GAIN_1L = 1, 7 /
   STATION = 'VLA_10N'    FQID = 1
      GAIN_1R = 1, 7
      GAIN_1L = 1, 7 /
   STATION = 'VLA_12N'    FQID = 1
      GAIN_1R = 1, 7
      GAIN_1L = 1, 7 /
   STATION = 'VLA_14N'    FQID = 1
      GAIN_1R = 1, 7
      GAIN_1L = 1, 7 /
   STATION = 'VLA_16N'    FQID = 1
      GAIN_1R = 1, 7
      GAIN_1L = 1, 7 /
   STATION = 'VLA_18N'    FQID = 1
      GAIN_1R = 1, 7
      GAIN_1L = 1, 7 /
END /
!
! Source model data: point source unit flux density
!
SU_MODEL /
   SOURCE = '3C286'
   TYPE = 1, 0,0, 9,1,.5,0, 0,0,0
   SPEC = 0,0,0,0,0
   VEL = 0,0
   /
   SOURCE = 'Target'
   TYPE = 1, 0,0, 9,0,0,0, 0,0,0
   /
   SOURCE = 'Target'
   TYPE = 2, -10,10, 0,20,10, 4,0,0,0
   /
   SOURCE = 'Target'
   TYPE = 2, 20,-20, 90,20,10, 8,0,0,0
   /
END /
!
! Schedule records
!
SCHEDULE /
!
! All antennas
!
   START = 16:31:00   STOP = 16:35:00
   SOURCE = '3C286'   SUBA = 1   FQID = 1
   TINT = 20 /
!
   START = 16:40:00   STOP = 17:25:00
   SOURCE = 'Target'   SUBA = 1   FQID = 1
   TINT = 20 /
!
   START = 17:31:00   STOP = 17:35:00
   SOURCE = '3C286'   SUBA = 1   FQID = 1
   TINT = 10  /
!
   START = 17:40:00   STOP = 19:02:00
   SOURCE = 'Target'   SUBA = 1   FQID = 1
   TINT = 20 /
!
   START = 19:08:00   STOP = 19:13:00
   SOURCE = '3C286'   SUBA = 1   FQID = 1
   TINT = 10  /
END /
!
-----------------------------------------------------------------------
