MSP'01 Mission

Mars Reconnaissance Orbiter

Software Interface Specification

Interface Title: SPICE Spacecraft Clock Kernel (SCLK)

Mission: MRO Date:12/17/03

Module ID: SIS-NAF007-MRO

Module Type (REFerence Only or MISsion-specific info included): REF

Reference Module ID: NAIF Document No. 374 Date: 8/28/01

Approvals

Generating Subsystem:

Mission Navigation Subsystem/NAIF Element

Charles Acton _______________________________________________

Cog E Date

Receiving Subsystems:

APSS

Curt Eggemeyer _______________________________________________

Cog E Date

MNS

Tung-Han You _______________________________________________

Cog E Date

SEPA

Mike Haggard _______________________________________________

Cog E Date

DMAS

Young Lee _______________________________________________

Cog E Date

DACS

Mike Levesque _______________________________________________

Cog E Date

POSS

Daniel Wenkert _______________________________________________

Cog E Date

GDS System Engineer:

Ground Data System (GDS)

Magdi Carlton _______________________________________________

GDS SE Date

Multimission Software Interface Specification (SIS)

SPICE

Spacecraft Clock Coefficients Kernel

SCLK

NAIF Document No. 374

Version 1.0

Prepared by: C. Acton

Navigation and Ancillary Information Facility (NAIF)

Jet Propulsion Laboratory

National Aeronautics and Space Administration

PURPOSE: This SIS describes the format and content of SPICE Spacecraft Clock Coefficients Kernel (SCLK) file, used to used for converting between spacecraft clock time and Barycentric Dynamical Time (TDB), which was called Ephemeris Time (ET) prior to 1984. It also describes and gives examples of how to use SPICE Toolkit modules provided to access and use the data in a SPICE SCLK file.

CHANGE LOG

Version	Date	Page Nos.	Reason
1.0	28 Aug 2001	All	New multimission version.

List of Acronyms

AMMOS Advanced Multimission Operations System

ANSI American National Standards Institute

ASCII American Standard Code for Information Interchange

CK SPICE C-kernel

ET Ephemeris Time (also called TDB, or Barycentric Dynamical Time)

FK SPICE Frames Kernel

FTP File Transfer Protocol

JPL Caltech/Jet Propulsion Laboratory

MSOO Mars Surveyor Operations Office

NAIF Navigation and Ancillary Information Facility

PDS Planetary Data System

SCLK (SPICE) Spacecraft Clock Coefficients Kernel

SCLKvSCET AMMOS SCLK/SCET Coefficients File

SFDU Standard Formatted Data Unit

SIS Software Interface Specification

SPICE S-, P-, I-, C- and E-kernels; the principal logical data components of a particular NASA ancillary information system

TDB Barycentric Dynamical Time

Section 1

General Description

1.1 Purpose of Document

This Software Interface Specification (SIS) describes the contents and structure of a SPICE Spacecraft Clock Coefficients file. It also describes and gives examples of how to use SPICE Toolkit modules to access and use the data in a SCLK file.

1.2 Scope

This is a multimission SIS, applicable for all flight projects.

1.3 Applicable Documents

No.	Document ID	Version	Title
1.	NAIF Doc. No. 318	Latest release	Kernel Required Reading
2.	NAIF Doc. No. 222	Latest Release	Spacecraft Clock Coefficients Kernel (SCLK) Required Reading

1.4 Functional Description

SPICE SCLK files contain data needed by SPICE Toolkit software to convert between spacecraft clock time (SCLK) and ephemeris time (ET, or TDB). SCLK files are also used by SPICE software to convert between SCLK time and Encoded SCLK time, which is the time form used within the SPICE C-kernel system.

1.4.1 Data Source, Destinations, and Transfer Method

At JPL a SPICE SCLK file is created on a flight project computer using a special program provided by NAIF (MAKCLK) and with a traditional AMMOS-style SCLKvSCET file as the principal source of input data. The specific computer from which a SPICE SCLK is delivered to a project's SPICE data base depends on the assignment of responsibility for SCLK production.

At other mission operations centers where the AMMOS-style SCLKvSCET file is not available, locally produced software that uses some SPICE Toolkit modules is used to produce SCLK files.

A SCLK file is transferred to that project's SPICE kernel data base using the means mandated by the project.

1.4.2 Labeling and Identification

SCLK files may and should begin with pertinent descriptive information, generally called metadata. This will subsequently be used in the construction of Planetary Data System (PDS) labels.

SCLK file names may utilize any syntax picked by a flight project, although limiting the length to the "27.3" specification adopted by the Planetary Data System (PDS) is suggested. Using the "*.tsc" file name extension as normally used by NAIF is also encouraged.

Section 2

Data Object Definition

2.1 Structure and Organization

A SCLK file is an ASCII file containing data sections and descriptive text sections. The structure conforms to the specifications described in NAIF Document “Kernel Required Reading,” (Reference 3).

Text sections of a SCLK file are used to describe the data. They are preceded by the token:

