Fermi Gamma-ray Space Telescope

Notes on Using Timelines with gtorbsim

The Fermi science tool orbit simulator gtorbsim can create FT2 (spacecraft) files. A realistic pointed observation does not do limb following for long periods but instead has primary and secondary targets, or pointed observation interleaved with slices of sky survey. To produce this kind of observation in gtorbsim, it is necessary to provide the input to gtorbsim in the form of a TAKO timeline.

note on time formats: the timeline uses year/doy:hh:mm:ss, gtobsim command line input uses mjd and gtorbsim output is MET.

The timeline consists of a sequence of observations (e.g. to different ra, dec or a slice of sky survey). Each observation needs to be separated by: 

//-------------------------------------

There are 3 kinds of observations that gtorbsim can read from the timeline: Obs, Profile and Survey.

Obs

This is a standard pointed observation. You need to specify RA, dec, start time, stop time. An example is given below. Note that the following are case sensitive (Obs, RA, dec, Begin, End). The units (deg, sec) are not necessary, but can help make the timeline more human readable. 

// ---------------------------------------------------

// 2013/022:07:09:00 Obs        Begin
//                   RA          = 71.60230 deg
//                   dec         = 64.39160 deg
// 2013/022:20:26:00 Obs        End	

// ---------------------------------------------------

Profile

This is survey mode specified by a 17 point profile. You need to specify the start time and stop time of the observation, the 17 time, angle pairs. You also need to specify the phase of the rocking profile (i.e. define the clock time that corresponds to rocktime of zero) this is specified by a parameter called ROCKSTART.

Here is an example using the current (130202 50 deg profile): 

// ---------------------------------------------------

// 2013/022:20:26:00 Profile    Begin 
//                   Rocking Profile:
//                        ROCKSTART   = 2013/016:22:24:00 (380067842)
//                        ROCKDEFAULT = 0.000000
//                            ROCKTIME   ROCKANGLE
//                        01         0    0.000000
//                        02       190   38.000000
//                        03       230   46.000000
//                        04       270   50.000000
//                        05      3000   50.000000
//                        06      5463   50.000000
//                        07      5503   46.000000
//                        08      5543   38.000000
//                        09      5733    0.000000
//                        10      5923  -38.000000
//                        11      5963  -46.000000
//                        12      6003  -50.000000
//                        13     10000  -50.000000
//                        14     11196  -50.000000
//                        15     11236  -46.000000
//                        16     11276  -38.000000
//                        17     11466    0.000000

// 2013/025:07:09:00 Profile    End

Survey

Survey is survey mode with a fixed rocking angle. You need to specify start and stop time, and offset (the rocking angle). Note that the mission definition of rocking angle is that +ve is south and -ve is north. This has opposite sign to the LAT definition, so the -50 in the example below will result in a +50 deg rocking angle in the resulting FT2 file. 

// ---------------------------------------------------

// 2013/022:20:26:00 Survey    Begin 
//                   offset      = -50.0 deg
// 2013/025:07:09:00 Survey    End   

// ---------------------------------------------------

Running gtorbsim

FSSC documentation is here and here.

Here is an example of running gtorbsim using a two-line element to provide the ephemeris information. The start MJD must be the same as the start time in the timeline, the end time cannot extend past the last end Obs/Profile/Survey in the timeline (but can end early). 

mcenery-2:gtorbsim mcenery$ gtorbsim EAA=5
This is gtorbsim version ScienceTools-v9r27p1-fssc-20120410
Type of input {file or console}[console] 
Input Type is: console
start MJD[56309] 
stop MJD[56317] 
Timeline Type {TAKO, ASFLOWN or SINGLE}[TAKO] 
Name of timeline file[test_timeline.00] 
Ephemeredis file name[tle2.txt] 
Ephemeredis function name[tlederive] 
Conversion factor to Km[1] 
Time resolution in minutes[1] 
Initial RA[0] 
Initial DEC[0] 
OutPut File[test1.fits] 
SAA file definition[L_SAA_2008198.03] 
Earth Avoidance Angle: 5 degrees
No target found in occultation


WARNING ===> At k=11520, Interval (from Start time -4485024059) is -4865788739, while resolution is 60
WARNING ===> At k=11520, Interval (from Stop time -4485023999) is -4865788739, while resolution is 60

The warning at the end tells you that the last entry in the output FT2 file is bogus. This always happens. I don't know why. You can just delete that entry from the file. I've appended all the files used to generate test1.fits, so that you can try this for yourself, if you like.

Doing something sensible

It's now fairly straightforward to see how to create a realistic timeline. You could generate two months or a year of profiled sky survey. You will almost certainly want this anyway, to make a survey profile to compare your great idea. With the resulting FT2 file, you can easily calculate when a candidate target gets to xx deg of the Earth limb (either entering or exiting occultation), you can also get the coordinates of the boresight in survey mode at those times.

This gives you all the information that you need to write a script to generate a timeline that will interleave pointed mode observations with survey mode when the target is occulted or close to the Earth.

The piece of information that you are missing is the slew times. The FSSC planning tools use a lookup table provided by Dean Tsai (a GSFC guidance, navigation and control engineer). The tables are available in the gtobsim src directory, but there is no standalone tool to use them. If you want to get a rough estimate of what it will be, you can calculate the angular difference between the start and end points of the slew and assume that the observatory will move at 0.2 deg/s, or you can just look at the output in the resulting FT2 file.

I've created a one year profile survey observation (the 70MB file is here) for 2013 using the TLE from the example above.

I then wrote a little script (attached to this page) to generate a timeline with a pointed mode observation interleaved with +-50 deg when the target is occulted. You can run the script with

python makeTimeLine.py survey_year.fits 30 10 103 >timeline1.txt

This will take the survey_year.fits file and make a timeline that has pointed observation at 30, 10 and moves to survey mode when the target gets within 10 deg of the Earth (i.e. zenith angle of 103 deg).

For the timeline to run, you'll need to edit the first entry to make it be survey mode. I do this by starting the second observation (which is survey mode) a little earlier and deleting the first one (which is pointed mode). I don't know why gtorbsim will not run if the first observation is pointed mode. You'll also need to edit the last entry, which is half written because I was sloppy when I wrote the script. The resulting (edited and ready to use) timeline is here.

You could modify the script to move the target from orbit to orbit, if you wished.