WIRE SO Tool: autotilefile


Perl script autotilefile is an automatic means of creating a tile file from a list of targets. Moon-violation checking is done as final step, just prior to tile placement (in the tile file). The resulting tile file can then be edited as usual with the WIRE mission planning tool, plansky.

The tool reads in an IPAC-table-formatted target list, calls planquery to get the orbit number and angle ranges for each target, and, using this information, creates a tile file with non-overlapping tiles.   It also creates an IPAC-table-formatted output target list that additionally contains start and end dates over which the targets are viewable.   Error messages are generated for tiles that cannot be placed on the orbital map without overlapping other tiles.

The tiles are made in target-list order, and placed in the first available orbit. As such, it is possible for tile placement near the beginning of the WIRE mission before cover ejection, so user beware! The command-line option -earliestorbit (or -eo) allows the user to specify the earliest orbit for placement of all tiles in the input target list, so as to preclude scheduled observations prior to certain mission events, such as cover ejection (which occurs around orbit #35). The default orbit number is zero for this option. For controlling tile placement at the other end of the available orbit range of the mission, the command-line option -latestorbit (or -lo) can be used. The -eo and -lo options apply to the tile center, so allowances must be made by the user for tile widths.

If multiple orbit-number ranges are returned by planquery, then these ranges are sorted in ascending order to assure that the tiles are placed in the earliest available orbits.

Optionally, an input tile file can be specified, in which case the automatically-placed tiles will be positioned so that there is no overlapping of input tiles. The tiles in the input tile file may be either primary-science or associate-investigator types.

Tile truncation is now handled automatically by this tool, that is, for tiles that are truncatable. This capability can be forced off with the -nt switch. If it is left on, either of the two alternatives below for scheduling truncatable tiles is available (controlled by the command-line switch -obo):

  1. Try all possible orbits to schedule the observation with its nominal tile height. If the observation can't be scheduled (due to overlap with other observations), then retry scheduling the observation with its minimum tile height revisiting all possible orbits.
  2. For each possible orbit it turn, first try to schedule the observation with its nominal tile height and if that can't be done, then try to do it again with the observation's minimum tile height. If this fails, go to the next possible orbit.

Since planquery currently does not have the capability to start observations late, the tile truncation feature is only useful for scheduling observations whose ending portion, beyond the truncation point, overlap with other observations.

Values for the orbit period and on-target observation integration time for a standard segments are assumed for calculating the truncated tile heights. These can be overridden by command-line options, if necessary.

The tool includes checking that each tile's target is not within a certain angular distance from the Moon. This checking is independent of planquery. The default minimum separation angle between the telescope boresight and the Moon's center is 8 degrees, but this value can be overridden with the -moonminangle command-line option. For tiles with Moon violations, their placement is deferred to a later orbit when the Moon is sufficiently far removed from the observation.

The input target list may optionally include a specification of the exact orbit where the targetted tile should be placed. The orbit should be within the user-specified range (by the -eo and -lo command-line options); otherwise a warning will be given. The associated value in the repeat column should be set to 1 as well; otherwise, overlapping tile warnings will be given, and no tiles beyond the first repeat will be placed. If the input target list has blank entries in its orbit column, then, for these targets, tiles consistent with the specified number of repeats will be placed at the earliest available orbit.

The following IPAC-table column headings in the input target list are handled:

Column Format
type  (character, just one) 
ra  (double precision, in degrees) 
dec  (double precision, in degrees) 
repeats (integer) 
note  (character, up to 50 char. max.)
orbit  (integer) 

This information is used to either create a tile, or is stored along with other information about the tile. The note and orbit columns are optional. The rest of the data columns are required. The target list should have data columns separated with spaces, as tabs are not allowed.

See the environment variables section below for information on controlling the versions of planquery and planner input files used by this tool.

The tool is now under both CVS version control (/proj/wire/cvsroot/so/plansky), and make control (makefile.p). The following perl libraries are required: moonviolation.pl, tileutils.pl, readutils.pl, posrecutils.pl, wireutils.pl, params.pl, and mytime.pl. CVS version 4.21 of this tool has been delivered to /proj/wire/so_ops/bin. The source code is located in /proj/wire/russ/so/plansky/autotilefile.

Required and Optional Inputs

The table below describes the available command-line inputs. Note that only the first two command-line inputs are required.
Command-line input  Definition 
-targlist or -tl filename Input list of targets. Required.
-outputtilefile or -tf filename Output tile file. Required.
-inputtilefile or -itf filename Input tile file. Optional.
-earliestorbit or -eo value Earliest orbit number for placement of all tiles in input target list. Default value is zero. Optional.
-latestorbit or -lo value Latest orbit number for placement of all tiles in input target list. Default value is 10000. Optional.
-NoTruncation or -nt Switch for disallowing tile truncation.
-OrbitByOrbit or -obo Switch that causes an orbit-by-orbit attempt to place a full-height tile, and then, if necessary, a truncated version of the tile in the same orbit. The default behavior is try to all possible orbits for the full-height tile, and, if that fails, retry all possible orbits with the truncated tile.
-ADFpath or -ap pathname Used to override the environment variable PLANROOT only for specifying the location of the area-definition files. Optional.
-orbitperiod or -op value Orbit period in minutes. Used to compute the truncated tile heights. The default value is 95.39424 minutes (consistent with planquery).
-StandSegIntTime or -st value On-target observation segment integration time for a standard segment. Used to compute the truncated tile heights. The default value is 497 seconds.
-moonminangle or -ma or -a value Minimum separation allowed between telescope boresight and Moon's center. The default value is 8 degrees.
-verbose or -v switch Verbose mode. Default is off.

Environment Variables

There are four different environment variables that can be manually set to override certain default file paths and names that specify various files used by this tool (see the table below). TARGET refers to the target directory specified in the make process.
Environment variable Description  Defaults
PLANSKYROOT Path to generic plansky input files  /proj/wire/soda/so/plansky
PLANQUERYROOT Path to planquery  /proj/wire/TARGET/bin/
PLANROOT Path to evolution-scenario dependent input files  /proj/wire/TARGET/data/isoev
PLANPROJECT Filename suffix for *.zzh evolution-scenario dependent image files in directory specified by PLANROOT  DGH_sf


Two output files are created: a tile file and an output target list. The tile file is named with the -tf command-line option and is written in plansky format. The output target list is called "autotilefile.tbl" and is written in IPAC-table format.

The output target list contains essential input-target-list data columns, plus the following additional columns: "index", "trunc", "startdate", "enddate", "mjdstart", and "mjdend". The index column is a target counter. The "trunc" column gives the number of tiles associated with each target that were truncated. The start and end date columns list up to three available date ranges for tile placement. The modified Julian start and end dates correspond to the first date range listed, and are given for convenience in sorting targets by viewing date.

In the event that the target that is not viewable, there will be blank entries for start and end dates in the output target list.

You can easily sort autotilefile.tbl by observation date using Tim Conrow's tblmanip tool; for example:

tblmanip -s mjdstart autotilefile.tbl > autotilefile.tbl2


Example of how to execute autotilefile:
autotilefile -tl mylist3.tbl -tf mylist3.tile -itf nick.tile -ap . -obo
In this case, the input target list is mylist3.tbl. The tool will create the tile file mylist3.tile in the file format required by plansky, and the output target-list file autotilefile.tbl in IPAC-table format. The tiles will be placed so as not to interfere with observations specified in nick.tile. The orbit-by-orbit mode for tile truncation has been selected. For this example, the ADF for the "s" tile was modified to make the tile truncatable (the pathname to this special ADF is specified by the -ap command-line option), in order to demonstrate the tool's capabilities.

The standard output is:

autotilefile version $Id: autotilefile,v 4.14 1999/01/14 03:16:00 laher Exp $  update Wed_1999/01/13(013)_19:16:00 , PID=12468
User: laher   Date/time: Wed_1999/01/13(013)_19:17:30   PCPU: 1.61/0.31/3  CCPU: 0.12/0.25


Named parameters for Autotilefile:
  targlist = mylist3.tbl; inputtilefile = nick.tile; 
  outputtilefile = mylist3.tile; earliestorbit = 0; latestorbit = 10000; 
  notruncation = undef; orbitbyorbit = 1; adfpath = .; orbitperiod = 95.39424; 
  standseginttime = 497; verbose = undef; execpath = @/; debug = undef; 
  log = undef; 

Starting survey prog: planquery ...
Process '/proj/wire/so_tst/bin//planquery /wire/pit/so/alternate_missions/v611_990224_300_7adv_3spin_isoev/ DGH_sf' started with PID 12480.
Directory for all binary files:/wire/pit/so/alternate_missions/v611_990224_300_7adv_3spin_isoev/
Projection & coordinate system string:DGH_sf
Projection code=0, axes code=12
Planquery version planquery version 6.1.2
Info only: allocating memory for 4539 state vectors 
finished survey start: 0 
Primary-science tile types:

       Type   Width    Height
         u      81    38.0776
         d      81    38.0776
         m      27    38.0776
         s      27    24.4919
         p      36    38.0776
         f      27    24.4919

Number of tile types = 6

AI-science and other tile types from /wire/pit/so/alternate_missions/v611_990224_300_7adv_3spin_isoev//AItilesizes.inp

       Type   Width    Height      Color
         a       1    17.6991     purple
         b       1    38.0776      brown
         e       1    24.4919       cyan
         g       1    17.6991      green
         j       1    18.5796        red
         k       1    17.6991     purple
         n       1    35.0586      brown
         o       1    35.0586       cyan
         q       1    35.0586      green

Number of tile types = 9

End of autotilefile status 0, PID=12468
User: laher   Date/time: Wed_1999/01/13(013)_19:18:46   PCPU: 61.43/0.78/79  CCPU: 0.13/0.31

Here is a portion of plansky's orbit-angle map showing the tile placement for this example:

The tiles with cyan dots are reference tiles around which autotilefile places the targeted tiles without overlap (unless the targeted tiles are truncatable, as in this case). The overlap shown between the middle reference tile and the four targeted tiles is due to tile truncation (see the "trunc" column in the autotilefile.tbl listing below). In the absence of the reference tiles, the targeted tiles would have been placed in a straight row. However, for this case, since there is tile-center angle leeway (because the observation segment limit index is zero for this targeted tile type), autotilefile automatically shifts the tile position up or down to accommodate the reference tiles.

Here is a listing of mylist3.tbl:

|type |ra                |dec               |repeats |note         |
|c    |d                 |d                 |i       |c            |
s     131.68778418540    -56.77061832466     20       Ma HD75311

Here is a listing of the output target-list autotilefile.tbl:
|type   |ra             |dec            |repeats |trunc|note                                             |index  |startdate                                      |enddate                                        |mjdstart    |mjdend      |
|c      |d              |d              |i       |i    |c                                                |i      |c                                              |c                                              |c           |c           |
s             131.687784      -56.770618     20     4  Ma HD75311                                             1  3-020.02-1999, 11-008.25-1999                   7-021.43-1999, 12-003.10-1999                   36237.517982 36360.925426 

Last revised: March 15, 1999

Software Developer: Russ Laher

Webpage by: Russ Laher and Rosalie Ewald

URL: http://spider.ipac.caltech.edu/staff/laher/autotilefile.html

Return to Home Page