The Configuration File

The NAIF PDS4 Bundler needs a configuration file to be executed. This configuration file is bundle-specific and it can also be release-specific. It is a rather long file and setting it up for the first time for a given bundle might take some effort.

Once the configuration file is generated for the bundle and is adapted to the user’s environment using NPB becomes an trivial task.

The following sections provide a detailed description and recommendations to facilitate the task of writing the NPB configuration file.

If you are not familiar with the generation of PDS4 SPICE archives we recommend you to first read the chapter SPICE Kernel Archive Description in such a way that you get familiar with some concepts that are discussed in the following sections.

Configuration File Format

The NPB configuration file is an XML (eXtensible Markup Language) file. The extension of the file should be .xml, although this is not strictly necessary.

XML files (or documents), contain XML elements; these elements can contain:

• text

• attributes

• other elements

• a mix of these elements.

Each XML element is defined in between angle brackets:

<element>

elements enclose contents such as:

<element>Some content<\element>

and elements can have attributes with a value:

<element an_attribute="with value">Some content<\element>

The NPB Configuration File includes all the elements described above. This document refers to configuration elements as parameters interchangeably.

NPB includes a Configuration File XML Schema src/naif_pds4_bundler/templates/configuration.xsd that is used to validate configuration files. This validation is performed to confirm that the file is well-formed and also “valid” according to the structure defined in the Schema.

Do not use the XML Schema as a reference to generate a configuration file, instead use one of the configuration files included in the test area of the NPB package. The MAVEN Configuration is the recommended reference: tests/naif_pds4_bundler/config/maven.xml. If the bundle to be generated includes secondary observers and/or targets complement the MAVEN Configuration with the DART configuration: tests/naif_pds4_bundler/config/dart.xml.

The Configuration File consists of a number of nested parameters that are grouped in the following categories:

1. PDS parameters

2. Bundle parameters

3. Mission parameters

4. Directories

5. Kernel list

6. Meta-kernel

7. Orbit number file (if ORBNUM files are present)

In order to facilitate the understanding of the Configuration File, the MAVEN example is provided hereunder. We encourage you to first take a look at the example and then continue to the sections that explain in detail each parameter.:

