Spy User's Guide =========================================================================== Last revised on 2012 SEP 19 by N. J. Bachman. Abstract -------------------------------------------------------- Spy is a command-driven utility for validating, inspecting, and analyzing SPK files. Introduction -------------------------------------------------------- Spy enables SPICE users to perform detailed inspections of the contents of binary SPK files in several ways: -- Sampling evaluated ephemeris data as a time series -- Dumping specified portions of an SPK file's contents -- Finding times when specified geometric criteria are satisfied by an ephemeris -- Checking sampled ephemeris data for excursions beyond specified value ranges -- Checking SPK file structure and low-level semantic validity Spy's user interface is implemented in standard Fortran 77, so all inputs and outputs are text-oriented. Spy is controlled via a command language; users enter commands at the Spy prompt. Optionally commands may be supplied via command file. By default, Spy writes results to the standard output stream. Optionally results may be captured in a specified ``save'' file. Spy also records in a log file the user commands issued during an interactive or batch session. Spy Command Set -------------------------------------------------------- The principal Spy command set consists of the following: SAMPLE command --- sample evaluated ephemeris data DUMP command --- display SPK contents FIND command --- find times when geometric constraints are met CHECK command --- perform semantic checks on files or data To support the above, the following additional commands control and display program settings: LOAD command --- load SPICE kernels UNLOAD command --- unload SPICE kernels SET command --- set defaults RESET command --- restore original settings of defaults SHOW command --- show defaults Finally, there are commands that control starting, stopping, logging, and assist with command entry: DEFINE command --- define a symbol DISCARD command --- close file opened by SAVE TO DO command --- repeat a previous command ECHO command --- show translated symbols EDIT command --- edit a previous command EXIT command --- exit the program HELP command --- display this text NO ECHO command --- disable echoing RECALL command--- show command history SAVE TO command --- save results to a file SET EDITOR command --- specify a command editor SHOW SYMBOL command --- show symbol definitions START command --- execute a command file UNDEFINE command --- delete a symbol definition Command Language Basics -------------------------------------------------------- Command Syntax -- Words in commands must be separated by blanks. -- Each command must end with a semicolon (except when running Spy in command-line mode). -- Commands can be continued across multiple lines. No continuation character is needed; just hit one carriage return and continue typing. -- In a continued command, leaving a line entirely blank causes the command to be discarded. -- Commands are case-insensitive, except for file names and time format tokens. Symbols Use symbols to abbreviate words or commands. The syntax is DEFINE ; for example, DEFINE QUIT EXIT; DEFINE ABCORR ABERRATION CORRECTION; Symbols are evaluated recursively, for example: DEFINE COORDS COORDINATES; DEFINE LAT LATITUDINAL; DEFINE LATSAM SAMPLE STATES COORDS LAT; Symbols may not be used to override built-in commands such as DEFINE. Use SHOW SYMBOL ; to see the translation of a specific symbol; use SHOW SYMBOL *; to see all symbol translations. Use UNDEFINE ; to delete a user-defined symbol. Command files -------------------------------------------------------- You can create Spy ``command files'' by placing in a text file the same commands you'd normally execute interactively. Use command files to conveniently collect and execute groups of commands. For instance, a start-up command file is helpful for loading leapseconds kernels and defining your commonly used symbols. Command file comments are started with semicolons. In this document we'll use the expression ``execute a command file'' as a shortcut meaning ``execute the commands contained in a command file.'' In interactive mode, execute a command file by using the START command: START ; As a simple example, let the file lsk_cmd contain the lines: ; ; My setup file: ; LOAD leapseconds.ker; DEFINE QUIT EXIT; ; Commands that require interaction, such as EDIT, aren't supported in command files. Start-up -------------------------------------------------------- Interactive Mode To run Spy in interactive mode, type the program name (all lower case): spy Spy will display a start-up banner followed by the Spy interactive command prompt Spy > To make Spy execute a command file at start up, specify the command file after the -start keyword: spy -start The command file name may include any needed path specification. Spy will execute the commands in the file before displaying the command prompt. Typically a command file will contain names of kernels to load and any symbol definitions used to create command shortcuts. By default Spy creates a command log file when run in interactive mode. Log file creation is disabled using the ``-nolog'' option: spy -nolog -start In interactive mode, when an input command error is detected, a brief diagnostic message will be displayed. Additional information about the error can be obtained by typing ?; When the detailed error message contains a description of the syntax of the expected command, often only a portion of the actual syntax description is shown. To see the full syntax of any Spy command, consult the syntax diagrams at the end of this document. Often shortcuts are available to simplify recovery from command errors. Spy supports display, editing and re-execution of past commands, so it is usually unnecessary to start from scratch when correcting a command failure. See the sections below on the RECALL, DO, and EDIT commands for details. Batch Mode To run Spy in batch mode, specify the name of a command file following the -start keyword; Spy will execute the commands in the file and then terminate. By default Spy will create a log file. No prompt will be shown. The ``-b'' option invokes batch mode: spy -b -start Command line mode In this mode, Spy will optionally execute a specified command file, then execute a command typed on the host system command line. This method doesn't create a log file; SAVE TO and DISCARD (see Logging below) are not supported. Use output redirection to capture results in a file. The ``-cl'' option invokes command line mode: spy -cl -start For example, to see summary and parameter information from an SPK file, using the example command file lsk_cmd shown above, you could use the command spy -cl -start lsk_cmd DUMP DATA SPK SUMMARIES PARAMETERS BORDERS Spy commands entered on the host command line are not terminated with a semi-colon. They are continued across lines in the same (system-dependent) manner as any other host command. Some Spy commands executed in command-line mode don't require a set-up file because these commands don't perform time conversion or other computations dependent on auxiliary loaded kernels. For example, to see the file record information from an SPK file, you could use the command spy -cl DUMP FILE RECORD SPK Spy's command-line mode can be convenient for processing multiple files using the host command language. For example, on a Unix system, one could run Spy's CHECK INTEGRITY command on a set of files having names of the form *.bsp as follows: foreach file (*.bsp) spy -cl -start lsk_cmd CHECK INTEGRITY SPK $file MESSAGE LIMIT 3 end The RECALL and DO Commands -------------------------------------------------------- The RECALL command displays a short, numbered list of recent commands. This list is called the ``command buffer,'' ``command history list,'' or the ``history list.'' For example, after entering the commands set target 5; set observer earth; sample position frame j2000 aberration correction LT+S start time jan 1 2006 stop time jan 1 2007 n 10; the command recall; produces the output 3 set target 5; 2 set observer earth; 1 sample position frame j2000 aberration correction LT+S start time jan 1 2006 stop time jan 1 2007 n 10; The most recent command always has index 1. As each new command is entered, the indices of buffered commands are incremented. Any of the commands in the list may be repeated using the DO command. For example, the command do 1; will execute the SAMPLE command above. The command serving as the target of a RECALL or DO command may be identified by either its integer index in the history list or by an initial substring of the first word of the command, if that word is sufficient to identify the command. When a substring is used to identify the command and the substring matches multiple history list entries, the most recent matching command is selected. Continuing the example above, we can execute the SAMPLE command by typing any of do 1; do sample; do sam; do s; When a command in the To re-execute the most recent SET command, we could type either of do set; do 2; The earlier SET command can only be referenced by its list index: do 3; If we simply want to see rather than execute a previous command, we can use the reference methods shown above together with the verb RECALL in place of DO. Given the command history shown above, for example, the command recall 3; displays, but does not execute, the command set target 5; The EDIT Command -------------------------------------------------------- Previous commands can be modified and re-executed using the EDIT command. As with the RECALL and DO commands, previous commands to be edited may be referenced by command history index or by initial command substring. For example, if the RECALL command displays the command history 3 load lsk; 2 set page width 170; 1 load de405s.bsp; we can edit the most recent LOAD command by typing edit load; We can edit the earlier LOAD command by typing edit 3; The EDIT command presents the selected command in an editor buffer, where the command text may modified and saved, after which the saved command is executed. The editor may be selected at run time via the SET EDITOR command. For example, on a Unix system, to switch from the default vi editor to the xemacs editor, type set editor xemacs; The selected editor must be specified with sufficient path information in order for the host system to run it. To see the current editor setting, type show environment; Loading and Unloading Kernels -------------------------------------------------------- To make kernels available for use by Spy, use the LOAD command. Typically a leapseconds kernel should be loaded at start-up. LOAD ; You can make Spy unload a kernel using the UNLOAD command: UNLOAD ; In many cases you need to load supporting kernels to enable operation of certain SAMPLE, FIND, or CHECK commands. Examples: -- You may need to load multiple SPK files to define state vectors of interest. -- You will need to load a PCK file to provide body spin sense and reference ellipsoid shape data in order to sample states in planetographic coordinates. -- You also may load CK, PCK or FK kernels to define certain reference frames. For example, you might load a frame kernel defining a view frame for a particular spacecraft. -- To sample ephemeris information in the form of osculating elements, you must load a text kernel containing GM data for the central body. The form of the kernel data is BODYnnn_GM = where nnn is the NAIF integer ID code of the body and the GM value is specified in units of 3 2 km / s For example, the GM for the Earth may be specified as BODY399_GM = 3.98600436E5 You do not need to load SPK files that are the target of DUMP commands; this is because these commands operate on a specific file that is named in the command or is identified as a default. Managing Default Settings -------------------------------------------------------- Spy maintains several program variables that control Spy's behavior; the values of these variables are called Spy's ``default settings.'' Use the SHOW ALL to see the default settings. Loaded kernels are included in the display. At start-up, the command show all; yields Spy default settings ================================================================== Aberration Correction: NONE Angular Units : DEGREES Coordinates : RECTANGULAR Frame : is not set N : 10 Number Format : 1PE15.8 Observer : is not set Page Width : 150 Reference Body : is not set SPK : is not set Start Time : is not set Step Size : is not set Stop Time : is not set Target : is not set Time Format : YYYY-MON-DD HR:MN:SC.###### (TDB) ::TDB ================================================================== Use SHOW ; to see only a particular default item. Use SET to change a default value. Examples: set target moon; set observer earth; set frame j2000; set page width 175; set number format E24.16; set time format numeric E15.6; set step size 1.e3; set coordinates geodetic; set reference body earth; set spk de405s.bsp; Setting defaults allows you to abbreviate some commands, since Spy will use applicable default values when required arguments are omitted from a command. Note that the set of loaded kernels can't be changed by a SET command, but you can set the default SPK file so that you don't need to specify it by name when using commands such as DUMP DATA that operate on a single target SPK file. Use RESET to set a default to its original value, for example: reset time format; Page Width -------------------------------------------------------- The variable ``PAGE WIDTH'' refers to the number of columns Spy assumes are available for formatting its output. By default, Spy's output occupies 150 columns. The minimum page width setting Spy supports is 80 columns. Spy will automatically wrap outputs to accommodate the specified page width. Number and Time Formats -------------------------------------------------------- Many Spy commands, such as SAMPLE and DUMP, produce output in the form of double precision numbers and time strings. Spy allows you to customize the formats of these outputs. Number Formats On output, double precision data can be expressed as formatted floating point decimal or hexadecimal numbers. The syntax of a number format specification is NUMBER FORMAT Number format specifications may by used to set the default number format via the SET NUMBER FORMAT command or as options in other commands. Specify double precision number formats using either Fortran floating point formats such as E15.8 1PE24.16 F19.6 or the string HEX The latter invokes formatting using SPICELIB hexadecimal scientific notation. Hexadecimal formats allow comparison of outputs at the bit level: if two numbers have the same hexadecimal representation (as output by Spy), they are identical. Such comparisons are generally not valid when decimal formats are used, even when mantissas are displayed to full double precision (about 16 digits for IEEE-compliant double precision implementations). Time Formats The syntax of an output time format specification is TIME FORMAT Output time format specifications may by used to set the default output time format via the SET TIME FORMAT command or as options in other commands. Output time formats can be either string formats supported by the SPICELIB routine TIMOUT (timout_c in CSPICE) or numeric formats. TIMOUT supports a wide variety of formats; we cover just a few examples here. See the text below the examples for an explanation of the tokens used in the example format strings. Suppose the time value to be displayed is 2006 Jan 2 03:04:05.678 TDB Then the following format strings produce the outputs shown: Format String Output ------------- ------ YYYY-MON-DD HR:MN:SC.### ::TDB TDB 2006-JAN-02 03:04:05.678 TDB MM/DD/YYYY HR:MN:SC.## ::TDB 01/02/2006 03:04:05.67 MM/DD/YYYY HR:MN:SC.## ::TDB::RND 01/02/2006 03:04:05.68 MM-DD-YYYY HR:MN:SC.### ::UTC UTC 01-02-2006 03:03:00.494 UTC DD MM YYYY Wkd HR:MN:SC.### ::UTC 02 01 2006 Mon 03:03:00.494 YYYY-MM-DDTHR:MN:SC.###### 2006-01-02T03:03:00.494042 YYYY-DOY/HR:MN:SC 2006-032/06:03:59 JULIAND.######## ::TDB 2453737.62784350 JULIAND.######## ::TDB JD TDB 2453737.62784350 JD TDB JULIAND.######## 2453737.62708900 JULIAND.######## (JD UTC) 2453737.62708900 (JD UTC) JULIAND.## JDUTC ::RND 2453737.63 JDUTC In TIMOUT-style format strings, the following tokens are among those recognized and which receive special handling by TIMOUT. Token Meaning ----- ------- YYYY 4-digit year MON 3-letter month MM 2-digit month DD 2-digit day DOY 3-digit day of year HR 2-digit hour MN 2-digit minute SC 2-digit integral second Wkd 3-letter day of week, first letter capitalized .### 3-digit fraction of second or day JULIAND integer portion of Julian date ::TDB Output is expressed in TDB time system ::TDT Output is expressed in TDT (TT) time system ::TDB Output is expressed in UTC time system ::RND Output is to be rounded rather than truncated The tokens below, which appear in the examples, are not recognized by TIMOUT and are simply copied into the output string. These tokens are labels which disambiguate the strings: TDB UTC JD TDB (JD UTC) JDUTC Note that TIMOUT-style string format specifications are case-sensitive and must be entered in the exact form expected by TIMOUT. Unrecognized tokens will be copied verbatim into output strings. See the header of the SPICELIB routine TIMOUT (or the CSPICE routine timout_c) for a detailed discussion of supported output formats. Specify numeric output time formats using the phrase NUMERIC where is one of the numeric formats described in the section ``Number Formats'' above. Numeric formats always display times in the form of seconds past J2000 TDB. Use TIMOUT-style formats such as those shown above to obtain Julian date output formats. Spy's allowed input time formats are those supported by the SPICELIB routine STR2ET (str2et_c in CSPICE). Because input time strings must be unambiguous, the set of supported input formats is not nearly as large as the set of supported output formats. Below are a few examples of recognized strings: String Time string is interpreted as ------ ----------------------------- 2006 JAN 2 03:04:05.678 TDB TDB calendar date jan 2 2006 03:04:05.678 tdt TDT calendar date 01/02/2006 03:03:00.494 UTC UTC calendar date 01/02/2006 03:03:00.494 UTC calendar date 2453737.62784350 jd Tdb TDB Julian date 2453737.62784350 JD utc UTC Julian date 2453737.6 UTC Julian date Time string inputs, unlike output time formats, are case-insensitive. See the header of the SPICELIB routine STR2ET (or the CSPICE routine str2et_c) for a detailed discussion of supported input formats. Body names and IDs -------------------------------------------------------- In general, bodies (ephemeris objects) may be identified in Spy commands by either their names or their integer ID codes. Body names are case-insensitive. For example, Jupiter may be identified by the strings 'JUPITER' or 'jupiter', or by the ID code 599. Spy supports body names containing up to five words separated by blanks. Bodies whose names contain more than five words must be specified by integer ID codes. Additional name-ID associations may be introduced to Spy at run time by loading a text kernel containing the associations. See the NAIF_IDS Required Reading for further information. Logging -------------------------------------------------------- In modes other than command-line, Spy will create a command log by default. Use the keyword -nolog at start-up to disable command logging: spy -nolog Spy will attempt to create the command log in the current working directory. If a log file cannot be opened due to inadequate user permissions, Spy will display an error message and continue running. To save results to a specified file while continuing to send results to the standard output stream, use the command save to ; You can only save to one file at a time; a second SAVE command will cut off output to the previous SAVE file. To command Spy to discontinue saving results to the file, type discard; Shut-down -------------------------------------------------------- To exit Spy gracefully, type EXIT; If you prefer to use an alternative command such as the verb ``quit'' you can define that verb as a symbol in your start-up file: DEFINE QUIT EXIT; To kill Spy immediately, type the host system interrupt command, for example ``Control C.'' Note that the Unix command ``Control D'' is not recognized by Spy. Sampling Ephemeris Data =========================================================================== The SAMPLE Command -------------------------------------------------------- The SAMPLE command allows you to see a time-tagged list of evaluated states or other ephemeris data. Like the SPICE SPK system's subroutine API, the SAMPLE command can draw on data from multiple loaded SPK files or other kernels. The basic form of the SAMPLE command is SAMPLE Here the ephemeris item may be any of ACCELERATION (obtained via numerical differentiation) ACCELERATION MAGNITUDE (magnitude of derived acceleration) DISTANCE DERIVED SPEED (magnitude of derived velocity) DERIVED VELOCITY (obtained via numerical differentiation) ELEMENTS POSITION SPEED STATE VELOCITY The quantities ACCELERATION and DERIVED VELOCITY are obtained via numerical differentiation; ACCELERATION MAGNITUDE and DERIVED SPEED are the respective magnitudes of the former quantities. Derived velocity can be compared to velocity obtained directly from the SPICE SPK system (via the SAMPLE VELOCITY command) to identify mathematical inconsistencies between an SPK file's position and velocity data. Sampled data are expressed in the units 2 2 km, km/s, km/s, degrees, degrees/s, degrees/s Angular units may be reset to any units supported by the SPICELIB routine CONVRT (convrt_c in CSPICE). Length and time units are not adjustable. The parameters may be set within the command or may be supplied as defaults. Parameters specified in a command override default values. The minimum parameter set that must be provided is START TIME