; LDGPS
;---------------------------------------------------------------
;! load GPS data from an ASCII file
;# Task Calibration VLA
;-----------------------------------------------------------------------
;;  Copyright (C) 1996, 1999
;;  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
;;  MERCHANTABILITY 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
;-----------------------------------------------------------------------
;---------------------------------------------------------------
LDGPS     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
LDGPS     Task to load GPS TEC data from ASCII files
INNAME                             Input UV file name (name)
INCLASS                            Input UV file name (class)
INSEQ             0.0     9999.0   Input UV file name (seq. #)
INDISK            0.0        9.0   Input UV file disk unit #
INFILE                             GPS transfer file.
OUTVERS                            Output GP table version
----------------------------------------------------------------
LDGPS
Task:   Loads GPS delay data from a CONAN-ASCII file into a GP
        table for use by ionospheric calibration tasks.
Adverbs
  INNAME.....Input UV file name (name).      Standard defaults.
  INCLASS....Input UV file name (class).     Standard defaults.
  INSEQ......Input UV file name (seq. #).    0 => highest.
  INDISK.....Disk drive # of input UV file.  0 => any.
  INFILE.....Name of file containing GPS data.
  OUTVERS....Version number of GP table.  0 => highest + 1
----------------------------------------------------------------
LDGPS:  Task to load GPS TEC data from ASCII files
Documentor: Chris Flatters
Related Programs: APGPS

LDGPS loads total electron content (TEC) data from a GPS
ASCII data file, corrects it for receiver and satellite
delay offsets and stores it in a GP table for use by programs
that calculate corrections for ionospheric delay and Faraday
rotation.

1. INPUT FILE FORMAT

The input file contains raw data from one or more dual-frequency
GPS receivers together with information about satellite and
receiver biases.

This file shall contain lines of ASCII text. The end of each
line shall be marked by an new-line character (hexadecimal code
0A). No line shall contain more than 200 characters (not
counting the new-line character marking the end of the line).

The input file shall be divided into sections. Each section
shall end with the terminal character '/' (hexadecimal code
2F). Each section shall either be a structured record or a data
block.

A structured record shall contain one or more keyword clauses
seperated by spaces and tab characters. A keyword clause shall
consist of a keyword specification, optionally followed by an
equals sign followed by a scalar or vector value. The equals
sign may be separated from the keyword specification or value by
one or more spaces or tab characters.

A keyword specification shall consist of a keyword name, optionally
followed by an array index in parentheses. Upper-case and
lower-case letters are regarded as equivalent in the keyword
name. An array index shall be a positive integer.

A scalar value shall either be an integer, a floating point
number (which may contain an exponent beginning with 'e', 'E',
'd', or 'D'), a time, a character string delimited by either
single quotes or double quotes (but not a mixture of the two) or
a simple floating-point expression in parentheses.

A time shall consist of one or more digits (representing hours),
followed by a colon and either a floating-number (representing
minutes) or an integer (representing minutes) followed by
another colon and a floating point number representing seconds.

An vector value shall be a sequence of scalar values separated
by commas and optional spaces or tabs.

A structured record may span more than one line but a line-break
shall not occur within a keyword clause unless it follows
immediately after a comma separating two scalar values in a
vector value.

A data block shall consist of zero or more scalar values
separated by spaces or tab characters.

The input file may contain comments. A comment shall begin with
an explamation mark ('!') and extend to the end of the
line. Comments are used to provide explanatory information to
human readers and may occur anywhere in the file except within a
keyword clause.

The file shall contain satellite bias records and receiver data
blocks. A receiver data block consists of a data header record
that is immediately followed by a data block containing raw GPS
delay measurements.

The first record in the file shall be a satellite bias record.

1.1 SATELLITE BIAS RECORD

A satellite bias record specifies the transmitter offsets (the
difference in the electrical delays in the signal paths for L1
and L2) for each satellite in the GPS constellation. It is
identified by the presence of the keyword 'GPS'.

The following keywords may occur in a satellite bias record.

+---------+----------+-------+--------------------------------+
| Keyword | Required | Value | Description                    |
+---------+----------+-------+--------------------------------+
| GPS     |    yes   | none  | Identifies the current record  |
|         |          |       | as a satellite bias record.    |
|         |          |       |                                |
| BIAS    |    yes   | float | Specifies the satellite biases |
|         |          | array | as an array of floating point  |
|         |          |       | numbers with the array indices |
|         |          |       | corresponding to satellite     |
|         |          |       | PRNs.                          |
|         |          |       |                                |
| TECU    |    no    | none  | Indicates that bias values are |
|         |          |       | given in TEC units.            |
|         |          |       |                                |
| NANOSEC |    no    | none  | Indicates that bias values are |
|         |          |       | given in nanoseconds.          |
+---------+----------+-------+--------------------------------+

One TEC units corresponds to a column density of 10^16 electrons
per square meter and is equivalent to a differential delay of
2.854 nanoseconds between L1 and L2.

The TECU and NANOSEC keywords shall not both appear in the same
record. If neither keyword is present in the record then the
biases shall be assumed to be given in nanoseconds.

1.2 RECEIVER DATA BLOCK

The following keywords may occur in a data header record.

+----------+----------+--------+------------------------------+
| Keyword  | Required | Value  | Description                  |
+----------+----------+--------+------------------------------+
| GPSDATA  |   yes    |  none  | Identifies the record as a   |
|          |          |        | data header record.          |
|          |          |        |                              |
| RECEIVER |   yes    | string | Specifies the name of the    |
|          |          |        | receiver (no more than 8     |
|          |          |        | characters).                 |
|          |          |        |                              |
| BIAS     |   yes    | float  | Specifies the receiver bias. |
|          |          |        |                              |
| TECU     |    no    |  none  | Indicates that bias value is |
|          |          |        | given in TEC units.          |
|          |          |        |                              |
| NANOSEC  |    no    |  none  | Indicates that bias value is |
|          |          |        | given in nanoseconds.        |
|          |          |        |                              |
| X        |   yes    | float  | x-coordinate of receiver in  |
|          |          |        | meters                       |
|          |          |        |                              |
| Y        |   yes    | float  | y-coordinate of receiver in  |
|          |          |        | meters                       |
|          |          |        |                              |
| X        |   yes    | float  | z-coordinate of receiver in  |
|          |          |        | meters                       |
+----------+----------+--------+------------------------------+

The x, y, and z coordinates shall be given in the WGS-84
geocentric coordinate system.

The TECU and NANOSEC keywords shall not both appear in the same
record. If both are omitted the bias shall be assumed to be
given in nanoseconds.

The data header shall be followed by a data block containing no
more than 36000 measurements. Each measurement shall consist of
the following fields.

+-------+-------+---------------------------------------------+
| Field | Type  | Description                                 |
+-------+-------+---------------------------------------------+
|     1 | int   | Year number                                 |
|       |       |                                             |
|     2 | int   | Day of year (1 to 366)                      |
|       |       |                                             |
|     3 | time  | Time of the observation (UTC)               |
|       |       |                                             |
|     4 | int   | Satellite PRN                               |
|       |       |                                             |
|     5 | float | Azimuth of satellite in degrees (increasing |
|       |       | north through east)                         |
|       |       |                                             |
|     6 | float | Elevation of satellite in degrees           |
|       |       |                                             |
|     7 | float | TEC from phase measurements (TEC-phase) in  |
|       |       | TEC units                                   |
|       |       |                                             |
|     8 | float | TEC from delay measurements (TEC-tau) in    |
|       |       | TEC units                                   |
+-------+-------+---------------------------------------------+

The TEC measurements shall not be corrected for receiver or
satellite biases. That is, given a TEC measurement t, the
true TEC along the line of sight to the satellite should be

t' = t - (s + r)

where r is the receiver bias from the data header and s is the
satellite bias from the nearest preceding satellite bias
record.

1.3 EXAMPLE INPUT FILE

GPS BIAS =  -6.104,  -2.786,  -8.370, -11.275,
            -7.682,  -9.106,  -3.263,  -8.059,
           -10.282,  -3.163,  -3.620,  -3.620,
           -22.921,  -4.628,  -4.235,  -1.263,
            -2.862,  -9.521,  -3.306,  -4.719,
            -4.719,  -7.248,  -5.219,  -1.190,
           -14.175, -12.648,  -8.076, -11.628,
           -13.995, -14.613, -11.363,  -3.620 TECU /
!
! Biases from JPL global model, September 22 1998
!
GPSDATA RECEIVER = 'PIE TOWN'
        BIAS     = +2.961 NANOSEC
        X        =  1640916.7642
        Y        = -5014781.1987
        Z        =  3575447.1372 /
!
! Year  Day        Time  PRN      Az       El  TEC-phi  TEC-tau
  1998  277  01:45:10.2    2   40.20    53.23   3.9281   4.2359
  1998  277  01:45.10.2   15  157.63    43.09   7.2385   6.1423
!
! ...
!
/
! End of file

1.4 LIMITATIONS

Although the file may contain data from several receivers, LDGPS
can only handle data from a single receiver.


2. GP TABLE FORMAT

This extension table for a uv data set contains corrected
measurements of TEC-tau from GPS satellites.

2.1 HEADER KEYWORDS

The header keywords provide information about the GPS receiver.

Keyword       Type         Description
-------       ----         -----------

RECVR          A           The name of the receiver
RLONG          R           The East longitude of the receiver
                           (degrees)
RLAT           R           The latitude of the receiver (deg)
RHEIGHT        R           The height of the receiver above mean
                           sea level (m)

2.2 RECORDS

Each record contains a single measurement of the TEC along the
line of sight to a satellite.

Title    Units     Code         Description
-----    -----     ----         -----------

TIME      days      1D          Time of measurement
PRN                 1I          Satellite PRN
AZ        deg       1E          Satellite azimuth
ELEV      deg       1E          Satellite elevation
TECTAU    m^-2      1E          TEC from delay
TECPHS    m^-2      1E          TEC from phase

Times are given relative to the reference time for the UV data
(0h UTC or IAT on the reference date).