<?xml version='1.0' encoding='UTF-8'?>
<naif-pds4-bundler_configuration>

    <!-- =========================== -->
    <!-- PDS parameters              -->
    <!-- =========================== -->
    <pds_parameters>
        <pds_version>4</pds_version>
        <information_model>1.5.0.0</information_model>
        <xml_model>http://pds.nasa.gov/pds4/pds/v1/PDS4_PDS_1500.sch</xml_model>
        <schema_location>http://pds.nasa.gov/pds4/pds/v1 http://pds.nasa.gov/pds4/pds/v1/PDS4_PDS_1500.xsd
        </schema_location>
        <logical_identifier>urn:nasa:pds:maven.spice</logical_identifier>

        <!-- Optional Parameters -->
        <!-- Context Products that are not present in the registered context
             products JSON file -->
        <context_products>
            <!-- The product name, type, and lidvid needs to be provided -->
            <product name="MAVEN">
                <type>Spacecraft</type>
                <lidvid>urn:nasa:pds:context:instrument_host:spacecraft.maven::1.0</lidvid>
            </product>
            <product name="Oumuamua">
                <type>Hyperbolic Asteroid</type>
                <lidvid>urn:nasa:pds:context:target:asteroid.oumauma::2.0</lidvid>
            </product>
        </context_products>
    </pds_parameters>

    <!-- =========================== -->
    <!-- Bundle parameters           -->
    <!-- =========================== -->
    <bundle_parameters>
        <producer_name>Marc Costa Sitja</producer_name>
        <author_list>Semenov B. V.; Costa Sitja M.</author_list>
        <institution>NAIF/JPL</institution>
        <doi>10.17189/1520434</doi>
        <!-- Location fo the SPICE archive description HTML file to be
             included -->
        <spiceds>../data/spiceds_maven.html</spiceds>
        <spice_name>MAVEN</spice_name>
        <!-- Information to be included in the archive readme file, only used
             if the file is not present -->
        <readme>
            <overview>
                The MAVEN SPICE archive bundle contains observation geometry and
                other ancillary data in the form of SPICE System kernel files for
                the MAVEN spacecraft, its instruments, and targets.
            </overview>
            <cognisant_authority>
                This archive bundle was produced by Boris Semenov, Planetary Data
                System Navigation and Ancillary Information Facility Node, Jet
                Propulsion Laboratory, Pasadena, California.
            </cognisant_authority>
        </readme>

        <!-- Optional Parameters -->
        <!-- Release date as a UTC calendar string. Use the following format:
             YYYY-MM-DD e.g. 2021-04-09 -->
        <release_date>2021-06-25</release_date>
        <!-- Creation date and time for all the new archive products, usage
             of this parameter is highly discouraged -->
        <creation_date_time>2021-06-25T08:00:00</creation_date_time>
        <!-- Increment start and stop times provided as a UTC calendar string.
             Use the following format: YYYY-MM-DDThh:mm:ssZ
             e.g. 2021-04-09T15:11:12Z -->
        <increment_start>2021-05-25T08:00:00Z</increment_start>
        <increment_finish>2021-06-25T08:00:00Z</increment_finish>
        <!-- Date format can be 'maklabel' style or 'infomod2' style. Default
             value is 'maklabel'-->
        <date_format>maklabel</date_format>
        <!-- End of line format can either be 'CRLF' or 'LF', 'CRLF' is the
             default value -->
        <end_of_line>CRLF</end_of_line>
        <binary_endianness>LTL-IEEE</binary_endianness>
    </bundle_parameters>

    <!-- =========================== -->
    <!-- Mission Parameters          -->
    <!-- =========================== -->
    <mission_parameters>
        <mission_acronym>maven</mission_acronym>
        <mission_name>MAVEN</mission_name>
        <mission_start>2013-11-18T19:20:43Z</mission_start>
        <mission_finish>2050-01-01T00:00:00Z</mission_finish>
        <observer>MAVEN</observer>
        <target>MARS</target>
        <kernels_to_load>
            <lsk>naif[0-9][0-9][0-9][0-9].tls</lsk>
            <sclk>MVN_SCLKSCET.[0-9][0-9][0-9][0-9][0-9].tsc</sclk>
            <fk>maven_v[0-9][0-9].tf</fk>
        </kernels_to_load>
    </mission_parameters>

    <!-- =========================== -->
    <!-- Directories                 -->
    <!-- =========================== -->
    <directories>
        <working_directory>working</working_directory>
        <kernels_directory>kernels</kernels_directory>
        <staging_directory>staging</staging_directory>
        <bundle_directory>maven</bundle_directory>

        <!-- Optional Parameters -->
        <orbnum_directory>misc/orbnum</orbnum_directory>
        <templates_directory>../../../src/pds/naif_pds4_bundler/templates/1.5.0.0</templates_directory>
    </directories>

    <!-- =========================== -->
    <!-- Kernel List                 -->
    <!-- =========================== -->
    <kernel_list>
        <kernel pattern="naif[0-9][0-9][0-9][0-9].tls">
            <description>SPICE LSK file incorporating leapseconds up to $DATE, created by NAIF, JPL.</description>
            <patterns>
                <DATE value="naif0011.tls">2015-JAN-01</DATE>
                <DATE value="naif0012.tls">2017-JAN-01</DATE>
            </patterns>
        </kernel>
        <kernel pattern="pck[0-9][0-9][0-9][0-9][0-9].tpc">
            <description>SPICE text PCK file containing constants from the $REPORT report, created by NAIF, JPL.
            </description>
            <patterns>
                <REPORT value="pck00010.tpc">IAU 2009</REPORT>
            </patterns>
        </kernel>
        <kernel pattern="maven_v[0-9][0-9].tf">
            <description>SPICE FK file defining reference frames for the MAVEN spacecraft, its structures, and science
                instruments, created by NAIF, JPL.
            </description>
        </kernel>
        <kernel pattern="maven_ant_v[0-9][0-9].ti">
            <description>SPICE IK file providing FOV definitions for the MAVEN communication antennae, created by NAIF,
                JPL.
            </description>
        </kernel>
        <kernel pattern="maven_euv_v[0-9][0-9].ti">
            <description>SPICE IK file providing FOV definitions and other instrument parameters for the MAVEN Extreme
                Ultraviolet (EUV) monitor instrument, created by NAIF, JPL.
            </description>
        </kernel>
        <kernel pattern="maven_iuvs_v[0-9][0-9].ti">
            <description>SPICE IK file providing FOV definitions and other instrument parameters for the MAVEN Imaging
                Ultraviolet Spectrograph (IUVS) instrument, created by IUVS Team, CU/LASP.
            </description>
        </kernel>
        <kernel pattern="maven_ngims_v[0-9][0-9].ti">
            <description>SPICE IK file providing FOV definitions and other instrument parameters for the MAVEN Neutral
                Gas and Ion Mass Spectrometer (NGIMS) instrument, created by NGIMS Team, GSFC.
            </description>
        </kernel>
        <kernel pattern="maven_sep_v[0-9][0-9].ti">
            <description>SPICE IK file providing FOV definitions and other instrument parameters for the Solar Energetic
                Particle (SEP) instrument, created by SEP Team, UC Berkeley.
            </description>
        </kernel>
        <kernel pattern="maven_static_v[0-9][0-9].ti">
            <description>SPICE IK file providing FOV definitions and other instrument parameters for the SupraThermal
                And Thermal Ion Composition (STATIC) instrument, created by STATIC Team, UC Berkeley.
            </description>
        </kernel>
        <kernel pattern="maven_swea_v[0-9][0-9].ti">
            <description>SPICE IK file providing FOV definitions and other instrument parameters for the MAVEN Solar
                Wind Electron Analyzer (SWEA) instrument, created by SWEA Team, UC Berkeley.
            </description>
        </kernel>
        <kernel pattern="maven_swia_v[0-9][0-9].ti">
            <description>SPICE IK file providing FOV definitions and other instrument parameters for the MAVEN Solar
                Wind Ion Analyzer (SWIA) instrument, created by SWIA Team, UC Berkeley.
            </description>
        </kernel>
        <kernel pattern="mvn_sclkscet_[0-9][0-9][0-9][0-9][0-9].tsc">
            <mapping>MVN_SCLKSCET.$VERSION.tsc</mapping>
            <description>SPICE SCLK file containing time correlation data for the main MAVEN on-board clock, created by
                NAIF, JPL. The original name of this file was MVN_SCLKSCET.$VERSION.tsc.
            </description>
            <patterns>
                <VERSION pattern="KERNEL">mvn_sclkscet_$VERSION.tsc</VERSION>
            </patterns>
        </kernel>
        <kernel pattern="de[0-9][0-9][0-9]s.bsp">
            <description>SPICE SPK file containing JPL planetary ephemerides version $VERSION, created by NAIF, JPL.
            </description>
            <patterns>
                <VERSION pattern="de430s.bsp">DE430</VERSION>
            </patterns>
        </kernel>
        <kernel pattern="mar[0-9][0-9][0-9]s.bsp">
            <description>SPICE SPK file containing JPL Martian satellite ephemerides version $VERSION, created by NAIF,
                JPL.
            </description>
            <patterns>
                <VERSION pattern="mar097s.bsp">MAR097</VERSION>
            </patterns>
        </kernel>
        <kernel pattern="maven_struct_v[0-9][0-9].bsp">
            <description>SPICE SPK file containing relative locations of selected MAVEN structures and science
                instruments, created by NAIF, JPL.
            </description>
        </kernel>
        <kernel pattern="maven_cru_rec_[0-9][0-9][0-9][0-9][0-9][0-9]_[0-9][0-9][0-9][0-9][0-9][0-9]_v[0-9].bsp">
            <description>SPICE SPK file containing reconstructed cruise trajectory of the MAVEN spacecraft, created by
                MAVEN NAV Team, JPL. The original name of this file was trj_c_131118-140923_rec_v1.bsp.
            </description>
        </kernel>
        <kernel pattern="maven_orb_rec_[0-9][0-9][0-9][0-9][0-9][0-9]_[0-9][0-9][0-9][0-9][0-9][0-9]_v[0-9].bsp">
            <description>SPICE SPK file containing reconstructed orbital trajectory of the MAVEN spacecraft, created by
                NAIF, JPL by merging operational weekly reconstructed SPK files produced by MAVEN NAV Team, JPL.
            </description>
        </kernel>
        <kernel pattern="mvn_swea_nom_[0-9][0-9][0-9][0-9][0-9][0-9]_[0-9][0-9][0-9][0-9][0-9][0-9]_v[0-9][0-9].bc">
            <description>SPICE CK file containing nominal orientation of the MAVEN SWEA instrument boom, created by
                NAIF, JPL.
            </description>
        </kernel>
        <kernel pattern="mvn_app_rel_[0-9][0-9][0-9][0-9][0-9][0-9]_[0-9][0-9][0-9][0-9][0-9][0-9]_v[0-9][0-9].bc">
            <description>SPICE CK file containing reconstructed orientation of the MAVEN Articulated Payload Platform
                (APP), created by NAIF, JPL.
            </description>
        </kernel>
        <kernel pattern="mvn_iuvs_rem_[0-9][0-9][0-9][0-9][0-9][0-9]_[0-9][0-9][0-9][0-9][0-9][0-9]_v[0-9][0-9].bc">
            <description>SPICE CK file containing reconstructed orientation of the MAVEN IUVS instrument internal
                mirror, created by NAIF, JPL by merging data from daily IUVS CKs produced by the IUVS Team, CU/LASP.
            </description>
        </kernel>
        <kernel pattern="mvn_sc_rel_[0-9][0-9][0-9][0-9][0-9][0-9]_[0-9][0-9][0-9][0-9][0-9][0-9]_v[0-9][0-9].bc">
            <description>SPICE CK file containing reconstructed orientation of the MAVEN spacecraft, created by NAIF,
                JPL.
            </description>
        </kernel>
        <kernel pattern="mvn_sc_pred_[0-9][0-9][0-9][0-9][0-9][0-9]_[0-9][0-9][0-9][0-9][0-9][0-9]_v[0-9][0-9].bc">
            <description>SPICE CK file containing predicted orientation of the MAVEN spacecraft, created by NAIF,
                JPL. The original name of this file was $ORIGINAL.
            </description>
            <patterns>
                <ORIGINAL value="mvn_sc_pred_210104_210120_v01.bc">mvn_sc_pred_210104_210120_vm321_322_v03.bc</ORIGINAL>
                <ORIGINAL value="mvn_sc_pred_141205_141209_v01.bc">mvn_sc_pred_141205_141209_vm002OTM_v02.bc</ORIGINAL>
                <ORIGINAL value="mvn_sc_pred_141223_150109_v01.bc">mvn_sc_pred_141223_150109_vm004_v02.bc</ORIGINAL>
                <ORIGINAL value="mvn_sc_pred_150302_150315_v01.bc">mvn_sc_pred_150302_150315_vm013ar01_v01.bc</ORIGINAL>
                <ORIGINAL value="mvn_sc_pred_150630_150707_v01.bc">mvn_sc_pred_150630_150707_vm027b_v01.bc</ORIGINAL>
            </patterns>
        </kernel>
        <kernel pattern="mvn_app_pred_[0-9][0-9][0-9][0-9][0-9][0-9]_[0-9][0-9][0-9][0-9][0-9][0-9]_v[0-9][0-9].bc">
            <description>SPICE CK file containing predicted orientation of the MAVEN Articulated Payload Platform
                (APP), created by NAIF, JPL. The original name of this file was $ORIGINAL.
            </description>
            <patterns>
                <ORIGINAL value="mvn_app_pred_210104_210120_v01.bc">mvn_app_pred_210104_210120_vm321_322_v03.bc</ORIGINAL>
                <ORIGINAL value="mvn_app_pred_141205_141209_v01.bc">mvn_app_pred_141205_141209_vm002OTM_v02.bc</ORIGINAL>
                <ORIGINAL value="mvn_app_pred_141223_150109_v01.bc">mvn_app_pred_141223_150109_vm004_v02.bc</ORIGINAL>
                <ORIGINAL value="mvn_app_pred_150302_150315_v01.bc">mvn_app_pred_150302_150315_vm013ar01_v01.bc</ORIGINAL>
                <ORIGINAL value="mvn_app_pred_150630_150707_v01.bc">mvn_app_pred_150630_150707_vm027b_v01.bc</ORIGINAL>
            </patterns>
        </kernel>
        <kernel pattern="maven_[0-9][0-9][0-9][0-9]_v[0-9][0-9].tm">
            <description>SPICE MK file listing kernels for $YEAR, created by NAIF, JPL.</description>
            <patterns>
                <YEAR pattern="KERNEL">maven_$YEAR_v[0-9][0-9].tm</YEAR>
            </patterns>
        </kernel>
    </kernel_list>

    <!-- =========================== -->
    <!-- Meta-kernel                 -->
    <!-- =========================== -->
    <meta-kernel>
        <!-- Each meta-kernel present in the bundle can be automatically
             generated by NPB, providing the parameters below. -->
        <mk name="maven_$YEAR_v$VERSION.tm">
            <name>
                <pattern length="2">VERSION</pattern>
                <pattern length="4">YEAR</pattern>
            </name>
            <coverage_kernels>
                <!-- These kernels determine the coverage of the increment -->
                <pattern>maven_orb_rec_[0-9]{6}_[0-9]{6}_v[0-9].bsp</pattern>
            </coverage_kernels>
            <interrupt_to_update>False</interrupt_to_update>
            <grammar>
                <!-- LSK -->
                <pattern>naif0012.tls</pattern>
                <!-- PCK -->
                <pattern>pck00010.tpc</pattern>
                <!-- FK -->
                <pattern>maven_v[0-9]{2}.tf</pattern>
                <!-- IK -->
                <pattern>maven_ant_v[0-9]{2}.ti</pattern>
                <pattern>maven_euv_v[0-9]{2}.ti</pattern>
                <pattern>maven_iuvs_v[0-9]{2}.ti</pattern>
                <pattern>maven_ngims_v[0-9]{2}.ti</pattern>
                <pattern>maven_sep_v[0-9]{2}.ti</pattern>
                <pattern>maven_static_v[0-9]{2}.ti</pattern>
                <pattern>maven_swea_v[0-9]{2}.ti</pattern>
                <pattern>maven_swia_v[0-9]{2}.ti</pattern>
                <!-- SCLK -->
                <pattern>MVN_SCLKSCET.[0-9]{5}.tsc</pattern>
                <pattern>mvn_sclkscet_[0-9]{5}.tsc</pattern>
                <!-- SPK -->
                <pattern>de430s.bsp</pattern>
                <pattern>mar097s.bsp</pattern>
                <pattern>maven_struct_v[0-9]{2}.bsp</pattern>
                <pattern>date:maven_orb_rec_[0-9]{6}_[0-9]{6}_v[0-9].bsp</pattern>
                <!-- CK -->
                <pattern>date:mvn_iuvs_rem_[0-9]{6}_[0-9]{6}_v[0-9]{2}.bc</pattern>
                <pattern>date:mvn_app_pred_[0-9]{6}_[0-9]{6}_v[0-9]{2}.bc</pattern>
                <pattern>date:mvn_app_rel_[0-9]{6}_[0-9]{6}_v[0-9]{2}.bc</pattern>
                <pattern>mvn_swea_nom_131118_300101_v[0-9]{2}.bc</pattern>
                <pattern>date:mvn_sc_pred_[0-9]{6}_[0-9]{6}_v[0-9]{2}.bc</pattern>
                <pattern>date:mvn_sc_rel_[0-9]{6}_[0-9]{6}_v[0-9]{2}.bc</pattern>
                <!-- DSK -->
            </grammar>
            <metadata>
                <description>
                    This meta-kernel lists the MAVEN SPICE kernels providing coverage
                    for $YEAR. All of the kernels listed below are archived in the PDS
                    MAVEN SPICE kernel archive. This set of files and the order in which
                    they are listed were picked to provide the best available data and
                    the most complete coverage for the specified year based on the
                    information about the kernels available at the time this meta-kernel
                    was made. For detailed information about the kernels listed below
                    refer to the internal comments included in the kernels and the
                    documentation accompanying the MAVEN SPICE kernel archive.
                </description>
                <!-- The keyword field is used to speficy parameters such as the
                     meta-kernel year.
                -->
                <keyword> </keyword>
                <data> </data>
            </metadata>
        </mk>
    </meta-kernel>

    <!-- =========================== -->
    <!-- Orbit number file           -->
    <!-- =========================== -->
    <orbit_number_file>
        <orbnum>
            <pattern>maven_orb_rec_[0-9]{6}_[0-9]{6}_v[0-9].orb</pattern>
            <!-- Parameters from the orbnum generation preference file -->
            <event_detection_frame>
                <spice_name>IAU_MARS</spice_name>
                <description>Mars body-fixed frame</description>
            </event_detection_frame>
            <header_start_line>1</header_start_line >
            <pck>
                <kernel_name>pck0010.tpc</kernel_name>
                <description>IAU 2009 report</description>
            </pck>
            <coverage>
                <kernel cutoff="True">../data/kernels/spk/maven_orb_rec_210101_210401_v2.bsp</kernel>
            </coverage>
            <author>NAIF, JPL</author>
        </orbnum>
    </orbit_number_file>