\begintext

which must appear on a line by itself. If it appears first in the file, before any data, the first text section does not need this delimiter—it is interpreted as a text section by default.

The initial text section may contain labels (metadata) providing provenance for the file. This labeling practice is highly recommended by NAIF, although it is not a SPICE requirement. Such labels may utilize the same "keyword = value" syntax used in data sections of the SCLK file. In general the text sections are not restricted to a particular format other than each line must not exceed 79 characters.

All data sections start with the begin data delimiter,

\begindata

which must appear on a line by itself. Data are provided using a "keyword = value" syntax. The data sections are parsed by SPICE kernel file readers and so must adhere to the format specified in the NAIF Document Kernel Required Reading, Applicable Document No. 1.

2.2 Data Format and Definition

The data found in a SCLK file are briefly described below. A more comprehensive description of these data may be found in Applicable Document No 2, SCLK Required Reading. The data description given here is not particularly important because the user is provided API modules in the SPICE Toolkit for reading and using SCLK data. Those are described in Section 3 of this SIS.

2.2.1 Metadata Description

At the beginning of a SCLK file there may be optional descriptive metadata that could include version and date, references, author, and comments about using the SCLK file. Examples of such metadata follow:

MISSION_NAME = MARS_OBSERVER

SPACECRAFT_NAME = MARS_OBSERVER

MISSION_PHASE_NAME = LAUNCH

SPICE_DATA_TYPE = SCLK

DATA_SET_ID = MO-M-SPICE-6-SCLK-V1.0

PRODUCT_ID = MO_DAT_00003

PRODUCT_CREATION_TIME = 1992-04-16T11:46:31.53

START_TIME = 1991-01-01T00:00:00.000

STOP_TIME = 2127-09-07T14:11:44.255

SPACECRAFT_CLOCK_START_COUNT = 0000000000.000

SPACECRAFT_CLOCK_STOP_COUNT = 4294967295.255

PRODUCER_ID = MO_DAT

SOURCE_PRODUCT_ID = MO_SCLKSCET.3

NOTE = A STANDARD CRUISE FILE.

2.2.2 Data Description

An SCLK file contains a modest amount of data, in ASCII format, provided using the “keyword = value” syntax used in all SPICE text kernels. The first pieces of data identify the spacecraft and the characteristics of the specific spacecraft clock. (It is possible that a spacecraft could have more than one clock for which calibration data are provided in an SCLK file.) An example of these data follows:

SCLK_KERNEL_ID = ( @1992-04-16/11:46:31.53 )

SCLK_DATA_TYPE_94 = ( 1 )

SCLK01_TIME_SYSTEM_94 = ( 2 )

SCLK01_N_FIELDS_94 = ( 2 )

SCLK01_MODULI_94 = ( 4294967296 256 )

SCLK01_OFFSETS_94 = ( 0 0 )

SCLK01_OUTPUT_DELIM_94 = ( 1 )

The next pieces of data define the time bounds for each partition extent in the SCLK file. If no clock resets or other discontinuities have occurred there will be only one partition, and thus only one entry in each of the “partition_start” and “partition_stop” arrays, examples of which appear below. The bounds are given in units of “ticks,” which are the shortest time increment expressible by a particular spacecraft’s clock. By definition the first entry in the “partition_start”array is zero. An example of partition boundary data follows, where there have been four partitions (and so four entries in each of the two arrays):

SCLK_PARTITION_START_94 = ( 0.0000000000000E+00

2.5600000000000E+05

3.3519289250000E+09

1.9678257014000E+10 )

SCLK_PARTITION_END_94 = ( 4.6994205080000E+09

3.3740470680000E+09

1.9652482261000E+10

1.0995116277750E+12 )

The last kind of data found in a SCLK file are the clock calibration “coefficients.” These data are coefficients of linear polynomials–as a set they define a piecewise linear function that maps SCLK to the parallel time system (TDB). Each line consists of three related items: a SCLK value given as total number of ticks since clock start, the corresponding time in the parallel time system (generally barycentric dynamical time [TDB], also called Ephemeris Time [ET], measured in seconds since epoch J2000), and the clock rate, given in units of the most significant clock count of the parallel time system (seconds, if the parallel time system is TDB and its units are seconds).

An example of these coefficient data follows.

SCLK01_COEFFICIENTS_94 = (

0.0000000000000E+00 -2.8403994181600E+08 1.0000000000000E+00

2.2118400000000E+07 -2.8395354181600E+08 1.0001000000000E+00

4.4236800000000E+07 -2.8386713317600E+08 1.0000000000344E+00

4.6994205080000E+09 -2.6568282181600E+08 1.0000000000000E+00

4.7112169880000E+09 -2.6563674181600E+08 1.0001000172362E+00

4.7333331760000E+09 -2.6555034181600E+08 1.0000000001533E+00

8.0732115760000E+09 -2.5250394181400E+08 1.0000000001103E+00

1.2496891831000E+10 -2.3522394081600E+08 1.0001000001373E+00

1.9574072112000E+10 -2.0757594081600E+08 1.0000000000000E+00

2.4373764912000E+10 -1.8882714081600E+08 1.0000000000000E+00 )

