March 28, 2005
The extensive scope of the ICY system's functionality includes features the average user may not expect or appreciate, features NAIF refers to as "Other Stuff." This workbook includes a set of lessons to introduce the beginning to moderate user to a several such features.
The lessons provide a brief description to several related sets of routines, associated reference documents, a programming task designed to teach the use of the routines, and an example solution to the programming problem.
This workbook includes several lessons to demonstrate use of the less
celebrated ICY routines.
The technical complexity of the various ICY subsystems mandates an
extensive, user-friendly documentation set. The set differs somewhat
depending on your choice of development language, FORTRAN, C, or IDL,
but provides the same information with regards to SPICE operation.
The sources for a user needing information concerning the ICY System or other NAIF product:
NAIF Required Reading (*.req) documents introduce the functionality of
particular ICY subsystems:
cells.req ek.req intrdctn.req problems.req ck.req ellipses.req kernel.req rotation.req cspice.req error.req naif_ids.req scanning.req daf.req frames.req pck.req sclk.req das.req icy.req planes.req sets.req spc.req spk.req symbols.req time.req windows.reqNAIF Users Guides (*.ug) describe the proper use of particular ICY tools:
brief.ug convert.ug spacit.ug tictoc.ug chronos.ug inspekt.ug spkmerge.ug tobin.ug ckbrief.ug mkspk.ug states.ug toxfr.ug commnt.ug simple.ug subpt.ug version.ugThese text documents exist in the 'doc' directory of the main Toolkit directory:
../icy/doc/HTML format documentation
As of delivery N57, the ICY distributions include HTML versions of Required Readings and Users Guides, accessible from the HTML documentation directory:
../icy/doc/html/index.html
All SPICELIB and CSPICE source files include usage and design
information incorporated in a comment block known as the "header."
A header consists of several marked sections:
The Icy package includes the CSPICE Reference Guide, an index of all
CSPICE wrapper APIs with hyperlinks to API specific documentation.
Each API documentation page includes cross links to any other wrapper
API mentioned in the document.
..icy/doc/html/cspice/index.htmlAlso included is Icy Reference Guide, an index of all Icy APIs with hyperlinks to API specific documentation. Each API documentation page includes cross-links to any other Icy APIs mentioned in the document and a link to the API documentation for the CSPICE routine called by the Icy interface.
..icy/doc/html/icy/index.html
A set of Microsoft PowerPoint presentations provide a general overview
of the complete ICY toolkit. Download the set at:
http://naif.jpl.nasa.gov/naif/tutorials.htmlAccess individual files in the 'office/individual_docs/' directory; an archive of all tutorial files is available in the 'office/packages/' directory.
Several workbooks use SPICE text kernels. SPICE identifies a text
kernel as an ASCII text file containing the mark-up tags the kernel
subsystem requires to identify data assignments in that file, and
"name=value" data assignments.
The subsystem uses two tags:
\begintextand
\begindatato mark information blocks within the text kernel. The \begintext tag specifies all text following the tag as comment information to be ignored by the subsystem.
Things to know:
\begintext ... commentary information on the data assignments ... \begindata ... data assignments ...
Scalar assignments.
VAR_NAME_DP = 1.234 VAR_NAME_INT = 1234 VAR_NAME_STR = 'FORBIN'Please note the use of a single quote in string assignments.
Vector assignments. Vectors must contain the same type data.
VEC_NAME_DP = ( 1.234 , 45.678 , 901234.5 ) VEC_NAME_INT = ( 1234 , 456 , 789 ) VEC_NAME_STR = ( 'FORBIN', 'FALKEN', 'ROBUR' ) also VEC_NAME_DP = ( 1.234, 45.678, 901234.5 ) VEC_NAME_STR = ( 'FORBIN', 'FALKEN', 'ROBUR' )Time assignments.
TIME_VAL = @31-JAN-2003-12:34:56.798 TIME_VEC = ( @01-DEC-2004, @15-MAR-2004 )The at-sign character '@' indicates a time string. The pool subsystem converts the strings to double precision TDB (a numeric value). Please note, the time strings must not contain embedded blanks. WARNING - a TDB string is not the same as a UTC string.
The above examples depict direct assignments via the '=' operator. The kernel pool also permits incremental assignments via the '+=' operator.
Please refer to the kernels required reading, kernel.req, for additional information.
The lessons may include kernels a program must load to operate. For
this workbook, a user can download all kernels from the NAIF anonymous
ftp site:
ftp://naif.jpl.nasa.gov/pub/naif/generic_kernels FILE NAME TYPE DESCRIPTION ----------------------- ---- ---------------------- naif0007.tls LSK Generic LSK leapseconds.tls LSK The current leapseconds kernel (naif0007.tls as of May 2004) de405s.bsp SPK Planet Ephemeris SPK pck00007.tpc PCK Generic PCK
The code examples listed in this workbook include corresponding
outputs for the described inputs. The output of a given example on a
particular platform may not exactly match that shown since compilers
and math libraries differ between platform architectures.
Lesson Goals:
This lesson demonstrates us of the kernel subsystem to load, unload, and list loaded kernels. Comprehension of kernel file data access precedence. Data loaded last (later) has precedence over similar data loaded first (earlier).
This lesson requires creation of a SPICE meta kernel.
Knowledge of information in the kernels.req document, the mk.ppt and
intro_to_kernels.ppt tutorial files.
Write a program to load a meta kernel, interrogate the ICY system for
the names and types of all loaded kernels, then demonstrate the unload
functionality and the resulting effects.
You can use two versions of a meta kernel with code examples
(meta.ker) in this lesson. Either a kernel with explicit path
information:
\begindata KERNELS_TO_LOAD = ( 'kernels/spk/de405s.bsp', 'kernels/pck/pck00007.tpc', 'kernels/lsk/leapseconds.tls') \begintext... or a more generic meta kernel using the PATH_VALUES/PATH_SYMBOLS functionality to declare path names as variables:
\begintext Define the paths to the kernel directory. Use the PATH_SYMBOLS as aliases to the paths. \begindata PATH_VALUES = ( 'kernels/lsk', 'kernels/spk', 'kernels/pck' ) PATH_SYMBOLS = ( 'LSK', 'SPK', 'PCK' ) KERNELS_TO_LOAD = ( '$LSK/naif0007.tls', '$SPK/de405s.bsp', '$PCK/pck00007.tpc' ) \begintext
PRO KERNEL ;; ;; Assign the path name of the meta kernel to META. ;; META = 'meta.ker' ;; ;; Load the meta kernel then use KTOTAL to interrogate the SPICE ;; kernel subsystem. ;; cspice_furnsh, META cspice_ktotal, 'ALL', count print, 'Kernel count after load: ', count ;; ;; Loop over the number of files; interrogate the SPICE system ;; with kdata_c for the kernel names and the type. 'found' ;; returns a boolean indicating whether any kernel files of ;; the specified type were loaded by the kernel subsystem. ;; This example ignores checking 'found' as kernels are known ;; to be loaded. ;; for i = 0, (count-1) do begin cspice_kdata, i, 'ALL', file, type, source, handle, found print, 'File ' + file print, 'Type ' + type print, 'Source ' + source print endfor ;; ;; Unload one kernel then check the count. ;; cspice_unload, 'kernels/spk/de405s.bsp' cspice_ktotal, 'ALL', count ;; ;; The subsystem should report one less kernel. ;; print, 'Kernel count after one unload : ', count ;; ;; Now unload the meta kernel. This action unloads all ;; files listed in the meta kernel. ;; cspice_unload, META ;; ;; Check the count. Icy should return a count of zero. ;; cspice_ktotal, 'ALL', count print, 'Kernel count after meta unload: ', count END
First we see the number of all loaded kernels returned from the
cspice_ktotal call:
Kernel count after load: 4Now the cspice_kdata loop returns the name of each loaded kernel, the type of kernel (SPK, CK, TEXT, etc.) and the source of the kernel - the mechanism that loaded the kernel. The source either identifies a meta kernel, or contains an empty string. An empty source string indicates a direct load of the kernel with a cspice_furnsh call.
File meta.ker Type META Source File kernels/spk/de405s.bsp Type SPK Source meta.ker File kernels/pck/pck00007.tpc Type TEXT Source meta.ker File kernels/lsk/naif0007.tls Type TEXT Source meta.ker Kernel count after one unload: 3 Kernel count after meta unload: 0
Lesson Goals:
The lesson demonstrates the ICY system's facility to retrieve different types of data (string, numeric, scalar, array) from the kernel pool.
For the code examples, use this generic text kernel (cassini.ker) containing PCK-type data, kernels to load, and example time strings:
\begintext Ring model data. \begindata BODY699_RING1_NAME = 'A Ring' BODY699_RING1 = (122170.0 136780.0 0.1 0.1 0.5) BODY699_RING1_1_NAME = 'Encke Gap' BODY699_RING1_1 = (133405.0 133730.0 0.0 0.0 0.0) BODY699_RING2_NAME = 'Cassini Division' BODY699_RING2 = (117580.0 122170.0 0.0 0.0 0.0) \begintext The kernel pool recognizes values preceded by '@' as time values. When read, the kernel subsystem converts these representations into double precision ephemeris time. Caution: The kernel subsystem interprets the time strings identified by '@' as TDB. The same string passed as input to @STR2ET is processed as UTC. The three expressions stored in the EXAMPLE_TIMES array represent the same epoch. \begindata EXAMPLE_TIMES = ( @APRIL-1-2004-12:34:56.789, @4/1/2004-12:34:56.789, @JD2453097.0242684 ) \begintext Name the kernels to load. Use path symbols. \begindata PATH_VALUES = ('kernels/spk', 'kernels/pck', 'kernels/lsk') PATH_SYMBOLS = ('SPK' , 'PCK' , 'LSK' ) KERNELS_TO_LOAD = ( '$SPK/de405s.bsp', '$PCK/pck00007.tpc', '$LSK/leapseconds.tls') \begintext
Knowledge of the material in the kernels.req document and the
intro_to_kernels.ppt tutorial file.
The main references for pool routines are found in the source files or API documentation for the particular routines.
Write a program to retrieve particular string and numeric text kernel
variables, both scalars and arrays. Interrogate the kernel pool for
assigned variable names.
PRO KERVAR ;; ;; Define the max number of kernel variables ;; of concern for this examples. ;; N_ITEMS = 20 ;; ;; Define the maximum length for any string. 80 characters, ;; plus on for the C null terminator. ;; STRLEN = 81 ;; ;; Load the example kernel containing the kernel variables. ;; The kernels defined in KERNELS_TO_LOAD load into the ;; kernel pool with this call. ;; cspice_furnsh, "cassini.ker" ;; ;; Initialize the start value. This values indicates ;; index of the first element to return if a kernel ;; variable is an array. start = 0 indicates return everything. ;; start = 1 indicates return everything but the first element. ;; start = 0; ;; ;; Set the template for the variable names to find. Let's ;; look for all variables containing the string RING. ;; Define this with the wildcard template '*RING*'. Note: ;; the template '*RING' would match any variable name ;; ending with the RING string. ;; tmplate = "*RING*" ;; ;; We're ready to interrogate the kernel pool for the ;; variables matching the template. gnpool tells us: ;; 1. Does the kernel pool contain any variables that ;; match the template (value of found). ;; 2. If so, how many variables? ;; 3. The variable names. (cvals, an array of strings) ;; cspice_gnpool, tmplate, start, N_ITEMS, STRLEN, cvals, found if ( found) then begin print, "No. variables matching template: ", n_elements(cvals) endif else begin print, "No kernel variables matched template" stop endelse ;; ;; Okay, now we know something about the kernel pool ;; variables of interest to us. Let's find out more... ;; for i=0, (n_elements(cvals)-1) do begin ;; ;; Use dtpool to return the dimension and type, ;; C (character) or N (numeric), of each pool ;; variable name in the cvals array. ;; cspice_dtpool, cvals[i], found, dim, type print, cvals[i] print, " No. items: " + string(dim) + " Of type: " + type ;; ;; Test character equality, 'N' or 'C'. ;; case type of 'N': begin ;; ;; If 'type' equals 'N', we found a numeric array. ;; In this case any numeric array will be an array ;; of double precision numbers ("doubles"). ;; cspice_gdpool retrieves doubles from the ;; kernel pool. ;; cspice_gdpool, cvals[i], start, N_ITEMS, dvars, $ found for j=0, (n_elements(dvars)-1) do begin print, " Numeric value: ", dvars[j] endfor end 'C': begin ;; ;; If 'type' equals 'C', we found a string array. ;; gcpool retrieves string values from the ;; kernel pool. ;; cspice_gcpool, cvals[i], start, N_ITEMS, STRLEN, $ cvars, found for j=0, (n_elements(cvars)-1) do begin print, " String value : ", cvars[j] endfor end endcase print endfor ;; ;; Now look at the time variable EXAMPLE_TIMES. Extract this ;; value as an array of doubles. ;; cspice_gdpool, "EXAMPLE_TIMES", start, N_ITEMS, dvars, found print, "EXAMPLE_TIMES" for j=0, (n_elements(dvars)-1) do begin print, FORMAT='(A14,F24.5)', " Time value: ", dvars[j] endfor END
The program runs and first reports the number of kernel pool variables
matching the template, 6.
No. variables matching template: 6The program then loops over the cspice_dtpool 6 times, reporting the name of each pool variable, the number of data items assigned to that variable, and the variable type. Within the cspice_dtpool loop, a second loop outputs the contents of the data variable using cspice_gcpool or cspice_gdpool.
BODY699_RING1 No. items: 5 Of type: N Numeric value: 122170.00000000 Numeric value: 136780.00000000 Numeric value: 1.0000000000000D-01 Numeric value: 1.0000000000000D-01 Numeric value: 0.50000000000000 BODY699_RING2 No. items: 5 Of type: N Numeric value: 117580.00000000 Numeric value: 122170.00000000 Numeric value: 0. Numeric value: 0. Numeric value: 0. BODY699_RING1_1_NAME No. items: 1 Of type: C String value: Encke Gap BODY699_RING2_NAME No. items: 1 Of type: C String value: Cassini Division BODY699_RING1_NAME No. items: 1 Of type: C String value: A Ring BODY699_RING1_1 No. items: 5 Of type: N Numeric value: 133405.00000000 Numeric value: 133730.00000000 Numeric value: 0. Numeric value: 0. Numeric value: 0.Note the final time value differs from the previous values in the final two decimal places despite the intention that all three strings represent the same time. This results from round-off when converting a decimal Julian day representation to the seconds past J2000 ET representation.
EXAMPLE_TIMES Time value: 134094896.78900 Time value: 134094896.78900 Time value: 134094896.78975
Lesson Goals:
The ICY system provides functions to convert coordinate tuples between Cartesian and various non Cartesian coordinate systems including conversion between geodetic and rectangular coordinates.
This lesson presents these coordinate transform routines for rectangular, cylindrical, and spherical systems.
Basic knowledge of the standard coordinate systems used in celestial
mechanics. The contents of concepts.ppt and derived_quant.ppt tutorial
files.
Write a program to convert a Cartesian 3-vector representing some
location to the other coordinate representations. Use the position of
the Moon with respect to Earth in an inertial and non-inertial
reference frame as the example vector.
PRO COORD ;; ;; Define the inertial and non inertial frame names. ;; ;; Initialize variables or set type. All variables ;; used in a PROMPT construct must be initialized ;; as strings. ;; INRFRM = "J2000" NONFRM = "IAU_EARTH" timstr = '' ;; ;; Load the needed kernels using a cspice_furnsh call on the ;; meta kernel. ;; cspice_furnsh, "meta.ker" ;; ;; Prompt the user for a time string. Convert the ;; time string to ephemeris time J2000 (ET). ;; read, timstr, PROMPT = "Time of interest: " cspice_str2et, timstr, et ;; ;; Access the kernel pool data for the triaxial radii of the ;; Earth, rad[0] holds the equatorial radius, rad[2] ;; the polar radius. ;; cspice_bodvrd, "EARTH", "RADII", 3, rad ;; ;; Calculate the flattening factor for the Earth. ;; ;; equatorial_radius - polar_radius ;; flat = ________________________________ ;; ;; equatorial_radius ;; flat = (rad[0] - rad[2])/rad[0]; ;; ;; Make the cspice_spkpos call to determine the apparent ;; position of the Moon w.r.t. to the Earth at 'et' in the ;; inertial frame. ;; cspice_spkpos, "MOON", et, INRFRM, "LT+S","EARTH", pos, ltime ;; ;; Show the current frame and time. ;; print, " Time : " , timstr print, " Inertial Frame: ", inrfrm ;; ;; First convert the position vector ;; X = pos[0], Y = pos[1], Z = pos[2], to RA/DEC. ;; cspice_recrad, pos, range, ra, dec print, " Range/Ra/Dec" print, " Range: ", range print, " RA : ", ra * cspice_dpr() print, " DEC : ", dec* cspice_dpr() ;; ;; ...latitudinal coordinates... ;; cspice_reclat, pos, range, lon, lat print, " Latitudinal" print, " Rad : ", range print, " Lon : ", lon * cspice_dpr() print, " Lat : ", lat * cspice_dpr() ;; ;; ...spherical coordinates use the colatitude, ;; the angle from the Z axis. ;; cspice_recsph, pos, range, colat, lon print, " Spherical" print, " Rad : ", range print, " Lon : ", lon * cspice_dpr() print, " Colat: ", colat * cspice_dpr() ;; ;; Make the cspice_spkpos call to determine the apparent ;; position of the Moon w.r.t. to the Earth at 'et' in the ;; non-inertial, body fixed, frame. ;; cspice_spkpos, "MOON", et, nonfrm, "LT+S","EARTH", pos, ltime print print, " Non-inertial Frame: " + nonfrm ;; ;; ...latitudinal coordinates... ;; cspice_reclat, pos, range, lon, lat print, " Latitudinal " print, " Rad : ", range print, " Lon : ", lon * cspice_dpr() print, " Lat : ", lat * cspice_dpr() ;; ;; ...spherical coordinates... ;; cspice_recsph, pos, range, colat, lon print, " Spherical" print, " Rad : ", range print, " Lon : ", lon * cspice_dpr() print, " Colat: ", colat * cspice_dpr() ;; ;; ...finally, convert the position to geodetic coordinates. ;; cspice_recgeo, pos, rad[0], flat, lon, lat, range print, " Geodetic" print, " Rad : ", range print, " Lon : ", lon * cspice_dpr() print, " Lat : ", lat * cspice_dpr() print END
Input a time/date at which to calculate the Moon's position. (the
'TDB' tag indicates a Barycentric Dynamical Time value).
Time of interest: Feb 3 2002 TDBExamine the Moon position in the J2000 inertial frame, display the time and frame:
Time : Feb 3 2002 TDB Inertial Frame: J2000Convert the Moon Cartesian coordinates to right ascension declination.
Range/Ra/Dec Range: 369340.82 RA : 203.64369 DEC : -4.9790104Latitudinal. Note the difference in the expressions for longitude and right ascension though they represent a measure of the same quantity. The RA/DEC system measures RA in the interval [0,2Pi). Latitudinal coordinates measures longitude in the interval (-Pi,Pi].
Latitudinal Rad : 369340.82 Lon : -156.35631 Lat : -4.9790104Spherical. Note the difference between the expression of latitude in the Latitudinal system and the corresponding Spherical colatitude. The spherical coordinate system uses the colatitude, the angle measure away from the positive Z axis. Latitude is the angle between the position vector and the x-y (equatorial) plane with positive angle defined as toward the positive Z direction
Spherical Rad : 369340.82 Lon : -156.35631 Colat: 94.979010The same position look-up in a body fixed (non-inertial) frame, IAU_EARTH.
Non-inertial Frame: IAU_EARTHLatitudinal coordinates return the geocentric latitude.
Latitudinal Rad : 369340.82 Lon : 70.973950 Lat : -4.9896751Spherical.
Spherical Rad : 369340.82 Lon : 70.973950 Colat: 94.989675Geodetic. The cartographic lat/lon.
Geodetic Rad : 362962.84 Lon : 70.973950 Lat : -4.9902493
Lesson Goals:
Introduce the routines used for advanced manipulation of time strings. Understand the concept of ephemeris time (ET) as used in ICY.
Knowledge of the time.req document, the time.ppt, lsk_and_sclk.ppt,
and other_functions.ppt tutorial files.
Also, examine the header of cspice_timout for a list of the string markers used by cspice_timout and cspice_tpictr to describe time string format. Always keep in mind cspice_str2et assumes 'UTC' unless indicated otherwise.
Demonstrate the advanced functions of the time utilities with regard
to formatting of time strings for output. Formatting options include
altering calendar representations of the time strings. Convert
time-date strings between different ICY-supported formats.
Caution: Be sure to assign sufficient string lengths for time
formats/pictures.
PRO TIC ;; ;; Assign the LSK variable to the name of the leapsecond, ;; kernel and create an arbitrary time string. ;; ;; Define the maximum length for any string, 80 ;; characters plus one null terminator for C. ;; CALSTR = "Mar 15, 2003 12:34:56.789 AM PST"; LSK = "kernels/lsk/leapseconds.tls"; AMBIGSTR = "Mar 15, 79 12:34:56"; STRLEN = 81 ;; ;; Load the leapseconds kernel. ;; cspice_furnsh, LSK print, "Original time string : " + CALSTR ;; ;; Convert the time string to the number of ephemeris ;; seconds past the J2000 epoch. This is the most common ;; internal time representation used by the CSPICE ;; system; CSPICE refers to this as ephemeris time (ET). ;; cspice_str2et, CALSTR, et print, "Corresponding ET : ", et ;; ;; Make a picture of an output format. Describe a Unix-like ;; time string then send the picture and the 'et' value through ;; cspice_timout to format and convert the ET representation ;; of the time string into the form described in cspice_timout. ;; The '::UTC-7' token indicates the time zone for the 'timstr' ;; output - PDT. 'PDT' is part of the output, but not a time ;; system token. ;; cspice_timout, et, 'Wkd Mon DD HR:MN:SC PDT YYYY ::UTC-7', $ STRLEN, timstr print, "Time in string format 1 : " + timstr ;; ;; Create another picture, this time combine a calendar, ;; 2 digit year , with Julian Day format. ;; cspice_timout, et, $ 'Wkd Mon DD HR:MN ::UTC-7 YR (JULIAND.##### JDUTC)', $ STRLEN, timstr print, "Time in string format 2 : " + timstr ;; ;; Why create a picture by hand when Icy can do it for you? ;; Input a string to cspice_tpictr with the format of interest. ;; 'ok' returns a boolean indicating whether an error occurred ;; while parsing the picture string, if so, an error diagnostic ;; message returns in 'error'. In this example the picture ;; string is known as correct.. ;; cspice_tpictr, '12:34:56.789 P.M. PDT January 1, 2006', $ STRLEN, pictr, ok, error if ( NOT ok ) then begin print, 'ERROR from cspice_tpictr: ' + error stop endif cspice_timout, et, pictr, STRLEN, timstr print, "Time in string format 3 : " + timstr ;; ;; Two digit year representations often cause problems due to ;; the ambiguity of the century. The routine cspice_tsetyr gives ;; the user the ability to set a default range for 2 digit year ;; representation. SPICE uses 1969AD as the default start ;; year so the numbers inclusive of 69 to 99 represent years ;; 1969AD to 1999AD, the numbers inclusive of 00 to 68 represent ;; years 2000AD to 2068AD. ;; ;; The defined time string 'AMBIGSTR' contains a two-digit ;; year. Since the SPICE base year is 1969, the time subsystem ;; interprets the string as 1979. ;; cspice_str2et, AMBIGSTR, et1 ;; ;; Set 1980 as the base year causes SPICE to interpret the ;; time string's "79" as 2079. ;; cspice_tsetyr, 1980 cspice_str2et, AMBIGSTR, et2 ;; ;; Calculate the number of years between the two ET ;; representations, ~100. ;; print, "Years between evaluations : ", $ (et2 - et1)/cspice_jyear() ;; ;; Reset the default year to 1969 so other scripts use the ;; default. ;; cspice_tsetyr, 1969 END
Original time string : Mar 15, 2003 12:34:56.789 AM PST Corresponding ET : 100989360.974561 Time in string format 1 : Sat Mar 15 01:34:56 PDT 2003 Time in string format 2 : Sat Mar 15 01:34 03(2452713.85760 JDUTC) Time in string format 3 : 01:34:56.789 A.M. PDT March 15, 2003 Years between evaluations: 100.000000
Lesson Goal:
The Icy error subsystem differs from other SPICE packages in that the user cannot alter the state of the subsystem, rather the user can respond to an error signal using the "catch" function. This function natively receives and processes any SPICE error signaled from Icy. The user can therefore "catch" an error signal so as to respond in an appropriate manner.
Knowledge of material in the error.req document and the exceptions.ppt
tutorial file. Comprehension of the catch/throw concept.
Write an interactive program to return a state vector based on a
user's input. Code the program with the capability to recover from
user input mistakes, inform the user of the mistake, then continue to
run.
PRO ADDERR ;; ;; Set initial parameters. ;; SPICETRUE = 1L SPICEFALSE= 0L doloop = SPICETRUE; ;; ;; Load the data we need for state evaluation. ;; cspice_furnsh, "meta.ker" ;; ;; Start our input query loop to the user. ;; while (doloop) do begin ;; ;; Initialize the input value as a string. YOU MUST ;; do this to use PROMPT in a read. ;; targ = '' ;; ;; For simplicity, we request only one input. ;; The program calculates the state vector from ;; Earth to the user specified target 'targ' in the ;; J2000 frame, at ephemeris time zero, using ;; aberration correction LT+S (light time plus ;; stellar aberration). ;; read, targ, PROMPT= "Target: " if cspice_eqstr( targ, "NONE") then begin ;; ;; An exit condition. If the user inputs NONE ;; for a target name, set the loop to stop... ;; doloop = SPICEFALSE; endif else begin ;; ;; ...otherwise evaluate the state between the Earth ;; and the target. Initialize an error handler. ;; catch, err ;; ;; What if the program can't perform the evaluation? ;; Then ICY sets an error message informing ;; the user of the problem's cause. ;; ;; Examine the value of 'err' to determine if we ;; output a state vector or not. ;; if ( err ne 0 ) then begin ;; ;; Error signal detected. Output the error response ;; information. ;; print, !error_state.name print, !error_state.msg print endif else begin ;; ;; Perform the state lookup. If an error occurs, ;; program flow returns the first line after the ;; "catch, err"; in that case, 'err' will have a ;; non-zero value. ;; cspice_spkezr, targ, 0.d, "J2000", "LT+S", "EARTH", $ state, ltime ;; ;; No error, output the state. ;; print, FORMAT = '( "R : ", 3F17.5)', state[0:2]; print, FORMAT = '( "V : ", 3F17.5)', state[3:5]; print, "LT: ", ltime print endelse catch, /cancel endelse endwhile ;; ;; Done. Unload the kernels. ;; cspice_unload, "meta.ker" END
Now run the code with various inputs to observe behavior. Begin the
run using known astronomical bodies. Recall the ICY default units are
kilometers, kilometers per second, kilograms, and seconds. The 'R'
marker identifies the (X,Y,Z) position of the body in kilometers, the
'V' marker identifies the velocity of the body in kilometers per
second, and the 'LT' marker identifies the one-way light time between
the bodies at the requested evaluation time.
Target: Moon R : -291584.61659 -266693.40236 -76095.64756 V : 0.64353 -0.66608 -0.30132 LT: 1.3423106 Target: Mars R : 234536077.41914 -132584383.59557 -63102685.70619 V : 30.95976 28.93646 13.11449 LT: 923.00108 Target: Pluto barycenter R : -1451304742.83853-4318174144.40632 -918251433.58736 V : 35.03838 3.06560 -0.01514 LT: 15501.258 Target: Puck ICY_M_SPICE_ERROR CSPICE_SPKEZR: SPICE(SPKINSUFFDATA): [spkezr_c->SPKEZR->SPKEZ-> SPKAPP->SPKSSB->SPKGEO] Insufficient ephemeris data has been loaded to compute the state of 715 (PUCK) relative to 0 (SOLAR SYSTEM BARYCENTER) at the ephemeris epoch 2000 JAN 01 12:00:00.000.Perplexing. What happened?
The kernel files named in meta.ker did not include ephemeris data for Puck. When the SPK subsystem tried to evaluate Puck's position, the evaluation failed due to lack of data, so an error signaled.
The above error signifies an absence of state information at ephemeris time 2000 JAN 01 12:00:00.000 (the requested time, ephemeris time zero).
Try another look-up.
Target: Casper ICY_M_SPICE_ERROR CSPICE_SPKEZR: SPICE(IDCODENOTFOUND): [spkezr_c->SPKEZR] The target, 'Casper', is not a recognized name for an ephemeris object. The cause of this problem may be that you need an updated version of the SPICE Toolkit. Alternatively you may call SPKEZ directly if you know the SPICE ID codes for both 'Casper' and 'EARTH'An easy to understand error. The SPICE system does not contain information on a body named 'Casper.'
Another look-up, this time, something easy.
Target: Venus R : -80970027.54053 -139655772.57390 -53860125.95820 V : 31.16969 -27.00018 -12.31622 LT: 567.65507The look-up succeeded despite two errors in our run. The ICY system can respond to error conditions (not system errors) in much the same fashion as languages with catch/throw instructions.
Lesson Goal:
This lesson introduces the concepts of the ICY data types 'cell' and 'window. A 'cell' is as the basis for set calculations in ICY. A 'window' permits a user to manipulate continuous intervals of the real line. A 'window' is nothing more than an ordered, double precision cell that contains zero or more intervals
An interval being an ordered pair of numbers,
[ a(i), b(i) ]where
a(i) < b(i) -The intervals within a window are both ordered and disjoint. That is, the beginning of each interval is greater than the end of the previous interval
b(i) < a(i+1)A common use of a window is to calculate when the time intervals covering known events, eclipses, occultation, right ascension within a certain value, etc intersect.
Knowledge of cells.req, sets.req, and windows.req documents, as well
as the other_functions.ppt tutorial file.
Given the times of line-of-sight for a vehicle from a ground station
and the times for an acceptable Sun-station-vehicle phase angle, write
a program to determine the time intervals common to both
configurations.
PRO WIN ;; ;; Define the cells to use as windows. ;; The windows can hold 8 data values i.e. ;; four intervals. ;; MAXSIZ = 8 loswin = cspice_celld( MAXSIZ ) phswin = cspice_celld( MAXSIZ ) sched = cspice_celld( MAXSIZ ) ;; ;; Define a set of time intervals. For the purposes of this ;; tutorial program, define time intervals representing ;; an unobscured line of sight between a ground station ;; and some body. ;; los = [ "Jan 1, 2003 22:15:02", "Jan 2, 2003 4:43:29", $ "Jan 4, 2003 9:55:30", "Jan 4, 2003 11:26:52", $ "Jan 5, 2003 11:09:17", "Jan 5, 2003 13:00:41", $ "Jan 6, 2003 00:08:13", "Jan 6, 2003 2:18:01" ] ;; ;; A second set of intervals representing the times for which ;; an acceptable phase angle exits between the ground station, ;; the body and the Sun. ;; phase = [ "Jan 2, 2003 00:03:30", "Jan 2, 2003 19:00:00", $ "Jan 3, 2003 8:00:00", "Jan 3, 2003 9:50:00", $ "Jan 5, 2003 12:00:00", "Jan 5, 2003 12:45:00", $ "Jan 6, 2003 00:30:00", "Jan 6, 2003 23:00:00" ] ;; ;; Load our meta kernel for the leapseconds data. ;; cspice_furnsh, "meta.ker" ;; ;; SPICE windows consist of double precision values; convert ;; the string time tags defined in the 'los'and 'phase' ;; arrays to double precision ET. Store the double values ;; in the 'loswin' and 'phswin' windows. ;; cspice_str2et, los , los_et cspice_str2et, phase, phs_et ;; ;; Initialize the cells from the double precision arrays, ;; then validate the cells as windows. ;; for i=0, (MAXSIZ/2) -1 do begin cspice_wninsd, los_et[i*2], los_et[i*2 + 1], loswin cspice_wninsd, phs_et[i*2], phs_et[i*2 + 1], phswin endfor cspice_wnvald, MAXSIZ, MAXSIZ, loswin cspice_wnvald, MAXSIZ, MAXSIZ, phswin cspice_wnvald, MAXSIZ, MAXSIZ, sched ;; ;; The issue for consideration, at what times do line of ;; sight events coincide with acceptable phase angles? ;; Perform the set operation AND on loswin, phswin, ;; (the intersection of the time intervals) ;; place the results in the window 'sched'. ;; cspice_wnintd, loswin, phswin, sched ;; ;; Output the results. The number of intervals in 'sched' ;; is half the number of data points (the cardinality). ;; Use a call to card_c to retrieve the window's cardinality. ;; print print, "No. data values in sched : ", $ cspice_card(sched) print, "Space available for values in sched : ", $ cspice_size(sched) print print, "Time intervals meeting defined criterion." for i=0, (cspice_card(sched)/2)-1 do begin ;; ;; Extract from the derived 'sched' the values defining the ;; time intervals. ;; cspice_wnfetd, sched, i, left, right ;; ;; Convert the ET values to UTC for human comprehension. ;; cspice_et2utc, left , "C", 3, utcstr_l cspice_et2utc, right, "C", 3, utcstr_r ;; ;; Output the UTC string and the corresponding index ;; for the interval. ;; print, i, " ", utcstr_l, utcstr_r endfor ;; ;; Summarize the 'sched' window. ;; cspice_wnsumd, sched, meas, avg, stddev, small, large print print, "Summary of sched window" print, "o Total measure of sched : ", meas print, "o Average measure of sched : ", avg print, "o Standard deviation of " print, " the measures in sched : ", stddev ;; ;; The values for small and large refer to the indexes of the ;; values in the window ('sched'). The shortest interval is ;; ;; [ sched.base[ sched.data + small] ;; sched.base[ sched.data + small +1] ]; ;; ;; the longest is ;; ;; [ sched.base[ sched.data + large] ;; sched.base[ sched.data + large +1] ]; ;; ;; Output the interval indexes for the shortest and longest ;; intervals. As IDL bases an array index on 0, the interval ;; index is half the array index. ;; print, "o Index of shortest interval: ", small/2 print, "o Index of longest interval : ", large/2 END
The output window has the name SCHED (schedule).
Output the amount of data held in SCHED compared to the maximum possible amount.
No. data values in SCHED : 6 Space available for values in SCHED : 8List the time intervals for which a line of sight exists during the time of a proper phase angle.
Time intervals meeting defined criterion. 0 2003 JAN 02 00:03:30.0002003 JAN 02 04:43:29.000 1 2003 JAN 05 12:00:00.0002003 JAN 05 12:45:00.000 2 2003 JAN 06 00:30:00.0002003 JAN 06 02:18:01.000Finally, an analysis of the SCHED data. The measure of an interval [a,b] (a <= b) equals b-a. Real values output in units of seconds.
Summary of sched window o Total measure of sched : 25980.000 o Average measure of sched : 8660.0000 o Standard deviation of the measures in sched : 5958.5502 o Index of shortest interval: 1 o Index of longest interval : 0
Lesson Goals:
ICY provides several routines to perform commonly needed tasks. Among these include calls to convert values between unit expressions, determine the equality of strings, and indicate whether a file exists.
ICY also includes a set of functions that return constant values often used in astrodynamics, time calculations, and geometry.
The references used to define or calculate the constants functions are
found in the source code file and/or the API reference. Also reference
the other_functions.ppt tutorial file.
Write an interactive program to convert values between various units.
Demonstrate the flexibility of the unit conversion routine, the string
equality function, and show the version ID function.
PRO UNITS ;; ;; Initialize variables. All variables used in a PROMPT ;; construct must be initialized as strings. ;; funits = '' fromstr = '' tunits = '' ;; ;; Display the Toolkit version string with a ;; cspice_tkvrsn call. ;; vers = cspice_tkvrsn( "TOOLKIT" ) print, "Convert demo program compiled against CSPICE Toolkit " $ + vers ;; ;; The user first inputs the name of a unit of measure. ;; Send the name through TOSTAN for de-aliasing. ;; read, funits, PROMPT= "From Units : " tostan, funits ;; ;; Input a double precision value to express in a new ;; unit format. ;; read, fromstr, PROMPT = "From Value : " cspice_prsdp, fromstr, fvalue ;; ;; Now the user inputs the name of the output units. ;; Again we send the units name through TOSTAN for ;; de-aliasing. ;; read, tunits, PROMPT = "To Units : " tostan, tunits cspice_convrt, fvalue, funits, tunits, tvalue print, tvalue, " ", tunits END PRO TOSTAN, alias ;; ;; As a convenience, let's alias a few common terms ;; to their appropriate counterpart. Use cspice_eqstr ;; to compare strings. The comparison ignores ;; letter case and trailing/leading spaces. NOTE: the SWITCH ;; statement performs the same function as the multiple ;; "if" blocks. SWITCH was not used in order to demonstrate ;; the cspice_eqstr call. ;; if ( cspice_eqstr( alias, "meter") ) then begin ;; ;; First, a 'meter' by any other name is a ;; 'METER' and smells as sweet ... ;; alias = "METERS" endif if ( cspice_eqstr( alias, "clicks" ) OR $ cspice_eqstr( alias, "kilometers") OR $ cspice_eqstr( alias, "kilometer" ) ) then begin ;; ;; ... 'clicks' and 'KILOMETERS' and 'KILOMETER' ;; identifies 'KM'.... ;; alias = "KM" endif if ( cspice_eqstr( alias, "secs") ) then begin ;; ;; ... 'secs' to 'SECONDS'. ;; alias = "SECONDS" endif if ( cspice_eqstr( alias, "miles") ) then begin ;; ;; ... and finally 'miles' to 'STATUTE_MILES'. ;; Normal people think in statute miles. ;; Only sailors think in nautical miles - one ;; minute of arc at the equator. ;; alias = "STATUTE_MILES" endif ;; ;; Much better. Now return. If the input matched ;; none of the aliases, this routine did nothing. ;; END
Run a few conversions through the application to ensure it works. The
intro banner gives us the Toolkit version against which the
application was linked:
Convert demo program compiled against CSPICE Toolkit CSPICE_N0057 >From Units : clicks >From Value : 3 To Units : miles 1.8641136 STATUTE_MILESNow we know. Three kilometers equals 1.864 miles.
Pheidippides ran 26.2 miles from the Marathon Plain to Athens. How far in kilometers?
Convert demo program compiled against CSPICE Toolkit CSPICE_N0057 >From Units : miles >From Value : 26.2 To Units : km 42.164813 km
Write a program to output ICY constants and use those constants to
calculate some rudimentary values.
PRO CONST ;; ;; All the function have the same calling sequence: ;; ;; VALUE = function_name() ;; ;; some_procedure( function_name() ) ;; ;; print, function_name() ;; ;; First a simple example using the seconds per day ;; constant... ;; print, $ FORMAT = $ '("Number of (S)econds (P)er (D)ay : ", F19.12)',$ cspice_spd() ;; ;; ...then show the value of degrees per radian, 180/Pi... ;; print, $ FORMAT = $ '("Number of (D)egrees (P)er (R)adian : ", F19.16)',$ cspice_dpr() ;; ;; ...and the inverse, radians per degree, Pi/180. ;; It is obvious cspice_dpr() equals 1.d/cspice_rpd(), or ;; more simply cspice_dpr() * cspice_rpd() equals 1 ;; print, $ FORMAT = $ '("Number of (R)adians (P)er (D)egree : ", F19.16)',$ cspice_rpd() ;; ;; What's the value for the astrophysicist's favorite ;; physical constant (in a vacuum)? ;; print, $ FORMAT = $ '("Speed of light in KM per second : ", F19.12)',$ cspice_clight() ;; ;; How long (in Julian days) from the J2000 epoch to the ;; J2100 epoch? ;; print, "Number of days between epochs J2000 and " print, $ FORMAT = $ '(" J2100 : ", F19.12)',$ cspice_j2100() - cspice_j2000() ;; ;; Redo the calculation returning seconds... ;; print, "Number of seconds between epochs J2000 " print, $ FORMAT = $ '(" and J2100 : ", F19.5)',$ cspice_spd() * (cspice_j2100() - cspice_j2000() ) ;; ;; ...then tropical years. ;; print, "Number of tropical years between epochs " print, $ FORMAT = $ '(" J2000 and J2100 : ", F19.12)',$ ( cspice_spd() / cspice_tyear() ) $ * (cspice_j2100() - cspice_j2000() ) ;; ;; Finally, how can I convert a radian value to degrees. ;; print, $ FORMAT = $ '("Number of degrees in Pi/2 radians of arc : ", F19.16)',$ cspice_halfpi() * cspice_dpr() ;; ;; and degrees to radians. ;; print, $ FORMAT = $ '("Number of radians in 250 degrees of arc : ", F19.16)',$ 250.D * cspice_rpd() END
Number of (S)econds (P)er (D)ay : 86400.000000000000 Number of (D)egrees (P)er (R)adian : 57.2957795130823229 Number of (R)adians (P)er (D)egree : 0.0174532925199433 Speed of light in KM per second : 299792.457999999984 Number of days between epochs J2000 and J2100 : 36525.000000000000 Number of seconds between epochs J2000 and J2100 : 3155760000.00000 Number of tropical years between epochs J2000 and J2100 : 100.002135902909 Number of degrees in Pi/2 radians of arc : 90.0000000000000000 Number of radians in 250 degrees of arc : 4.3633231299858242