N IF Navigation and Ancillary Information Facility

SPICE Conventions

A broad summary of standards, terms and synanons used within SPICE

January 2020 N IF SPICE Lexicon - 1 Navigation and Ancillary Information Facility

SPICE • The name of this ancillary information system

NAIF • The name of the team of people at JPL who lead development of the SPICE system. • Also the name of the ancillary data node of NASA’s Planetary Data System (PDS).

SPICE-based (code) • A program incorporating some SPICE APIs (a.k.a. subroutines or modules) to compute some geometric quantities. SPICE Conventions 2 N IF SPICE Lexicon - 2 Navigation and Ancillary Information Facility

SPICE Toolkit • Names that refer to the principal collection of software produced by The Toolkit JPL’s NAIF Team as part of the SPICE information system. Toolkit • The Fortran 77 version of the Toolkit. SPICELIB • The principal user library found within Fortran versions of the Toolkit.

CSPICE • Refers to the entire C Toolkit, and also to the principal user library found within C versions of the Toolkit. Icy • An IDL interface to CSPICE Mice • A MATLAB interface to CSPICE Kernel • A SPICE data file

Sorry for this rather confusing terminology! SPICE Conventions 3 N IF SPICE Lexicon - 3 Navigation and Ancillary Information Facility • Text kernel – Any kernel type consisting entirely of ASCII information, with each line terminated using the local operating system convention (CR, LF, or CR+LF) – Text kernel types are FK, IK, text PcK, LSK, SCLK, MK – Any set of text kernels, excepting MKs, could be combined in a single file. » But this is certainly not recommended! • Binary kernel – Any kernel type using a binary file format – Binary types are SPK, binary PcK, CK, DBK and DSK – Different binary kernel types cannot be combined together

• Transfer format kernel – A hexadecimal (ASCII) version of a binary kernel, used ONLY for porting a binary kernel between incompatible computers. – Not as important as it was prior to the addition of the “run-time translation” capability added in Toolkit version N0052 (January 2002). » But still has a role in making native binary kernels required for some operations.

SPICE Conventions 4 N IF SPICE Lexicon - 4 Navigation and Ancillary Information Facility • “Command file” – Many SPICE application and utility programs either require, or optionally accept, an input file containing program directives, and sometimes input data. – The following names are used synonymously: » setup file » preferences file » command file » specifications file » definitions file • “Found flag” – A Boolean output (“True” or “False”) from a SPICE API that informs your program whether or not data were found that match your request • Database Kernel (DBK) – A SPICE kernel that, in conjunction with Toolkit DBK software, provides a self-contained SQL-like database capability.