</naif-pds4-bundler_configuration>

PDS Parameters

PDS Parameters are mission-level and bundle-level agnostic and are only related to the PDS version, information model (IM), and available registered context products. The table below provides a summary of the parameters:

PDS Parameters

Element	Description	Required?
pds_version	Archive PDS version. Currently only 4 is fully implemented.	Yes
information_model	Specifies the PDS4 information model to be used.	Yes
xml_model	URL location of the XML Schematron associated with an information model. The information_model and xml_model parameters must refer to the same information model. If not provided NPB generates it from the information_model.	No
schema_location	URL location of the XML Schema associated with an information model. The schema_location and xml_model parameters must refer to the same information model. If not provided NPB generates it from the information_model.	No
logical_identifier	Logical identifier for the bundle.	Yes
context_products	Provides the location of a file that lists required context products that are not available in the registered context products. More information below.	No

The Information Model

The information_model parameter will determine the PDS4 artifacts templates that will be used for the bundle generation. NPB provides different templates depending on the specified IM. The available templates are located under naif-pds4-bundler/src/pds/naif_pds4_bundler/templates.

NAIF currently uses IM 1.5.0.0 for all its archives, but it is recommended to use IM 1.16.0.0 or higher especially if you need to include a DOI in the bundle label and have Line Feed (LF) as line endings for all the products. NPB will choose the templates that apply to the version you specify: if the IM is equal or higher than one of the available version templates, these templates will be used. You can also specify a directory with your own templates, see section Templates Directory.

The choice of the IM will determine the xml_model and schema_location values. The only element value that will change is the one that specifies the IM version.

The IM choice impacts other elements of the configuration file and of the archive generation such as some contents of the SPICEDS file and the templates used for the generation of PDS artifacts. These impacts are described in the appropriate sections.

Context Products

The context_products parameter provides the location of a JSON file that contains additional context un-registered context products. This file is required if the primary and/or secondary observer(s) and/or target(s) of the bundle are not registered. The registered products are available in the following file: src/naif_pds4_bundler/templates/registered_context_products.json. This list of registered context products is generated based on the registered context products obtained with the PDS Validate tool with minor modifications, and is maintained by the NAIF NPB developer.

The management of context products requires a bit of attention. Although NPB will raise a run time error if any of the observers or targets is not registered, we recommend that you search these items in the registered context products. If you cannot find them, you need to provide them in the configuration file. In order to do so, you will need to include the following elements per product:

• Product Name e.g.: DART, InSight Mars Lander Spacecraft

• Product Type e.g.: Spacecraft, Planet, Asteroid, Satellite

• Product LIDIV e.g.: urn:nasa:pds:context:instrument_host:spacecraft.dart::1.0 urn:nasa:pds:context:instrument_host:spacecraft.insight::2.0

Here’s an example for the DART mission:

<context_products>
    <product name="DART">
        <type>Spacecraft</type>
        <lidvid>urn:nasa:pds:context:instrument_host:spacecraft.dart::1.0</lidvid>
    </product>
    <product name="LICIA">
        <type>Spacecraft</type>
        <lidvid>urn:nasa:pds:context:instrument_host:spacecraft.licia::1.0</lidvid>
    </product>
    <product name="Earth">
        <type>Planet</type>
        <lidvid>urn:nasa:pds:context:target:planet.earth::1.0</lidvid>
    </product>
    <product name="Didymos">
        <type>Asteroid</type>
        <lidvid>urn:nasa:pds:context:target:asteroid.didymos::1.0</lidvid>
    </product>
    <product name="Dimorphos">
        <type>Satellite</type>
        <lidvid>urn:nasa:pds:context:target:satellite.didymos.dimorphos::1.0</lidvid>
    </product>
</context_products>

In addition, contact your archiving authority contact to ensure that the context product information is correct. If your archiving authority is the PDS you will need to consult with the leading node of the mission archive.

Bundle Parameters

Bundle Parameters provide bundle level information required for the PDS4 artifacts and are SPICE Kernel collection-agnostic. The table below provides a summary of the parameters:

Bundle Parameters

