NAME gtorbsim - Generate spacecraft orbit and attitude data for a variety of pointing or survey mode strategies. USAGE gtorbsim start_MJD stop_MJD Timeline EphemName EphemFunc Resolution Units Initial_Ra Initial_DEC OutPutFile saafile DESCRIPTION The FSSC Orbit Simulator, gtorbsim, is a spacecraft attitude calculator based on the code already implemented in the general purpose scheduling and planning system TAKO (Timeline Assembler Keyword Oriented) at the Fermi Science Support Center. The simulator inherits many features of TAKO, but it does not have any scheduling capabilities. The main purpose of this simulator is: 1) to calculate spacecraft attitude, that is where the local body frame axes are oriented relative to the sky 2) to determine when events such as entry/exit in South Atlantic Anomaly (SAA) will take place The above must be accomplished starting with a series of pointing commands. The output of the orbit simulator is a FITS spacecraft data file. Several Fermi Science Tools such as gtobssim, gtltcube, gtlike, etc require the spacecraft data file as input. You may use the spacecraft data file provided by the FSSC, but in many cases you will probably need to generate that file if you want to perform a particular analysis of simulated data. The first input you will have to provide to gtorbsim is the observation mode strategy. Several operational modes are used with Fermi, but the spacecraft will acquire scientific data only in survey and pointed modes. The sky survey mode is basically zenith pointed throughout the orbit and has two sub modes: 1) with rocking, and 2) without rocking. Rocking provides more uniform sky coverage and allows for complete sky coverage within a shorter period of time. Different rocking profiles may be implemented, (square or sinusoid) with a basic 2-orbit period and a 60-degree maximum amplitude (above and below the orbit plane). In pointed observation mode, the Z-axis of the observatory is commanded to point at a celestial target. An observing sequence is implemented via a series of commanded targets. There are two sub modes for observing any given target: 1) target tracking, 2) target inertial. Target tracking mode maintains a commanded celestial target within a 60-degree diameter field of view. The target is allowed to drift at about 1 degree/minute across this field of view during the non-occulted part of the orbit. Target inertial mode maintains the Z-axis on the target to within the 2-degree control capability of the spacecraft. This mode may be interrupted for downlink transmissions of science data. Earth avoidance is accomplished in this mode via stored commands that keep the field of view on the sky while the target is occulted. Alternatively, an automatic earth avoidance capability may be used. Even though it will be possible to do pointed observations, the large FOV of LAT provides such extensive data on individual sources that strong justification is required to use other types of observation modes than sky survey. For that reason, Fermi operates in sky-survey mode most of the time. With the gtorbsim tool you may choose to calculate the attitude in survey or pointed mode. In survey mode you may chose between two options: fixed or profiled. In fixed survey mode the spacecraft does a sky survey with a specified offset with respect to its local zenith for one orbit, and then uses the opposite offset for the next orbit, and so on. In profiled survey the spacecraft observes in survey mode according to a specified profile consisting of 17 increasing times and 17 zenith offsets. The 17 increasing times (in seconds) are used to indicate the time that it takes during each cycle to go from a corresponding zenith offset to the next. The 17 angles (in degrees) are the zenith offsets reached at the end of the corresponding time interval. The first and last of these offsets must be identical in order for the profile to be repeated. On the other hand, in pointed mode the spacecraft stares at a specified location in the sky identified by an RA and DEC provided by the user. The orbit simulator needs to know the spacecraft position in the entire interval of interest in order to properly calculate the attitude, therefore it must be capable of either reading in a file that contains the spacecraft ephemeris, or to calculate one on the fly. The orbit simulator can handle three different types of ephemeris files: * NASA Flight Dynamic Facility (FDF) format, already used for missions such as RXTE. * Satellite Tool Kit (STK) format, already in use for SWIFT. * NORAD Two Line Elements (see http://celestrak.com/NORAD/elements), in which case the spacecraft position is calculated on the fly. Additionally, the initial spacecraft position in celestial (equatorial) coordinates should be provided by the user as an input parameter. The South Atlantic Anomaly region: The instrument high voltage power supplies are protected when the spacecraft traverses the South Atlantic Anomaly (SAA). This occurs about 15% of the time. Gtorbsim has the capability to handle SAA constraints. The SAA region is approximated by a polygon, which is specified by the Longitude and Latitude of its vertices. It is passed to the program as an input file where the specification of the polygon is given. Earth limb: The Earth Limb Tracing maneuvering is an optional feature that can easily be enabled/disabled using the appropriate input parameter in gtorbsim. This maneuvering consists of tracing the Earth Limb if a target is Earth-occulted. Targets are assumed to be occulted if their Earth angle (Angle between target and the Earth Limb) is smaller or at most equal to 30 degrees. Once the target is occulted by the Earth, the orbit simulator finds when is visible again, and where from the Earth Limb is coming out. From the above it finds the angular separation between the in-occult and out-occult position. Finally, the orbit simulator let the local z-axis to sweep equal angles in equal times during its motion along the Earth Limb. In general, when using TAKO Science timelines this step is not necessary since the TAKO avoids scheduling any target during occultation time. However, in special cases the occultation constraint in TAKO can be intentionally disabled to achieve some observational goal. Consequently, the orbit simulator calculates the occultation times, and then performs the Earth Limb tracing maneuvering. The occultation times are calculated using the same algorithm that TAKO uses. PARAMETERS typeinput [string] Type of input, either 'file' or 'console'. This tells gtorbsim to take input from the console with the usual ftools prompting or to read the input from a file. initFile [file] Name of initialization file. Must be specified for 'file' input. start_MJD [double] The start time for the time interval of interest must be specified in Modified Julian Date (MJD) using this parameter. For time conversion you can refer to: http://heasarc.gsfc.nasa.gov/cgi-bin/Tools/xTime/xTime.pl stop_MJD [double] The stop time for the time interval of interest must be specified in Modified Julian Date (MJD) using this parameter. For time conversion you can refer to: http://heasarc.gsfc.nasa.gov/cgi-bin/Tools/xTime/xTime.pl TLType [string] TLType specifies the type of timeline that must be parsed. Its possible values are: * TAKO - for TAKO generated timelines * ASFLOWN - to parse an AS-FLOWN timeline * SINGLE - to use a single command, as explained above, to calculate the spacecraft attitude. Since the As-Flown timeline is simply a chronological list of events (pointing command or entry/exit SAA), each line of the timeline must be properly identified, and parsed. Furthermore, this timeline does not report any information about slew (start time, stop time, etc), the function assumes that slew will take place between the previously indicated sky location and the current one. Timeline [string] This parameter encodes the desired pointing strategy. It can be either the path of the file to be parsed or a single command. In the case of single command, each portion of the command is separated by a "|". For instance, in the case of a simple survey with a rocking offset of +50, the command to be passed will be: Timeline = |SURVEY|+50.0| On the other hand, for a PROFILED survey the syntax should be as follows: Timeline = |PROFILED| 54301.0| 600 +35.0 1200 +25.0 1800 +15.0 ....| The first item specifies the survey as PROFILED, the second item must be the epoch or ROCKSTART in MJD format, then the rocking parameters are specified using the sequence TIME0 ANGLE0 TIME1 ANGLE1 TIME2 ANGLE2 ... and so on. Times must be in seconds, and angles in degrees. Notice also, that times must be increasing, and that the first and last angles must be the same. Finally, a command to simulate a pointed observation can be given as: Timeline = | POINTED | 234.98 | 34.56 | where the first parameter after "POINTED" is the Right Ascension in degrees with values between 0.0 and 360.0, and the second is the Declination expressed in degrees between -90.0 and 90.0. Only empty spaces are allowed between each entry. * FIXED SURVEY - the spacecraft does a sky survey with a specified offset with respect to its local zenith for one orbit, and then uses the opposite offset to another orbit, and so on. * PROFILED SURVEY - the spacecraft observes in survey mode according to a specified profile consisting of 17 increasing times and 17 zenith offsets * POINTED - the spacecraft stares at a specified location in the sky identified by RA and DEC. EphemName [string] The keyword EphemName is used to specify the ephemeris file that the orbit simulator will use to propagate its position. Of course, the file must be specified with its full path. EphemFunc [string] EphemFunc is used to specify which function must be used to calculate the position. The orbit simulator is capable of using 3 different types of ephemeris: * NASA Flight Dynamic Facility (FDF) format, previously used for missions such as RXTE. In this case the value of EphemFunc is yyyy_eph. * Satellite Tool Kit (STK) format, already in use for SWIFT. xyzll_eph is the name of the function that is used to propagate the spacecraft position. * NORAD Two Line Elements (see http://celestrak.com/NORAD/elements), in this case the spacecraft position is calculated on the fly. The value for EphemFunc in this case is tlederive. The user may extract the Fermi TLE into a file from that web site. The orbit simulator needs to know the spacecraft position in the entire interval of interest in order to properly calculate the attitude, therefore it must be capable of either reading in a file that contains the spacecraft ephemeris, or of calculating this on the fly. As already mentioned, the orbit simulator can handle three different types of ephemeris files. In the case of FDF or STK ephemeris format, the corresponding functions (respectively yyyy_eph or xyzll_eph) simply reads the file and populates the EphemData structure: * MJD - vector for time stamp in MJD format * X - X component of the spacecraft position vector * Y - Y component of the spacecraft position vector * Z - Z component of the spacecraft position vector * Lat - vector for the Latitude in EC system * Lon - vector for the Longitude in EC system * Alt - vector for the Height in EC system * VelRA - vector for the velocity component in RA in EC system * VelDEC - vector for the velocity component in RA in EC system * Period - Ephemerides Period, not used with the available Ephemerides formats * SemiMajorAxis - not used with the available Ephemerides formats * ent - number of entries in each vector In the case of Two Line Elements file, the corresponding function, tlederive, calls readTLE, which searches for the specific satellite (Fermi), and parses the Two Line Elements parameters into the structure atElemTle. The function then uses the Simplified General Perturbations Satellite Orbit Model 4 (SGP4) algorithm to calculate the satellite position in the interval of interest with the requested time resolution, and then populates the EphemData structure. The accuracy of SGP4 is 0.1o in both latitude and longitude from the ground. Notice also that TLE files should not be used for intervals greater than 30 days since the accuracy tends to degrade due to perturbations. Units [double] The Units keyword is used as conversion factor to km since not all ephemerides have the position calculated in the same way. In the case of tlederive or xyzll_eph the value for Units is 1, while in the case of yyyy_eph it is 10000.0. Resolution [double] This keyword is used to specify a parameter for the time resolution for the orbit simulator. Clearly, if yyyy_eph or xyzll_eph are used to calculate the spacecraft position, then the time resolution of the ephemeris file must be the same as the specified one. An error is generated otherwise. If Two Line Elements file is used, then the spacecraft position is propagated using the indicated time resolution. Notice that the resolution must be specified in minutes, or fraction of a minute. Initial_RA [double] This parameter specifies the initial RA spacecraft position. Its value must be in decimal degrees, and 0.0 < RA < 360.0. Initial_DEC [double] This parameter specifies the initial DEC spacecraft position. Its value must be in decimal degrees, -90.0 < DEC < 90.0 OutPutFile [string] The OutPutFile option is used to specify the file name and path of the output spacecraft data file where all the data are written. OptFile [string] OptFile is an optional parameter used for debugging purposes. An ASCII version of the data is written to this file if it is specified. This is the only case where the absence of a parameter is not counted as an error. saafile [file] saafile gives the file name that contains the specification of the polygon, in terms of Latitude and Longitude, that defines the South Atlantic Anomaly (SAA) region. Only LATSAA files are supported. The function saa is called to calculate the South Atlantic Anomaly (SAA) entry/exit. The SAA region is approximated by a polygon, which is specified by the Longitude/Latitude of its vertices. Currently, there are two different ways to indicate the polygon, and the above function is capable of handling both of them. The algorithm used for the event times calculations is the same as the one used by TAKO. This routine determines if each ephemeris point is in or out of the SAA polygon. A filename should be passed which defines SAA polygon (longitude/latitude pairs). In addition to an ephemeris point being in the SAA polynomial, the ephemeris point prior will also be included as in the SAA region, since somewhere between the two points is when the actual SAA is entered. For this routine to work, the last latitude/longitude pair must be the same as the first. (EAA) [double] Earth Avoidance Angle Limit (degrees). (ELT_OFF_START) [double] Earth limb tracing exclusion start time (MJD). (ELT_OFF_STOP) [double] Earth limb tracing exclusion stop time (MJD). (chatter) This is an optional parameter used to control the verbosity level of the program. This keyword is only available in the file input mode. This is a hidden parameter. The default value is 2. (debug = no) Very similar to the previous keyword, the Debug option is used to control the output level of the program. This is a hidden parameter. The default value is no. (gui = no) Graphical user Interface (GUI) mode activated if "yes" is specified. This is a hidden parameter. The default value is "no". (mode = ql) Mode of automatic parameters. This is a hidden parameter. The default value is "ql". EXAMPLES The orbit simulator is designed so that its needed inputs can be passed either using the existing Fermi Science Tools infrastructure, by answering a prompt or as a list in a command, or using an input file. For this reason, the very first input of the simulator is the type of input, which can either be "console" or "file". To be prompted for gtorbsim options type on the command line: >gtorbsim You will be prompted for parameter values. Beware that not all parameters are prompted for: some of the parameter are "hidden". If you want to change one of the "hidden" parameters you should specify the values on the command line or modify its mode by editing the parameter file. For example if you do not want to overwrite the existing output file you should type in the command line: >gtorbsim clobber=no An example of how to run the tool from the console for 55 days of survey mode operation is given below > gtorbsim Type of input {file or console} [console] Input Type is: console start MJD[54867] stop MJD[54923] Timeline Type {TAKO, ASFLOWN or SINGLE}[SINGLE] Timeline SINGLE Command[|SURVEY| +50.0 |] Ephemeris file name[] Fermi_TLE_09033.78481577.tle Ephemeris function name[] tlederive Conversion factor to km[1] Time resolution in minutes[1] Initial RA[0] Initial DEC[0] OutPut File[] FT2_Fermi_TLE_09033.78481577.fits SAA file definition[] L_SAA_2008198.03 The same task could be performed from an ini file like this: start_MJD = 54867 stop_MJD = 54923 TLType = SINGLE Timeline = |SURVEY|+50.0| EphemFunc = tlederive EphemName = Fermi_TLE_09033.78481577.tle Units = 1.0 Resolution = 1 Initial_RA = 0 Initial_DEC = 0 saafile = L_SAA_2008198.03 OutPutFile = FT2_Fermi_TLE_09033.78481577.fits NOTE: To generate a realistic pointed mode observation a timeline generated by TAKO is needed. The FSSC does not provide the user with that tool. If you need to run a realistic pointed mode observation, please contact the FSSC. LIST OF BUGS There are certain parameters in real spacecraft files that currently cannot be reasonably calculated by gtorbsim. In these cases, that column is filled in with "NULL" in the output fits file. SEE ALSO gtobssim