SPICE Conventions 5 N IF SPICE Lexicon - 5 Navigation and Ancillary Information Facility • Coverage – The period(s) of time for which a time-based kernel contains data • Deprecated software – Toolkit code that, while still useable, has been superseded with a newer and presumably better version – We encourage you to not use deprecated SPICE software – Deprecated modules are so marked in their headers • Toolkit version naming – "Nxxxx" e.g. N0066 is Version 66 » Often shortened to just Nxx (e.g. N66) – Used for all instances of a given toolkit release » Fortran (“Toolkit”), C (“CSPICE”), IDL (“Icy”), MATLAB (“Mice”) • “Satellite” is used to refer only to a natural satellite, never to a spacecraft. • “Run-time” occurs when you execute a program SPICE Conventions 6 N IF SPICE Lexicon - 6 Navigation and Ancillary Information Facility Names used synonymously • Kernel, SPICE file, SPICE kernel, SPICE kernel file • Meta-kernel, Furnsh Kernel • Module, routine, subroutine, procedure, function, application program interface (API) • Application, program, utility, executable • Metadata, comments • Time, Epoch • Encoded SCLK, ticks* • Frame, Reference Frame** ( ≠ Coordinate System) (See the "Frames & Coordinate Systems tutorial) • Ephemeris, trajectory • Rectangular coordinates, Cartesian coordinates** • Geodetic, Planetodetic (coordinate system) • Ephemeris time (ET), Barycentric Dynamical Time (TDB) • Attitude, orientation • International Celestial Reference Frame (ICRF) and Earth Mean Equator and Equinox of 2000 reference frame (J2000) • “Body”, “solar system object,” “ephemeris object” * Encoded SCLK always refers to absolute time; “ticks” is used to refer to both durations and absolute times.

** Outside of SPICE the term “coordinate system” is often used synonymously with “frame” or “reference frame.” We prefer to use “coordinate system” in the sense of describing how coordinates are measured (e.g. cylindrical coordinate system, rectangular coordinate system, polar coordinate system, etc) within a frame, and to use “frame” in the sense of a set of three SPICE Conventions orthogonal vectors that define an orientation. 7 N IF Kernel File Names Navigation and Ancillary Information Facility

• SPICE imposes some restrictions on kernel file names – No white space allowed within a name – Maximum length of a name (including any path specifications) is 255 characters » See the tutorial “Intro_to_kernels” for limitations on file name specifications contained within meta-kernels (“furnsh kernels”)

• NAIF suggests names conform to the PDS3 standard: “36.3” – <1 to 36 alphanumeric characters>.<1 to 3 chars>

• Common usage within NAIF for SPICE kernel file name extensions is listed on the next page, with the following general style used: t* text format (e.g. pck00010.tpc) b* binary format (e.g. de430.bsp) x* transfer format (e.g. de430.xsp)

SPICE Conventions 8 Common SPICE Kernel N IF File Name Extensions Navigation and Ancillary Information Facility

SPK: SCLK: .bsp binary SPK file .tsc text SCLK file .xsp transfer format SPK file MK: PcK: .tm text meta-kernel file (“FURNSH kernel”) .tpc text PcK file (The most common type PcK) DSK: .bpc binary PcK file .bds binary DSK file (Very few instances of this) .xpc transfer format PcK file DBK: .bdb binary database kernel IK: .xdb transfer format database kernel .ti text IK file EK Family (ESP, ESQ, ENB) FK: ESP: .tf text FK file .bep binary Science Plan EK file LSK: .xep transfer format Science Plan EK file .tls text LSK file ESQ: CK: .bes binary Sequence Component EK file .bc binary CK file .xes transfer format Sequence Component EK file .xc transfer format CK file ENB: .ten text Experimenter’s Notebook EK file SPICE Conventions These are strong suggestions but not requirements 9 N IF Common Document Name Extensions Navigation and Ancillary Information Facility

• These extensions are used for plain ASCII documents included with each Toolkit delivery .ug User’s Guide .req “Required Reading” technical reference document .txt Used for a few miscellaneous documents .idx Used only for the permuted index document

• All HTML documents included in the Toolkit have extension .html

SPICE Conventions 10 N IF Public and Private Modules Navigation and Ancillary Information Facility

• All Toolkits include public and private modules

• Public modules are for you to use – Names of public APIs are different in the four SPICE library implementations. For example, the top level SPK reader SPKEZR has the following names » in SPICELIB (FORTRAN) SPKEZR » In CSPICE (C) spkezr_c » ICY (IDL) cspice_spkezr » MICE (MATLAB) cspice_spkezr and mice_spkezr

• Private modules are for NAIF staff use only – Names of private modules start with “ZZ” – They are present in the Toolkit only to support operations of “public” modules – Do not use “private” modules in your code – they may be changed by NAIF without notice

SPICE Conventions 11 N IF Reference Frame Conventions Navigation and Ancillary Information Facility

• All reference frames used within SPICE are right handed systems: this means X cross Y = Z

Z

Y

X

SPICE Conventions 12 N IF Quaternions Navigation and Ancillary Information Facility

• The SPICE system uses quaternions to provide orientation in C-kernels

• There are different “styles” of quaternions used in science and engineering applications. Styles are characterized by – The order of the quaternion elements – The quaternion multiplication formula – The convention for associating quaternions with rotation matrices

• Two of the commonly used styles are – “SPICE” » Used by Sir William Rowan Hamilton (discoverer of quaternions) » Used in math and physics textbooks – “Engineering” or “MSOP” » Widely used in attitude control and other aerospace applications

• Details about SPICE quaternions are found in: – Rotations Required Reading document – NAIF white paper on quaternions: https://naif.jpl.nasa.gov/pub/naif/misc/Quaternion_White_Paper/ – SPICE quaternion conversion routines: M2Q, Q2M SPICE Conventions 13 N IF Names and IDs Navigation and Ancillary Information Facility

• Many items within SPICE have assigned names (text strings) and IDs (integer numbers)

• The rules, standards, practices and exceptions regarding these names and IDs are discussed in a separate tutorial (“NAIF IDs and Names”)

SPICE Conventions 14 N IF Use of Quotes Navigation and Ancillary Information Facility

• Reminder of language-specific rules for quoting strings used as values in API arguments – Use double quotes in C and Java Native Interface (JNI) codes "this is a string" – Use single quotes in Fortran, IDL, MATLAB, and Python codes 'this is a string'

• Regardless of the language version of the SPICE Toolkit you're using, in all SPICE text kernels, string values are enclosed in single quotes. For example: INS-43012_FOV_SHAPE = 'CIRCLE'

SPICE Conventions 15 N IF Pluto is a Special Case in SPICE Navigation and Ancillary Information Facility

• For practical and historical reasons, Pluto is treated as a planet when speaking about ephemerides (SPK).

• But Pluto is treated as a “dwarf planet” when speaking about orientation and rotational state (PCK).

SPICE Conventions 16