Element	Description	Required?
producer_name	Name of the archive producer (or NPB operator.)	Yes
author_list	Name of the SPICE kernel main author(s) and the archive producer (or NPB operator.)	Yes
institution	Institution affiliation of the archive produced e.g., NAIF/JPL, PSA/ESA, etc.	Yes
doi	Digital Object Identifier (DOI) of the bundle. More information in Digital Objects Identifiers.	No
spice_name	Specifies the SPICE name of the main spacecraft of the archive.	Yes
spiceds	Indicates the location of the SPICE Data Archive Description document (SPICEDS) for the release.	No
readme	Provides the parameters required to generate the bundle readme file by using the readme file template or the path to an input readme file.	No
release_date	Bundle increment release date. The date is provided with a UTC calendar format string with following syntax: YYYY-MM-DD e.g. 2021-04-09. If not provided the NPB execution date is used. NAIF does not recommend to include this parameter.	No
creation_date_time	Creation date and time for all the products of the release. Usage of this parameter is highly discouraged. The date is provided with a UTC calendar format string with following syntax: YYYY-MM-DDThh:mm:ss e.g. 2021-06-25T08:00:00. If not provided the NPB execution date is used.	No
increment_start	Archive release start time. This time forces the More details are provided in Product Coverage Assignment Rules. The date is provided with a UTC calendar format string with following syntax: YYYY-MM-DDThh:mm:ssZ e.g. 2021-06-25T08:00:00Z. NAIF does not recommend to include this parameter.	No
increment_finish	Release stop time. More details are provided in Product Coverage Assignment Rules. The date is provided with a UTC calendar format string with following syntax: YYYY-MM-DDThh:mm:ssZ e.g. 2021-06-25T08:00:00Z. NAIF does not recommend to include this parameter.	No
date_format	Product labels use different date and time formats. The values can be infomod2 or maklabel. More information is provided below. The default value is maklabel.	No
end_of_line	The end of line character for products can either be CRLF or LF. The default is CRLF (for <CR><LF>). NAIF recommends to use <CRLF> when using PDS IM version prior to 1.14.0.0. The choice of this parameter affects the content of the SPICEDS file (section “File Formats”.) More information is provided in SPICE Data Set Catalog File.	No
binary_endianness	Binary SPICE kernels (SPK, CK, DSK, PCK) can either be little endian (LTL-IEEE, little) or big endian (BIG-IEEE, big). NAIF requires little endian binary kernels for PDS4 archives and therefore it is the default value of this element. The choice of this parameter affects the content of the SPICEDS file (section “File Formats”.) More information is provided in Binary Kernels Endianness.	No

SPICEDS

In addition to the NPB Configuration File -if the meta-kernel is generated automatically - the SPICEDS file is the only bundle product that requires manual intervention. More details on SPICEDS are provided in the section SPICE Data Set Catalog File.

Readme File

The readme file configuration provides either the parameters required to generate the readme file by NPB or the path to an input readme file.

If the readme file is generated by NPB, the readme file template will be used along with the elements included in the configuration:

• overview provides an overview of the archive and

• cognisant_persons indicates the institution responsible for the archive generation.

If present these elements should have the same value for all archive releases.

Otherwise if a path for the readme file is specified the following element needs to be included in the configuration:

• input provides the relative or absolute path to the input readme file.

This element of the configuration file must be present, when a readme file already exists in a bundle its generation will be ignored.

More information on the readme file is provided in section Bundle Products Construction Rules.

Increment Start and Finish Times

These configuration elements, if present, set the archive increment start and stop times regardless of the coverage times provided by the MK(s) –if any–.

NPB will set the MK(s) start and finish times to this elements –each individually–, and will propagate these times to the SPICE Kernels Collection and to the Bundle labels. Note that for yearly MKs –see section Preparing Meta-kernels–, NPB will only update the start or finish times for the MKs that correspond either to the start or finish year.

Note that these configuration elements should be used with care and understanding their implications on the bundle coverage.

Date Format

There two possible strategies for date time string format across the archive: maklabel and infomod2.

infomod2 stands for “PDS Information Model 2.0.0.0”. This format sets the format of all date time instances across the label products to:

yyyy-mm-ddThh:mm:ss.sssZ

where

• yyyy is the 4-digit year

• mm is the 2-digit month

• dd is the 2-digit day

• hh is the 2-digit hour (24h format)

• mm are the 2-digit minutes

• ss.sss are the seconds and milliseconds rounded inwards to milliseconds.

For example: 2016-01-01T00:00:00.000Z. The main characteristic is of this format is that is used for all labels and milliseconds are rounded inwards: start times are rounded to the next nearest millisecond and stop times are rounded to the previous nearest millisecond. The coverage specified for SPICE kernels products and for those products whose coverage is determined by them will always be within the time bounds of the SPICE kernel. For example 2016-01-01T00:00:00.1257Z will be rounded to 2016-01-01T00:00:00.126Z if it is a start time, and to 2016-01-01T00:00:00.125Z if it is a stop time.

The maklabel format replicates the date time formats provided by NAIF’s MAKLABEL utility [MAKLABEL]. MAKLABEL has been used for all NAIF’s PDS3 data sets and for some PDS4 archives and sets the format of all date time instances across the label products, except for the CK kernel labels to:

yyyy-mm-ddThh:mm:ssZ

whereas sets times for CK kernel labels to:

yyyy-mm-ddThh:mm:ss.sssZ

the fields are the same as for the infomod2 format except that for non CK labels it rounds the decimal part of the seconds to the nearest second. Because of this, labels with non-integer-second times are outside of the actual file coverage.

Note that the date time strings provided via configuration (mission_start, mission_finish at least) that feed label tags need to be provided with the appropriate format to NPB, if not NPB will raise a run time error. This does not apply to the times provided in the kernel list section of the configuration.

NAIF uses the maklabel format for PDS IM 1.5.0.0 archives for comparison and reproducibility reasons. The idea is that NAIF will use infomod2 only after the PDS IM 2.0.0.0 is released. NAIF recommends using the infomod2 format, especially for new archives.

More details on the determination of coverage for different files in the archives are provided in section Product Coverage Assignment Rules.

Mission Parameters

Mission parameters provide mission-specific information such as: mission name, acronym, observers, and targets. The table below provides a summary of the parameters:

Mission Parameters

Element	Description	Required?
mission_acronym	Specifies the mission acronym that is used to construct the directory structure and some of the NPB execution by-products.	Yes
mission_name	Specifies the mission name that is used in several product labels. This name must correspond to the name provided by the registered context products (including the ones provided via configuration.)	Yes
observer	The observer is the main spacecraft of the data and the SPICE kernels, this name must correspond to the name provided by the registered context products (including the ones provided via configuration.)	Yes
target	The target is the mission’s primary target (investigated natural body), this name must correspond to the name provided by the registered context products including the ones provided via configuration.)	Yes
kernels_to_load	Lists the SPICE kernels that are required to run NPB. More information is provided below.	Yes
mission_start	Mission start time; typically is the start time of the post-launch SPK. The date is provided with a UTC calendar format string. The syntax of the string is determined by the date_format used.	Yes
mission_finish	Mission finish time; typically is the start time of the post-launch SPK. The date is provided with a UTC calendar format string. The syntax of the string is determined by the date_format used.	Yes
secondary_observers	Provides a list of the secondary spacecrafts present in the SPICE kernels. Each name entry must use the observer tag. These names must correspond to the names provided by the registered context products (including the ones provided via configuration.)	No
secondary_targets	Provides a list of the secondary targets present in the SPICE kernels. Each name entry must use the target tag. These names must correspond to the names provided by the registered context products (including the ones provided via configuration.)	No

On Names and Acronyms

Distinction in between mission_acronym, mission_name, observer, and the Bundle parameter spice_name can be rather confusing. A good example to distinguish in between the parameters is the Mars 2020 SPICE kernel archive, for which the values are as follows:

• mission_acronym: mars2020

• mission_name: Mars 2020 Perseverance Rover Mission

• observer: Mars 2020 Perseverance Rover

• spice_name: M2020

Contrarily for other archives, such as MAVEN, is as follows:

• mission_acronym: maven

• mission_name: MAVEN

• observer: MAVEN

• spice_name: MAVEN

A note on secondary observers and targets: although secondary s/c and/or targets might be present in the SPICE kernels, they do not have to be present in the Configuration File, nor in the bundle PDS4 labels. It is perfectly fine to use the primary s/c and target for all kernels.

This is the case for the InSight SPICE kernel bundle: the secondary s/c MARCO-A and MARCO-B use InSight in their labels as observer. If this simplified approach is followed then it must be noted in the Errata section of the SPICE archive description document (SPICEDS) as follows:

