AIPS NRAO AIPS HELP file for ALBUS in 31DEC25



As of Mon Feb 17 7:28:19 2025


ALBUS: Calibrate ionospheric delay and Faraday rotn. w ALBUS

INPUTS

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 #
SOURCES                            Limit solution to sources
ANTENNAS                           Antennas to include VLBA
GAINVER                            Input CL table version
GAINUSE                            Output CL table version
DATAOUT                            Directory for output and work
                                   files
DODATE          -1.0         1.0   > 0 -> store files in a dated
                                      subdirectory of DATAOUT
                                   <= 0 -> use DATAOUT
TECRTYPE                           'G03' (default), 'G01'-'G09'
DETIME                             Time out limit in seconds for
                                   data downloads  default 250
DOBTWEEN                           > 0 => use one download area
                                       for all sources
                                   <= 0 => do data downloads for
                                       each source separately
                                   ABS() >= 10 => do not use
                                       parallel operations
RADIUS         0.0                 Radius in km to search for
                                   data sources.  0 -> 300 with
                                   200 for VLBA station OV
DOALL         -1.0           1.0   > 0 -> do all sources in one
                                          pass
                                   <= 0 -> do a pass for each
                                          source individually
PRTLEV        -1.0           3.0   > 1 => all messages written
                                          to msg.txt file
                                   > 2 => invoke debug messages
AVERSION                           '0.1' else latest ALBUS vers
PROGRAM                            'SINGULARITY' else apptainer

HELP SECTION

