gtorbsim.txt

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