All MARCO-A and MARCO-B kernels included in the archive
are labeled as being associate the INSIGHT instrument host.

This simplified approach is especially convenient for missions that have a main prime s/c or target. For other missions such as BepiColombo where the Mercury Planet Orbiter (MPO) and the Mercury Magnetospheric Orbiter (MMO or MIO) have a comparable relevance, the bundle must include a secondary s/c. Here’s an example of the entries for secondary s/c and targets for DART:

<observer>DART</observer>
<target>Didymos</target>
(...)
<secondary_observers>
    <observer>LICIA</observer>
</secondary_observers>
<secondary_targets>
    <target>Dimorphos</target>
    <target>Earth</target>
</secondary_targets>

Kernels To Load

The kernels_to_load mission parameter lists the SPICE kernels that are required to run NPB. At least a LSK, a SCLK, and a FK kernel will be required; if there are multiple observers most likely more FKs and SCLKs will be required. PCKs might also be needed.

These kernels are used by NPB to use SPICE (via SpiceyPy [SPICEYPY] a wrapper to CSPICE for Python) to perform time conversions (a LSK kernel is needed), to obtain different bundle coverages (SPKs, CKs, FKs and SCLKs are needed), and to support coverage determination of kernels included in the release.

Understanding which kernels need to be loaded requires some experience with SPICE and some experience with the SPICE kernels of the mission to be archived. If you have any questions please contact the NAIF NPB developer.

You can either specify a kernel name or a kernel name with a pattern (recommended). More information on kernel patterns is provided in Kernel patterns.

In the Configuration File, each entry must be specified by its kernel type, there can be multiple entries with the same kernel type. For InSight for example:

<kernels_to_load>
    <lsk>naif[0-9][0-9][0-9][0-9].tls</lsk>
    <sclk>NSY_SCLKSCET.[0-9][0-9][0-9][0-9][0-9].tsc</sclk>
    <sclk>marcoa_fake_v[0-9][0-9].tsc</sclk>
    <fk>../data/kernels/fk/insight_v05.tf</fk>
    <fk>marcob_v[0-9][0-9].tf</fk>
</kernels_to_load>

NPB will use the bundle_directory and kernels_directory directories specified in the next section of the Configuration File “Directories” to search for the latest version of these kernels (if provided by patterns) or to the kernel specified (if the kernel name does not contain patterns.)

Kernel patterns

Throughout the configuration you will find multiple occurrences of kernels that are specified with a pattern. The usage of patterns allows NPB to know that it must scan a directory or a list of directories, for a specific version of the kernel within the possibilities provided by the pattern, such as the latest version of a specific kernel.

The patterns recognised by NPB are quite limited and are a subset of the ones used for regular expressions. They are the following:

• [0-9]: any digit

• [a-z]: any lowercase letter

• [A-Z]: any uppercase letter

In addition there are two special patterns:

• {n}: is placed after another pattern and indicates “n” repetitions of that pattern; n spans from 1 to a N where N is a number limited by the SPICE file name length. E.g., [0-6]{4} are four consecutive digits (used to specify a year for example: 2021.)

• $: indicates that the contiguous set of uppercase letters correspond to a literal pattern e.g., $YEAR indicates that this will be replaced by a year. Use cases are provided later in the document.

Therefore the following FK kernel pattern: maven_v[0-9][0-9].tf, would be matched by any version of the MAVEN FK, for example maven_v09.tf.

Directories

They specify the directories used to run NPB. The table below provides a summary of the required and optional directories:

Directories

Element	Description	Required?
working_directory	Specifies the directory that will be used by NPB to generate the execution by-products that include but are not limited to: execution log, kernel list, and the file list. It is a good idea to use the working directory to store the configuration file(s), validation reports, archive plans, etc. More information of this directory is provided in section Working Directory.	Yes
kernels_directory	Specifies the directory(ies) that will be used by NPB to obtain the kernels to be archived from. It is recommended that these directories follow the usual operational SPICE kernel sub-directory structure by kernel type.	Yes
staging_directory	This directory will be used by NPB to store the files generated by its execution for the archive (the release or increment.)	Yes
bundle_directory	Indicates the directory where the current version of the SPICE kernel bundle is present (before the execution of NPB.)	Yes
orbnum_directory	Indicates the directory(ies) where the orbit number files to be archived are present.	No
templates_directory	Indicates the directory where the user input templates are present.	No

The working, staging, and bundle directories cannot be the same. More information on the setup of the NPB directories is provided in Workspace Setup.

Templates Directory

This entry is optional and specifies the directory where your own templates reside. These templates need to follow the specifications of the templates provided with NPB. An example of user provided templates is available for the ExoMars2016 bundle under naif-pds4-bundler/tests/naif_pds4_bundler/templates/em16.

The templates need to include all the keywords present in the default NPB templates. These keywords start with $ and are uppercase. You will also need to make sure that the resulting PDS4 products are correct by running the PDS validate tool against them. It is also recommended to provide them to NAIF for review.

Kernel List

The Kernel List is an NPB execution by-product (more information on NPB execution by-products is provided in Execution by-products) that is used for two main purposes:

• to generate a description for each kernel to be archived; the description of the kernel is present in all kernel labels

• if necessary, to change the name of the provided kernels to the name required by the archive

NPB will try to match every input kernel, including meta-kernels, with an entry of the kernel list and based on that will generate a Kernel List product. This section of the configuration provides a list of all the kernels that might be included in the bundle for any release. Consequently, the Kernel List section in the configuration file is prone to grow as new archive releases are prepared.

The Kernel List configuration section includes a kernel element for each kernel that has a pattern attribute the value of which is a kernel name with (or without) a pattern. For example:

<kernel_list>
    <kernel pattern="naif[0-9][0-9][0-9][0-9].tls">

This kernel element is used to identify the leapseconds kernels present in the kernels to be archived. An important remark of the pattern attribute value is that it cannot contain any of the special patterns {n} or $, and therefore can only include [0-9], [a-z], and [A-Z] patterns.

element is a leftover of the PDS3 data sets and for all the kernels in PDS4 bundles can be omitted.

If the number of characters for a given pattern of a kernel to load is not known in advance then multiple entries in the kernel list should be used in the configuration file. For example, if you do not know whether you will have one of the following files:

msl_76_sclkscet_refit_j5.tsc
msl_76_sclkscet_refit_k13.tsc

Then the two entries specified hereunder can be provided in the kernel list:

<kernel pattern="msl_76_sclkscet_refit_[a-z][0-9].tsc">       (...)
<kernel pattern="msl_76_sclkscet_refit_[a-z][0-9][0-9].tsc">  (...)

The second and third element patterns are optional and provide the observers and targets required by the kernels. By default, the kernel label will set its observer and target elements to the <observer> and <target> provided in the Mission Parameters section of the configuration file. But what happens if the kernel data for one of the secondary observers/targets or for several of them? Since there is no way to fully automatize the identification of all possible cases this is indicated in this element of the kernel list. The following example should be self-explanatory:

<observers>
    <observer>DART</observer>
    <observer>LICIA</observer>
</observers>
<targets>
    <target>Didymos</target>
    <target>Dimorphos</target>
</targets>

Kernel Descriptions

The fourth (or second) nested element is the kernel description. This is a very important configuration parameter and its content must describe synthetically and precisely the SPICE kernel. The recommended structure of the description is:

SPICE <text/binary> <kernel type> kernel ... created by <producer>, <institution>.

where

• <text/binary> is either text or binary

• <kernel type> is the kernel type acronym (SPK, FK, etc.)

• <producer> is the author or the group that generated the kernel

• <institution> is the affiliation of the kernel producer.

For example:

<description>SPICE LSK file incorporating leapseconds up to $DATE, created by NAIF, JPL.</description>

The description element might contain patterns based on the special expression $ followed by an upper case name, $DATE in the example above. These patterns are used to accommodate information particular to each individual kernel of each kind. In the example above the $DATE expression is meant to specify the year of the latest leapsecond provided by that kernel. Other examples are: original name of the kernel (see Renaming Files), version of the IAU report, kernel coverage, etc. These patterns are determined by the next element: patterns.

The patterns element maps the patterns present in the description element with its value. NPB maps the patterns with one of the following methods:

• match by value

• match by pattern

• match from comment

These are described in the following subsections.

Match by value

The first method to identify patterns in the kernel pattern attribute value is by value. In order to do so, the kernel pattern attribute value is set to value and its value corresponds to the actual name of the kernel, without patterns, in such a way that the value of the element is substituted by the pattern in the resulting description. It is also possible to use a subset of the kernel name but this option should be used carefully and only if the subset identifies a unique kernel “type”.