ALBUS
Task:   Derives corrections for ionospheric Faraday rotation and
        dispersive delay using the ALBUS ionospheric software
        package.

        This task is a departure from normal AIPS matters.  It makes
        a list of all requested sources and, for VLBA, all requested
        antennas.  Then, for each source and antenna, it creates and
        fills two text files: a python file and a shell script.  The
        latter is used primarily to invoke the ALBUS package located
        in a software "container".  In order to do this, the user must
        have the "apptainer" software package installed on the local
        computer and available in the $PATH.  ALBUS runs, producing a
        vast number of messages which will fly by on the terminal.
        When it finishes, the ALBUS AIPS task reads the report file
        and updates a CL and TE table.

        ALBUS uses the antenna location to determine which public
        GPS and ionospheric data sources to try.  It then downloads
        the selected ionospheric data files.  This is somewhat a
        dynamic process, which means that multiple executions of
        ALBUS will probably not all use the same data files.  This
        curiosity appears to make little difference in the results
        however.  ALBUS then fits a model to the data to compute the
        STEC and IFR values.  The IFR and calculated dispersive delay
        are then written to a CL and a TE table.  The process involves
        a loop over source and, for VLB, a loop over antenna.  First
        ALBUS is invoked via the program "apptainer" to access the
        "container" called contain_albus.sif (in $LOAD) and to run
        therein a python script created by this AIPS task.  When the
        script finishes, the output file is read to add DISP and IFR
        values to a CL and a TE table.  The data stations actually
        used by the code are written into the history and message
        files.  The meaning of the station codes may be found in the
        text file named $AIPSIONS.ALBUS.stations.

        The data files used by ALBUS include ones that are "final"
        which means that they may not be available for as many as
        20 days after the observation.

        The task uses somewhat simplified names for things and has to
        delete any pre-existing file or directory of the same name.
        Therefore, it is a good idea to use a different directory for
        every data set.  DODATE > 0 is an easy way to do this.

        We regard this task as experimental; the last 5 adverbs are
        intended to explore its aspects.  Note also that two executions
        of this task will probably end up downloading different data
        sets.  The downloaded data are in the directory named
        ALBUSdata where nn and mm depend on DOBTWEEN and whether
        this is VLBA or not.  With DOBTWEEN <= 0, nn is source number
        and mm is the antenna number (VLBA) or 0.  If DOBTWEEN > 0,
        nn is the antenna number (VLBA) or 0 and mm is not present.
        A file named albus.inputs.txt is written to DATAOUT to
        document all the adverbs used by the AIPS task and the stations
        actually used bu ALBUS.

        A larger RADIUS will include more data sources which may be
        appropriate for larger zenith angles.  However, the ALBUS
        solution code takes longer when there are more stations in
        a seriously non-linear fashion.  For a modest number of data
        sources, the model computation can take less than two minutes
        per source.  However, for a larger number of stations, that
        computation can even take an hour per source.  A 300 km radius
        around OV (Owens Valley VLBA antenna) falls in the latter
        category, while the VLA falls in the former.
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.
  SOURCES....Include only listed source names.  ' ' => all
  ANTENNAS...Antenna numbers to be included.  0 -> all,
             used only for VLBA
  GAINVER....Version number of the input CL table to use.
             0 => highest
  GAINUSE....version number of output CL table.  If not equal
             GAINVER, then it is set to highest+1 and new TE and
             CL tables are written.  If it is equal to GAINVER,
             then the highest numbered TE table is updated as
             well as updating GAINVER.
             highest pre-existing TE table is modified.
  DATAOUT....This must point at a directory to contain the
             python input and output files.  It may be an
             environment variable of the form MYAREA: (note
             trailing colon) or an actual path (e.g.
             /home/primate/albus) with out without a trailing "/".
  DODATE.....If > 0, use a disk subdirectory below DATAOUT
             named by ddmmmyyhhss.
             If <= 0, use DATAOUT itself.  Note that files can
             be over-written since their names contain the source
             number (and antenna number for VLBA) only.  The
             report file does include the source name and so will
             only be over-written by data from the same source.
  TECRTYPE...Ionosphere model type: 'G03' is the default, 'G04'
             'G05' are similar.  ALBUS has additional models but
             these 3 seem best.  'GO1' through 'G09' are allowed.
             See explain albus.
  DETIME.....Default time out period on downloads in seconds.
             < 100, > 600 => 250
  DOBTWEEN...> 0 => use one RINEX data download area for all
                 sources and do only one download (per antenna
                 in the case of VLBA data).  DOALL > 0 also does
                 one data area for all sources.
                 DO_SER = 1 in Albus
             <= 0 => use separate download areas for each source
                 and do separate downloads for each source
                 DO_SER = 0 in Albus
             If ABS (DOBTWEEN) >= 10, use only one cpu
             (NUM_PROCESSORS=1 in Albus); otherwise use what you
             have (NUM_PROCESSORS=36 in Albus).  The Albus tool
             is capable of going parallel where possible, but
             this option may allow more data files to be used.
             Of course, the task will take much longer to run,
             e.g. 7.6 vs 1.8 minutes for one VLA source, but
             with 9 GPS stations actually used versus 3 or 4.
  RADIUS.....Max radius to find GPS stations in km.
             0 -> 300 except 'OV' which is 150.
  DOALL......> 0 -> use a mode in which a source list is
                    generated and read into Albus.  All sources
                    selected are done in one pass of Albus.
                    Planets may not be done in this mode.
             <= 0 -> do sources one at a time.  If STRA3='0.1',
                    this mode will be forced.
  PRTLEV.....> 1 => all Albus messages are written to a text file
                    named msg.txt in the data area - warning this
                    file can be 90000 lines or more.  If this
                    file is being written, you can monitor its
                    progress with "tail -f msg.txt".
             else => all Albus messages spew out on the terminal
                    and control is returned to you only when the
                    task finishes.
  AVERSION...The ALBUS version code: '0.1' selects container
             dated Jul 29, 2024.  Otherwise, the container called
             1.0 dated Sep 23, 2024 is used.
  PROGRAM....'SINGULARITY' selects container program singularity,
             else apptainer is used.

EXPLAIN SECTION

Here's a bit more detail of what the RI_G0*s equate to:

  single_nearest   = 0,
  single_all       = 1,
  multiple_2D      = 2,
  multiple_3D_mult = 3, // multiple layers with the same poly dependance
  multiple_3D_many = 4, // multiple layers with different poly
                           dependance
  multiple_3D_sphe = 5, // spherical harmonics with different h layers
  multiple_2D_time = 6, // 2D ionosphere with time dependance
  multiple_2D_grad = 7, // 2D ionosphere with gradient least squares
  multiple_2D_timg = 8, // 2D ionosphere with time, gradient least
                           squares
  multiple_3D_sphg = 9  // 3D ionosphere spherical, gradient least
                           squares

AIPS