How To Tile Targets

Introduction

The short version of this document is that you log into sdssdp4 and type:

cd /opdb/d1/data/tileChunk/chunk##
mkdir tiling
cd tiling
setup ts
setup tiling
setup sm

Then you type "ts", and run the commands:

source $env(TILING_DIR)/etc/setupTiling.tcl
exit

Then you type "tiling", and run the commands:

runTile

You will get some simple queries to answer.

This procedure produces a file of targets which conforms to the data model for a tiInputTargets.fit file. The coordinates should be in right ascension and declination (in degrees). It should be true either in ra/dec space or eta/lambda space that they do not come closer than 3 degrees to the pole. Tiling will not try to do anything closer to the pole than this; if this ever turns out to be a problem it can be fixed. They should fill approximately a rectangle in nu-mu space or in eta-lambda space.

Then the tiling procedure is:

Create the tilingBoundary and tilingMask files to record the set of rectangles which define this chunk.
Use the tilingBoundary and tilingMask files to trim the targets.
Set the tiPlan.par and tiParam.par parameters
Run tiling
Plot the results and make sure they are reasonable

This procedure will break every once in a while, and you may not want to rerun everything when that happens, so I supply here a description of what setupTiling and runTile actually do.

Setting up Tiling Within OPDB

To setup the files for tiling you need to run on sdssdp4. You need to run the script setupTiling.tcl provided with the tiling distribution within ts (note that this script actually only works within ts, not tiling!).

The script basically has two steps:

extract tiling boundaries (conforming to data model specifications)
extract targets which have not been assigned to fibers (conforming to data model specifications)

Once this is done, tiling has all the information necessary to proceed on its own. The following steps (up until Running the Algorithm) are preparation performed by runTile, which can be skipped by calling "runTile 0" (eg. if you want to change parameters by hand).

Creating the tilingBoundary File

After deciding some trivial issues about how to number the chunk and how to number the tiles, tiling attempts to construct the tilingBoundary file. The tilingBoundary file is a Yanny parameter file where each element represents a rectangular region in which to include objects. Since these files are designed to be used to define the survey window function, it is of the UTMOST IMPORTANCE that each rectangular region cover regions which actually have been targeted.

Tiling tries to figure out the boundaries by looking at the list produced by OPDB of all possible boundary regions. It finds the existing large, contiguous regions which haven't been tiled, and queries you on which one you would like to run on. If you want to change the results, you can do so and then call "runTile 0", so it does not overwrite the changes.

Creating the tiPlan.par and tiParam.par File

Tiling also creates a tiPlan.par file and a tiParam.par with a number of parameters set in it. Again, you can change the parameters, and if you call "runTile 0" it will not remake these. It knows the default settings for all the parameters and sets these. The only step of any consequence is the setting of the initial conditions, which currently defaults to a rectangle in eta-lambda in the north, and mu-nu in the south.

Running the Algorithm

When runTile finally calls the tiling routines proper, all sorts of messages will fly by.

If "tileSearchFudge" is positive, the code will run until it finds the smallest number of tiles which satisfies the constraints in "desCoverage" and "desCoverageResolved". This is the default which runTile tries. If "tileSearchFudge" is negative, it just looks at the single number of tiles specified by you. There are situations in which you want to do this. Note that the code will still bail without outputting any results if you do not satisfy the requirements.

Interpreting the Output

The main output comes in the form of three files:

tileFullChunk##.par, which gives the location of each tile
tiOutputFinalChunk##.fit, which lists what happens to each target.
tilingBoundaryChunk##.par, which describes the geometry.

The main results in the targets file are stored in the "tileId" parameter, which gives which tile each target was assigned to (-1 if none), and "mask", which sets bits according to what happened to the target. "collisionGroup" gives the index of the 55 arcsec group the target belonged to.

QA is given in the form of several files:

tiStatsChunk##.txt, which gives some useful performance numbers
tiMissingChunk##.fit, which lists all targets which did *not* get fibers
tiMissingStatsChunk##.txt, which lists some stats about missing targets
tilesChunk##.ps, which is an SM-produced PostScript file with the results.

Snail Mail: Michael Blanton; Email: blanton@fnal.gov