Going back to the leapseconds example, the complete entry in the kernel list would be:

<kernel pattern="naif[0-9][0-9][0-9][0-9].tls">
    <description>SPICE LSK file incorporating leapseconds up to $DATE, created by NAIF, JPL.</description>
    <patterns>
        <DATE value="naif0011.tls">2015-JAN-01</DATE>
        <DATE value="naif0012.tls">2017-JAN-01</DATE>
    </patterns>
</kernel>

In this case, if the kernel to be archived is naif0012.tls then the description for the label will be:

SPICE LSK file incorporating leapseconds up to 2017-JAN-01, created by NAIF, JPL.

Because the $DATE pattern has been replaced by the DATE element nested from the patterns element and the kernel name equals one of the values of the value attribute. With this configuration, archiving naif0010.tls would have resulted into a runtime error:

RuntimeError: -- Kernel naif0010.tls description could not be updated with pattern.

The names of the elements to map the patterns are defined by the user. Some examples are provided hereunder:

• ORIGINAL: specify the original name of the kernel.

• REPORT: specify the IAU report for PCKs.

• DATE: specifies a date.

• FILE: specify the original name of the kernel

These names are meant to help the archive producers to understand the pattern matching.

The limitation of this method is that each individual kernel type requires an element entry in the configuration file.

Match by pattern

This method uses parts of the kernel name pattern to identify patterns required by the kernel description. Another way to describe it, using XML terminology: this method uses the pattern attribute value of the kernel element to map one pattern of its file name as obtained from the kernel name without patterns.

To do so, nested elements from patterns are provided. The name of the element coincides with a pattern with the special pattern $ and is indicated by an attribute called pattern.

Take the following kernel element form the kernel list for MAVEN:

<kernel pattern="maven_[0-9][0-9][0-9][0-9]_v[0-9][0-9].tm">
    <description>SPICE MK file listing kernels for $YEAR, created by NAIF, JPL.</description>
    <patterns>
        <YEAR pattern="KERNEL">maven_$YEAR_v[0-9][0-9].tm</YEAR>
    </patterns>
</kernel>

In this case we need to obtain the $YEAR pattern for the description. The value of the YEAR element indicates that NPB must extract the $YEAR value from the first pattern of the kernel pattern:

maven_[0-9][0-9][0-9][0-9]_v[0-9][0-9].tm
maven_       $YEAR        _v[0-9][0-9].tm

If the archived kernel is maven_2021_v01.tm the $YEAR value will be 2021 and the description will be:

SPICE MK file listing kernels for 2021, created by NAIF, JPL.

The names of the elements to map the patterns are defined by the configuration file schema. They are currently limited to:

• YEAR: used to specify a year.

• START: indicates that we are looking at the coverage start time.

• FINISH: indicates that we are looking at the coverage finish time.

• COVERAGE: specific name for OSIRIS-REx DSKs.

• REFERENCE: specific name for OSIRIS-REx DSKs.

• VERSION: indicates that SPICE kernel version.

• DATE: indicates that we are extracting a date from the name.

• ORIGINAL: indicates that we obtaining the original kernel name.

These names are meant to help the archive producers to understand the pattern matching. Any of these names can be used regardless of the pattern. If you need to add additional elements please contact the NAIF NPB developer.

Match from Comment

Sometimes the original name of the kernel that must be included in the description is only present in the comment area of the binary kernel (SPK, CK, DSK or binary PCK), if so the comment must be extracted from the kernel. The kernel file name must be in a single line. NPB will extract the comment if you indicate it to do so similar to the way the “Match by pattern” method is used.

The pattern nested element must have an attribute called file the value of which must be COMMENT. Currently the only available name for the element is ORIGINAL, to indicate that you are mapping the description with the original kernel name. Also, the value of the ORIGINAL element must be the text of the line that precedes the original kernel name in the comment area of the kernel:

<kernel pattern="mro_sc_psp_[0-9][0-9][0-9][0-9][0-9][0-9]_[0-9][0-9][0-9][0-9][0-9][0-9]p.bc">
    <description>MRO SPICE CK file providing predicted orientation of the MRO spacecraft bus modeled by the MRO Spacecraft Team, LMA using the AtArPS tool for a part of the Extended Science phase of the mission, created by NAIF, JPL. The original name of this file was $ORIGINAL
    </description>
    <patterns>
        <ORIGINAL file="COMMENT">The original name of this file was</ORIGINAL>
    </patterns>
</kernel>

The value of the ORIGINAL element will be then used to extract the kernel name from the CK comment area. If we use the NAIF utility COMMNT we can read the comment in an example kernel mro_sc_psp_210628_210710p.bc:

$ commnt -r mro_sc_psp_210628_210710p.bc

********************************************************************************

The original name of this file was CK_Pred_21180_21192_sc_20210629155609.bc.
It was changed to mro_sc_psp_210628_210710p.bc on Thu Aug 12 17:51:24 PDT 2021.
(...)

The line with The original name of this file was must be present and will be used and therefore CK_Pred_21180_21192_sc_20210629155609.bc will be extracted and the description will then be:

MRO SPICE CK file providing predicted orientation of the MRO spacecraft
bus modeled by the MRO Spacecraft Team, LMA using the AtArPS tool for a
part of the Extended Science phase of the mission, created by NAIF, JPL.
The original name of this file was CK_Pred_21180_21192_sc_20210629155609.bc.

This method has been implemented for the MRO PDS3 SPICE kernel data set generation. NAIF does not recommend to record the original name of the kernel in the comment area kernels.

Mapping kernels

Sometimes the name of the archived kernel is modified with respect to the original kernel - sometimes present in the kernels operational area - this happens for kernels that have long names, mixed case, fields that are meaningless to users but are meaningful to operation engineers, etc. In such cases NAIF recommends to update the archived kernel name for it to be more user friendly.

The mapping in between the original kernel name and the archived kernel name can be achieved in two different ways.

The first approach consists to update the name manually and to use the updated name in the release plan. If the original name of the kernel has to be included in the kernel description, this can be implemented with the “Match by value” method by reflecting this on the attribute value of the given kernel element.

The second and recommended approach also requires the name in the release plan to be the updated one but adds a special element nested in the corresponding kernel element of the kernel list configuration section. This special “mapping” element is called mapping and if present, it must be the first element of the nested elements of a kernel. If this element is present then the patterns present for the “Match by pattern” method must also be present. The mapping element contains the original kernel name with the patterns provided with the special pattern $; those patterns are then correlated with the ones provided in the patterns nested elements.

Say that we need to rename the OSIRIS-REx asteroid Bennu DSKs. The original name is:

l_00050mm_alt_ptm_5595n04217_v021.bds

and we want to rename it to:

bennu_l_00050mm_alt_ptm_5595n04217_v021.bds

With the first approach we would simply rename it, and given that in the description we want to include the original file name, the <kernel> entry in the Kernel List section of the configuration file would be:

<kernel pattern="bennu_l_[0-9][0-9][0-9][0-9][0-9]mm_alt_dtm_[0-9][0-9][0-9][0-9][a-z][0-9][0-9][0-9][0-9][0-9]_v[0-9][0-9][0-9].bds">
    <description>SPICE DSK file containing shape model data for the surface of asteroid (101955) Bennu,
        created by the ORX Altimetry Working Group (AltWG). The original name of this file was $ORIGINAL.</description>
    <patterns>
        <ORIGINAL value="bennu_l_00050mm_alt_ptm_5595n04217_v021.bds">l_00050mm_alt_ptm_5595n04217_v021.bds</ORIGINAL>
        <ORIGINAL value="bennu_l_00050mm_alt_ptm_5595n04217_v020.bds">l_00050mm_alt_ptm_5595n04217_v020.bds</ORIGINAL>
    </patterns>
</kernel>

This approach would require a pattern entry per DSK. The second approach, albeit more difficult to implement, would work for each DSK:

<kernel pattern="bennu_l_[0-9][0-9][0-9][0-9][0-9]mm_alt_dtm_[0-9][0-9][0-9][0-9][a-z][0-9][0-9][0-9][0-9][0-9]_v[0-9][0-9][0-9].bds">
    <mapping>l_$RESOLUTIONmm_alt_dtm_$REFERENCE_v$VERSION.bds</mapping>
    <description>SPICE DSK file containing shape model data for the surface of asteroid (101955) Bennu,
        created by the ORX Altimetry Working Group (AltWG). The original name of this file was l_$RESOLUTIONmm_alt_dtm_$REFERENCE_v$VERSION.bds.</description>
    <patterns>
        <RESOLUTION pattern="KERNEL">bennu_l_$RESOLUTIONmm_alt_dtm_[0-9][0-9][0-9][0-9][a-z][0-9][0-9][0-9][0-9][0-9]_v[0-9][0-9][0-9].bds</RESOLUTION>
        <REFERENCE pattern="KERNEL">bennu_l_[0-9][0-9][0-9][0-9][0-9]mm_alt_dtm_$REFERENCE_v[0-9][0-9][0-9].bds</REFERENCE>
        <VERSION pattern="KERNEL">bennu_l_[0-9][0-9][0-9][0-9][0-9]mm_alt_dtm_[0-9][0-9][0-9][0-9][a-z][0-9][0-9][0-9][0-9][0-9]_v$VERSION.bds</VERSION>
    </patterns>
</kernel>

As you can see the three patterns present in the mapping element: $RESOLUTION, $REFERENCE, and $VERSION are present as pattern elements.

When no release plan is provided as an input, the mapping of kernels does not occur and the kernels present in the kernels directories need to have their final names as described in the first approach.

Meta-kernel

The next section of the configuration file is the one that defines the generation of the meta-kernels (MKs). NPB is capable to either generate MKs automatically or to assist you in their generation.

If NPB is set to generate kernels automatically, after the MK is generated and if indicated via configuration, NPB will pause the execution and will provide you with the option to review the MK that it has generated. More information is provided in Interactive step for Meta-kernels.

Alternatively you can provide MKs that you have generated manually or by any other mean to NPB via configuration as well. The elements of the MK section of the configuration file are the following:

Meta-kernels

Element	Description	Required?
mk_inputs	You can specify a list of MKs for the archive release by providing their path.	No
mk	This element provides the configuration elements necessary to automatically generate a MK.	Yes

The elements present in the mk element are: name, coverage_kernels, interrupt_to_update, grammar, and metadata - that at the same time consists of the description, keyword and data elements. There can be as many mk elements as needed. This element is described in detail below.

Automatic generation of Meta-kernels

The <mk> element of the configuration provides the parameters required to automatically generate MKs. The first nested element of <mk> is the <name> element, that provides a mapping to the patterns in the name by specifying the length of these patterns; therefore these patterns must have a fixed length.

The element <name> is required even if the MK is provided as an input –and therefore is not generated automatically.

For example a MAVEN MK that provides yearly coverage and can have multiple versions would be as follows:

<mk name="maven_$YEAR_v$VERSION.tm">
    <name>
        <pattern length="2">VERSION</pattern>
        <pattern length="4">YEAR</pattern>
    </name>

Please note that the patterns of the <mk> name attribute cannot be contiguous, the following is not permitted: insight_$YEAR$VERSION.tm.

The next element is <interrupt_to_update>, this element determines whether if after kernel generation and before the kernel label generation NPB must be paused to provide the option to manually edit the generated MK. It must be set to either True or False.

Meta-kernel grammar

The next element is <grammar>. The kernel grammar provides an ordered list of kernel names with patterns that will populate the MK. For example:

<grammar>
    <!-- LSK -->
    <pattern>naif0012.tls</pattern>
    <!-- PCK -->
    <pattern>pck00010.tpc</pattern>
    <!-- FK -->
    <pattern>maven_v[0-9]{2}.tf</pattern>
    <!-- IK -->
    <pattern>maven_ant_v[0-9]{2}.ti</pattern>
    <pattern>maven_euv_v[0-9]{2}.ti</pattern>
    <pattern>maven_iuvs_v[0-9]{2}.ti</pattern>
    <pattern>maven_ngims_v[0-9]{2}.ti</pattern>
    <pattern>maven_sep_v[0-9]{2}.ti</pattern>
    <pattern>maven_static_v[0-9]{2}.ti</pattern>
    <pattern>maven_swea_v[0-9]{2}.ti</pattern>
    <pattern>maven_swia_v[0-9]{2}.ti</pattern>
    <!-- SCLK -->
    <pattern>MVN_SCLKSCET.[0-9]{5}.tsc</pattern>
    <pattern>mvn_sclkscet_[0-9]{5}.tsc</pattern>
    <!-- SPK -->
    <pattern>de430s.bsp</pattern>
    <pattern>mar097s.bsp</pattern>
    <pattern>maven_struct_v[0-9]{2}.bsp</pattern>
    <pattern>date:maven_orb_rec_[0-9]{6}_[0-9]{6}_v[0-9].bsp</pattern>
    <!-- CK -->
    <pattern>date:mvn_iuvs_rem_[0-9]{6}_[0-9]{6}_v[0-9]{2}.bc</pattern>
    <pattern>date:mvn_app_pred_[0-9]{6}_[0-9]{6}_v[0-9]{2}.bc</pattern>
    <pattern>date:mvn_app_rel_[0-9]{6}_[0-9]{6}_v[0-9]{2}.bc</pattern>
    <pattern>mvn_swea_nom_131118_300101_v[0-9]{2}.bc</pattern>
    <pattern>date:mvn_sc_pred_[0-9]{6}_[0-9]{6}_v[0-9]{2}.bc</pattern>
    <pattern>date:mvn_sc_rel_[0-9]{6}_[0-9]{6}_v[0-9]{2}.bc</pattern>
    <!-- DSK -->
</grammar>

As it can be seen in the example, there are three types of entries:

• entries without patterns e.g., naif0012.tls

• entries with patterns e.g., maven_v[0-9]{2}.tf

• entries with patterns and preceded by date: e.g., date:maven_orb_rec_[0-9]{6}_[0-9]{6}_v[0-9].bsp

Entries without patterns will include the kernels literally specified. Entries with patterns will look for the last version of the kernel sorted in alphanumerical order. Entries with patterns and with date: will include the last version in alphanumerical order for each date specified by a set of its patterns; this allows for multiple SPK and CK kernels with the same pattern that provide coverage for a given year of for the whole mission to be included in the appropriate order.

For example, the SPK kernel pattern date:maven_orb_rec_[0-9]{6}_[0-9]{6}_v[0-9].bsp, includes two patterns that specify the coverage start and finish: [0-9]{6}, by including the date: prefix in the pattern, NPB will include the following kernels:

'$KERNELS/spk/orx_200827_201020_201020_od294_v1.bsp'
'$KERNELS/spk/orx_201020_210524_210103_od297_v1.bsp'
'$KERNELS/spk/orx_201020_201109_201020_od294_v1.bsp'

instead of only:

'$KERNELS/spk/orx_201020_201109_201020_od294_v1.bsp'

NPB will combine search these kernels in the staging_directory, the bundle_directory, and as a last resort kernels present in other MKs.

Kernel entries left padding

In addition the <grammar> element can include an optional <padding> element. This element indicates whether if the kernels listed in the meta-kernel should have the usual 26 blank spaces left padding or not. Usually these blank spaces are recommended but sometimes due to long kernel names the resulting line length can exceed the maximum recommended length of 80 characters. In such case it is better to remove this left padding. This can be done by setting the element <padding> to False. The default value, even if not defined is True:

<grammar>
    <!-- Left padding -->
    <padding>False</padding>
    <!-- LSK -->
    <pattern>naif0012.tls</pattern>
    <!-- PCK -->