Section 3

Using a SCLK File

3.1 SPICE Toolkit APIs

Included in the SPICE Toolkit are several APIs (subroutines or C modules) for accessing SCLK data. These SPICELIB or CSPICE APIs are the only recommended method for using SCLK data.

3.1.1 Initialization

In order to use a SCLK file the file must first be “loaded” into your SPICE-based application. This is accomplished with the following code.

CALL FURNSH (<sclk file name>) FORTRAN version

furnish_c (<sclk file name>); C version

Execution of the FURNSH command loads all of the SCLK file data into your computer’s memory, available for immediate use.

3.1.2 SCLK Time Conversions

Two kinds of time conversion are available using a SCLK file and SPICE Toolkit modules. Each of these is summarized below; detailed specifications for using the Toolkit modules are found in the source code headers for those modules, and in Applicable Document No. 2.

3.1.2.1 SCLK to TICKS Time Conversion

The Toolkit modules SCENCD and SCDECD are used to convert from SCLK to encoded spacecraft clock ticks, and vice-versa, respectively. Examples of these conversions are illustrated below. In these examples the SCLK string shown includes a partition number of 4, which is indicated by the “4/” characters at the beginning of the string.

SCLK Encoded Ticks

4/81792991.118 à SCENCD à 25634513712

4/81792991.118 ß SCDECD ß 25634513712

These two routines (FORTRAN versions) are used thusly:

SCENCD Converts character representation of SCLK CLKSTR to its double precision encoding SCLKDP for the spacecraft with integer code SC.

SCDECD Makes the opposite conversion.

SUBROUTINE SCENCD( SC, CLKSTR, SCLKDP )

SUBROUTINE SCDECD( SC, SCLKDP, CLKSTR )

INTEGER SC

CHARACTER*(*) CLKSTR

DOUBLE PRECISION SCLKDP

3.1.2.2 SCLK to ET Time Conversion

The Toolkit modules SCS2E and SCE2S are used to convert from SCLK to ephemeris time, and vice-versa, respectively. Examples of these conversions are illustrated below. In these examples the SCLK string shown includes a partition number of 4, which is indicated by the “4/” characters at the beginning of the string. Also in these examples, the SCLK time string happens to represent a time before the epoch J2000, and so the ephemeris time, which is a measure of the seconds from the J2000 epoch, is a negative number. (The corresponding UTC time happens to be 1994 03 05 00:00:00.0.)

SCLK ET (also called TDB)

4/81792991.118 à SCS2E à -183902340.8145978

4/81792991.118 ß SCE2S ß -183902340.8145978

These two routines (FORTRAN versions) are used thusly:

SCE2S Calculates for ephemeris time ET the corresponding CLKSTR represented as a character string for the spacecraft with integer code SC.

SCS2E Makes the opposite conversion.

SUBROUTINE SCE2T( SC, ET, CLKSTR )

SUBROUTINE SCT2E( SC, CLKSTR, ET )

INTEGER SC

DOUBLE PRECISION ET

CHARACTER*(*) CLKSTR

APPENDIX A

Example of a SCLK File

MISSION_NAME = MARS_OBSERVER

SPACECRAFT_NAME = MARS_OBSERVER

MISSION_PHASE_NAME = LAUNCH

SPICE_DATA_TYPE = SCLK

DATA_SET_ID = MO-M-SPICE-6-SCLK-V1.0

ARCHIVE_FILE_NAME = DAT00003.TSC

PRODUCT_ID = MO_DAT_00003

PRODUCT_VERSION_TYPE = OPERATIONS

PRODUCT_CREATION_TIME = 1992-04-16T11:46:31.53

START_TIME = 1991-01-01T00:00:00.000

STOP_TIME = 2127-09-07T14:11:44.255

SPACECRAFT_CLOCK_START_COUNT = 0000000000.000

SPACECRAFT_CLOCK_STOP_COUNT = 4294967295.255

TARGET_NAME..................= MARS

INSTRUMENT_NAME = N/A

INSTRUMENT_ID = N/A

PRODUCER_ID = MO_DAT

SOURCE_PRODUCT_ID = MO_SCLKSCET.3

NOTE = A STANDARD CRUISE FILE.

LEAPSECONDS_KERNEL = NAF0000C.TLS

OLD_SCLK_KERNEL = DAT00002.TSC

LOG_FILE = DAT00003.LOG

NAIF_SPACECRAFT_ID = -94

SCLKSCET_FILE = MO_SCLKSCET.3

PARTITION_TOLERANCE = 1

This file is a SPICE spacecraft clock (SCLK) kernel. This file was generated by the NAIF utility program MAKCLK, version 2.0. Please refer to the SCLK Required Reading file, NAIF document number 222, and the MAKCLK User's Guide, NAIF document number 267, for information regarding this kernel file.