will result in a MK as follows:

   \begindata

      PATH_VALUES     = ( '..'      )

      PATH_SYMBOLS    = ( 'KERNELS' )

      KERNELS_TO_LOAD = (

'$KERNELS/lsk/naif0012.tls'

'$KERNELS/pck/pck00010.tpc'
'$KERNELS/pck/gm_de431.tpc'

whereas the with “padding” set to “True” or not defined:

<grammar>
    <!-- Left padding -->
    <padding>True</padding>
    <!-- LSK -->
    <pattern>naif0012.tls</pattern>
    <!-- PCK -->

will result in a MK as follows:

\begindata

  PATH_VALUES       = ( '..' )

  PATH_SYMBOLS      = ( 'KERNELS' )

  KERNELS_TO_LOAD   = (

                       '$KERNELS/lsk/naif0012.tls'

                       '$KERNELS/pck/pck00010.tpc'
                       '$KERNELS/pck/gm_de431.tpc'

Meta-kernel metadata

The MK metadata are all the other elements of the MK that are not kernels to be included in the NPB MK template, several templates are available in the different IM template directories e.g.: naif-pds4-bundler/src/pds/naif_pds4_bundler/templates/1.5.0.0/template_metakernel.tm.

The metadata includes:

• a MK description that can have patterns;

• a keyword element that provides the values of the description patterns;

• a data element that provides additional data to be included in the MK.

Here’s an example for InSight:

<metadata>
    <description>
        This meta-kernel lists the INSIGHT SPICE kernels providing coverage
        for the whole $MISSION. All of the kernels (...).
    </description>
    <keyword>
       <MISSION>mission</MISSION>
    </keyword>
    <data>
        SPACECRAFT_ID     = -189
        CENTER_ID         = 499
        LANDING_TIME      = '2018-11-26T19:44:52.444'
        LANDING_SOL_INDEX = 0
        BODY10_GM         = 1.3271244004193938E+11
    </data>
</metadata>

Manual Input

If you choose to provide a manually generated MK, an alternative to specify the MK in the release plan or in the kernel list is to provide it in the MK section of the configuration file: you can provide the location of the MK(s) using the required number of entries of the file element in mk_inputs. E.g. for the LADEE archive the MK section of the configuration file can be as simple as:

<meta-kernel>
    <mk_inputs>
        <file>../data/ladee_v01.tm</file>
    </mk_inputs>
    <mk name="ladee_v$VERSION.tm">
        <name>
            <pattern length="2">VERSION</pattern>
        </name>
     </mk>
</meta-kernel>

If the MKs specified by this list are not found the pipeline will stop its execution.

Coverage determination

Whether if you generate the MKs automatically or provide them as inputs, NPB needs to know how to determine their coverage. The <coverage_kernel> element is optional and indicates the kernels that will determine the coverage of the MKs by providing a list of kernel patterns and binding each of them to a MK pattern using an attribute for each entry.

The kernel pattern must match a kernel that is included in the MK. What follows is a Mars 2020 configuration file extract example:

<coverage_kernels>
    <pattern>m2020_cruise_od138_v[0-9].bsp</pattern>
    <pattern>m2020_surf_rover_loc_[0-9][0-9][0-9][0-9]_[0-9][0-9][0-9][0-9]_v[0-9].bsp</pattern>
</coverage_kernels>

With this configuration, specified in the <mk> element m2020_v$VERSION.tm if the release includes the m2020_v01.tm. The MK coverage will be determined by the kernels included in the MK defined by the pattern. For example:

m2020_cruise_od138_v1.bsp
m2020_surf_rover_loc_0001_0083_v1.bsp

If the <coverage_kernel> element is not specified the MK coverage will be set to the mission start and mission stop times specified in Mission Parameters.

Please note that unless specified via configuration, the combined coverage of MKs for which kernels have been provided to determine their coverage will be used to determine the coverage of the SPICE Kernels and Miscellaneous Collections and the Bundle coverage. More details are provided in the section Product Coverage Assignment Rules.

Final remarks

Regardless of the content of the Meta-Kernel section of the configuration file, MKs must have entries in the Kernel List section in order to be considered by NPB as an input.

Generating MKs is not a trivial task. NPB’s automated MK generation is designed to support you on the task.

There is an infinite number of combinations in which a MK can be organised. This is a problem for already existing archives that start using NPB and the MK style of which does not match with the one provided by NPB. For such cases NPB can still be helpful since it can be set to pause after the MK generation and before the MK is labeled for the operator to update the automatically generated MK at will.

When starting a new archive, NAIF recommends that you follow the style provided by NPB.

Orbit number file

The last element of the Configuration File is the Orbit number (ORBNUM) file configuration. ORBNUM files, if present, are included in the miscellaneous collection since they are not SPICE kernels. The generation of their labels requires some special configuration elements described in this section.

An ORBNUM file provides a table of records ordered by an increasing orbit numbering scheme. The orbit number changes at every given orbit event (periapsis, apoapsis, etc.) and the information contained for each record includes a number of fields. Some of these fields are expressed in a given reference frame that makes use of a set of kernels (generally a PCK). More information on ORBNUM files is provided in the section A Word on Orbit Number Files. Here’s an example of the orbit number file section of the configuration file for MAVEN:

<orbit_number_file>
    <orbnum>
        <pattern>maven_orb_rec_[0-9]{6}_[0-9]{6}_v[0-9].orb</pattern>
        <!-- Parameters from the orbnum generation preference file -->
        <event_detection_frame>
            <spice_name>IAU_MARS</spice_name>
            <description>Mars body-fixed frame</description>
        </event_detection_frame>
        <header_start_line>1</header_start_line >
        <pck>
            <kernel_name>pck0010.tpc</kernel_name>
            <description>IAU 2009 report</description>
        </pck>
        <coverage>
            <kernel cutoff="True">../data/kernels/spk/maven_orb_rec_210101_210401_v2.bsp</kernel>
        </coverage>
        <author>NAIF, JPL</author>
    </orbnum>
</orbit_number_file>

This section requires a <orbnum> configuration element nested from <orbit_number_file> per ORBNUM file type to be archived. Each of these orbnum elements will have a number of elements to facilitate the generation of the ORBNUM label:

orbnum (nested from orbit_number_file)

Element	Description	Required?
pattern	Provides the ORBNUM file name with patterns to match with the ORBNUM file to be archived.	Yes
event_detection_frame	Provides the SPICE name (e.g., IAU_MARS) and the description (e.g., “Mars body-fixed frame”) for the reference frame that has been used to detect the orbit event.	Yes
header_start_line	Specifies the line where the ORBNUM file header starts (typically 1.)	Yes
pck	Provides the PCK kernel name used with the event detection frame and its description (e.g., pck0010.tpc and IAU 2009 report.)	Yes
coverage	Provides the element to determine the coverage of the ORBNUM file. This element is described in detail in the next subsection.	Yes
author	Indicates the organisation that originally generated the ORBNUM file. (e.g., NAIF, JPL)	Yes

ORBNUM Coverage determination

The coverage of an ORBNUM file can be determined in four different ways:

• If there is a one to one correspondence with an SPK file, the SPK file can be provided with the <kernel> element. The element value can be: a path to a specific kernel that does not have to be part of the increment, a kernel with patterns present in the increment, or a kernel with patterns present in the final directory of the archive. E.g.,

  <kernel>maven_orb_rec_[0-9][0-9][0-9][0-9][0-9][0-9]_[0-9][0-9][0-9][0-9][0-9][0-9]_v[0-9].bsp</kernel>
  

• If there is a quasi one-to-one correspondence with an SPK file with a given cutoff time prior to the end of the SPK file, the SPK file can be provided with the <kernel> element. The value can be: a path to a specific kernel that does not have to be part of the increment, a pattern of a kernel present in the increment, or a pattern of a kernel present in the final directory of the archive. Currently the only cutoff pattern available is the boundary of the previous day of the SPK coverage stop time. The cutoff time is provided as an attribute of the <kernel> element and must be set to True or False. E.g.,

  <kernel cutoff="True">../data/kernels/spk/maven_orb_rec_210101_210401_v2.bsp</kernel>
  

• A user can provide a look up table with this configuration file, as follows:

  <lookup_table>
     <file name="maven_orb_rec_210101_210401_v1.orb">
        <start>2021-01-01T00:00:00Z</start>
        <finish>2021-04-01T01:00:00Z</finish>
     </file>
  </lookup_table>
  

  Note that in this particular case the first three and last three lines of the orbnum files would have provided:

  Event UTC PERI
  ====================
  2021 JAN 01 00:14:15
  2021 JAN 01 03:50:43
  2021 JAN 01 07:27:09
  (...)
  2021 MAR 31 15:00:05
  2021 MAR 31 18:36:29
  2021 MAR 31 22:12:54
  

• If nothing is provided NPB will provide the coverage based on the event time of the first orbit and the opposite event time of the last orbit. This will generate a warning because it is likely to be incorrect.

Summary

After going through the detailed description of every section of the Configuration File we hope that the MAVEN example provided at the beginning of this chapter is better understood.

Some NPB configuration files can become quite complex especially because of the Kernel List, MK, and ORBNUM sections. A good example of a complex configuration file is the the OSIRIS-REx sample file: naif-pds4-bundler/tests/naif_pds4_bundler/config/orex.xml.

Other configuration files can be really simple: descriptions do not require complex pattern matching and MKs are manually generated. An example of such configuration files is the LADEE sample file: `naif-pds4-bundler/tests/naif_pds4_bundler/config/ladee.xml.

Generating the configuration file should be a one time effort for which the NAIF NPB developer can assist you. After the configuration file has been setup for the first release, it can be used with limited changes for all subsequent releases. Changes will probably be limited to:

• update spiceds name and/or location

• update directories

• addition of Kernel List elements

• meta-kernel updates

• new archive producer.